How to Self-host AFFiNE with Docker Compose
Run AFFiNE for one VPS with Docker Compose: see the 4 containers, pinned image tags, data location, backups, and wetin 2 GB RAM really fit handle.
Wetin you go get when you self-host AFFiNE
Self-hosting AFFiNE go give you Notion-style workspace for server wey you control. E dey run as four containers: the application, one-shot migration job, Postgres, and Redis. Real-time collaboration dey included, up to the 10 seats wey self-hosted workspace get by default. The installation na one compose file plus one JSON config file. The things wey need proper planning na the image tags, disk layout, memory ceiling, and the proxy wey you put for front.
AFFiNE dey keep document editor and infinite canvas for the same workspace. So, you fit read one page as document or spread am out as whiteboard. If you still dey decide wetin to run, read comparison of self-hosted Notion alternatives first. This guide assume say you don make the choice. E cover how to run AFFiNE properly, instead make e compare am again.
We check everything here against AFFiNE self-host documentation and the published release files on 8 August 2026. The newest stable release for that date na 0.27.3, wey dem publish on 23 July 2026. We re-check claims wey get later date against their primary sources on 12 October 2026. For that date, the newest stable release na 0.27.4, wey dem publish on 18 August 2026.
Wetin the four containers actually dey do
affine na the server and web client inside one image. E dey listen on port 3010.
affine_migration na one-time job wey dey run node ./scripts/self-host-predeploy.js, apply the database migrations, then exit. The application declare condition: service_completed_successfully on that job, so if migration exit with non-zero status, affine no go start at all. When web interface no come up, na that job log you suppose read first.
postgres dey keep your documents, users, workspaces and permissions. The image wey dem ship na pgvector/pgvector:pg16, wey be ordinary Postgres 16 with pgvector extension compiled inside. pgvector add vector column type to Postgres. Na the numeric format dem dey use store embeddings, so text fit dey searched by meaning.
redis na hard dependency: both server and migration job go wait for its health check before dem start. Notice say the compose file wey dem ship no give Redis volume. Nothing inside am survive a docker compose down, and this tell you clearly say e no hold any content wey belong to you and e no need backup.
Why the Postgres image na be pgvector, no be stock postgres
This requirement come from AFFiNE schema, no be preference. For v0.27.4, schema.prisma still declare extensions = [pgvector(map: "vector")], but e no get embedding columns. The four models wey get embedding columns typed vector(1024) for v0.27.3 no dey for v0.27.4. Keep the supplied pgvector/pgvector:pg16 image: the extension still dey declared, and stock postgres:16 no include am.
The official v0.27.4 template dey use the pgvector image; the v0.21.0 template still dey use postgres:16. For older install, changing the image line no be the complete upgrade. Read the upgrade page for the AFFiNE self-host docs before you pull anything.
One more thing about that tag. pg16 mean Postgres 16, and you no fit just increase a Postgres major version number. If you change am to pg17 for an existing data directory, Postgres go refuse to start, with a line like The data directory was initialized by PostgreSQL version 16, which is not compatible with this version 17 inside docker compose logs postgres. Major version upgrade need one of the three methods wey PostgreSQL 17 release notes name: dump and restore into a fresh data directory, pg_upgrade, or logical replication. For one Compose install, dump and restore usually dey simplest, because pg_upgrade need the old and new server binaries side by side.
Self-hosted AFFiNE need how much CPU and RAM
AFFiNE requirements page talk say you need at least 4 CPU cores and 2 GB RAM. E also increase memory requirement to 4 GB once your documents pass 10,000 words. The same page explain where the memory dey go: sync system and document merging. E give one figure wey worth remembering: merging document with 10,000 modifications fit reach 1 GB at peak.
Now compare this with 2 GB plan where two people dey write. Average usage dey okay. Postgres and Node process fit stay below the limit with some memory left. Na the peak be the problem. One large merge fit push server memory usage reach around 1 GB. For 2 GB server wey no get swap, that peak plus Postgres and every other resident process fit use all the memory. Kernel out-of-memory (OOM) killer go then kill one process to free memory. Since AFFiNE server na the largest process, e likely be the victim. But Docker documentation make am clear say any process fit get killed, including Docker itself.
When na AFFiNE server get killed, your colleague no go see error. The page go just reload, because restart: unless-stopped bring the container back within seconds. No guess this one; confirm am:
docker inspect affine_server --format '{{.State.OOMKilled}} {{.RestartCount}}'
sudo dmesg -T | grep -i -E 'out of memory|killed process'true from the first command, or a Killed process line wey name node from the second command, mean say memory finish. E no mean say you find bug. Fix the issue from both sides. Add swap first, so spike get buffer wey e fit spill into before OOM killer act:
sudo fallocate -l 2G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile
echo '/swapfile none swap sw 0 0' | sudo tee -a /etc/fstab
free -hfree -h suppose now report 2.0Gi swap total. Swap no make AFFiNE fast, and na not wetin e dey meant for. E give short spike somewhere to go. This make the spike more likely to cause one slow second instead of killing the container. E na buffer, no be guarantee. The other side of the fix na to stop Postgres from growing its cache into the memory wey application need during merge. Na wetin memory limits for a Compose service dey handle. If the kills continue after you do both, server need the 4 GB wey AFFiNE requirements page ask for larger documents.
Storage easier to predict. These na the figures wey AFFiNE publish for that same page:
Di data wey dey behind dis chart
[
{
"label": "Server install",
"gb": 1.5
},
{
"label": "Postgres per 1,000 docs",
"gb": 0.1
},
{
"label": "Blob store per 1,000 uploads",
"gb": 10
}
]Server installation take 1.5 GB. One thousand documents of about one thousand words each add 0.1 GB of Postgres data, and this almost be nothing. One thousand uploaded files add 10 GB, and na this carry the main storage usage. These figures na published planning estimates, no be measurements from running instance. So use dem to understand the pattern, no be as promise. The pattern na wetin matter: your database go remain small, while your uploads go decide how much disk you need.
Write the compose file yourself, with the tags pinned
The documented install dey download one ready-made file with curl -L -o docker-compose.yml https://github.com/toeverything/AFFiNE/releases/latest/download/docker-compose.yml. E dey work. But you need know one detail before you depend on am: as of 8 August 2026, the file wey dey attached to release 0.27.3 still dey read its paths from a .env file, using ${UPLOAD_LOCATION}, ${CONFIG_LOCATION} and ${DB_DATA_LOCATION}. But the documentation reference page dey show newer layout wey put storage and PostgreSQL data under ./data, keep configuration under ./config, and no need .env at all. Release 0.27.4 move the attached file to that layout. As of 12 October 2026, both agree. If you install from the older file, your paths still dey come from .env. AFFiNE upgrade page warn say if you replace the compose file without carrying those settings forward, Postgres fit start with empty data directory. If you write the file yourself, this question no go come up. You still need edit am anyway to pin the images and set database password.
mkdir -p ~/affine/config ~/affine/data
cd ~/affine
printf 'DB_PASSWORD=%s\n' "$(openssl rand -hex 24)" > .env
chmod 600 .envCompose go read .env from the project directory by itself and substitute ${DB_PASSWORD} for you. So the password no go show inside the file wey you fit paste for support thread. Keep this habit for every stack wey you run. The reason dey explained for keeping secrets out of the compose file.
Now write ~/affine/docker-compose.yml:
name: affine
services:
affine:
image: ghcr.io/toeverything/affine:stable
container_name: affine_server
ports:
- '127.0.0.1:3010:3010'
depends_on:
redis:
condition: service_healthy
postgres:
condition: service_healthy
affine_migration:
condition: service_completed_successfully
volumes:
- ./data/storage:/root/.affine/storage
- ./config:/root/.affine/config
environment:
- REDIS_SERVER_HOST=redis
- DATABASE_URL=postgresql://affine:${DB_PASSWORD}@postgres:5432/affine
- AFFINE_INDEXER_ENABLED=false
restart: unless-stopped
affine_migration:
image: ghcr.io/toeverything/affine:stable
container_name: affine_migration_job
command: ['sh', '-c', 'node ./scripts/self-host-predeploy.js']
volumes:
- ./data/storage:/root/.affine/storage
- ./config:/root/.affine/config
environment:
- REDIS_SERVER_HOST=redis
- DATABASE_URL=postgresql://affine:${DB_PASSWORD}@postgres:5432/affine
- AFFINE_INDEXER_ENABLED=false
depends_on:
postgres:
condition: service_healthy
redis:
condition: service_healthy
redis:
image: redis:8-alpine
container_name: affine_redis
healthcheck:
test: ['CMD', 'redis-cli', '--raw', 'incr', 'ping']
interval: 10s
timeout: 5s
retries: 5
restart: unless-stopped
postgres:
image: pgvector/pgvector:pg16
container_name: affine_postgres
volumes:
- ./data/postgres:/var/lib/postgresql/data
environment:
POSTGRES_USER: affine
POSTGRES_PASSWORD: ${DB_PASSWORD}
POSTGRES_DB: affine
POSTGRES_INITDB_ARGS: '--data-checksums'
healthcheck:
test: ['CMD', 'pg_isready', '-U', 'affine', '-d', 'affine']
interval: 10s
timeout: 5s
retries: 5
restart: unless-stoppedThese four things different from the file upstream ships, and each one get reason.
127.0.0.1:3010:3010publish the port for loopback address only. Docker releases before 28.0.0 allow hosts for the same L2 segment to reach ports published on localhost. Configured direct routing fit still expose the container port even when you publish am for loopback. Use Docker 28.0.0 or newer, and keep direct routing disabled during setup. The upstream'3010:3010'bind every interface. For most VPS images, that includes the public interface.POSTGRES_HOST_AUTH_METHOD: trustno dey there again, and password dey set instead. Trust authentication accept any connection to that database as theaffineuser without password. E limited to the private Compose network. That one dey okay until you attach another container to the network, or publish 5432 while you dey debug.redis:8-alpinereplace bareredis, wey resolve tolatest. As of August 2026, that one na Redis 8. The pin keep the major version wey you test and stop future Redis 9 from arriving during unrelateddocker compose pull.pgvector/pgvector:pg16remain exactly as upstream set am, for the reason wey we give above.
POSTGRES_PASSWORD dey read only when Postgres create its data directory for the first time. If the instance already dey exist, set the password with docker compose exec postgres psql -U affine -c "ALTER USER affine WITH PASSWORD 'yourpassword'", then update DATABASE_URL to match.
Configuration dey for config/config.json
AFFiNE dey read im settings from config/config.json, wey be the directory you mount for /root/.affine/config. Nothing go create that file for you, so write am before the first start. Open ~/affine/config/config.json with editor and put this content inside, using your own domain instead of the example:
{
"$schema": "https://github.com/toeverything/affine/releases/latest/download/config.schema.json",
"server": {
"name": "Team workspace",
"externalUrl": "https://affine.example.com"
},
"copilot": {
"enabled": false,
"byok": {
"enabled": false
}
}
}server.externalUrl must be the address wey your users actually open for browser. AFFiNE dey build share links and workspace invitations from that value. So if you leave am as http://localhost:3010, invitation wey you send go point the recipient to their own machine and e go fail there. Set am to the public HTTPS address before the first start, so the file and the admin panel no go disagree about am. Settings wey you later change for the admin panel dey save for the database; dem no dey write back to this file.
copilot dey control the AI features. copilot.byok.enabled na the bring-your-own-key switch. E allow workspace owner paste their own model provider key inside workspace settings. Self-hosting AFFiNE no include AI subscription. Leave both false if you no want am.
Start the stack:
docker compose up -d
docker compose ps --alldocker compose ps --all suppose list affine_postgres and affine_redis as healthy, affine_server as running, and affine_migration_job with state exited (0). The --all dey important: without am, docker compose ps go show only containers wey dey run, so migration job wey finish clean no go show at all. Any other exit code for the migration job na wetin you need investigate, and im log go name the step wey stop:
docker compose logs affine_migrationPin the image before you forget
stable na moving tag. AFFiNE release workflow dey point several tags to each stable build, and two of dem matter here: stable, wey dem dey point again for every release, and stable- followed by the git short hash, wey no dey change. If you leave am for stable, a docker compose pull six months from now go fetch different image and run its migrations against your database when you no choose. Pin the exact image wey you test:
docker compose pull
docker image inspect ghcr.io/toeverything/affine:stable --format '{{index .RepoDigests 0}}'That one go print line like ghcr.io/toeverything/affine@sha256: followed by long hash. Paste the complete string inside the image: line for both affine and affine_migration. The two ones must always match, because na the same image wey dey play two roles. If dem no match, you fit migrate the database to one schema while you dey serve am with another. Upgrade go then be deliberate edit instead of surprise: change the digest, back up, docker compose pull, docker compose up -d.
Create the admin account before anybody else
Open /admin for fresh instance, and AFFiNE go send you go account creation page because server never get administrator yet. That flow no get invitation code or setup token. The first person wey complete registration go become administrator for your server, so the port must remain closed until you register.
Na why the compose file above bind to 127.0.0.1. Reach am through SSH tunnel from your own machine:
ssh -L 3010:127.0.0.1:3010 you@your-server-ipLeave am running and open http://127.0.0.1:3010/admin for your local browser. Register and log in, then close the tunnel. Na only now e safe to put the instance for public name. The same race dey happen for other self-hosted apps. E worse for apps wey first login create passkey wey bind to hostname. Na why you must settle TLS and final domain before the first account when you self-host openGym.
Where AFFiNE dey keep your data
Three paths hold everything, and all of dem dey inside the directory wey you create.
./data/postgresna the Postgres data directory: documents, users, workspaces, permissions, and any server settings wey you save from the admin panel../data/storagedey mounted for/root/.affine/storageinside the container, and e hold every uploaded file../configdey mounted for/root/.affine/config, and e holdconfig.jsonplusprivate.keywey the migration job generate.
Upstream dey use bind mounts here instead of named volumes, and na deliberate choice be that: you fit use ordinary commands to tar and copy these paths, without asking Docker where e put dem. The cost be say file ownership for the host don become your problem. Na this trade-off bind mounts and named volumes dey cover.
How to back up AFFiNE
Two things need backup, and dem dey need different backup method. Database na live server, so if you copy its files while e dey run, the copy fit corrupt. Dump am instead:
mkdir -p ~/affine/backup
cd ~/affine
docker compose exec -T postgres pg_dump --format c --username affine affine \
> backup/affine-$(date +%F).dump
ls -lh backup/The dump dey run inside the container through its local socket, so e no go ask for password. Check the size for that ls output. If the file na only few hundred bytes, e mean say dump fail while the shell still create the file. Na this kind failure people dey discover six months later. The -T matter too: without am, Compose fit allocate terminal and corrupt the binary stream.
Uploaded files na just files, so use tar for dem:
tar czf backup/storage-$(date +%F).tgz -C data storage
tar czf backup/config-$(date +%F).tgz config docker-compose.yml .envKeep the complete config directory, Compose file, and .env for your backup, because the dump no contain dem. The migration job dey also create config/private.key, so if you copy only config.json, that file go miss. Settings wey you save for admin panel dey inside database, so the dump above don already carry dem. As of 12 October 2026, AFFiNE backup page also add say you fit export modified server settings from admin panel. Copy all three files comot from the server. Backup wey dey for the same disk with the thing e suppose protect no be backup. This split of database dump plus tar of uploads directory na the pattern to repeat for every other stateful container wey you run. Na the same method wey keep conversation history and attachments safe when you self-host Chatwoot as support desk.
Restore, and one trap for the published steps
Read the official restore steps before you need dem, and read dem well. As dem publish am for August 2026, dem copy one file wey dem name affine.backup enter the container, then restore from ./pg.backup. Those na two different names. Dem also remove one ./postgres directory, even though the current compose file dey keep its data for ./data/postgres. As of 12 October 2026, the page dey use affine.backup everywhere and talk say make you keep the old Postgres directory until you verify the restore. So upstream don fix the trap. But any copy of the steps wey you save before then still get the problem. For any case, follow the paths wey you actually use, no be the ones for any snippet. Na this sequence you go use with the layout for this guide:
cd ~/affine
docker compose down
sudo mv data/postgres data/postgres.old
docker compose up -d postgres
docker compose cp backup/affine-2026-08-08.dump postgres:/tmp/affine.dump
docker compose exec postgres pg_restore --format c --username affine \
--dbname affine --verbose /tmp/affine.dump
docker compose up -dNotice say na mv, no be rm. If you restore over database wey you never keep copy of, one wrong command fit cause total data loss. Moving the old directory go one side no cost anything. Restore the uploads too with tar xzf backup/storage-2026-08-08.tgz -C data, or every document go show broken attachments. Then log in and open one document wey get image. Na that be the test. Restore wey you never open for browser na just file; e no be backup.
Putting AFFiNE behind proxy wey you already dey run
AFFiNE dey use WebSocket, and you no fit skip am. The documentation talk am clearly: WebSocket na the foundation of AFFiNE sync and collaboration system. So, if proxy no upgrade those connections, workspace go load but editing go quietly stop syncing. Page go open, login go work, but edit wey you make for one browser no go reach the other one. For your browser developer tools, open Network tab and filter to WS. If connection dey open and close repeatedly, proxy no dey pass the upgrade.
If you already dey run Traefik for other containers, AFFiNE go join am as normal service. Delete the ports: block from the affine service, then add:
networks:
- default
- proxy
labels:
- 'traefik.enable=true'
- 'traefik.docker.network=proxy'
- 'traefik.http.routers.affine.rule=Host(`affine.example.com`)'
- 'traefik.http.routers.affine.entrypoints=websecure'
- 'traefik.http.routers.affine.tls.certresolver=letsencrypt'
- 'traefik.http.services.affine.loadbalancer.server.port=3010'For bottom of the file, together with services:, add:
networks:
proxy:
external: trueThe certificate resolver name must match the one wey you define for your Traefik configuration. loadbalancer.server.port na the container port 3010, never host port. Traefik dey proxy WebSocket connections without extra configuration, so you no need add anything else. If the rest of your stack already dey behind Authentik for single sign-on, forward auth middleware for this router go control browser access to AFFiNE. But leave am off until you test the desktop app, because e no get browser session and e go simply fail to sync. One Traefik wey dey in front of several apps cover how to run several apps behind one instance.
For nginx, you must request the upgrade explicitly:
location / {
proxy_pass http://127.0.0.1:3010;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
client_max_body_size 100m;
}client_max_body_size for nginx dey default to 1 MB. Without that line, every upload wey pass small photo size go fail with 413 status. Nothing go appear for AFFiNE logs because the request never reach am. Caddy need one line, reverse_proxy http://127.0.0.1:3010, and e go handle certificates and WebSocket upgrades by itself.
Wetin the self-hosted build no include
Make you honest with yourself about this before you move team enter am.
Real-time collaboration dey available, and na this feature all the sizing advice dey focus on, because AFFiNE own documentation talk say sync system and document merging dey use memory. Offline editing na why plenty people want local-first tool, and desktop application fit add your self-hosted server to its workspace list and log in against am. Test the exact offline behaviour wey your team depend on before you commit: edit for desktop app when network off, reconnect, then check the result for another device. Feature lists no be evidence, and this one sef no be exception.
Server-side full-text search dey off for the compose file wey ship with am, where AFFINE_INDEXER_ENABLED=false set for server and migration job. To turn am on, you need add Manticore Search container. This go make am fifth service and e go use more memory. For 2 GB box, na this change go push you pass the limit. Search inside the client still dey work for the workspace wey you open.
Two limits dey worth knowing before you invite people. Self-hosted workspace fit get maximum 10 seats, and to pass that number you need Team license from AFFiNE. Documentation describe unlimited blob storage and unlimited blob size for self-hosted instances as something dem intend to support but never fully implement, as checked for October 2026. None of these matter for household or small team. Both matter if you plan move forty people.
Upgrades
Read the release notes first, especially when you dey move from one minor version go another, like 0.26 to 0.27, because breaking changes fit enter. Back up the database and storage directory before you touch anything, because the migration job go change your schema for the next start, and you no fit undo am. Then change the pinned digest, run docker compose pull followed by docker compose up -d, and monitor docker compose logs -f affine_migration until e exit cleanly. docker image prune go clear the old layers afterwards. One historical note for anybody wey dey use very old install: from version 0.23.0, the image name change from affine-graphql to affine, so compose file wey older than that need make you rewrite the image lines before pull fit find anything. And from version 0.27.4, the official compose template move the Postgres, upload, and configuration paths, and change the default database connection. So compare the new file with your own file instead of copying am over a working install.
FAQ
Why AFFiNE container no dey start?
The affine service declare condition: service_completed_successfully for the affine_migration job. So if migration finish with any status wey no be 0, server no go start and web interface no go show at all. Run docker compose logs affine_migration to see which step stop. Check say hand-edited compose file still dey use pgvector/pgvector:pg16. Stock Postgres no get pgvector extension wey AFFiNE schema still declare, even though v0.27.4 no longer define the four embedding models wey dey for v0.27.3.
How much RAM self-hosted AFFiNE need?
AFFiNE requirements page ask for at least 4 CPU cores and 2 GB of RAM. E fit rise to 4 GB when documents pass 10,000 words. E also note say merging document with 10,000 modifications fit reach 1 GB at peak. For 2 GB server, na this peak dey cause the problem, no be idle load. The kernel out-of-memory killer go choose process to stop, most likely AFFiNE server because e be the largest one. Then restart: unless-stopped start am again, so users go see page reload instead of error. Confirm am with docker inspect affine_server --format '{{.State.OOMKilled}}' and sudo dmesg -T | grep -i 'out of memory'. Then add 2 GB swap file as buffer for short spikes. Move to 4 GB of RAM if the kills continue.
Where AFFiNE dey store my data, and wetin I need back up?
Three paths under your compose directory hold everything: ./data/postgres for the database, ./data/storage for uploaded files, and ./config for config.json plus the generated private.key. Back up the database with docker compose exec -T postgres pg_dump --format c --username affine affine > affine.dump instead of copying the files, because you no fit safely copy running Postgres. The dump also carry any settings wey you save for admin panel, because AFFiNE dey store dem for the database. Tar ./data/storage for the uploads. Keep the complete config directory, Compose file, and .env, because those files no dey inside the database.
Real-time collaboration dey work for self-hosted AFFiNE?
Yes, and you no need enable anything for am. The only requirement na your reverse proxy, because sync dey run over WebSocket connections. For nginx, that mean proxy_http_version 1.1 plus the Upgrade and Connection: upgrade headers. Traefik and Caddy pass those connections through without extra configuration. If proxy no upgrade the connections, workspace go load and login normally, but edits wey you make for one browser no go appear for another.
I fit run AFFiNE with stock Postgres image?
Use pgvector/pgvector:pg16. Na Postgres 16 with pgvector extension compiled inside. AFFiNE v0.27.4 still declare extensions = [pgvector(map: "vector")] for schema.prisma, but e no longer define the four models with vector(1024) embedding columns wey dey for v0.27.3. Stock Postgres no include the declared extension. If you point AFFiNE to external Postgres server, install pgvector there and create the extension for the target database before you run migration.