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.
What CirCI is made of
Section titled “What CirCI is made of”| 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. |
Notes on the list
Section titled “Notes on the list”- 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.
Sizing
Section titled “Sizing”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-workersengine 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.
Database connection
Section titled “Database connection”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
Section titled “The image”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.