Persistent Storage & Backups

The explorer database is the heart of your deployment. Give it durable, fast storage and backups you have actually tested.

Storage Layout

Use named Docker volumes on your fast disk so the database survives container replacement:

volumes:
  pgdata:
    driver: local

and in the database service:

services:
  postgres:
    volumes:
      - pgdata:/var/lib/postgresql/data

Guidelines:

• NVMe SSD only — database latency directly shapes API latency.
• Plan for growth — the database grows with chain history; see Hardware Requirements.
• Keep 25–30% free space — vacuums, migrations, and reindexes need working room.

Backup Strategy

Logical Dumps (Primary)

docker compose exec postgres pg_dump -U explorer explorer_db | gzip > /backups/explorer-$(date +%F).sql.gz

• Schedule daily via cron or systemd timer.
• Copy off-host (object storage or another machine).
• Retain at least two weeks of daily dumps.

Volume Snapshots (Fast Recovery)

If your disk or VM supports snapshots, take weekly snapshots of the database volume while the database is running (PostgreSQL tolerates crash-consistent snapshots) or during a brief stop for full consistency.

Configuration Backups

Keep docker-compose.yml, .env (sans secrets), and branding assets in version control. Rebuilding a deployment from config + backup should be a documented, practiced procedure.

Restore Procedure (Practice This)

# Stop writers
docker compose stop indexer api

# Restore
gunzip -c /backups/explorer-YYYY-MM-DD.sql.gz | \
  docker compose exec -T postgres psql -U explorer explorer_db

# Restart
docker compose up -d

Test restores quarterly. A restore that takes longer than a full reindex should trigger a review of your snapshot strategy.

Disaster Recovery Notes

The explorer database is derived data: worst case, it can be rebuilt by reindexing from the chain node. Backups exist to make recovery fast, not to make it possible. Prioritize:

1. Chain node snapshots (slowest to rebuild)
2. Explorer database dumps
3. Configuration and branding in version control