Upgrade

Before upgrading

Before upgrading a self-hosted AFFiNE deployment:

1. Choose the target AFFiNE version you want to upgrade to.
2. Read the GitHub Releases notes for that target version.
3. Check release notes carefully for breaking changes, especially in minor releases such as 0.xx.0.
4. Back up Postgres with Backup and Restore.
5. Back up uploaded blobs if you use filesystem storage.
6. Export modified configuration from the Admin Panel and keep a copy of your .env file.
7. Plan a maintenance window and make sure you can roll back or restore if the upgrade fails.

Do not treat latest as a blind production upgrade path. Read the release notes first, then upgrade deliberately.

Docker Compose

To upgrade an AFFiNE self-host deployment installed with Docker Compose, download the compose file for your target release.

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

If you have deliberately chosen to upgrade to the latest release after reading the release notes, you can use the latest release asset instead.

wget -O docker-compose.yml https://github.com/toeverything/affine/releases/latest/download/docker-compose.yml

Pull the target images and restart the deployment:

docker compose pull
docker compose up -d

After the upgrade, open your AFFiNE instance and verify that login, workspace loading, document editing, uploads, and admin access work as expected.

After you verify the upgraded instance, old images can be cleaned up.

docker image prune