Generally, site builds work in three stages: clone, build, and publish. Each stage is broken down into a number of PyInvoke tasks. First, the container checks out the site from GitHub. Then it builds the site with the specified build engine. Then it gzip compresses text files and sets cache control headers. Finally, it uploads the built site to S3, and also creates redirect objects for directories, such as
Each site build is configured using a number of environment variables, as described below:
AWS_ACCESS_KEY_ID: AWS access key for accessing the S3 bucket.
AWS_SECRET_ACCESS_KEY: AWS secret key for accessing the S3 bucket.
AWS_DEFAULT_REGION: AWS region.
BUCKET: S3 bucket to upload the built site.
GITHUB_TOKENGitHub auth token for cloning the repository.
CACHE_CONTROL: Value to set for the
Cache-Controlheader of all published files.
CONFIG: A yaml block of configuration to add to
_config.ymlbefore building. Currently only used in
GENERATOR: The static generator to use to build the site (
FEDERALIST_BUILDER_CALLBACK: The URL the container should use to let federalist-builder know that it has finished.
STATUS_CALLBACK: The URL the container should use to report the status of the completed build (ie, success or failure).
LOG_CALLBACK: The URL the container should use to post build logs periodically during the build.
OWNER: the GitHub account that owns the repository.
REPOSITORY: the repository name.
BRANCH: the branch being built.
SITE_PREFIX: the S3 bucket "path" that the site files will be published to. It should not have a trailing or prefix slash.
- for the live site:
- for the demo site:
- for branch previews:
- for the live site:
BASEURL: the base URL that will be used by the build engine to determine the path for site assets.
- for a live site with a custom URL, this will be empty.
- for anything else, it will be the same as
SITE_PREFIXbut with a
/at the beginning. ex:
SKIP_LOGGING: if true-like, skip posting logs and status callbacks. This is used when launching builds from local development instances of the Federalist web application, which cannot be reached from the cloud.gov-hosted build containers. By skipping posting logs and status callbacks, the builds will be able to finish without throwing errors due to unreachable callback endpoints.
Variables exposed during builds
The following environment variables are available during site builds and when running the
federalist npm script. They may be useful for customizing the display of certain information in the published site, for example, to display the current published branch name.
To make setting environment variables easier for local development,
create a new
.env file based on the
.env.sample and fill out the environment variables in it. Your
.env file should not be committed to the repository
because it will contain sensitive information. It is ignored by
cp .env.sample .env
GITHUB_TOKEN, create a new personal token for your GitHub account and use that.
Building and running
Build the development container using Docker Compose:
The main builder application is called
app within the Docker Compose environment.
You can run any commands within the
app container by prefixing them with
docker-compose run app <THE COMMAND>.
One of the easiest ways to run the container's code during development is to start
bash shell in the
docker-compose run app bash
After running the above command, you will be in a shell inside of the
app container. From there, you can easily run PyInvoke tasks or execute the test suite.
invoke --help # prints Invoke's usage invoke --list # lists all the available tasks invoke main # runs the full clone-build-publish pipeline pytest # run all the python tests
Deploying to cloud.gov
For detailed instructions on deploying this build container to cloud.gov, see https://federalist-docs.18f.gov/pages/how-federalist-works/cloud-gov-setup/.
This project is in the public domain within the United States, and copyright and related rights in the work worldwide are waived through the CC0 1.0 Universal public domain dedication.
All contributions to this project will be released under the CC0 dedication. By submitting a pull request, you are agreeing to comply with this waiver of copyright interest.