Skip to content

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-).

The proxy in front of CirCIBrowsers and CI reach the proxy over https. The proxy forwards to CirCI on port 3000 with the Host header unchanged and X-Forwarded-For set. CirCI talks to Postgres and storage. The proxy asks CirCI's internal tls-ask endpoint before it issues a certificate for a custom domain, and never exposes it.Browsers, CIhttpsTLS proxyCaddy or your ownCirCI :3000plain httpHost kept/internal/tls-askthe proxy asks, nobody else reaches it
  1. Set the hosts. Edit .env:

    Terminal window
    DASHBOARD_HOST=ci.acme.io
    SITES_HOST=acme-sites.com # only if you host sites
  2. 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).

  • DASHBOARD_HOST: reverse proxy to circi:3000, with a certificate by HTTP-01.
  • *.SITES_HOST: one wildcard certificate by DNS-01 with Route53, reverse proxy to CirCI (Caddy keeps the Host header, 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_HOST answers 404.
  • A catch-all https:// site with on-demand TLS serves custom domains: before issuing a certificate Caddy asks CirCI at http://circi:3000/internal/tls-ask, which answers 200 only 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.

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: no by 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-stream and keep idle timeouts above 25 seconds.

If the stream is held back, events arrive late or in a burst, so pages show changes late.

  1. Set the new address. Set PUBLIC_URL, and put the old one in PREVIOUS_PUBLIC_URLS so old links redirect. Both are read-only in Instance settings: they name their variables, and you change them there and restart.

  2. Keep the old address working. Keep DNS and TLS for the old address pointing at CirCI.

  3. 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).