Skip to content

Getting started

Run it locally

Start CirCI with Docker Compose in a few minutes.

This starts the whole stack on one machine: the app (server, worker and dashboard in one process) and Postgres, with files on a Docker volume. It's also the starting point of a production install: see Docker Compose for what to change.

You need Docker with Compose v2, and a clone of the CirCI repository (the image is built from it).

  1. Create your settings file. Copy the example in the deploy folder.

    Terminal window
    cd deploy
    cp .env.example .env
  2. Edit .env. Two values are required: POSTGRES_PASSWORD, and BETTER_AUTH_SECRET, which signs sessions and must be 32 characters or more.

    openssl rand -base64 32

    PUBLIC_URL defaults to http://localhost:3000, which is right for a local try-out.

  3. Build and start.

    Terminal window
    docker compose up -d --build

    The first build compiles the server, the dashboard and the native diff engine, and takes a few minutes. Later builds use the layer cache.

  4. Open http://localhost:3000. A fresh install shows a Set up CirCI page. It asks for a setup code. Find it in the server log, or print it:

    Terminal window
    docker compose logs circi
    docker compose exec circi circi admin setup-code

Next: Sign in and set up.

Terminal window
curl http://localhost:3000/healthz # liveness: the process serves
curl http://localhost:3000/readyz # readiness: Postgres and storage answer

If readyz fails, docker compose exec circi circi admin doctor names the check that did.

Terminal window
docker compose logs -f circi # follow the server log
docker compose exec circi circi admin doctor # check storage, database, mail and the domains
docker compose down # stop (data stays in the volumes)
docker compose down -v # stop and delete the data

To try CirCI with S3-compatible storage locally, add the MinIO overlay: docker compose -f docker-compose.yml -f docker-compose.s3.yml up -d --build. See Storage.