Deploying Open Analytics with Neon

Neon is the managed Postgres we recommend for a self-hosted Open Analytics, and the one the hosted service at getopen.so runs its own control plane on. This guide moves Postgres only off your host: ClickHouse and the two Valkeys stay where they are, in the same docker compose stack.

It is a change of four environment variables and one line in .env. It assumes the normal install in SELF-HOSTING.md; read that first. Everything here is a difference from it.

• What you gain.Postgres backups and point-in-time restore become Neon's job, and one of the two stateful volumes on your server disappears.
• What does not change. ClickHouse (the events) is still on your disk and still yours to back up, and upgrading Open Analytics is still ./upgrade.sh.

Backups

The pg_dumpline in SELF-HOSTING.md's Backups section talks to the local container and does not apply. Neon keeps your database's history, and restoring to a point in time is a console action on the branch. For a copy that is also off Neon, pg_dump works from any machine, but only one whose major version is at least the server's. An older one refuses outright (aborting because of server version mismatch), and the one inside the bundled postgres image is 17. Running it from the image that matches your Neon database avoids the question:

$ docker run --rm postgres:18-alpine pg_dump "$NEON_URL" | gzip > oa-pg-$(date +%F).sql.gz

(18 for a Postgres 18 project; SELECT version()in Neon's SQL editor says which you have.)

ClickHouse still needs the backup SELF-HOSTING.md describes; nothing about it changed.

Upgrades

./upgrade.sh works as documented (v0.7.0 → v0.8.0 was run on Neon this way). Its snapshot holds ClickHouse and the configuration only, because Postgres is not on this host to copy, and it prints the instant the stack stopped:

snapshot: Postgres is not part of this stack — it is NOT in this snapshot
          nothing writes to it from now until the stack starts again;
          to go back, restore your provider's Postgres to 2026-09-25T18:40:12Z

Nothing writes to Postgres between that instant and the upgraded stack starting, so that timestamp is the matching point for Postgres. ./rollback.sh restores ClickHouse and the configuration, then stops with the stack downand tells you to restore the Neon branch to that timestamp before starting it. Starting earlier would run the old images against the new schema. Your Neon plan's restore window has to reach back that far; if you are unsure it will, create a branch in the console just before upgrading.

Expect the compute to stay active

The worker queries Postgres continuously (the job queue, the outbox, its heartbeat), so an Open Analytics database is rarely idle long enough to scale to zero. Size your Neon plan for a compute that runs all the time.

Coolify and Dokploy

This guide is written for the Docker Compose install. The platform compose files spell the Postgres URL inline rather than in env/*.env, so the same four variables have to change in the platform's editor, and the postgres service has to be removed there. We have not walked that path end to end yet.

If you already run Open Analytics with the bundled Postgres, copy the data across, then follow steps 4–6. The stack is down for as long as the copy takes; for a control-plane database that is usually seconds to a few minutes.

cd infra/selfhost
docker compose stop api collector worker realtime gateway web

# Dumped by the local server's own pg_dump and restored with its psql, in one
# pipe. A dump restores into the same or a newer major version, so this works
# into Neon's Postgres 17 or 18 alike.
docker compose exec -T postgres pg_dump -U openanalytics --no-owner --no-privileges openanalytics \
  | docker compose exec -T postgres psql "$NEON_URL" -v ON_ERROR_STOP=1 -q

--no-owner --no-privileges because the objects are owned by openanalytics locally and by neondb_owner on Neon. ON_ERROR_STOP so that a failure stops the copy instead of leaving a half-restored database that looks complete. The one set_configrow it prints is the dump's own preamble, not an error.

Then stop the local Postgres, so nothing can write to the copy you are leaving:

$ docker compose stop postgres

Then steps 4 and 5, and docker compose up -d. The migrate container finds every migration already applied and changes nothing ("applied":0 … "already_applied":46).

Keep the old pg-data volume until you have signed in and seen your sites. It is outside the stack from then on, so docker compose down -v does not remove it either; docker volume rm openanalytics_pg-data does, and is the one step here that cannot be undone.