Skip to content
Cawdit

Self-host with Docker

cawdit serve reviews pull requests on webhooks, for every repository you allow, without a CI step in each one. This guide runs it with Docker Compose next to a Postgres database.

Before you start

  • Docker with the Compose plugin.
  • A bot account and its token, from Set up the forge.
  • A model provider and its key, from Configure a model provider.
  • A public HTTPS address for Cawdit that your forge can reach, such as https://cawdit.example.com, served by a reverse proxy.

Choose an image

The images are published to codefloe.com/cawdit/cawdit and, with the same tags, to docker.io/cawdit/cawdit.

Tag What it is
1.2.3, 1.2, 1, latest A stable release, and the newest release of its minor version, major version, and overall.
0.1.0-rc.1 A release candidate. latest never points to one.
main The newest build of the default branch.
sha-<commit> The build of one commit, by its first seven characters.

Use a release tag in production, so an upgrade happens only when you change it. The image runs as the non-root user 65532, and the cawdit binary is the only program in it.

Each image is signed with cosign. Verify it with the public key cosign.pub from the repository root:

cosign verify --key cosign.pub codefloe.com/cawdit/cawdit:latest

Write the configuration

Create a directory with three files. cawdit.toml is the deployment configuration, and its secrets point to environment variables:

public_url = "https://cawdit.example.com"

[database]
url = "env:DATABASE_URL"

[forges.codefloe]
url = "https://codefloe.com"
token = "env:FORGE_TOKEN"
webhook_secret = "env:WEBHOOK_SECRET"
allowed_owners = ["my-org"]

[providers.anthropic]
kind = "anthropic"
api_key = "env:ANTHROPIC_API_KEY"
models = { review = "claude-opus-5-5", verify = "claude-sonnet-5-5" }

.env contains the secrets, and only you may read it:

POSTGRES_PASSWORD=change-me
FORGE_TOKEN=the-bot-token
WEBHOOK_SECRET=the-webhook-secret
ANTHROPIC_API_KEY=the-api-key

compose.yaml runs Postgres and Cawdit:

services:
  db:
    image: docker.io/library/postgres:18-alpine
    environment:
      POSTGRES_USER: cawdit
      POSTGRES_DB: cawdit
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
    volumes:
      - db:/var/lib/postgresql
    healthcheck:
      test: ["CMD", "pg_isready", "-U", "cawdit"]
      interval: 5s
    restart: unless-stopped

  cawdit:
    image: codefloe.com/cawdit/cawdit:latest
    command: ["serve", "--migrate"]
    environment:
      CAWDIT_CONFIG: /etc/cawdit/cawdit.toml
      DATABASE_URL: postgres://cawdit:${POSTGRES_PASSWORD}@db:5432/cawdit?sslmode=disable
      FORGE_TOKEN: ${FORGE_TOKEN}
      WEBHOOK_SECRET: ${WEBHOOK_SECRET}
      ANTHROPIC_API_KEY: ${ANTHROPIC_API_KEY}
    volumes:
      - ./cawdit.toml:/etc/cawdit/cawdit.toml:ro
    ports:
      - "127.0.0.1:8080:8080"
    depends_on:
      db:
        condition: service_healthy
    restart: unless-stopped

volumes:
  db:

--migrate applies the database migrations on every start, so a new version updates the schema itself. A migration that ran already is skipped.

Start it

docker compose up -d
docker compose logs -f cawdit
curl -fsS http://127.0.0.1:8080/readyz

/readyz answers 200 once the database schema is current and the workers run. When Cawdit exits at once, its log names every configuration key that has a problem. docker compose run --rm cawdit serve --print-config prints the configuration it loaded, with the secrets as their references.

Put it behind HTTPS

Cawdit serves plain HTTP on port 8080. Point your reverse proxy at 127.0.0.1:8080 and serve it on the address in public_url. Keep /metrics internal, such as by answering 404 for it at the proxy.

Add the webhook

Connect the organisation or the repository in the dashboard’s settings, as Set up the forge describes, and Cawdit keeps its webhook with the URL https://cawdit.example.com/webhooks/codefloe in sync. Without the dashboard, add the webhook by hand. The last segment is the forge’s name in cawdit.toml.

Open a pull request in an allowed repository. Cawdit’s log shows webhook handled and review queued, and the review appears on the pull request a little later.

Keep secrets in files

Docker secrets, or any other mounted file, work with file: references instead of env::

[forges.codefloe]
token = "file:/run/secrets/forge_token"

Cawdit reads the file at start and drops one trailing line break.

Upgrade

  1. Read the release notes for changes to the configuration.
  2. Change the image tag in compose.yaml.
  3. Run docker compose up -d.

On SIGTERM, Cawdit stops taking new reviews and waits up to five minutes for the running ones, as --drain-timeout sets. Give the container that long to stop, with stop_grace_period: 5m on the cawdit service. A review that it had to cancel runs again after the start.