Skip to content

Install

Requirements

What you need to run CirCI, and how big a machine.

Before you start, have:

  • A Linux host (or any machine) with Docker and Compose v2.
  • A hostname for the dashboard, such as ci.acme.io, with TLS.
  • Optionally a second domain used for nothing else, for hosted sites.
  • Optionally an SMTP server, for sign-in codes and invitations.
Part What it's
The app One image (circi) that runs the HTTP server, the dashboard and the background worker. circi all runs them in one process; circi serve and circi worker run them separately.
Postgres The only database. The compose file uses postgres:18-alpine. The worker's job queue lives in it.
File storage Screenshots, diffs, thumbnails and hosted sites: local disk (a Docker volume) or any S3-compatible bucket.
A reverse proxy Optional for a try-out, needed for https. The repository ships a Caddy setup.
SMTP Optional. Needed for email sign-in codes, invitations and "new sign-in" mail.
  • A small install is one VM. Logins need https outside local development.
  • Hosted sites need their own separate domain, never one you serve anything else from.
  • Plan disk (local storage) or a bucket. Storage is usually the biggest cost: every screenshot, diff and thumbnail is an object, though unchanged screenshots are stored once.

From reading the code and the load tests (see Performance):

  • About 2 vCPU and 4 GB with a small Postgres serves dozens to a couple of hundred people browsing, and a few CI builds per minute. Browsing is cheap; image processing is the limit.
  • The worker runs two builds at a time by default. With the native diff engine a 12-core machine processed about 250 builds of 10 screenshots per minute in the load tests. A server with fewer cores gets less.
  • Worker memory peaks around 700 MB with the default engine in those tests (the js-workers engine used about 2 GB).
  • Keep the worker in the same process on a 1 to 2 vCPU box. Run a second worker only when the queue depth (Instance › Health) stays above zero.

The worker wakes on Postgres LISTEN/NOTIFY, so give it a direct connection or session pooling. A transaction pooler such as PgBouncer in transaction mode can't carry notifications, so the worker polls every second instead and builds start a little later. DATABASE_POOL_MAX (default 10) caps connections per process.

The image is built from the repository (docker compose up -d --build in deploy/) and includes a Rust build of the native diff engine for the image's own architecture. It runs one bundle plus sharp, pg and the AWS SDK, about 457 MB.

Next: Docker Compose.