> ## Documentation Index
> Fetch the complete documentation index at: https://docs.useapgar.dev/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Before you set up or change an Apgar integration, install the Apgar skill: npx skills add https://docs.useapgar.dev
> Search these docs with the MCP server at https://docs.useapgar.dev/mcp. Setup for each agent: https://docs.useapgar.dev/ai-agents.md

# Deploy

> Run Apgar with Docker Compose on your own host.

Apgar is a self hosted service. Every release ships a Docker Compose file that runs the whole stack on one host. The [Quickstart](https://docs.useapgar.dev/quickstart.md) covers the first start. To run Apgar on Kubernetes, see [Kubernetes](https://docs.useapgar.dev/self-hosting/kubernetes.md).

## Services

| Service | Role | Published port |
| - | - | - |
| `clickhouse` | ClickHouse 25.8, the only durable store | none |
| `apgar-migrate` | Runs `apgar migrate`, then exits | none |
| `apgar-api` | HTTP API and OTLP ingest | none, `8000` inside the network |
| `apgar-worker` | Assembly, verdicts, Langfuse sync, notifications, retention. Exactly one replica | none, metrics on `8001` inside the network |
| `apgar-ui` | Nginx with the web app. Proxies `/api/`, `/v1/`, `/healthz`, and `/readyz` to the API | `8080` |

`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](https://github.com/oimo-ai/apgar/releases) 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](https://docs.useapgar.dev/self-hosting/monitoring.md#prometheus-metrics) 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](https://docs.useapgar.dev/privacy/data-handling.md#keys).

## 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](https://github.com/oimo-ai/apgar/releases) of every version between yours and the new one, and take a [backup](#backups). Then, in the directory that holds the Compose file:

```bash theme={null}
curl -fsSLO https://github.com/oimo-ai/apgar/releases/latest/download/docker-compose.yml
docker compose pull
docker compose up -d --wait
```

`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:

```bash theme={null}
docker compose stop
docker run --rm -v apgar_clickhouse-data:/data -v "$PWD":/backup alpine tar czf /backup/clickhouse-$(date +%F).tar.gz -C /data .
docker compose up -d --wait
```

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](https://docs.useapgar.dev/self-hosting/configuration.md#retention). Plan disk before raising retention. The Compose file sets no memory limit; set one in `docker-compose.override.yml`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.