Skip to main content
Apgar is a self hosted service. Every release ships a Docker Compose file that runs the whole stack on one host. The Quickstart covers the first start. To run Apgar on Kubernetes, see Kubernetes.

​
Services

apgar-migrate runs before the API and the worker, which wait for it to finish. Everything users and exporters need goes through apgar-ui on port 8080.

​
Versions

Every GitHub release attaches a docker-compose.yml that pins the images of that release. The file of the latest release is at https://github.com/oimo-ai/apgar/releases/latest/download/docker-compose.yml, and the file of a given release at https://github.com/oimo-ai/apgar/releases/download/vX.Y.Z/docker-compose.yml.

​
Customize

Put changes in docker-compose.override.yml next to the Compose file, and variables in .env. Compose reads both, and an upgrade replaces only docker-compose.yml. Monitoring shows an example.

​
Before production

  • Set APGAR_PUBLIC_URL to the address people and exporters use, for example https://apgar.example.com. Message links and the exporter snippet use it.
  • Terminate TLS in a reverse proxy in front of apgar-ui, and have the proxy send X-Forwarded-Proto: https so the session cookie is marked Secure. Or set APGAR_COOKIE_SECURE=true.
  • Have the proxy send X-Forwarded-For too, and add APGAR_TRUSTED_PROXY_HOPS=2 to .env. The login rate limit then counts each client’s address. With the default of 1, every sign in counts against the proxy’s address, and the API logs a warning that a proxy is not counted.
  • Keep ClickHouse and the API unpublished, as the released file does. A client that reaches port 8000 directly can choose the X-Forwarded-For address the login rate limit counts.
  • Keep APGAR_SECRET_KEY in a secret store. Losing it makes stored connection secrets unreadable. See Data handling.

​
One worker

Run exactly one worker. A second worker that sees a heartbeat younger than 30 seconds exits with code 1. A heartbeat older than 30 seconds is ignored, so a crashed worker can be replaced after that interval. Do not raise deploy.replicas above 1.

​
Upgrade

Migrations run forward only. Read the release notes of every version between yours and the new one, and take a backup. Then, in the directory that holds the Compose file:
apgar-migrate applies the new migrations before the API and the worker start. The API and the worker exit with code 3 when the schema version does not match, so new code never runs on an old schema. To go back, restore the backup and start the Compose file of the version that wrote it.

​
Backups

All durable state lives in the clickhouse-data volume, which Docker names apgar_clickhouse-data. To take a backup, stop the stack, archive the volume, and start the stack again:
Or use ClickHouse BACKUP to a location you control. Restoring the volume while the stack is down, then starting the same version of Apgar, is a full restore.

​
Resources

ClickHouse holds every span, turn, and tool call, so its disk grows with trace volume and with retention. Plan disk before raising retention. The Compose file sets no memory limit; set one in docker-compose.override.yml.