Install
TLS and reverse proxy
Caddy with automatic certificates, or your own proxy.
CirCI speaks plain HTTP on port 3000. Put a TLS proxy in front of it: sign-in needs https, and over https the session cookie is locked to the exact host (its name starts with __Host-).
-
Set the hosts. Edit
.env:Terminal window DASHBOARD_HOST=ci.acme.ioSITES_HOST=acme-sites.com # only if you host sites -
Start the overlay. Give Caddy AWS credentials for Route53 (see below) first:
Terminal window docker compose -f docker-compose.yml -f docker-compose.caddy.yml up -d --build
The overlay adds a caddy service (ports 80, 443 and 443/udp, a caddy-data volume for certificates), and sets PUBLIC_URL=https://$DASHBOARD_HOST, STATIC_SITES_HOST=$SITES_HOST and TRUSTED_PROXIES=172.16.0.0/12,192.168.0.0/16 on the app (Caddy reaches it over the Compose network).
Caddy needs AWS credentials for Route53 to get the wildcard certificate of the sites domain (DNS-01): an instance role works without variables, otherwise set AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY (and AWS_REGION, default us-east-1).
Proxy to circi:3000 (or the published port) and keep the Host header. Then tell CirCI to trust the client address the proxy passes in X-Forwarded-For:
TRUSTED_PROXIESThe proxy's address, or a range such as 172.16.0.0/12. By default no proxy is trusted and CirCI uses the address the connection came from, so behind a proxy without this setting every user appears to come from the proxy's address and shares one rate limit. true trusts every proxy in the chain and is only safe when the app can't be reached except through the proxy.
If you host sites, the proxy must pass every host on the sites domain, and any verified custom domain, to CirCI with the Host header unchanged, and must never expose /internal/*.
What the Caddyfile does
Section titled “What the Caddyfile does”DASHBOARD_HOST: reverse proxy tocirci:3000, with a certificate by HTTP-01.*.SITES_HOST: one wildcard certificate by DNS-01 with Route53, reverse proxy to CirCI (Caddy keeps theHostheader, which is how CirCI tells a site from the dashboard). Sites can set many cookies, so Caddy waits up to 60 seconds for a site's response headers.- The bare
SITES_HOSTanswers 404. - A catch-all
https://site with on-demand TLS serves custom domains: before issuing a certificate Caddy asks CirCI athttp://circi:3000/internal/tls-ask, which answers200only for a domain a project has verified. /internal/*answers 404 from outside on every site.
To use another DNS provider than Route53, swap the caddy-dns/route53 module in deploy/caddy/Dockerfile and the dns line in the Caddyfile.
Live updates need an unbuffered stream
Section titled “Live updates need an unbuffered stream”The dashboard keeps one GET /api/live request open for live updates: a text/event-stream response that is quiet between events and carries a heartbeat every 25 seconds. CirCI sends Cache-Control: no-cache, no-transform and X-Accel-Buffering: no with it. The proxy must pass it through as it arrives, and its read timeout must be longer than 25 seconds.
-
Bundled Caddy needs no setting; the Caddyfile is unchanged.
-
nginx honors
X-Accel-Buffering: noby default. If your configuration ignores or strips that header, turn buffering off for the path:location /api/live {proxy_pass http://circi:3000;proxy_buffering off;proxy_read_timeout 1h;} -
Other proxies and load balancers: disable response buffering for
text/event-streamand keep idle timeouts above 25 seconds.
If the stream is held back, events arrive late or in a burst, so pages show changes late.
Moving the dashboard to another address
Section titled “Moving the dashboard to another address”-
Set the new address. Set
PUBLIC_URL, and put the old one inPREVIOUS_PUBLIC_URLSso old links redirect. Both are read-only in Instance settings: they name their variables, and you change them there and restart. -
Keep the old address working. Keep DNS and TLS for the old address pointing at CirCI.
-
Follow the checklist. Open Instance › Health. The admin sees a "Moving to …" checklist: people sign in again once (cookies belong to one host), OpenID Connect (OIDC) redirect URIs must be changed to the new address, and a GitHub App's OAuth callback URL has to be updated by hand (its webhook URL is updated automatically).