How Federalist Works
Federalist is a hosted service run by 18F 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 Federalist. The main code repository for the Federalist 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 Federalist’s modular repositories:
Functional Repositories
- federalist This is the core application for Federalist and contains the frontend interface as well as the code that interacts with the GitHub API and sets up new Federalist 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 Federalist 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 Federalist deploys static content. It adds some required headers for compliance.
- federalist-garden-build This container image contains the code to build Federalist sites in Garden Linux containers.
Documentation
- federalist.18f.gov The documentation website.
Templates
- federalist-uswds-template A Federalist template that uses the U.S. Web Design Standards Jekyll theme.
- federalist-report-template A Federalist template that offers an easy to use setup for hosting multiple pages about a recent report or order. This template code can be found in the report-config branch under the federalist-uswds-template repo.
- federalist-landing-page-template A single page meant to host information about a new initiative or report.
- federalist-modern-team-template A simple site to showcase the work of an organization with a few different page types.
Architecture
Federalist 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. 
https://federalist.18f.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
- Federalist API: /*
- Federalist 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 shared-psql
Simple Queue Service (SQS)
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)
Website bucket for hosting generated static website files
- federalist.18f.gov
- main builds: /site/*
- demo builds: /demo/*
- preview builds: /preview/*
Creating new buckets
The following guide is intended for use with the new cloud.gov, hosted on the GovCloud AWS region.
There are two buckets, one for each of Federalist’s environments (production and staging). These buckets should be active and properly configured, but there may be times when a developer needs to create a new one. To accomplish this, he developer should follow the documentation on cloud.gov.
Buckets intended to serve websites will need to be created using the basic-public plan. Once the bucket is created, the developer must enable CORS access, typically only allowing GET requests to come from the Federalist application the bucket serves.
An example configuration can be found in the here.
Finally, the developer will need to enable the website hosting using the AWS CLI’s s3 website command. These commands expects the developer’s local directory to contain a generic 404 page named 404.html:
aws s3 cp ./404.html s3://${BUCKET_NAME}/404.html
aws s3 website s3://${BUCKET_NAME} --index-document index.html --error-document 404.html
At this point, the bucket should be enabled to host websites generated by Federalist. The final step to allow the Federalist web app to access the bucket is to bind the service instance to the app. To bind the bucket to Federalist, add the name of the service to the environment specific manifest.yml file in Federalist, under the services key.
NOTE: Replacing the binding to the bucket service will point all future builds to the new bucket. Federalist will no longer be able to route to the old bucket, although sites built there will be accsible via the bucket url. Federalist currently only supports a single bucket per environement.
Public Internet
Sites are publicly available as part of an S3 website bucket
CloudFront is used for custom domains. 404 pages are configured manually for customers that submit a support request to the Federalist team.