Backup and Restore

Back up self-hosted AFFiNE before upgrades, storage moves, host migrations, and any operation that could affect persistent data. The most important recoverable data is Postgres, uploaded blobs, and modified configuration.

What to back up

Data	What it contains	Backup guidance
Postgres	AFFiNE application data.	Use the `pg_dump` flow below and keep the backup outside the container.
Blobs	Uploaded images, files, and other workspace blobs when using filesystem storage.	Back up the whole `{UPLOAD_LOCATION}` directory.
Configuration	Modified server configuration and operational settings.	Export modified configuration from the Admin Panel and keep a copy of your configuration files.

Postgres

Backup

Admin Panel

Automatic database backup configuration from the Admin Panel is not available yet.

pg_dump

Postgres provides the official pg_dump command to dump your database into a custom-format backup file. See the PostgreSQL backup documentation for more details.

The following commands assume the default Docker Compose container name, database user, and database name. If you changed DB_USERNAME or DB_DATABASE in .env, replace the values accordingly.

# Set these values to match your .env file.
POSTGRES_CONTAINER=affine_postgres
DB_USERNAME=affine
DB_DATABASE=affine

# Dump the database to a custom-format backup file inside the Postgres container.
docker exec "$POSTGRES_CONTAINER" pg_dump --format c --file /tmp/affine.backup --username "$DB_USERNAME" --verbose "$DB_DATABASE"

# Copy the backup file from the container to the current host directory.
docker cp "$POSTGRES_CONTAINER":/tmp/affine.backup ./affine.backup

After the command finishes, move affine.backup to durable storage outside the AFFiNE container directory.

Restore

Stop your instance first

Before restoring Postgres data, stop the AFFiNE instance so the application does not write to the database during restore.

Back up the current database first

Create and verify a backup of the current database before restoring another backup. Restoring the wrong file or restoring into the wrong environment can cause data loss.

The following commands assume the default Docker Compose container name and the DB_DATA_LOCATION, DB_USERNAME, and DB_DATABASE values shown below. If your .env uses different values, update the variables before running the commands.

# Set these values to match your .env file.
DB_DATA_LOCATION=./postgres
POSTGRES_CONTAINER=affine_postgres
DB_USERNAME=affine
DB_DATABASE=affine

# Stop all services before restoring.
docker compose down

# Move the current Postgres data directory aside instead of deleting it.
mv "$DB_DATA_LOCATION" "${DB_DATA_LOCATION}.before-restore.$(date +%Y%m%d%H%M%S)"

# Create and start only the Postgres service so it initializes a fresh data directory.
docker compose create postgres
docker compose start postgres

# Copy the backup file into the Postgres container.
docker cp ./affine.backup "$POSTGRES_CONTAINER":/tmp/affine.backup

# Restore the backup into the AFFiNE database.
docker exec "$POSTGRES_CONTAINER" pg_restore --format c --dbname "$DB_DATABASE" --username "$DB_USERNAME" --verbose /tmp/affine.backup

# Restart the full AFFiNE deployment.
docker compose up -d

After restore, open your AFFiNE instance and verify that users, workspaces, documents, and uploads are available as expected.

Blobs

If blob storage is configured to use fs as the provider, back up the whole {UPLOAD_LOCATION} directory.

If you use an S3-compatible provider, follow your storage provider's backup and versioning practices.

Configuration

Full automatic configuration backup is not implemented yet.

You can export all modified configurations from the Admin Panel. Keep that export together with a copy of your .env file and any files stored under {CONFIG_LOCATION} that are part of your deployment process.

Backup checklist

Before relying on a self-hosted AFFiNE instance in production, verify that you can:

Create a Postgres backup with pg_dump.
Copy the backup file outside the container and host directory.
Back up blob storage for your configured storage provider.
Export modified configuration from the Admin Panel.
Restore into a test environment and confirm documents and uploads load correctly.

ON THIS PAGE