Backup and recovery

What to back upCopy Anchor Link

1. Create a backupCopy Anchor Link

Bundled Docker Compose database:

umask 077
docker compose exec -T postgres pg_dump -U edgeweir -d edgeweir --format=custom > edgeweir.dump
docker compose exec -T postgres pg_restore --list < edgeweir.dump > edgeweir.dump.list

External PostgreSQL:

umask 077
pg_dump --format=custom --file=edgeweir.dump --dbname=edgeweir
pg_restore --list edgeweir.dump > edgeweir.dump.list

Verify:

grep -c 'TABLE DATA' edgeweir.dump.list

Expected: greater than 0.

With deploy.sh, ./deploy.sh backup (also run before update) writes an edgeweir.dump of the same format together with .env (without the master key and BETTER_AUTH_SECRET) and the Compose file, keeping the newest 5; see deploy.sh reference. Keep the master key offline separately.

2. RestoreCopy Anchor Link

Verify in an isolated environment first. The restore environment requires:

deploy.shCopy Anchor Link

In the deployment directory of a deploy.sh deployment:

./deploy.sh restore backups/20261001-080000

The command backs up the current database, stops the console, drops and recreates the database, imports the backup's edgeweir.dump, then starts and waits for the health checks. .env is left alone and must hold the master key from the table above. Preconditions and failure behavior: deploy.sh reference.

Docker ComposeCopy Anchor Link

On a new host or in a new Compose project:

1. Place compose.yml, the original .env, and edgeweir.dump.

2. Start an empty database:

   Copy Text

   docker compose up -d --wait postgres

3. Import:

   Copy Text

   docker compose exec -T postgres pg_restore -U edgeweir -d edgeweir --exit-on-error < edgeweir.dump

4. Start the console:

   Copy Text

   docker compose up -d

5. Verify: curl -s http://127.0.0.1:3000/healthz returns "status":"ok".

External PostgreSQLCopy Anchor Link

1. Restore into a new database:

   Copy Text

   createdb edgeweir_restored
   pg_restore --exit-on-error --dbname=edgeweir_restored edgeweir.dump

2. Point the console's DATABASE_URL at edgeweir_restored, configure it as in the table above, and start it.

3. Verify: curl -s http://127.0.0.1:3000/healthz returns "status":"ok".

3. Resynchronize nodesCopy Anchor Link

1. With the CA restored from the database, enrolled nodes reconnect over mTLS. Wait until every node reports a new heartbeat after the restore; heartbeats from before the restore do not count.
2. Publish a configuration (any site or cluster configuration change).

Revision numbering:

Upgrade older nodes and let them complete one configuration sync before the backup; keep config/receipts.json in the node state backup.

4. Restore acceptanceCopy Anchor Link

After acceptance, keep the old database and handle it under the backup retention policy.

ClickHouseCopy Anchor Link

• Restore ClickHouse from the same point as PostgreSQL, or start writing to a new ClickHouse database (EDGEWEIR_CLICKHOUSE_DATABASE).
• Restoring older PostgreSQL cursors while reusing newer ClickHouse tables can collide with existing batch sequence numbers.
• Cross-store restore is not automatic; a successful PostgreSQL restore does not restore ClickHouse.

DrillCopy Anchor Link

node scripts/e2e-restore.mjs