VA.gov CMS

This is the public/open documentation for the VA.gov Content Management System (CMS). The private/sensitive documentation is here. 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).

The VA.gov CMS is the backend for www.va.gov. The Frontend (WEB) repo is at https://github.com/department-of-veterans-affairs/vets-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. Prefix your commit with [DOCS] e.g. [DOCS] Commit message .... You may also need to use the -n flag with your commit command to skip usual commit message naming convention checks. 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 - DDEV
      3. BRD Environments
      4. HTTPS
      5. Environment Variables
      6. Kubernetes
   6. Quality Assurance (QA)
   7. Testing
   8. Debugging
   9. Code Review
   10. Comparing GraphQL Output
   11. 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 (TODO)
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
   4. Facilities
      1. VAMC Facilities
         1. VA Lovell / TRICARE

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.

Pull requests from the WEB repo and the CMS repo can be integrated together for testing. 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 Vets-Website Repo Readme.

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. See general EC2 info.

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.