VA.gov CMS

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

Contributing to this documentation

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

Table of Contents

1. Introduction
   1. About VA.gov
   2. Contributing
   3. High-Level Architecture
   4. Infrastructure
2. Developer Info
   1. Getting Started
   2. WEB & CMS Integration
   3. Workflow
   4. Project Conventions
   5. Code Ownership
   6. Environments
      1. CI Environments
      2. Local - DDEV
      3. BRD Environments
      4. HTTPS
      5. Environment Variables
      6. Kubernetes
   7. Alerts
   8. GitHub Workflows
   9. Logging into BRD (e.g. production, staging) instances
3. Quality and Testing
   1. Quality Assurance (QA)
   2. Development Best Practices
   3. Code Review
   4. Testing
   5. Debugging
   6. Comparing GraphQL Output
   7. Dependabot Alerts
   8. Dependabot Updates
   9. Sentry
   10. Profiling with Blackfire
   11. Scalability Testing
4. Release & Deployment
   1. The BRD System: Build, Release, Deploy
   2. CMS Release Process
   3. CMS-CI Release Process (TODO)
5. Architecture
   1. Drupal
      1. Memcache
   2. Content Models and Documentation
      1. Centralized Content
   3. MetalSmith
   4. GraphQL
   5. Interfaces - APIs and Feature Flag
   6. Migrations (data imports)
      1. Facility
      2. Form
   7. Removing deprecated fields
   8. Security
   9. Upstream Dependencies
   10. Downstream Dependencies
6. CMS Users
   1. Login / SSOi
   2. CMS User Notification Systems
   3. Drupal API Users
7. CMS Content
   1. Workflow
      1. Alias Lockdown
      2. Broken Links
      3. Content Preview
   2. Content Release
   3. Section Dashboards
   4. Facilities
      1. VAMC Facilities
         1. VA Lovell / TRICARE
8. Historical
   1. Main branch name change
   2. Elasticache Investigation
   3. EWA Rules of Engagement

Introduction

About the CMS

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.

Contributing

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.

High-Level Architecture

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.

Decoupled Drupal

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

Build and Release Process

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.

Infrastructure

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.

CMS-CI: Pull Request and Demo/Ad-hoc Environments

• 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
    • To access 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
• 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.

CMS in Build-Release-Deploy: Staging and Production

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.