Skip to main content
U.S. flag

An official website of the United States government

How Pages Works

Pages is a hosted service run by cloud.gov for use by US federal government agencies. The software behind this service is open source and released to the public domain for anyone to use. We also welcome your contributions and ideas.

We use GitHub to manage our work on Pages. The main code repository for the Pages is at https://github.com/18F/federalist. In addition to hosting code, we use the issue queue on this repository to manage our development tasks and milestones. If you’re interested in getting involved with this project, please see the contributing guide. Here is a specific description of each of Pages’ modular repositories:

Functional Repositories

  • federalist This is the core application for Pages and contains the frontend interface as well as the code that interacts with the GitHub API and sets up new Pages sites, including a GitHub webhook that triggers messages into the build queue through the app. It has a cloud.gov PostgreSQL database service instance for session storage and persistent data storage of users, sites, and logs.
  • federalist-builder This application launches build tasks for Pages in a Linux Garden container based on messages from a queue and contains scheduling logic.
  • federalist-proxy This application serves as a proxy for the S3 bucket to which Pages deploys static content. It adds some required headers for compliance.
  • federalist-garden-build This container image contains the code to build Pages sites in Garden Linux containers.

Documentation

Templates

Architecture

Pages is located on cloud.gov’s GovCloud environment, which has received FedRAMP certification. This blog post explains more about FedRAMP.

The diagram for Federalist’s architecture is below. It’s not intended for general audiences and is focused on concisely showing all of the components of Federalist as required for compliance. Please contact us with any questions: we aren’t expecting this diagram to be useful by itself to gain an understanding of Federalist. Diagram of Federalist architecture

https://pages.cloud.gov

Main application server providing an API and front-end website load balanced across at least two instances

Build messages generated by the API are sent to the SQS queue

  • GH: 18f/federalist
  • CF: -o federalist -s prod -n federalist
  • Pages API: /*
  • Pages front-end: /assets/*

GitHub

Changes from the editor are committed to repositories

Commits POST webhook PUSH events to the API

federalist-production-rds

General application database for the API

  • aws-rds medium-gp-psql

Elasticache for Redis

Message queue for handling build requests

  • federalist-builds

https://federalist-builder.fr.cloud.gov

Processes build requests from a queue and launches build tasks

Polls the queue for build messages

Message is deleted after a task is initiated

  • GH: 18f/federalist-builder
  • CF: -o federalist -s prod -n federalist-builder

cloud.gov Build Container Orchestration

Runs docker container tasks.

Build status sent back to API over HTTP POST

Static assets synced to S3 using the AWS CLI

  • GH: 18f/federalist-garden-build
  • ECS cluster: default
  • ECS task definition: federalist-builder
  • Cloud Formation: EC2ContainerService-default
  • EC2 instance
    • Docker image

Simple Storage Service (S3)

Each site repository has a dedicated S3 bucket.

Website bucket for hosting generated static website files

  • federalist.18f.gov
  • main builds: /site/*
  • demo builds: /demo/*
  • preview builds: /preview/*

Public Internet

Sites are publicly available as part of an S3 website bucket

CloudFront is used for custom domains. Error document settings can be configured manually for customers that submit a support request to the Pages Support team.

Suggest edits