SSD Nodes Learn Hosting plans →
Gidsen Matt ConnorDoor Matt Connor

AFFiNE zelf hosten met Docker Compose: handleiding

Installeer AFFiNE op uw eigen VPS met Docker Compose. Leer hoe u de vier containers configureert, data opslaat en waarom 2 GB RAM de ondergrens is voor stabiel gebruik.

Wat u krijgt bij het zelf hosten van AFFiNE

Het zelf hosten van AFFiNE biedt u een werkruimte in Notion-stijl op een server die u beheert, draaiend als vier containers: de applicatie, een eenmalige migratietaak, Postgres en Redis. Real-time samenwerking is inbegrepen, tot de 10 gebruikers die een zelf-gehoste werkruimte standaard krijgt. De installatie bestaat uit één compose-bestand plus één JSON-configuratiebestand. Zaken die aandacht vereisen zijn de image-tags, de schijfindeling, het geheugenplafond en de proxy die u ervoor plaatst.

AFFiNE houdt een documenteditor en een oneindig canvas in dezelfde werkruimte, waardoor één pagina kan worden gelezen als een document of kan worden uitgezet als een whiteboard. Als u nog beslist wat u wilt draaien, lees dan eerst de vergelijking van zelf-gehoste Notion-alternatieven. Deze handleiding gaat ervan uit dat de keuze is gemaakt en behandelt het correct draaien van AFFiNE in plaats van het opnieuw te vergelijken.

Alles hier is gecontroleerd aan de hand van de AFFiNE self-host documentatie en de gepubliceerde releasebestanden op 8 augustus 2026. De nieuwste stabiele release op die datum was 0.27.3, gepubliceerd op 23 juli 2026. Claims hieronder met een latere datum zijn opnieuw gecontroleerd aan de hand van hun primaire bronnen op 12 oktober 2026, toen de nieuwste stabiele release 0.27.4 was, gepubliceerd op 18 augustus 2026.

Wat de vier containers daadwerkelijk doen

affine is de server en de webclient in één image. Deze luistert op poort 3010.

affine_migration is een eenmalige taak die node ./scripts/self-host-predeploy.js uitvoert, de databasemigraties toepast en vervolgens afsluit. De applicatie declareert condition: service_completed_successfully voor die taak, wat betekent dat als een migratie met een status ongelijk aan nul afsluit, affine helemaal niet start. Wanneer de webinterface niet verschijnt, is het logboek van die taak het eerste wat u moet raadplegen.

postgres bevat uw documenten, gebruikers, werkruimten en rechten. De meegeleverde image is pgvector/pgvector:pg16, wat een standaard Postgres 16 is met de gecompileerde pgvector-extensie. pgvector voegt een vector-kolomtype toe aan Postgres, de numerieke vorm die wordt gebruikt om embeddings op te slaan zodat tekst op betekenis kan worden doorzocht.

redis is een harde afhankelijkheid: zowel de server als de migratietaak wachten op de health check van deze service voordat ze starten. Let op wat het meegeleverde compose-bestand niet aan Redis geeft: een volume. Niets daarin overleeft een docker compose down, wat duidelijk aangeeft dat het geen inhoud van u bevat en geen back-up vereist.

Waarom de Postgres-image pgvector is en niet de standaard postgres

Deze vereiste komt voort uit het schema van AFFiNE, niet uit een voorkeur. In v0.27.4 declareert schema.prisma nog steeds extensions = [pgvector(map: "vector")], maar bevat het geen embedding-kolommen. De vier modellen met embedding-kolommen van het type vector(1024) in v0.27.3 ontbreken in v0.27.4. Gebruik de meegeleverde pgvector/pgvector:pg16-image: de extensie is nog steeds gedeclareerd en de standaard postgres:16 bevat deze niet.

De officiële v0.27.4-template gebruikt de pgvector-image; de v0.21.0-template gebruikte nog postgres:16. Bij een oudere installatie is het aanpassen van de image-regel niet de volledige upgrade; lees daarom de upgrade-pagina in de AFFiNE self-host documentatie voordat u wijzigingen doorvoert.

Nog een punt over die tag. pg16 staat voor Postgres 16, en een major-versie van Postgres is geen getal dat u zomaar kunt verhogen. Wijzigt u dit naar pg17 boven op een bestaande datamap, dan weigert Postgres te starten met een melding zoals The data directory was initialized by PostgreSQL version 16, which is not compatible with this version 17 in docker compose logs postgres. Een overstap naar een nieuwe major-versie vereist een van de drie routes die in de release notes van PostgreSQL 17 worden genoemd: een dump en restore naar een nieuwe datamap, pg_upgrade, of logische replicatie. Bij een enkele Compose-installatie is een dump en restore meestal het eenvoudigst, omdat pg_upgrade vereist dat de oude en nieuwe server-binaries naast elkaar beschikbaar zijn.

Hoeveel CPU en RAM heeft zelf-gehoste AFFiNE nodig

De vereistenpagina van AFFiNE vraagt om ten minste 4 CPU-cores en 2 GB RAM, en adviseert het geheugen te verhogen naar 4 GB zodra uw documenten meer dan 10.000 woorden bevatten. Dezelfde pagina geeft aan waar het geheugen wordt verbruikt: het synchronisatiesysteem en het samenvoegen van documenten. Er is één cijfer dat het onthouden waard is: het samenvoegen van een document met 10.000 wijzigingen kan een piek van 1 GB bereiken.

Vergelijk dit nu met een 2 GB-abonnement waar twee personen tegelijkertijd in schrijven. Het gemiddelde verbruik is in orde. Postgres en het Node-proces blijven onder de limiet met nog wat ruimte over. De piek is echter het probleem. Een enkele grote samenvoeging kan het geheugengebruik van de server naar een piek van ongeveer 1 GB duwen. Op een machine met 2 GB en zonder swap kan die piek, in combinatie met Postgres en andere actieve processen, het geheugen uitputten. De out-of-memory (OOM) killer van de kernel beëindigt vervolgens een proces om geheugen vrij te maken. De AFFiNE-server is als grootste proces het waarschijnlijke slachtoffer, hoewel de documentatie van Docker duidelijk stelt dat elk proces kan worden gekozen, inclusief Docker zelf.

Wanneer de AFFiNE-server wordt beëindigd, ziet uw collega geen foutmelding. Zij zien de pagina verversen, omdat restart: unless-stopped de container binnen enkele seconden weer opstart. Gist hier niet naar, maar bevestig het:

docker inspect affine_server --format '{{.State.OOMKilled}} {{.RestartCount}}'
sudo dmesg -T | grep -i -E 'out of memory|killed process'

true uit het eerste commando, of een Killed process-regel die node noemt uit het tweede, betekent dat u een tekort aan geheugen had in plaats van een bug. Los dit aan beide kanten op. Voeg eerst swap toe, zodat een piek een buffer heeft om naar uit te wijken voordat de OOM-killer ingrijpt:

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 -h

free -h zou nu een totaal van 2.0Gi swap moeten rapporteren. Swap maakt AFFiNE niet snel, en dat is ook niet de bedoeling. Het geeft een korte piek een plek om naartoe te gaan, waardoor de piek eerder een trage seconde kost dan een dode container. Het is een buffer, geen garantie. De andere kant van de oplossing is voorkomen dat Postgres zijn cache uitbreidt naar de ruimte die de applicatie nodig heeft tijdens het samenvoegen; dit is waar geheugenlimieten op een Compose-service voor dienen. Als de beëindigingen aanhouden na beide acties, heeft de server de 4 GB nodig waar de vereistenpagina van AFFiNE om vraagt bij grotere documenten.

Opslag is veel eenvoudiger te voorspellen. Dit zijn de cijfers die AFFiNE op diezelfde pagina publiceert:

GrafiekPublished AFFiNE storage figures, August 2026
De gegevens achter deze grafiek
[
  {
    "label": "Server install",
    "gb": 1.5
  },
  {
    "label": "Postgres per 1,000 docs",
    "gb": 0.1
  },
  {
    "label": "Blob store per 1,000 uploads",
    "gb": 10
  }
]

De serverinstallatie neemt 1.5 GB in beslag. Duizend documenten van elk ongeveer duizend woorden voegen 0.1 GB aan Postgres-data toe, wat verwaarloosbaar is. Duizend geüploade bestanden voegen 10 GB toe, wat het hele verhaal is. Dit zijn gepubliceerde planningscijfers in plaats van metingen van een draaiende instantie, dus beschouw ze als een indicatie en niet als een garantie. De verhouding is wat telt: uw database blijft klein en uw uploads bepalen uw schijfgebruik.

Schrijf het compose-bestand zelf en pin de tags

De gedocumenteerde installatie downloadt een kant-en-klaar bestand met curl -L -o docker-compose.yml https://github.com/toeverything/AFFiNE/releases/latest/download/docker-compose.yml. Dat werkt. Eén detail is belangrijk om te weten voordat u hierop vertrouwt: op 8 augustus 2026 las het bestand dat bij release 0.27.3 hoorde de paden nog uit een .env-bestand, met gebruik van ${UPLOAD_LOCATION}, ${CONFIG_LOCATION} en ${DB_DATA_LOCATION}. De referentiepagina in de documentatie toonde echter een nieuwere indeling waarbij opslag en PostgreSQL-data onder ./data vallen, configuratie onder ./config wordt bewaard en er helemaal geen .env nodig is. Release 0.27.4 heeft het bijgevoegde bestand naar die indeling verplaatst en sinds 12 oktober 2026 komen beide overeen. Als u vanuit het oudere bestand heeft geïnstalleerd, komen uw paden nog steeds uit .env. De upgrade-pagina van AFFiNE waarschuwt dat het vervangen van het compose-bestand zonder deze instellingen over te nemen, Postgres kan starten met een lege datamap. Door het bestand zelf te schrijven, vermijdt u dit probleem volledig, en u moet het bestand toch bewerken om de images te pinnen en een databasewachtwoord in te stellen.

mkdir -p ~/affine/config ~/affine/data
cd ~/affine
printf 'DB_PASSWORD=%s\n' "$(openssl rand -hex 24)" > .env
chmod 600 .env

Compose leest .env automatisch uit de projectmap en vervangt ${DB_PASSWORD} voor u, zodat het wachtwoord nooit verschijnt in het bestand dat u in een support-thread zou plakken. Het is verstandig om deze gewoonte voor elke stack die u draait aan te houden; de reden hiervoor staat in geheimen buiten het compose-bestand houden.

Schrijf nu ~/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-stopped

Er zijn vier verschillen met het bestand dat upstream wordt geleverd, en voor elk daarvan is een reden.

  • 127.0.0.1:3010:3010 publiceert de poort alleen op het loopback-adres. Docker-releases van vóór 28.0.0 staan hosts op hetzelfde L2-segment toe om op localhost gepubliceerde poorten te bereiken, en geconfigureerde direct routing kan de containerpoort blootstellen ondanks publicatie op loopback. Gebruik Docker 28.0.0 of nieuwer en houd direct routing uitgeschakeld tijdens de installatie. De upstream '3010:3010' bindt aan elke interface, en op de meeste VPS-images omvat dat ook de publieke interface.
  • POSTGRES_HOST_AUTH_METHOD: trust is verwijderd en in plaats daarvan is een wachtwoord ingesteld. Trust-authenticatie accepteert elke verbinding met die database als de affine-gebruiker zonder wachtwoord. Dit is beperkt tot het private Compose-netwerk, wat prima is totdat u op een dag nog een container aan dat netwerk toevoegt of poort 5432 publiceert tijdens het debuggen.
  • redis:8-alpine vervangt een kale redis, die resolve naar latest. Sinds augustus 2026 is dat Redis 8, dus de pin behoudt de major-versie die u heeft getest en voorkomt dat een toekomstige Redis 9 arriveert tijdens een niet-gerelateerde docker compose pull.
  • pgvector/pgvector:pg16 blijft exact zoals upstream het instelt, om de reden die hierboven is gegeven.

POSTGRES_PASSWORD wordt alleen gelezen wanneer Postgres voor de eerste keer de datamap aanmaakt. Op een instantie die al bestaat, stelt u het wachtwoord in met docker compose exec postgres psql -U affine -c "ALTER USER affine WITH PASSWORD 'yourpassword'" en werkt u vervolgens DATABASE_URL bij om dit te laten overeenkomen.

Configuratie bevindt zich in config/config.json

AFFiNE leest de instellingen uit config/config.json, de map die u hebt gemount op /root/.affine/config. Er wordt niet automatisch een bestand voor u aangemaakt, dus maak dit aan vóór de eerste start. Open ~/affine/config/config.json in een editor en voeg de volgende inhoud toe, waarbij u het voorbeeld vervangt door uw eigen domein:

{
  "$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 moet het adres zijn dat uw gebruikers daadwerkelijk in een browser openen. AFFiNE genereert deellinks en uitnodigingen voor werkruimtes op basis van deze waarde. Als u dit op http://localhost:3010 laat staan, verwijst een verzonden uitnodiging de ontvanger naar hun eigen machine, wat daar zal falen. Stel dit in op het publieke HTTPS-adres vóór de eerste start, zodat het bestand en het beheerderspaneel altijd overeenstemmen. Instellingen die u later in het beheerderspaneel wijzigt, worden opgeslagen in de database en niet teruggeschreven naar dit bestand.

copilot beheert de AI-functies. copilot.byok.enabled is de schakelaar voor het gebruik van uw eigen sleutel, waarmee een eigenaar van een werkruimte een eigen modelprovider-sleutel in de instellingen van de werkruimte kan plakken. Bij het zelf hosten van AFFiNE is geen AI-abonnement inbegrepen. Laat beide op false staan als u dit niet wilt gebruiken.

Start de stack:

docker compose up -d
docker compose ps --all

docker compose ps --all zou affine_postgres en affine_redis als healthy moeten tonen, affine_server als running, en affine_migration_job met de status exited (0). De --all is van belang: zonder deze optie toont docker compose ps alleen actieve containers, waardoor een migratietaak die correct is afgerond niet zichtbaar is. Elke andere exitcode bij de migratietaak is de oorzaak die u moet onderzoeken; het logboek geeft aan bij welke stap het proces is gestopt:

docker compose logs affine_migration

Pin de image voordat u het vergeet

stable is een bewegende tag. De release-workflow van AFFiNE wijst meerdere tags toe aan elke stabiele build, en twee daarvan zijn hier van belang: stable, die bij elke release wordt verplaatst, en stable- gevolgd door de git short hash, die dat niet wordt. Als u stable gebruikt, haalt een docker compose pull over zes maanden een andere image op en voert deze migraties uit op uw database op een moment dat u niet heeft gekozen. Pin de exacte image die u heeft getest:

docker compose pull
docker image inspect ghcr.io/toeverything/affine:stable --format '{{index .RepoDigests 0}}'

Dit drukt een regel af zoals ghcr.io/toeverything/affine@sha256: gevolgd door een lange hash. Plak de volledige string in de image:-regel van beide affine en affine_migration. Deze twee moeten altijd overeenkomen, omdat het dezelfde image is die twee rollen vervult; een mismatch betekent dat de database naar het ene schema wordt gemigreerd terwijl deze met een ander wordt geserveerd. Upgraden is dan een bewuste wijziging in plaats van een verrassing: wijzig de digest, maak een back-up, docker compose pull, docker compose up -d.

Maak het beheerdersaccount aan voordat iemand anders dit doet

Open /admin op een nieuwe instantie en AFFiNE stuurt u door naar een pagina voor accountaanmaak, omdat de server nog geen beheerder heeft. Er is in die procedure geen uitnodigingscode of setup-token aanwezig. De eerste persoon die de registratie voltooit, wordt de beheerder van uw server. De poort moet daarom gesloten blijven totdat u zich heeft geregistreerd.

Daarom bindt het bovenstaande compose-bestand aan 127.0.0.1. Bereik dit via een SSH-tunnel vanaf uw eigen machine:

ssh -L 3010:127.0.0.1:3010 you@your-server-ip

Laat dit draaien en open http://127.0.0.1:3010/admin in uw lokale browser. Registreer u, log in en sluit daarna de tunnel. Pas nu is het veilig om de instantie onder een publieke domeinnaam te plaatsen. Hetzelfde risico op een race condition bestaat bij andere zelfgehoste applicaties. Dit is nog problematischer wanneer de eerste login een passkey aanmaakt die gebonden is aan de hostnaam. Daarom moeten TLS en het definitieve domein zijn geconfigureerd voordat het eerste account wordt aangemaakt wanneer u openGym zelf host.

Waar AFFiNE uw data opslaat

Drie paden bevatten alle gegevens, en deze bevinden zich allemaal in de map die u heeft aangemaakt.

  • ./data/postgres is de Postgres-datamap: documenten, gebruikers, workspaces, rechten en alle serverinstellingen die vanuit het beheerderspaneel zijn opgeslagen.
  • ./data/storage is gekoppeld aan /root/.affine/storage in de container en bevat elk geüpload bestand.
  • ./config is gekoppeld aan /root/.affine/config en bevat config.json en de private.key die door de migratietaak zijn gegenereerd.

Upstream gebruikt hier bind mounts in plaats van named volumes, en die keuze is bewust: u kunt deze paden met standaardcommando's archiveren (tar) en kopiëren, zonder aan Docker te hoeven vragen waar deze zijn opgeslagen. Het nadeel is dat het eigendom van de bestanden op de host nu uw verantwoordelijkheid is; dit is de afweging die wordt besproken in bind mounts en named volumes.

Hoe u AFFiNE back-upt

Er moeten twee onderdelen worden geback-upt en deze worden op verschillende manieren verwerkt. De database is een actieve server; het kopiëren van de bestanden terwijl deze draait, resulteert in een corrupt exemplaar. Maak in plaats daarvan een dump:

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/

De dump wordt uitgevoerd binnen de container via de lokale socket, waardoor er niet om een wachtwoord wordt gevraagd. Controleer de grootte in de uitvoer van ls. Een bestand van enkele honderden bytes betekent dat de dump is mislukt terwijl de shell het bestand toch heeft aangemaakt; dit is de fout die men vaak pas na zes maanden ontdekt. De -T is ook van belang: zonder deze vlag kan Compose een terminal toewijzen en de binaire stroom corrumperen.

Geüploade bestanden zijn gewone bestanden, dus archiveer deze met tar:

tar czf backup/storage-$(date +%F).tgz -C data storage
tar czf backup/config-$(date +%F).tgz config docker-compose.yml .env

Bewaar de volledige config-directory, het Compose-bestand en .env in uw back-up, aangezien de dump deze niet bevat. De migratietaak creëert ook config/private.key, dus het kopiëren van alleen config.json laat dat bestand achterwege. Instellingen die in het beheerderspaneel zijn opgeslagen, staan in de database, dus de bovenstaande dump bevat deze al. Sinds 12 oktober 2026 vermeldt de back-uppagina van AFFiNE dat gewijzigde serverinstellingen ook vanuit het beheerderspaneel kunnen worden geëxporteerd. Kopieer alle drie de bestanden van de server af. Een back-up op dezelfde schijf als de data die het moet beschermen, is geen back-up. Deze splitsing van een database-dump plus een tar-archief van de uploads-directory is het patroon dat u voor elke andere stateful container moet herhalen. Het is dezelfde methode die de gespreksgeschiedenis en bijlagen veiligstelt wanneer u Chatwoot zelf host als supportdesk.

Herstellen en een valkuil in de gepubliceerde stappen

Lees de officiële herstelstappen voordat u ze nodig heeft en lees ze aandachtig. Zoals gepubliceerd in augustus 2026 kopieerden ze een bestand genaamd affine.backup naar de container en herstelden ze vervolgens vanuit ./pg.backup; dit zijn twee verschillende namen. Ook verwijderden ze een ./postgres-directory, terwijl het huidige compose-bestand de data in ./data/postgres bewaart. Sinds 12 oktober 2026 gebruikt de pagina overal affine.backup en wordt geadviseerd de oude Postgres-directory te bewaren totdat het herstel is geverifieerd. De valkuil is dus upstream verholpen, maar een kopie van de stappen die van vóór die datum is opgeslagen, bevat deze nog steeds. Volg in ieder geval de paden die u daadwerkelijk heeft gebruikt in plaats van de paden in een willekeurig fragment. Hier is de reeks voor de indeling in deze handleiding:

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 -d

Let op de mv in plaats van een rm. Herstellen over een database waarvan u geen kopie heeft bewaard, is de manier waarop één foutief commando leidt tot totaal dataverlies; het verplaatsen van de oude directory kost niets. Herstel ook de uploads met tar xzf backup/storage-2026-08-08.tgz -C data, anders wordt elk document weergegeven met kapotte bijlagen. Log daarna in en open een document dat een afbeelding bevat. Dat is de test. Een herstelactie die u niet in een browser heeft geopend, is slechts een bestand, geen back-up.

AFFiNE achter een bestaande proxy plaatsen

AFFiNE maakt gebruik van WebSocket, en dit is niet optioneel. De documentatie is hier duidelijk over: WebSocket vormt de basis voor het synchronisatie- en samenwerkingssysteem van AFFiNE. Een proxy die deze verbindingen niet upgradet, resulteert in een werkruimte waarbij bewerkingen stilletjes stoppen met synchroniseren. De pagina laadt, inloggen werkt, maar een bewerking in de ene browser bereikt de andere nooit. Open in de ontwikkelaarstools van uw browser het tabblad Network en filter op WS. Een verbinding die herhaaldelijk opent en sluit, duidt op een proxy die de upgrade niet doorlaat.

Als u al Traefik gebruikt voor andere containers, voegt u AFFiNE toe als een normale service. Verwijder het ports:-blok uit de affine-service en voeg vervolgens het volgende toe:

    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'

En onderaan het bestand, naast services::

networks:
  proxy:
    external: true

De naam van de certificaat-resolver moet overeenkomen met de naam die in uw Traefik-configuratie is gedefinieerd, en loadbalancer.server.port is de containerpoort 3010, nooit een hostpoort. Traefik proxiet WebSocket-verbindingen zonder extra configuratie, dus er hoeft niets meer te worden toegevoegd. Als de rest van uw stack al achter Authentik voor single sign-on staat, zal een forward auth-middleware op deze router de browsertoegang tot AFFiNE afschermen. Schakel dit echter pas in nadat u de desktop-app heeft getest; deze beschikt niet over een browsersessie en zal simpelweg niet synchroniseren. Het draaien van meerdere applicaties achter één instantie wordt behandeld in één Traefik voor meerdere applicaties.

Bij nginx moet u expliciet om de upgrade vragen:

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 staat in nginx standaard op 1 MB. Zonder deze regel mislukt elke upload die groter is dan een kleine foto met een 413-status. Er verschijnt niets in de AFFiNE-logs, omdat het verzoek nooit is aangekomen. Caddy heeft slechts één regel nodig, reverse_proxy http://127.0.0.1:3010, en regelt certificaten en WebSocket-upgrades zelf.

Wat de self-hosted build niet bevat

Wees eerlijk tegen uzelf voordat u een team laat overstappen.

Real-time samenwerking is aanwezig en dit is de functie waar alle adviezen over schaalgrootte op gebaseerd zijn, aangezien de documentatie van AFFiNE het geheugengebruik toeschrijft aan het synchronisatiesysteem en het samenvoegen van documenten. Offline bewerken is de reden waarom veel mensen een local-first tool willen, en de desktopapplicatie kan uw self-hosted server toevoegen aan de werkruimtelijst en inloggen op de server. Test het exacte offline gedrag waar uw team afhankelijk van is voordat u een besluit neemt: bewerk iets in de desktop-app zonder netwerkverbinding, maak opnieuw verbinding en controleer het resultaat op een tweede apparaat. Functielijsten zijn geen bewijs, en dat geldt ook voor deze lijst.

Full-text search aan de serverzijde staat uit in het meegeleverde compose-bestand, waarbij AFFINE_INDEXER_ENABLED=false is ingesteld op de server en op de migratietaak. Dit inschakelen betekent het toevoegen van een Manticore Search-container, wat een vijfde service en meer geheugen vereist. Op een 2 GB-server is dit de wijziging die ervoor zorgt dat u over de limiet heen gaat. Zoeken binnen de client werkt nog steeds voor de werkruimte die u geopend heeft.

Twee limieten zijn belangrijk om te weten voordat u mensen uitnodigt. Een self-hosted werkruimte krijgt maximaal 10 licenties; voor meer gebruikers is een Team-licentie van AFFiNE vereist. Onbeperkte blob-opslag en onbeperkte blob-grootte voor self-hosted instanties worden in de documentatie beschreven als beoogd, maar zijn nog niet volledig geïmplementeerd (gecontroleerd in oktober 2026). Geen van beide is van belang voor een huishouden of een klein team. Beide zijn wel van belang als u van plan was om veertig mensen te laten overstappen.

Upgrades

Lees eerst de release notes, zeker bij een kleine versie-update zoals 0.26 naar 0.27, aangezien hierin vaak ingrijpende wijzigingen staan. Maak een back-up van de database en de opslagmap voordat u actie onderneemt; de migratietaak wijzigt namelijk het schema bij de volgende start en dit proces kan niet ongedaan worden gemaakt. Wijzig vervolgens de vastgezette digest, voer docker compose pull uit gevolgd door docker compose up -d, en monitor docker compose logs -f affine_migration totdat het proces correct wordt afgesloten. docker image prune verwijdert daarna de oude lagen. Een historische opmerking voor gebruikers met een zeer oude installatie: vanaf versie 0.23.0 is de naam van de image gewijzigd van affine-graphql naar affine. Een compose-bestand dat ouder is dan deze versie moet daarom worden aangepast voordat een pull succesvol kan zijn. Vanaf versie 0.27.4 zijn in het officiële compose-template de paden voor Postgres, uploads en configuratie verplaatst en is de standaard databaseverbinding gewijzigd. Vergelijk daarom het nieuwe bestand met uw huidige configuratie in plaats van het simpelweg over een werkende installatie heen te kopiëren.

FAQ

Waarom start de AFFiNE-container nooit?

De affine-service declareert condition: service_completed_successfully voor de affine_migration-taak. Als de migratie eindigt met een andere status dan 0, wordt de server nooit gestart en verschijnt de webinterface niet. Voer docker compose logs affine_migration uit om te zien bij welke stap het proces stopte. Controleer of een handmatig aangepast compose-bestand nog steeds pgvector/pgvector:pg16 gebruikt: de standaard Postgres-image bevat niet de pgvector-extensie die het schema van AFFiNE vereist, ook al definieert v0.27.4 niet langer de vier embedding-modellen die in v0.27.3 aanwezig waren.

Hoeveel RAM heeft zelfgehoste AFFiNE nodig?

De vereistenpagina van AFFiNE vraagt om minimaal 4 CPU-cores en 2 GB RAM. Dit loopt op naar 4 GB wanneer documenten meer dan 10.000 woorden bevatten. Het samenvoegen van een document met 10.000 wijzigingen kan een piek van 1 GB veroorzaken. Op een server met 2 GB RAM is die piek de oorzaak van problemen, niet de rustige belasting: de out-of-memory killer van de kernel kiest een proces om te stoppen, meestal de AFFiNE-server omdat dit het grootste proces is. restart: unless-stopped start het vervolgens opnieuw, waardoor gebruikers een paginaverversing zien in plaats van een foutmelding. Bevestig dit met docker inspect affine_server --format '{{.State.OOMKilled}}' en sudo dmesg -T | grep -i 'out of memory', voeg daarna een swap-bestand van 2 GB toe als buffer voor korte pieken, en upgrade naar 4 GB RAM als de processen blijven worden beëindigd.

Waar slaat AFFiNE mijn gegevens op en wat moet ik back-uppen?

Drie paden onder uw compose-directory bevatten alles: ./data/postgres voor de database, ./data/storage voor geüploade bestanden en ./config voor config.json en de gegenereerde private.key. Maak een back-up van de database met docker compose exec -T postgres pg_dump --format c --username affine affine > affine.dump in plaats van de bestanden te kopiëren, omdat een actieve Postgres-database niet veilig gekopieerd kan worden. Die dump bevat ook alle instellingen die in het admin-paneel zijn opgeslagen, aangezien AFFiNE deze in de database bewaart. Gebruik tar voor ./data/storage voor de uploads en bewaar de gehele config-directory, het Compose-bestand en .env, omdat deze bestanden geen deel uitmaken van de database.

Werkt real-time samenwerking op een zelfgehoste AFFiNE?

Ja, en hiervoor hoeft niets ingeschakeld te worden. De enige vereiste is uw reverse proxy, omdat synchronisatie verloopt via WebSocket-verbindingen. Op nginx betekent dit proxy_http_version 1.1 plus de Upgrade en Connection: upgrade-headers, terwijl Traefik en Caddy deze verbindingen zonder extra configuratie doorlaten. Het symptoom van een proxy die deze niet upgradet, is een werkruimte die normaal laadt en inlogt, terwijl wijzigingen die in de ene browser worden gemaakt, nooit in de andere verschijnen.

Kan ik AFFiNE draaien met een standaard Postgres-image?

Gebruik pgvector/pgvector:pg16, wat Postgres 16 is met de pgvector-extensie ingebouwd. AFFiNE v0.27.4 declareert nog steeds extensions = [pgvector(map: "vector")] in schema.prisma, maar definieert niet langer de vier modellen met vector(1024) embedding-kolommen die in v0.27.3 aanwezig waren. De standaard Postgres-image bevat de gedeclareerde extensie niet. Als u AFFiNE naar een externe Postgres-server laat wijzen, installeer dan pgvector op die server en maak de extensie aan in de doeldatabase voordat u de migratie uitvoert.

Was dit artikel nuttig?