Set up VA.gov locally

These instructions cover building and running VA.gov locally, including configuring any required dependencies.

Node setup

1. Install nvm:

   Mac:

   homebrew is recommended for installing nvm but other installation approaches are on nvm Github page.

   $ brew update && brew install nvm
   

   Linux:

   To get the latest version of NVM visit the official page. NVM

   $ curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.34.0/install.sh | bash
   

   Follow the post-install instructions in the success message.

2. Install node 14.15.0 (this also installs npm):

   $ nvm install 14.15.0
   

3. Configure nvm to use node 14.15.0 by default:

   $ nvm alias default 14.15.0
   

4. Install yarn 1.21.1 globally:

   $ npm i -g yarn@1.21.1
   

5. Verify correct versions of node and yarn are installed:

   $ node --version # 14.15.0
   $ yarn --version # 1.21.1
   

Get the source code

6. Clone VA.gov git repos as sibling directories:

   $ git clone git@github.com:department-of-veterans-affairs/vets-website.git
   $ git clone git@github.com:department-of-veterans-affairs/vagov-content.git
   $ git clone git@github.com:department-of-veterans-affairs/content-build.git
   $ git clone git@github.com:department-of-veterans-affairs/vets-json-schema.git
   $ git clone git@github.com:department-of-veterans-affairs/veteran-facing-services-tools.git
   $ git clone git@github.com:department-of-veterans-affairs/vets-api.git
   $ git clone git@github.com:department-of-veterans-affairs/vets-api-mockdata.git
   

   Front end repos

   • vets-website: Core front end platform and application code
   • vagov-content: Markdown content used to generate static pages
   • content-build: Liquid templates and content build for static pages
   • veteran-facing-services-tools: Shared front end components (including non VA.gov users) and front end documentation site

   Back end repos

   • vets-api: Core Rails API server application code
   • vets-api-mockdata: Mock data used when running locally and on dev for the backend

   Shared repos

   • vets-json-schema: Shared JSON Schema definitions used by form applications and the APIs that they consume

Start up the front end

vets-website

7a. Navigate to the vets-website repository, then install vets-website dependencies. See these common commands for more information.

$ cd vets-website
$ yarn install

8a. Build vets-website. If you're only doing application work inside vets-website you can run the build command which contains the scaffolding option by default:

$ yarn build

If you need the CSS and JS generated for work in content-build you can run a normal build:

$ yarn build

9a. Start the local development server. If you are applying CSS and/or JS changes to a static page/template that renders in content-build, we recommend leaving this command running so you will be able to see the changes in content-build.

$ yarn watch

The watch is complete when the CLI says Compiled successfully.

If you would like webpack to open a browser window for you, please run yarn watch --open. We use Webpack DevServer to watch and serve the files locally; all the same options and documentation should apply.

10a. Open http://localhost:3001 in a browser if you are working on an app; otherwise, continue on to the content-build section for viewing changes in the browser.

content-build

NOTE: In order to run content-build, you must first generate the CSS and JS files within vets-website (follow steps above). If you don't, you will see a build error in the console instructing you to first generate files in vets-website. If you are applying CSS and/or JS changes to a static page/template that renders in content-build (like the homepage) you will need to run a watch in vet-website to view the updates. The CSS and JS files within vets-website are locally connected through a symlink in the build process.

If you don't need to locally view static pages and are just working on applications, you don't need to set this part up.

7b. Navigate to the content-build repository, then install dependencies via yarn

$ cd content-build
$ yarn install

8b. Build content-build. Make sure you configured the SOCKS proxy to fetch content from Drupal.

$ yarn build

If you do not have access to the SOCKS proxy, you can alternately fetch the latest cached version of the content.

$ yarn fetch-drupal-cache

9a. Start the local development server.

$ yarn watch

The watch is complete when the CLI says Compiled successfully. If you just need a server running without watching the metalsmith files you can run npx http-server . -p 3002 inside /build/localhost to save some CPU.

10a. Open http://localhost:3002 in a browser

Backend and internal tools set up

Setting up the backend and internal tools allows local test account login and static content rendering.

• Backend (vets-api) set up instructions

  The local vets-website is configured to point to the vets-api backend at http://localhost:3000. Any website functionality that depends on the backend (i.e. login, save-in-progress, form submission, feature toggles) will require a locally running instance of vets-api.

• Local test account login instructions

• Internal tools setup instructions

  This proxy setup is required to access static content locally and to access to our reporting and monitoring tools. Running the yarn watch task with the SOCKS proxy active will automatically pull and cache the static content for vets-website.