Backups

Back up and restore your Hyperspeed Postgres database and object storage.

Hyperspeed state lives in two places. You need both to perform a full restore:

• Postgres — all application metadata: users, organizations, spaces, tasks, chat history, file tree, and settings.
• Object storage (MinIO by default) — the actual bytes of uploaded files.

Postgres

Back up

Run the following command from the directory that contains your docker-compose.yml:

docker compose exec -T postgres pg_dump -U hyperspeed -d hyperspeed > hyperspeed.pg.sql

This writes a plain-SQL dump to hyperspeed.pg.sql in your current directory. Store it somewhere safe—off the host machine if possible.

Restore

To restore into a running Postgres container (typically a fresh one):

cat hyperspeed.pg.sql | docker compose exec -T postgres psql -U hyperspeed -d hyperspeed

Restoring into a database that already contains data will produce conflicts. Use a clean database, or drop and recreate the hyperspeed database before restoring.

Object storage (MinIO)

Option 1: Volume snapshot

Stop the stack, take a disk or VM-level snapshot of the MinIO data volume, then start the stack again. This is the simplest approach for single-server setups where brief downtime is acceptable.

Option 2: Mirror with mc (online backup)

Use the MinIO client (mc) to mirror your bucket to another S3-compatible target while the stack is running.

# Register your local MinIO instance as an alias
mc alias set local http://localhost:9000 minioadmin minioadmin

# Register your backup destination
# mc alias set backup https://s3.example.com ACCESS_KEY SECRET_KEY

# Mirror the bucket
mc mirror --overwrite local/hyperspeed-files backup/hyperspeed-files

Replace minioadmin / minioadmin with the credentials from your .env file, and set backup to point at your actual backup target.

Run the mirror command on a schedule (for example, a daily cron job) to keep the backup reasonably current without stopping the stack.

Testing your backups

A backup you have never tested is not reliable. Periodically:

1. Restore the Postgres dump into an isolated environment and verify that the application starts and data looks correct.
2. Retrieve a sample of objects from the backup bucket or snapshot and confirm they are readable.

Test restores do not need to be full production replays. Spinning up the stack locally with the restored data and checking a few records is sufficient to confirm the backup is valid.