Requirements

The serverCopy Anchor Link

• Linux with Docker Engine and the Docker Compose plugin. Tested with Docker Engine 29.9.2 and Compose 5.6.1. Check with docker version and docker compose version.
• A checkout of this repository. docker-compose.yml builds the API image from backend/ and mounts the ClickHouse configuration from backend/docker/clickhouse/. No release images are published yet (Upgrades). The other images are pulled, Postgres's from ghcr.io.
• bash and openssl for backend/scripts/setup.sh, which writes the env file with generated secrets, or the Doppler CLI to keep the secrets in Doppler instead; git to update.
• No inbound port. The server only connects out (below).
• One API container. Its event spool lives in a volume that two processes must never share, so never scale it with --scale api=2.

Some sandboxed or rootless Docker setups cap the open files of containers below 262 144, and ClickHouse then cannot start ("error setting rlimit type 7"). Lower ulimits.nofile for clickhouse in a docker-compose.override.yml next to docker-compose.yml (Compose reads it together with the main file), never in docker-compose.yml itself.

MemoryCopy Anchor Link

The default memory limits suit a server with 8 GB of RAM or more: 3 GB for the API container and 2 GB for ClickHouse, while Postgres, its backup service, Valkey and cloudflared have no limit (a few hundred MB together at small scale). A container that reaches its limit is killed and restarted by Docker; for the API that loses the events still in memory (normally the last second) and every request in flight. Docker allows limits that add up to more than the RAM, and the host's own out-of-memory killer then picks a victim.

The API's largest consumer is session replay: decoding recordings uses up to 4 worker threads of about 560 MiB each. Replay only runs with R2 configured and replay turned on for a site. Profiles for smaller servers, set in .env (the repository marks them provisional until a target server is known):

ClickHouse caps itself at 0.8 times its container limit, and each dashboard query or export at CLICKHOUSE_QUERY_MAX_MEMORY (1 GiB by default); keep the second well under the first, hence 512 MiB with a 1 GB limit. Never put --max-old-space-size in API_NODE_OPTIONS: size the API with API_MEM_LIMIT. Valkey has no memory cap on purpose (every key expires); watch it with docker compose exec valkey valkey-cli info memory.

DiskCopy Anchor Link

Plan disk for the data, which grows with your traffic: events in ClickHouse, accounts and settings in Postgres, both on the server. Restores and restore drills need free disk about the size of the data, because the restored copy sits next to the live one until it is swapped in or dropped, and a restore also downloads the Postgres dump to the API's volume. With R2 set, Postgres also keeps its write-ahead log until it is in R2: about 1 GB normally, and at most 4 GiB more while R2 cannot be reached (PGBACKREST_ARCHIVE_PUSH_QUEUE_MAX; lower it on a small disk). Container logs rotate at 10 MB × 5 files per service.

PostgresCopy Anchor Link

Nothing to set up: docker-compose.yml runs PostgreSQL 17 itself, the postgres service, from the image ghcr.io/saiakashneela/postgres-ssl-pgbackrest:pg17 (Postgres 17 with TLS and pgBackRest). On its first start it creates the database app with the user app in the volume postgres-data, with the password POSTGRES_PASSWORD from your secrets, and the API migrates it.

With R2 set, Postgres also backs itself up continuously to your bucket (Backups and restore).

CloudflareCopy Anchor Link

• A Cloudflare account with your domain on Cloudflare DNS. The web app and the public site are a Worker on the route <your domain>/*, three routes without a Worker send /api/*, /.well-known/* and /maps/* to the tunnel, and the tunnel's published application is the API. See Cloudflare.
• A plan for the Worker's requests. Static files are free and unlimited; the Worker script runs only for the first load of an app URL, unknown paths and redirects. The Workers Free plan allows 100 000 of those a day; Workers Paid has no daily cap (and is needed for Cloudflare Email Sending to arbitrary recipients).
• Request bodies above the plan's limit (100 MB on Free and Pro) never reach the server, so an import file larger than that cannot be uploaded.

NetworkCopy Anchor Link

Inbound: nothing. Outbound, the server needs to reach:

Accounts and servicesCopy Anchor Link

Cloudflare is required. Each other service turns on features; without it the instance still runs.

The R2 token needs Object Read & Write on the bucket, and Admin Read & Write as well if backups should maintain their retention rule. Every setting is described in the configuration reference.