Docker Compose [Recommended]

Docker Compose is the recommended way to self-host AFFiNE.

Prerequisites

Install Docker with Docker Compose v2. You should be able to run:

docker compose version

Install

1. Create a deployment directory

mkdir affine
cd affine
mkdir -p config

Keep this directory in a stable location. The official Compose file stores PostgreSQL data under ./data/postgres, uploaded files under ./data/storage, and application configuration under ./config.

2. Download the current Compose file

curl -L -o docker-compose.yml \
  https://github.com/toeverything/AFFiNE/releases/latest/download/docker-compose.yml

You can also copy the file from docker-compose.yml.

3. Create`config/config.json`

curl -L -o config/config.json \
  https://github.com/toeverything/AFFiNE/releases/latest/download/config.json.example

Open config/config.json and set server.externalUrl to the URL that users will open. For a local installation, the default is:

{
  "$schema": "https://github.com/toeverything/affine/releases/latest/download/config.schema.json",
  "server": {
    "name": "AFFiNE Self-hosted",
    "externalUrl": "http://localhost:3010"
  },
  "copilot": {
    "enabled": true,
    "byok": {
      "enabled": true
    }
  }
}

For a public deployment, use the final HTTPS URL, for example https://affine.example.com. See Configuration for more options.

New installations do not need a .env file. Runtime settings belong in config/config.json; the Compose file already contains the internal service wiring and uses relative data directories.

4. Start AFFiNE

docker compose up -d
docker compose ps

The one-time migration container should finish successfully, while AFFiNE, PostgreSQL, and Redis remain running. To inspect startup problems:

docker compose logs --tail=200 affine affine_migration

5. Complete first-run setup

Open http://localhost:3010, or the URL configured in server.externalUrl, and create the initial administrator account.

Next steps

Read After Installation before exposing the instance publicly, and Upgrade before changing the image version. Back up both ./data and ./config; do not delete or relocate either directory after the instance contains data unless you are following the backup and restore guide.

ON THIS PAGE