Skip to main content

Forking Circus for Self-Hosting

Circus is designed to be forked and self-hosted. The reference guides use circus.sh domains and the circus-sh GitHub org as examples — running your own fork is mostly a matter of substituting your values in a handful of known places, then following the standard setup and deploy flow.

What to substitute​

Replace the reference identifiers with your own throughout:

  • GitHub org / repo — circus-sh → your org or username, circus → your repo name.
  • Domains — the staging/production app and n8n domains (staging.circus.sh, n8n-staging.circus.sh, demo.circus.sh, n8n-demo.circus.sh).
  • GHCR image paths — ghcr.io/circus-sh/circus-api and -frontend → ghcr.io/YOUR_ORG/YOUR_REPO-api / -frontend.

Where those values live​

The substitutions land in a small, specific set of files:

  • deploy/docker-compose.prod.yml — the image paths.
  • .github/workflows/build-docker-images.yml — the GHCR docker login and the ghcr.io/... image tags.
  • .github/workflows/deploy-staging.yml and deploy-production.yml — any ghcr.io/... references.
  • Server-side .env / n8n.env — your domains, CORS_ORIGIN, and freshly generated secrets (never reuse the examples).
  • DNS — four A-records pointing your domains at the server (see Provisioning a Circus Server).

Then make it yours​

Two more steps complete a fork:

  • Branding — rebrand the console via frontend/whitelabel.json; it's a single file plus your logo/favicon in frontend/public/.
  • Harden — a fork is a real deployment: run through Security Hardening once the first deploy is verified, and if you add plugin dependencies, consider the supply-chain protections described there.

Everything else — the platform, the plugin contract, the workflow model — is unchanged. A fork is the same Circus with your name, domains, registry, and (optionally) your own plugins on top.