Skip to content

department-of-veterans-affairs/va.gov-cms

Folders and files

NameName
Last commit message
Last commit date
Oct 28, 2024
Jun 17, 2022
Apr 29, 2019
Nov 18, 2024
Oct 25, 2023
Apr 1, 2022
Oct 28, 2024
Jun 16, 2022
Mar 25, 2022
Oct 23, 2024
Nov 13, 2024
Nov 12, 2024
Nov 18, 2024
Jun 16, 2022
Nov 15, 2023
Nov 18, 2024
Nov 4, 2021
Sep 21, 2023
Oct 2, 2024
Apr 9, 2024
Nov 15, 2024
Oct 12, 2021
Jul 13, 2023
Jan 27, 2023
Sep 13, 2023
Nov 9, 2023
Apr 20, 2023
Dec 9, 2020
Sep 28, 2021
Feb 7, 2019
Sep 27, 2022
Oct 2, 2023
Oct 9, 2024
Jul 23, 2021
Nov 22, 2024
Nov 22, 2024
Oct 7, 2024
Feb 7, 2019
Jul 27, 2023
Nov 14, 2023
Oct 28, 2024
Sep 15, 2022
Dec 14, 2022
Sep 6, 2024
Nov 3, 2022
Mar 2, 2021
Jun 27, 2023
Nov 29, 2023
Nov 13, 2020
Jul 12, 2019
Nov 13, 2020
Sep 11, 2024
Feb 2, 2024
Nov 8, 2023
May 5, 2021

Repository files navigation

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. Patches
    7. Environments
      1. CI Environments
      2. Local - DDEV
      3. BRD Environments
      4. HTTPS
      5. Environment Variables
      6. Kubernetes
    8. Alerts
    9. GitHub Workflows
    10. 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:

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:
  • 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.