Operations

Upgrade

docker compose pull
docker compose up -d

Migrations run when the api starts. Releases and their notes: github.com/innovafour/iforevents-selfhosted/releases. Every release is installed from scratch by CI (scripts/smoke.sh) before it is published, so latest always points at an install that came up clean.

Pin a version in .env (IFOREVENTS_VERSION=1.2.0) for production and move it on purpose.

Back up

The state worth keeping is the ClickHouse database and the api_data volume (the generated session secret):

docker compose exec clickhouse clickhouse-client \
  --query "BACKUP DATABASE iforevents TO Disk('backups', 'iforevents-$(date +%F).zip')"
docker run --rm -v iforevents_api_data:/data -v "$PWD/backups":/out alpine \
  tar czf /out/api_data.tgz -C /data .

Both land in ./backups next to the compose file (the backups disk is configured in clickhouse/iforevents.xml). Copy that directory off the host on a schedule.

Restore into an empty install:

docker compose up -d clickhouse
docker compose exec clickhouse clickhouse-client \
  --query "RESTORE DATABASE iforevents FROM Disk('backups', 'iforevents-<date>.zip')"
docker run --rm -v iforevents_api_data:/data -v "$PWD/backups":/in alpine \
  tar xzf /in/api_data.tgz -C /data
docker compose up -d

Redis holds caches only; it rebuilds itself.

Monitoring

• GET /ready on the api reports ClickHouse, the one dependency it cannot serve without; GET /health is the liveness probe.
• GET /metrics on the api is a Prometheus endpoint (ingest counts, buffer flushes, queue lag, dependency probes). It is on port 8000 next to the ingest routes; keep it off the internet with the reverse proxy or scrape it from inside the Docker network.
• docker compose logs -f api is JSON, one line per request.

Watch disk on the ClickHouse volume and the ingest lag metric (iforevents_ingest_lag_seconds).

Recovery

Uninstall

docker compose down -v

Removes containers, network and every volume. Without -v the data stays for the next up.