Backup & Restore

AI-in-a-Box stores durable state in PostgreSQL, Qdrant, MinIO, ClickHouse, and optional integration databases. Redis stores short-lived sessions and queues.

Use service names from deploy/docker-compose.yml; avoid hard-coded container names because Compose names change when the project name or working directory changes.

Prerequisites

• Platform services are stopped for restore and preferably quiet for backup.
• deploy/.env exists.
• You have shell access on the Docker host.

Set a helper in your shell:

COMPOSE="docker compose --env-file deploy/.env -f deploy/docker-compose.yml"

PostgreSQL

The main PostgreSQL service holds the AI-in-a-Box database plus consolidated databases for Keycloak, Dify, Airbyte, Firecrawl, Langfuse, and other services.

Backup the main application database:

$COMPOSE exec -T postgresql sh -lc 'pg_dump -U "$POSTGRES_USER" "$POSTGRES_DB"' > aibox-postgres.sql

Restore:

$COMPOSE exec -T postgresql sh -lc 'psql -U "$POSTGRES_USER" "$POSTGRES_DB"' < aibox-postgres.sql

For a full environment backup, dump every database that exists in the shared cluster, including Keycloak and optional integration databases.

After restore, verify the audit chain:

curl "http://localhost:8080/v1/admin/audit/verify?tenant_id=default" \
  -H "Authorization: Bearer $TOKEN"

Partial restores can intentionally break the audit chain from the restore point forward. Record the restore event operationally.

Qdrant

Qdrant stores vectors for memory and knowledge. Knowledge chunks also carry the extracted document text and metadata as Qdrant payloads, so Qdrant snapshots are required for complete document-content restore. Collection names depend on the service and tenant, for example mem0_default for memory.

curl http://localhost:6333/collections

Create and download a snapshot:

curl -X POST http://localhost:6333/collections/COLLECTION_NAME/snapshots
curl http://localhost:6333/collections/COLLECTION_NAME/snapshots
curl http://localhost:6333/collections/COLLECTION_NAME/snapshots/SNAPSHOT_NAME \
  -o COLLECTION_NAME.snapshot

Restore:

curl -X POST "http://localhost:6333/collections/COLLECTION_NAME/snapshots/upload" \
  -F "snapshot=@COLLECTION_NAME.snapshot"

MinIO

MinIO stores wiki pages, Dify storage, Langfuse buckets, and object-style artifacts. Uploaded document chunks/text are stored in Qdrant payloads after ingestion.

Mirror all buckets with the MinIO client:

mkdir -p backups/minio
docker run --rm --network aibox_default \
  --env-file deploy/.env \
  -v "$PWD/backups/minio:/backup" \
  minio/mc:RELEASE.2025-01-17T23-25-50Z \
  sh -lc 'mc alias set local http://minio:9000 "$MINIO_ROOT_USER" "$MINIO_ROOT_PASSWORD" && mc mirror local /backup'

If you use a non-default Compose project network, replace aibox_default with the network shown by docker network ls.

ClickHouse

ClickHouse is used by Langfuse. Back up it separately if you retain Langfuse analytics as production data.

Use a ClickHouse-native backup policy or a tested volume snapshot for your deployment. Do not rely on the PostgreSQL dump to preserve Langfuse analytics.

Redis

Redis is mostly ephemeral. Back it up only if you need active sessions or queue state.

$COMPOSE exec -T redis sh -lc 'redis-cli -a "$REDIS_PASSWORD" BGSAVE'

Copying Redis persistence files depends on how you mount Redis storage in your deployment.

Restore Order

1. Stop application services that write to the stores.
2. Restore PostgreSQL.
3. Restore Qdrant snapshots.
4. Restore MinIO buckets.
5. Restore optional ClickHouse/Redis data.
6. Start services.
7. Run health checks and audit verification.

make health

Troubleshooting

Problem	Check
Backup fails with permission errors	Use exec -T through Compose service names instead of container names.
Audit verification fails after restore	Confirm whether the restore was partial or missing signing key versions.
Qdrant restore fails	Restore into a compatible Qdrant version and matching vector dimensions.
MinIO mirror misses buckets	Confirm bucket names and access credentials in deploy/.env.