Skip to content

Install

Site domains

The sites domain, custom domains and the cookie rules you must check.

Hosted sites (a built Storybook, a test report, coverage) are optional and off until you set the sites domain and switch on Host static sites in a project's settings. How people use them is described in Hosted sites. This page is for the operator.

STATIC_SITES_HOSTdomain

A separate, dedicated domain for hosted sites, such as acme-sites.com. Hosting is off until it's set. Instance settings shows it read-only, or "Not set up" with a Check domain rules link to Health. To change it, edit the variable and restart.

STATIC_SITES_MAX_MBMBDefault 200

The largest site upload (1 to 5000). Also Largest hosted site in Instance settings: the variable, when set, wins and locks it; otherwise the saved value applies.

In the browser's developer tools (Application, Cookies) look at the dashboard host's parent domain and www, or:

Terminal window
curl -sI https://acme.io | grep -i 'set-cookie.*domain='
curl -sI https://www.acme.io | grep -i 'set-cookie.*domain='

circi admin doctor does a best-effort version. It can't see every host, so it repeats this warning.

CirCI
Instance settings, Hosted sites section: Not set up, with the note that projects can't host sites until a separate domain is configured.
Without STATIC_SITES_HOST the section says Not set up.

Every upload belongs to a commit and gets two addresses on the sites domain:

Address Serves
Commit <first 12 hex of the SHA>-<site>.acme-sites.com that commit's site, exactly
Branch <12 hex of sha256(branch)>-<site>.acme-sites.com the newest upload on that branch

Every request to a site needs sign-in. Opening a site address sends you to the dashboard, which hands the site a one-minute, single-use token if you belong to the project's workspace. The site then sets its own host-only HttpOnly cookie (__Host- over https), so the site's code never sees your dashboard cookie. An address that doesn't exist, has expired or isn't yours gets the same answer:

How a hosted site checks who is askingThe browser opens a site address. The site sends it to the dashboard. If you belong to the project's workspace, the dashboard hands back a one-minute single-use token. The site then sets its own host-only HttpOnly cookie, and re-checks it against your dashboard session at least once a minute.Site addressa1b2c3-storybook.sitesDashboardyou belong tothe workspace?Site cookiehost-only, HttpOnly1 min token

The site re-checks its cookie against your dashboard session at least once a minute, so signing out or leaving the workspace ends access within a minute. A custom domain signs in the same way, with the domain itself as the address.

  • A and AAAA for the dashboard host in its own zone.
  • A new hosted zone for the sites domain with * A and AAAA pointing at the server (leave the apex empty).
  • Certificates: the dashboard host by HTTP-01, and *.acme-sites.com by DNS-01 (needed for wildcards). The bundled Caddy covers both.

A minimal IAM policy for Caddy, on the sites hosted zone only:

{
"Version": "2012-10-17",
"Statement": [
{ "Effect": "Allow", "Action": ["route53:ListHostedZonesByName", "route53:GetChange"], "Resource": "*" },
{
"Effect": "Allow",
"Action": ["route53:ChangeResourceRecordSets", "route53:ListResourceRecordSets"],
"Resource": "arn:aws:route53:::hostedzone/SITES_ZONE_ID"
}
]
}
resource "aws_route53_zone" "sites" { name = "acme-sites.com" }
resource "aws_route53_record" "sites_wildcard" {
zone_id = aws_route53_zone.sites.zone_id
name = "*.acme-sites.com"
type = "A"
ttl = 300
records = [var.server_ip]
}

A site can have one custom domain, such as storybook.acme.com, that always serves the project's default branch. Owners and admins set it in the project's Sites page.

  1. Enter the domain. It must be a plain host name. CirCI refuses the dashboard host, anything related to it by the cookie rules (so with the dashboard on ci.acme.io, storybook.acme.io is refused; use another registrable domain such as storybook.acme.com), the sites domain and everything under or above it, and a domain another site already holds.
  2. Add the DNS record it shows. Use a CNAME to custom.<sites domain>. A domain that can't be a CNAME (an apex) can use A and AAAA records with the server's addresses.
  3. Press Check DNS. The domain is served, and gets a certificate, only once a check has seen it point at this server. A later failing check un-verifies it.

Certificates for custom domains come from Caddy's on-demand TLS. The first time a domain is requested, Caddy asks GET /internal/tls-ask?domain=<host>, which answers 200 for a verified custom domain and 404 for everything else. The endpoint refuses questions that came through a proxy (they carry X-Forwarded-For) and answers at most 300 a minute: keep it on the internal network and never publish it.

STATIC_SITES_MAX_MB (default 200) is the largest site. An expired address answers 410 Site expired to people who may open the site. Not supported yet: a live view of the site inside the build page, per-file S3 upload, branch expiry and garbage collection of old versions.