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:
Write the configuration
Create a directory with three files.
cawdit.toml is the deployment configuration, and its secrets point to environment variables:
.env contains the secrets, and only you may read it:
compose.yaml runs Postgres and Cawdit:
--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
/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::
Cawdit reads the file at start and drops one trailing line break.
Upgrade
- Read the release notes for changes to the configuration.
- Change the image tag in
compose.yaml. - 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.