This is the public/open documentation for the VA.gov Content Management System (CMS) for development, QA and DevOps topics. For product, design, support, research and cross-team documentation, visit the platform/cms docs. For private/sensitive documentation, visit the private docs repo. See sensitive-guidance.md to read about what should be public vs. private. We follow the U.S. Digital Services Playbook and default to open/public).
VA.gov is constructed at the highest level by three projects:
- the CMS or Content Management System, in this repository
- the vets-website project, covering the many special- and general-purpose applications making up the website
- the content-build project, which extracts and processes the content from the CMS for display on the website
If you find any improvements to make to this documentation and you have push access, please commit your changes directly to the main
branch. Please prefix your commit message with [DOCS]
e.g. [DOCS] Commit message ...
.
If you don't have push access, you can submit a pull request for review.
Thanks,
The VA.gov CMS Team
- Introduction
- Developer Info
- Quality and Testing
- Release & Deployment
- Architecture
- Drupal
- Content Models and Documentation
- MetalSmith
- GraphQL
- Interfaces - APIs and Feature Flag
- Migrations (data imports)
- Removing deprecated fields
- Security
- Upstream Dependencies
- Downstream Dependencies
- CMS Users
- CMS Content
- Historical
This repository hosts the source code for the Content Management System (CMS or CMS-API) utilized by VA.gov.
The production instance can be found at prod.cms.va.gov. Please note that access to the production CMS is limited; refer to Getting Access for more information.
Built on Drupal 10.1, the CMS employs the Composer package management system. To get started, consult Getting Started.
All of the source code used for generating VA.gov is open source, listed under the department-of-veterans-affairs organization on GitHub:
- CMS: github.com/department-of-veterans-affairs/va.gov-cms - Drupal 10.1
- vets-website: github.com/department-of-veterans-affairs/vets-website - Node.js
- vets-api: github.com/department-of-veterans-affairs/vets-api - Ruby
- content-build: github.com/department-of-veterans-affairs/vagov-content - Node.js, Metalsmith
The VFS team deploys all of these apps using a Jenkins server, configured with a private repository.
All development on these projects is done via Pull Requests.
The public-facing website at VA.gov is a static site hosted on S3, composed of HTML, CSS, JavaScript, and images.
This codebase is dedicated to the CMS, built on Drupal 10.
The source code for generating the public site is located in the vets-website repository. The component responsible for extracting raw content from the CMS and converting it to HTML is developed in a separate repository, content-build.
The production instance of the CMS is utilized in two main ways:
- as a tool for the VA.gov Content Team to efficiently create and manage content
- as a repository and API server for the content-build process to publish content to the world at large
In a continuous integration context, the content-build
project is managed as a dependency of the CMS project; the build script is executed targeting the local instance and runs all of the content queries performed as part of the normal content release process, to ensure no changes have been introduced to the CMS codebase that break compatibility. A full content build happens at the conclusion of the testing pipeline on our Tugboat preview environments.
In the normal content release process, GitHub Actions triggers a workflow that targets a mirror (hosted in Tugboat) of the production CMS instance. It retrieves content from the CMS via GraphQL (and other sources) and generates HTML, CSS, JavaScript, and images. These artifacts are then copied to an s3 bucket, which is then rotated into service to serve website visitors.
This section outlines only the systems utilized by the CMS. See the READMEs in the vets-website
or content-build
repositories for more information about those projects.
- Running Tugboat (docs) at tugboat.vfs.va.gov/. Access restricted to CAG, sign in with GitHub.
- A single "mirror" environment is regularly populated with a sanitized production database copy.
- Open Pull Requests get environments created automatically, cloned from the "mirror" environment, with URLs like:
- pr123-{hash}.ci.cms.va.gov for the CMS
- Cypress test logs and artifacts, see Testing for details.
- web-{hash}.ci.cms.va.gov for the frontend web build
- storybook-{hash}.ci.cms.va.gov for design system documentation
- pr123-{hash}.ci.cms.va.gov for the CMS
- Ad-hoc environments can be created and deleted at any time by any logged in user on tugboat.vfs.va.gov/:
- Should be created under "CMS Demo Environments"
- Can be named anything and can be set to any branch or Pull Request.
- These environments will not change or be rebuild unless the creator chooses.
- Useful for testing and demos outside of the CMS-CI process.
The VFS Team maintains a system called BRD: Build, Release, Deploy.
The system is powered by Ansible Roles in the VA's "DevOps" repository, located at github.com/department-of-veterans-affairs/devops/tree/master/ansible/build/roles/cms
The BRD system builds Amazon server images using Ansible, and tags those images for release along with the source code of CMS.
The VFS team then deploys those images to the staging and production environments inside the VAEC when the release is ready.
See The BRD System: Build, Release, Deploy for more information.