VA.gov CMS

This is the public/open documentation for the VA.gov Content Management System (CMS). The private/sensitive documentation is here. Follow sensitive-guidance.md to know what should be public vs private (we follow the U.S. Digital Services Playbook and default to open/public).

The VA.gov CMS is the backend for www.va.gov. Frontend repo is at https://github.com/department-of-veterans-affairs/vets-website/.

If you find any improvements to make to this documentation & you have push access then please commit your changes directly to the main branch. All commits that affect just *.md files will be ignored by the automated Continuous Deployment (CD) and not be tested so they won't have a commit status posted at https://github.com/department-of-veterans-affairs/va.gov-cms/commits. You SHOULD prefix your commit with [docs] e.g. [docs] Commit message ... so that we know why the commit status will be missing. 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. Environments
      1. CI Environments
      2. Local - Lando
      3. BRD Environments
      4. HTTPS
      5. Environment Variables
      6. Kubernetes
   6. Testing
   7. Debugging
   8. Code Review
   9. Comparing GraphQL Output
   10. Logging into BRD (e.g. production, staging) instances
3. Release & Deployment
   1. The BRD System: Build, Release, Deploy
   2. CMS Release Process
   3. CMS-CI Release Process
4. Architecture
   1. Overview
   2. Drupal
      1. Memcache
   3. Amazon Web Services
      1. Elasticache for Memcache
   4. content models
   5. MetalSmith
   6. Interfaces - APIs and Feature Flag
   7. Migrations (data imports)
      1. Facility
      2. Form
   8. Security
5. CMS Users
   1. Login / SSOi
   2. CMS User Notification Systems
6. CMS Content
   1. Workflow
      1. Alias Lockdown
      2. Broken Links
      3. Content Preview
   2. Content Release
   3. Section Dashboards

Introduction

About VA.gov

The VA.gov website is made possible by a number of different tools and systems. See High-Level Architecture for an overview of all of the components.

This repository contains the source code for the Content Management System (CMS or CMS-API) for VA.gov, running at prod.cms.va.gov.

Access to the production CMS is restricted with CAG. See Getting Access.

The CMS is built on Drupal 9, using the Composer package management system. See 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 9, Lightning Distribution
• WEB: github.com/department-of-veterans-affairs/vets-website - Metalsmith
• VETS-API: github.com/department-of-veterans-affairs/vets-api - Ruby
• VETS-CONTENT: github.com/department-of-veterans-affairs/vagov-content - Markdown

The VFS team deploys all of these apps using a Jenkins server, configured with a private GitHub Repo:

• DEVOPS: github.com/department-of-veterans-affairs/devops

All development on these projects is done via Pull Requests.

High-Level Architecture

The public website seen at VA.gov is a static site hosted on S3: just HTML, CSS, JavaScript and images.

The source code used to generate the public site is called vets-website or Front-end or WEB, and is available at github.com/department-of-veterans-affairs/vets-website.

Decoupled Drupal

The codebase in this repository (va.gov-cms) is for the CMS, which is built on Drupal 9. The CMS is not publicly available. It acts as a Content API for the WEB application, and a Content Management System for VA.gov Content Team.

The CMS codebase now includes the WEB codebase as a dependency: the version is set in composer.json. It is downloaded to the ./web folder during composer install.

Build and Release Process

When the content and code updates are ready for release, the WEB Build process is kicked off, it reads content from the CMS via GraphQL (and other locations), and outputs HTML, CSS, JavaScript and images.

See WEB & CMS Integration for full details on how the WEB and CMS projects work together.

Infrastructure

This section outlines only the systems utilized by the CMS. For information on the WEB project's infrastucture, see .

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 and a WEB instance built from that PR environment's content, like web-{hash}.ci.cms.va.gov.
• 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.
• Single EC2 Instance: @TODO: List size, storage, etc.

CMS in BRD: Dev, Staging, 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 dev, staging and production environments inside the VAEC when the release is ready.

See The BRD System: Build, Release, Deploy for more information.