Backup & Upgrade
Data persistence, backup and restore procedures, upgrading Sophon, and rollback.
What's Stored Where
| Data | Location | Tier |
|---|---|---|
| Configuration, agents, skills, memory, documents, logs | SOPHON_DATA (host bind mount) | All |
Encryption key (vault.key) | SOPHON_DATA/security/vault.key | All |
| SQLite database | SOPHON_DATA/data/sophon.db | Personal |
| PostgreSQL data | pgdata named volume | Pro, Enterprise |
| Qdrant vector data | qdrantdata named volume | Pro, Enterprise |
| Redis data | redisdata named volume | Enterprise |
| RabbitMQ data | rabbitmqdata named volume | Enterprise |
Backup
Sophon Data Directory
The most important backup — contains your configuration, agents, skills, documents, memory, and encryption keys.
# Stop Sophon (optional but recommended for consistency)
docker compose down
# Create a timestamped backup
tar czf sophon-backup-$(date +%Y%m%d).tar.gz -C "$SOPHON_DATA" .PostgreSQL (Pro/Enterprise)
# While running
docker compose exec postgres pg_dump -U sophon sophon \
> sophon-db-$(date +%Y%m%d).sql
# Or with compression
docker compose exec postgres pg_dump -U sophon -Fc sophon \
> sophon-db-$(date +%Y%m%d).dumpQdrant (Pro/Enterprise)
# Create a collection snapshot
curl -X POST http://localhost:6333/collections/sophon/snapshotsSnapshots are stored inside the qdrantdata volume. Copy them to your backup location.
Redis (Enterprise)
Redis with --appendonly yes persists to disk automatically. The data lives in the redisdata named volume. To back up:
# Trigger a save
docker compose exec redis redis-cli -a "$REDIS_PASSWORD" BGSAVE
# Copy the volume data
docker run --rm -v sophon_redisdata:/data -v $(pwd):/backup \
alpine tar czf /backup/redis-backup-$(date +%Y%m%d).tar.gz -C /data .Restore
Sophon Data Directory
# Stop Sophon
docker compose down
# Restore from backup
mkdir -p "$SOPHON_DATA"
tar xzf sophon-backup-20260324.tar.gz -C "$SOPHON_DATA"
# Restart
docker compose up -dPostgreSQL
# From SQL dump
docker compose exec -T postgres psql -U sophon sophon \
< sophon-db-20260324.sql
# From compressed dump
docker compose exec -T postgres pg_restore -U sophon -d sophon \
< sophon-db-20260324.dumpQdrant
Restore from the Qdrant snapshot API:
curl -X PUT "http://localhost:6333/collections/sophon/snapshots/recover" \
-H "Content-Type: application/json" \
-d '{"location": "file:///qdrant/storage/snapshots/sophon/<snapshot-name>.snapshot"}'The vault.key File
The file at SOPHON_DATA/security/vault.key contains the AES-256 encryption key used to encrypt all credentials at rest — API keys in models.json, channel tokens in channels.json, and TTS keys in tts.json.
If you lose this file, all encrypted credentials become unrecoverable. You would need to re-enter every API key and re-authenticate every channel.
Always verify vault.key is included in your backups:
# Verify it exists in a backup archive
tar tzf sophon-backup-20260324.tar.gz | grep vault.keyUpgrading
Pull and Restart
# Pull latest images
docker compose pull
# Restart with new images
docker compose up -dEF Core database migrations run automatically on startup. No manual migration step is needed.
Upgrade Checklist
- Back up your data directory and database (see above)
- Pull the latest images
- Restart the services
- Verify the health check passes:
curl http://localhost:8081/api/health - Check logs for migration errors:
docker compose logs sophon-gateway
Pinning a Version
To avoid unexpected upgrades, pin a specific image tag:
services:
sophon-gateway:
image: buildersoftdev/sophon:1.2.0
sophon-dashboard:
image: buildersoftdev/sophon-dashboard:1.2.0Rollback
If an upgrade causes issues:
- Stop the services:
docker compose down - Restore from your backup (data directory + database)
- Pin the previous image tag in your compose file
- Restart:
docker compose up -d
# Example: rollback to 1.1.0
docker compose down
# Restore data
tar xzf sophon-backup-20260324.tar.gz -C "$SOPHON_DATA"
# Restore database (Pro/Enterprise)
docker compose up -d postgres
docker compose exec -T postgres psql -U sophon sophon < sophon-db-20260324.sql
# Update compose to pin old version
# image: buildersoftdev/sophon:1.1.0
docker compose up -d