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_HOSTA 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_MBThe 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.
Check the rules
Section titled “Check the rules”In the browser's developer tools (Application, Cookies) look at the dashboard host's parent domain and www, or:
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.
Addresses
Section titled “Addresses”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:
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.
DNS and certificates with Route53
Section titled “DNS and certificates with Route53”AandAAAAfor the dashboard host in its own zone.- A new hosted zone for the sites domain with
*AandAAAApointing at the server (leave the apex empty). - Certificates: the dashboard host by HTTP-01, and
*.acme-sites.comby 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]}Custom domains
Section titled “Custom domains”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.
- 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.iois refused; use another registrable domain such asstorybook.acme.com), the sites domain and everything under or above it, and a domain another site already holds. - Add the DNS record it shows. Use a CNAME to
custom.<sites domain>. A domain that can't be a CNAME (an apex) can useAandAAAArecords with the server's addresses. - 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.
Limits
Section titled “Limits”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.