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.

Custom URLs

How Federalist custom URLs work

This is technical documentation about how custom domains work on Federalist. It is not required reading to use Federalist and only provided for background; instructions for our partners are here.

All Federalist deploys are rendered via S3 at a .com URL such as:

These web addresses are public and useful for testing, but the URLs are not useful and there’s no HTTPS. (You’ll also notice that images and CSS are not loading on the page. We’ll explain why below.)

Luckily, Federalist also proxies — that is, creates a forwarding address — for those S3 URLs at URLs such as:

The proxy adds some required headers and is much cleaner for sending preview links around.

When ready to go live at their own .gov URL, partners point DNS for at a CloudFront CDN service created by a broker. The Federalist team directs the CDN service to load from the proxy URL, and since the proxy is loading from S3, that completes a technical connection from the live URL to the S3 bucket contents.

Here’s a full example chain:

The URLs above have broken CSS and assets because published Federalist sites on their own URLs don’t publish to a “/site/18f” directory. The above links are showing HTML content that is published at The assets for this site are at addresses like - whereas to display properly on the proxy or S3 buckets the assets would need to be published at See the “/site/18f/” in the second link?

Technical steps to set up a new site

  1. The partner confirms the site is ready for an initial scan; the Federalist team scans the site and sends to GSA IT for initial approval.
  2. After initial scans, the partner confirms readiness for the site to go-live at a specific permanent URL (this URL process needs to happen within a few hours timespan when started).
  3. The Federalist team uses the CloudFront broker to begin set up for a distribution for a given URL.
    • We do this by accessing our org in and running the command cf create-service cdn-route cdn-route -c '{"domain": "", "origin": "", "path": "/site/<org>/<repo-name>"}'. Note that the path argument here does not have a trailing slash.
  4. After running the command above, the command cf service is used to retrieve the CloudFront URL to be used in DNS changes. We communicate that URL to whoever sets the DNS records.
  5. The partner sets DNS records with a CNAME to point the subdomain (e.g. to the CloudFront distribution URL (e.g.
    • It takes roughly 15-30 minutes for the CNAME to a URL to propagate and the broker to create an HTTPS certificate, which also must propagate. Once shows site content (perhaps without images or CSS) under the correct HTTPS certificate, the CloudFront delegation process is complete.
  6. The partner then modifies their site’s Federalist’s configuration with the custom URL to ensure assets and CSS are loaded at the custom URL. This is deliberate so that the site only loads at the correct URL, such as Please note that URLs must start with https://.
  7. The site is then served from the CloudFront broker with automatic HTTPS. Partners retain control of DNS.

Here’s a specific GitHub issue with instructions from a successful migration. Note that the HTTPS certifications are managed automatically by the broker using Let’s Encrypt, which means there is no cost for the HTTPS certificate to partners or 18F.