Step 1: Set up Node

  1. Install nvm:

    Mac:

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

    $ brew update && brew install nvm
    CODE

    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
    CODE

    Follow the post-install instructions in the success message.

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

    $ nvm install 14.15.0
    CODE

  3. Configure nvm to use node 14.15.0 by default:

    $ nvm alias default 14.15.0
    CODE

  4. Install yarn 1.21.1 globally:

    $ npm i -g yarn@1.21.1
    CODE

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

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

Step 2: Get the source code

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
CODE

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

Step 3: Start up the front end

vets-website

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

    $ cd vets-website
    $ yarn install
    CODE

  2. Build all applications for vets-website. Run this standard build script if you need all the CSS and JS generated for work in content-build.

    $ yarn build
    CODE

    If you are only working in an Isolated application(s) (or do not need to build all applications), you can build one or more application(s) with the --entry option.

    $ yarn build --entry=static-pages,auth
    CODE

  3. Start the local development server for all applications. 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
    CODE

    Again, you can limit the watch to one or more application(s) with the --entry option.

    yarn watch --env entry=static-pages,auth
    CODE


    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.

  4. 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.

You can learn more about building applications in the vets-website GitHub readme.

content-build

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.

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

    $ cd content-build
    $ yarn install
    CODE

  2. Content-build steps requires an additional set up step due to code changes in the app. If building content from Drupal, it requires a one-time setup of a .env file to supply connection information.

    cp .env.example .env
    CODE

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

    $ yarn build
    CODE

  4. 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
    CODE

  5. Start the local development server.

    $ yarn watch
    CODE

  6. 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.

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

Step 4: 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.