Github Codespaces provide an Integrated Development Environment (IDE) that is accessible entirely in a web browser. It is essentially a web based version of VS Code running on a cloud based virtual machine.

Codespaces is available for all members of the Department of Veterans Affairs organization on Github. Application config for Codespaces is a work in progress.

See #codespaces on Slack for additional questions about using Codespaces.

Getting Started

  1. Visit vets-website Github repository

  2. Click green "Code" button and select "Open with Codespaces"

    Inside the code dropdown in the GitHub UI
  3. If this is your first time using Codespaces select "New codespace"

    Message showing that we have no active codespace
  4. To provide sufficient resources, select a Machine type with at least 16GB of RAM and 64GB of disk space

    Codespaces machine type selection dialog with 8 core machine type selected
  5. On initial creation the Codespace will perform these actions:

    • Configure Node, NPM, NVM, and Yarn

    • Install dependencies

    • Download vagov-content repo

    • Download Drupal cache

    • See /.devcontainer/codespaces-create.shđź”— for full script

  6. If you are only developing apps and wish to skip the Drupal cache download and content build process, edit the Codespaces settings under your Github account and add an encrypted secret with the name VETS_WEBSITE_BUILD_CONTENT and value NO and make it accessible by the vets-website repository. This will significantly speed the creation process.

  7. Click notifications (bell icon in bottom right corner) and "See progress logs" to view status. There is also a VS Code command: >Codespaces: View Creation Log

    Viewing the creation log option
  8. While setup is in process the "Configure Codespace" step will be active.

    Creation log output
  9. Once setup is complete the "Configure Codespace" still will show as complete.

    Full logs are available at ~/post-create.log

    Configuration output in the terminal
  10. Start the development server

    • Open terminal

    • Run command:

      yarn watch

    • Ctrl + click on localhost link in terminal to open webserver in new tab

Customization

Settings sync

  • Click on user icon in lower left hand corner and select "Turn on settings sync"

  • Select your Github username

  • User settings will be synchronized to ~/.vscode/settings.json and will override any container or workspace settings.

Codespaces in vets-website and content-build repositories

The vets-website and content-build repositories are both enabled to work with GitHub CodeSpaces. Please follow the Quickstart instructions to get up and running. The system will execute some basic commands to build the environment. It takes a little while (around 20mins to initially complete), but you can follow the progress by viewing the creation log (Codespaces: View Creation Log) while the container starts up.

After the environment is set up you can run npx http-server build/localhost -s -c-1 -p 3002 from the content-build directory to view the built site. It will run on port 3002 (use 3001 if you’re only interested in vets-website), which can be made public by sharing the port for design reviews or whatever you need.

You have full access to the command line in codespaces. If you want to manually build or watch we have: yarn build:codespaces, content-build also has an additional watch command in:  yarn watch:codespaces available to help. If you’re only interested in vets-website (without content-build) or you want the process to complete quicker you can use the same commands you use locally when working (yarn build & yarn watch)

If your Codespace freezes up during the setup process, try turning it off and on again (Codespaces: Stop Current Codespace).

NOTE: Codespaces will spin down after 30mins of inactivity, so if you’re running a design review you may need to keep the container alive or rebuild.

vets-api in Codespaces

By default, CORS on vets-api will be blocked, but you can allow the request by adding the Allow CORS: Access-Control-Allow-Origin browser extension (or something similar if you're not using Chrome). Be sure to select "Access-Control-Allow-Credentials" in the settings or requests will continue to be blocked.