Production Deployment

This page describes the recommended shape for running Open Spanner outside a local demo.

Recommended Topology

Run Open Spanner as separate processes against the same Postgres database:

SQLite is useful for demos and small single-node installs. Use Postgres when you need normal production operations such as backups, connection pooling, multiple API instances, multiple workers, or managed database observability.

Container Image

Release images are published to Docker Hub:

docker pull ssubedir/open-spanner:latest

Use latest for a quick trial. Pin a version tag for production:

docker pull ssubedir/open-spanner:0.1.8

The image contains the API binary and both worker binaries:

/usr/local/bin/open-spanner
/usr/local/bin/open-spanner-export-worker
/usr/local/bin/open-spanner-alert-worker

API Process

Point the API at Postgres and publish HTTP plus gRPC only where your backend services need access:

docker run --detach \
  --name open-spanner \
  --publish 18081:18081 \
  --publish 18090:18090 \
  --env OPEN_SPANNER_DB_DRIVER=postgres \
  --env OPEN_SPANNER_POSTGRES_DSN="postgres://open_spanner:change-me@postgres.example.com:5432/open_spanner?sslmode=require" \
  --env OPEN_SPANNER_EXPORT_STORAGE_PATH=/data/exports \
  --volume open-spanner-exports:/data/exports \
  ssubedir/open-spanner:0.1.8

The API runs database migrations on startup. Back up Postgres before upgrading across releases, especially while Open Spanner is pre-1.0.

Worker Processes

Run workers from the same image. Workers must use the same database as the API.

docker run --detach \
  --name open-spanner-export-worker \
  --env OPEN_SPANNER_DB_DRIVER=postgres \
  --env OPEN_SPANNER_POSTGRES_DSN="postgres://open_spanner:change-me@postgres.example.com:5432/open_spanner?sslmode=require" \
  --env OPEN_SPANNER_EXPORT_STORAGE_PATH=/data/exports \
  --volume open-spanner-exports:/data/exports \
  --entrypoint /usr/local/bin/open-spanner-export-worker \
  ssubedir/open-spanner:0.1.8

docker run --detach \
  --name open-spanner-alert-worker \
  --env OPEN_SPANNER_DB_DRIVER=postgres \
  --env OPEN_SPANNER_POSTGRES_DSN="postgres://open_spanner:change-me@postgres.example.com:5432/open_spanner?sslmode=require" \
  --entrypoint /usr/local/bin/open-spanner-alert-worker \
  ssubedir/open-spanner:0.1.8

Queued exports need shared artifact storage. In a single-host Docker setup, a shared Docker volume is enough. In a multi-host deployment, the API and export workers need the same mounted filesystem path, or exports should stay co-located until external artifact storage is added.

With Postgres, multiple export workers and alert workers can run at the same time. Jobs are claimed through database locks so replicas can share the queue.

Network And TLS

Keep Postgres private to the deployment network. Expose:

• HTTP for dashboard, REST, Swagger UI, health checks, and readiness checks.
• gRPC only to trusted backend services that use stream ingestion.

Open Spanner does not terminate TLS itself. Put it behind your platform ingress, load balancer, or reverse proxy and terminate TLS there. If you expose gRPC outside a private network, use a proxy that supports gRPC over HTTP/2.

Health Checks

Use these endpoints from your orchestrator:

The Docker Compose app stack uses /ready for the API container health check.

Secrets

Treat these as production secrets:

• Postgres credentials in OPEN_SPANNER_POSTGRES_DSN.
• API keys created in the dashboard.
• Alert webhook signing secrets.

Only put API keys in trusted backend services, workers, or server-side jobs. Do not ship Open Spanner API keys in browser or mobile clients.

Data Protection

Back up Postgres. It is the system of record for meters, usage events, API keys, sessions, alert rules, alert state, and export job records.

Export CSV files are generated artifacts. If your finance or audit workflow treats generated files as evidence, back up the export storage path too. Otherwise, export files can be regenerated while the source usage events are still retained.

Retention pruning permanently deletes raw usage events older than each meter's retention policy. Enable pruning only after choosing retention windows that match your billing, audit, and reporting requirements.

Upgrade Checklist

Before upgrading a production deployment:

1. Pin the target image tag instead of using latest.
2. Back up Postgres.
3. Confirm API, export worker, and alert worker containers use the same image version.
4. Start the API and wait for /ready.
5. Restart workers after the API has completed migrations.
6. Check the dashboard, queued exports, and alert events after the rollout.