Configuration

AFFiNE application settings can be managed from the Admin Panel or from config/config.json.

Recommended configuration file

The official Docker Compose deployment mounts ./config into the AFFiNE container. Create config/config.json next to docker-compose.yml:

{
  "$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
    }
  }
}

The schema URL enables field documentation and validation in editors that support JSON Schema.

• server.name is the name shown for this AFFiNE server.

• server.externalUrl must be the final URL users open. Use the public HTTPS URL when AFFiNE is behind a reverse proxy.

• copilot.enabled enables AFFiNE AI features.

• copilot.byok.enabled lets workspace owners configure provider keys from Workspace Settings → Integrations → AI BYOK.

After editing the file, apply it by recreating the AFFiNE containers:

docker compose up -d

New official Compose deployments do not use .env for user configuration. Their data and config paths are relative to the deployment directory.

Existing.env deployments

Moving application settings to config/config.json does not move the Postgres database, uploaded files, or existing configuration files.

The Compose template changed in version 0.27.4. It uses ./data/postgres, ./data/storage, and ./config instead of the paths from .env, and its default Postgres connection no longer includes a password. Do not replace an older Compose file or delete .env without first checking these paths and database credentials.

Before migrating an existing deployment:

1. Back up Postgres, uploaded files, and configuration by following ​Backup and Restore.

2. Read ​Upgrade and compare the old and target Compose files.

3. Either carry the existing paths and database connection settings into the new Compose file, or restore the backup into the new directory layout.

POSTGRES_HOST_AUTH_METHOD=trust does not migrate an existing database and does not rewrite authentication for an already initialized Postgres data directory. See ​Legacy .env deployments for the migration checklist.

For a custom container deployment, mount the directory containing config.json at /root/.affine/config. Keep the file readable only by trusted administrators when it contains credentials such as SMTP settings.

Admin Panel

Open <your-affine-url>/admin/settings to view and edit supported server settings. Changes saved there take effect immediately.

Provider API keys are workspace settings, not server settings. Add and test them in Workspace Settings → Integrations → AI BYOK; see ​AI.