Skip to main content

How Federalist Works

Open source

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

Templates and Documentation

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 here: Diagram of Federalist architecture

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

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

Simple Queue Service (SQS)

Message queue for handling build requests

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

Elastic Container Service (ECS)

Runs docker container tasks on EC2s specified in the Cloud Formation template

After receiving a build message, initiate an ECS task

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 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 commnad. 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