AFFiNE Docs
Try Online
Try Online

Upgrade

Starting from version 0.23.0, the AFFiNE Docker image changed from affine-graphql to affine. If your Compose file still uses the old image name, update it when preparing the target Compose file.

Before upgrading

Before upgrading a self-hosted AFFiNE deployment:

  1. Choose the target AFFiNE version.

  2. Read the GitHub release notes for that version.

  3. Back up Postgres with ​Backup and Restore.

  4. Back up uploaded files if you use filesystem storage.

  5. Keep copies of the current Compose file, .env file, and configuration.

  6. Compare the current and target Compose files. Check volume paths, database credentials, image tags, and ports.

  7. Plan a maintenance window and make sure the backup can be restored.

Do not use latest as a blind production upgrade path.

Upgrading a legacy.env deployment

Version 0.27.4 changed the official Compose template:

  • Postgres moved from ${DB_DATA_LOCATION} to ./data/postgres.

  • Uploaded files moved from ${UPLOAD_LOCATION} to ./data/storage.

  • Configuration moved from ${CONFIG_LOCATION} to ./config.

  • The default database connection changed from the username, password, and database in .env to the affine user and database without a password.

Replacing the old Compose file without carrying these settings forward can start Postgres with an empty data directory or prevent AFFiNE from authenticating to the existing database.

POSTGRES_HOST_AUTH_METHOD=trust does not migrate data. The Postgres image uses it when initializing a new, empty data directory; it does not rewrite authentication for an existing data directory.

Choose one migration approach before starting the target version:

  • Keep the existing layout: carry the existing Postgres, storage, and configuration mounts and the existing database connection settings into the target Compose file. A restore is not required when the same compatible Postgres data directory is reused.

  • Adopt the current layout: back up Postgres, uploaded files, and configuration, then restore them into ./data/postgres, ./data/storage, and ./config by following ​Backup and Restore.

Do not delete .env, remove old data directories, or run docker compose down --volumes until the upgraded deployment has been verified. See ​Legacy .env deployments for the migration checklist.

Docker Compose upgrade

Download the Compose file for the target release to a new file. Do not overwrite the running deployment's Compose file before reviewing the differences.

# Replace v0.xx.x with the target release tag.
AFFINE_VERSION=v0.xx.x
wget -O docker-compose.yml.new "https://github.com/toeverything/affine/releases/download/${AFFINE_VERSION}/docker-compose.yml"

diff -u docker-compose.yml docker-compose.yml.new

Carry forward the required persistent paths, database connection settings, ports, and other deployment-specific changes. Then replace the old file and start the target version:

mv docker-compose.yml.new docker-compose.yml
docker compose pull
docker compose up -d

The affine_migration service runs the database migration and predeploy steps automatically during startup.

Verify login, workspace loading, document editing, uploads, and admin access. Confirm that existing workspaces and files are present before removing old data or images.

Troubleshootingrole "affine" does not exist

This error usually means that the target Compose file is connecting as the hardcoded affine role, but the mounted legacy database was initialized with another DB_USERNAME.

If AFFiNE asks you to create a new administrator after an upgrade, it usually means the target Compose file started a new, empty Postgres directory. It does not by itself prove that the old data was deleted.

  1. Stop the target deployment.

  2. Return to the old Compose file and .env that successfully open the existing workspaces.

  3. Confirm the Postgres mount and effective database identity before changing anything:

docker inspect affine_postgres   --format '{{range .Mounts}}{{println .Source "->" .Destination}}{{end}}'

docker exec affine_postgres sh -c   'printf "user=%s database=%s\n" "$POSTGRES_USER" "$POSTGRES_DB"'

  1. Create a backup with ​Backup and Restore. Its command reads the actual role and database name from the working container.

  2. Either carry the old mount and database connection settings into the target Compose file, or restore into a fresh current-layout database.

Do not create an affine role merely to silence the error. First verify that AFFiNE is connected to the intended Postgres data directory and choose a deliberate migration approach.

After verification, unused images can be cleaned up:

docker image prune
ON THIS PAGE