Upgrades & backups

In plain terms: How to back up your Postgres database before upgrades and safely apply new Eigen Mesh releases on a self-hosted deployment.

Who this is for

Operators running self-hosted Docker deployments in production
Contributors planning maintenance windows for key rotation

Backups

Eigen Mesh stores all durable state in PostgreSQL (relational data, pgvector embeddings, Apache AGE graph). Back up the database volume before upgrades or key rotation.

Docker Compose

# Stop writes (optional, for consistent snapshot)
docker compose stop app

# Dump from running db container
docker compose exec db pg_dump -U eigen -Fc eigen > eigen-backup-$(date +%Y%m%d).dump

docker compose start app

Restore:

docker compose exec -T db pg_restore -U eigen -d eigen --clean --if-exists < eigen-backup-YYYYMMDD.dump

What to back up

Asset	Location
Database	Postgres volume (`pgdata` in compose)
Secrets	`.env` or hosting dashboard (store securely offline)
Custom compose overrides	Your fork or deployment notes

Upgrading

Back up the database (above).
Pull the latest eigen repository release or commit.
Review release notes for breaking env var or migration changes.
Rebuild and restart:
```
docker compose up -d --build
```

Apply schema if release includes migrations:

docker compose exec app npx drizzle-kit push --force
docker compose exec app node scripts/apply-rls.mjs

Verify /api/health and a test capture.

Environment variable changes

Change	Risk	Procedure
`ORIGIN` domain change	OAuth callbacks break	Update OAuth app callback URLs; redeploy
`TENANT_MASTER_KEY` rotation	Decrypt failures	Re-encryption migration — Tenant envelope encryption
LLM gateway switch	Capture/search failures until keys valid	Update vars; test capture before announcing
`POSTGRES_PASSWORD` change	App can't connect	Update `DATABASE_URL`, `DATABASE_ADMIN_URL`, and Postgres role passwords together

Consolidation cron

After upgrades, confirm pg_cron schedule still points to CONSOLIDATION_INTERNAL_URL. If the app container name or network changed, update env and re-run cron bootstrap from the eigen repo.