Drupal Example

Getting Started 🚀

There are several options for getting started working on a UCEAP project. The first option is the simplest, then they increase in complexity and control:

1. ☁️ Cloud: quickly start editing code on a fresh copy of this project running live in the cloud
2. 🖼️ Hybrid: connect your local editor to this project running live in the cloud
3. 📦 Local: get this project running on your local workstation
4. 💻 Metal: the way we all used to do things back in the good ol' days

Once you're up and running, check out the UCEAP/devcontainer-drupal README for helpful tips about using these environments.

Option 1: Cloud ☁️

The quickest way to start is to run the browser version of Visual Studio Code connected to a cloud container running the server on GitHub Codespaces.

When to use this option

This is a great temporary option if you are new to the project, and is also suitable if you are away from your personal workstation using a different computer or an iPad. For everyday work, look at the options below.

1. Go to the GitHub repository for the project, click the green “<> Code” dropdown, select the "Codespaces" tab, then click the green “Create codespace on qa” button
2. OR visit a pull request you want to review, click the green “<> Code” dropdown, select the "Codespaces" tab, then click the green “Create codespace on <branch>” button
3. Wait several seconds while the Codespace is created
4. When the bottom panel opens up showing “Terminal”, wait for the “postStart.sh” command to finish running
5. Then click on the “Ports” tab in the bottom panel
6. Hover over the line for port 8080 and click the 🌐 globe icon to open the site in a new tab
7. Return to the original tab and start coding. You can check out other branches, create your own branch, and generally do anything you would if you were working locally.

Option 2: Hybrid 🖼️

For more control over your development environment, you can run your favorite IDE locally, connected to a cloud container running the server on GitHub Codespaces. These instructions assume you want to use Visual Studio Code. If you want to use PhpStorm instead then use the GitHub Codespaces plugin from the IntelliJ IDE Plugin Marketplace.

When to use this option

This is an ideal solution if you are reviewing a pull request and need to interact with a running version of the code, but don’t want to interrupt any in-progress work you may be doing on your local environment. This is also a great option if you want to give someone else access to a web server to test your work in progress. For the best long-term solution for local development, look at the next option.

1. Install Visual Studio Code
2. Install GitHub Codespaces extension for Visual Studio Code
3. (OPTIONAL) Set your TERMINUS_TOKEN secret¹
4. Press F1 (on Windows) or Shift-Command-P (on macOS) to open the command palette
5. Type “create new codespace”
6. Start typing the name of the project you are working on and select the matching autocomplete result
7. Select the branch you want to work on
8. Select the smallest instance type option (for this project, it’s 4 core 8gb ram)
9. Wait several seconds while the “Setting up remote connection” notification is displayed
10. When the bottom panel opens up showing “Terminal”, wait for the “postStart.sh” command to finish running
11. Then click on the “Ports” tab in the bottom panel
12. Hover over the line for port 8080 and click the 🌐 globe icon to open the site in your browser
13. Return to Visual Studio Code and start coding.

Option 3: Local 📦

For minimal latency you can run the server locally in a container using Docker, which also lets you work while offline. These instructions assume you want to use Visual Studio Code. If you want to use PhpStorm instead then use the Dev Containers plugin from the IntelliJ IDE Plugin Marketplace.

When to use this option

This should be your standard choice for long term work on this project. It is faster than Codespaces and almost as convenient.

1. If you haven’t already, generate a new SSH key and add the new SSH key to your GitHub account ²
2. Set your GH_TOKEN environment variable ³
3. (OPTIONAL) Setup Terminus ⁴
4. Install Docker Desktop
5. Install Visual Studio Code
6. Install Dev Containers extension for Visual Studio Code
7. Press F1 (on Windows) or Shift-Command-P (on macOS) to open the command palette
8. Type “dev container clone repo” and select the first result
9. Select GitHub as the source
10. Start typing the name of the project you are working on and select the matching autocomplete result
11. Select the branch you want to work on
12. Wait several seconds while the container is built
13. Once it is complete. press Shift-Command-P and “remote install local extensions” (select all and install)
14. Then click on the “Ports” tab in the bottom panel
15. Hover over the line for port 8080 and click the 🌐 globe icon to open the site in your browser
16. Return to Visual Studio Code and start coding.

Want to access these files from your regular tools?

Using "Clone Repository in Container Volume" as described above keeps your working copy inside the container. This is great for keeping things isolated (e.g. if you're working on multiple branches simultaneously you can easily do so using multiple containers), but it makes the files inaccessible to applications running on your local system such as Tower or Kaleidoscope. If you want your working copy to be accessible to your local operating system, then checkout the repository (perhaps using GitHub Desktop⁵) and open the directory in VS Code. You should get a VS Code notification prompting you to "Reopen in a container". Do that and you'll have the best of both worlds: easy containerized development environment, with files accessible to all your favorite local tools.

Option 4: Metal 💻

If you want to go old-school then you can run the project on bare metal rather than in a container.

When to use this option

Because everyone’s local environment is unique, this option comes without support. Proceed only if you are fully comfortable with figuring everything out on your own.

Follow the steps in Setup local development with Valet from scratch. These instructions are out of date and you will need to tweak them extensively.

Footnotes

1. Create a Terminus machine token then add it to your personal Codespaces secrets ↩

2. Note that if you are using 1Password for your ssh-agent, you’ll also need to set the SSH_AUTH_SOCK env var ↩

3. Follow GitHub CLI quickstart then edit your ~/.zprofile to add:

   export GH_TOKEN=`gh auth token`
   

   ↩

4. Add an SSH key for Pantheon and set a TERMINUS_TOKEN environment variable, perhaps by create a Terminus machine token then edit your ~/.zprofile to add:

   export TERMINUS_TOKEN='YOUR_TOKEN_HERE'
   

   ↩

5. Note that on macOS, GitHub Desktop defaults to checking out repositories in your Documents folder. If you keep your Documents in iCloud Drive, this will cause problems with bind mounts in Docker! So choose a different parent directory for your working copy. ↩