Skip to main content
U.S. flag

An official website of the United States government

Dot gov

The .gov means it’s official.
Federal government websites often end in .gov or .mil. Before sharing sensitive information, make sure you’re on a federal government site.


The site is secure.
The https:// ensures that you are connecting to the official website and that any information you provide is encrypted and transmitted securely.

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 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 is located on’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

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


Changes from the editor are committed to repositories

Commits POST webhook PUSH events to the API


General application database for the API

Simple Queue Service (SQS)

Message queue for handling build requests

Processes build requests from a queue and launches build tasks

Polls the queue for build messages

Message is deleted after a task is initiated 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

Simple Storage Service (S3)

Website bucket for hosting generated static website files

Creating new buckets

The following guide is intended for use with the new, 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

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.