Self-host AFFiNE con Docker Compose: guida completa
Configura AFFiNE su un VPS con Docker Compose: 4 container, tag delle immagini, dati persistenti, backup e limiti reali di un server con 2 GB di RAM.
Cosa si ottiene con il self-hosting di AFFiNE
Il self-hosting di AFFiNE offre un workspace in stile Notion su un server sotto il tuo controllo. L'installazione viene eseguita tramite quattro container: l'applicazione, un job di migrazione eseguito una sola volta, Postgres e Redis. La collaborazione in tempo reale è inclusa, fino alle 10 postazioni disponibili per impostazione predefinita in un workspace self-hosted. L'installazione richiede un solo file Compose e un solo file di configurazione JSON. Gli aspetti da valutare sono i tag delle immagini, la struttura del disco, il limite di memoria e il proxy da mettere davanti all'applicazione.
AFFiNE integra un editor di documenti e una canvas infinita nello stesso workspace. Una pagina può quindi essere letta come documento oppure sviluppata come lavagna. Se stai ancora valutando cosa eseguire, consulta prima il confronto tra le alternative self-hosted a Notion. Questa guida presuppone che la scelta sia già stata fatta e descrive come eseguire AFFiNE correttamente, senza riproporre il confronto.
Tutto il contenuto è stato verificato sulla documentazione ufficiale del self-hosting di AFFiNE e sui file di release pubblicati l'8 agosto 2026. La release stabile più recente a quella data era la 0.27.3, pubblicata il 23 luglio 2026. Le affermazioni riportate di seguito con una data successiva sono state ricontrollate sulle relative fonti primarie il 12 ottobre 2026, quando la release stabile più recente era la 0.27.4, pubblicata il 18 agosto 2026.
Cosa fanno realmente i quattro container
affine contiene il server e il client web nella stessa immagine. È in ascolto sulla porta 3010.
affine_migration è un job eseguito una sola volta. Esegue node ./scripts/self-host-predeploy.js, applica le migrazioni del database e termina. L'applicazione dichiara condition: service_completed_successfully come dipendenza da questo job. Se una migrazione termina con uno stato diverso da zero, affine non viene mai avviato. Se l'interfaccia web non si avvia, il log di questo job è il primo elemento da controllare.
postgres contiene documenti, utenti, workspace e autorizzazioni. L'immagine fornita è pgvector/pgvector:pg16, ovvero Postgres 16 standard con l'estensione pgvector compilata al suo interno. pgvector aggiunge a Postgres un tipo di colonna vector. Si tratta del formato numerico usato per memorizzare gli embedding, in modo da poter cercare il testo in base al significato.
redis è una dipendenza obbligatoria: sia il server sia il job di migrazione attendono il relativo health check prima di avviarsi. Notare che il file compose fornito non assegna a Redis alcun volume. Nulla al suo interno sopravvive a un docker compose down. Questo indica chiaramente che Redis non contiene dati personali e non richiede backup.
Perché l’immagine Postgres è pgvector e non postgres standard
Il requisito deriva dallo schema di AFFiNE, non da una preferenza. In v0.27.4, schema.prisma dichiara ancora extensions = [pgvector(map: "vector")], ma non contiene colonne per gli embedding. I quattro modelli con colonne embedding di tipo vector(1024) presenti in v0.27.3 non sono presenti in v0.27.4. Mantieni l’immagine pgvector/pgvector:pg16 fornita: l’estensione è ancora dichiarata e postgres:16 standard non la include.
Il template ufficiale di v0.27.4 usa l’immagine pgvector; il template v0.21.0 usava ancora postgres:16. In un’installazione precedente, modificare la riga dell’immagine non è sufficiente per completare l’aggiornamento. Prima di eseguire il pull, consulta quindi la pagina sull’aggiornamento nella documentazione self-host di AFFiNE.
Un’ultima informazione su quel tag. pg16 indica Postgres 16 e la versione major di Postgres non è un numero che puoi incrementare direttamente. Se lo cambi in pg17 mantenendo una directory dati esistente, Postgres rifiuta di avviarsi e in docker compose logs postgres compare una riga simile a The data directory was initialized by PostgreSQL version 16, which is not compatible with this version 17. Il passaggio a una nuova versione major richiede una delle tre procedure indicate nelle note di rilascio di PostgreSQL 17: esportare i dati e ripristinarli in una nuova directory dati, usare pg_upgrade oppure configurare la replica logica. In una singola installazione Compose, l’esportazione e il ripristino sono di solito la soluzione più semplice, perché pg_upgrade richiede che i binari del server vecchio e di quello nuovo siano disponibili contemporaneamente.
Di quanta CPU e RAM ha bisogno AFFiNE self-hosted
La pagina dei requisiti di AFFiNE richiede almeno 4 core CPU e 2 GB di RAM, aumentando il requisito di memoria a 4 GB quando i documenti superano 10,000 parole. La stessa pagina specifica dove viene utilizzata la memoria: il sistema di sincronizzazione e l'unione dei documenti. Riporta anche un dato da ricordare: l'unione di un documento con 10,000 modifiche può raggiungere un picco di 1 GB.
Consideriamo ora questo dato nel caso di un piano da 2 GB utilizzato da due persone per la scrittura. Il consumo medio non è un problema. Postgres e il processo Node restano sotto il limite, con memoria disponibile. Il problema è il picco. Una singola unione di grandi dimensioni può portare il consumo di memoria del server a circa 1 GB. Su un server da 2 GB senza swap, questo picco, sommato a Postgres e agli altri processi residenti, può esaurire la memoria. Il kernel attiva quindi l'out-of-memory (OOM) killer, che termina un processo per liberare memoria. Il server AFFiNE, essendo il processo più grande, è il candidato più probabile, anche se la documentazione Docker chiarisce che può essere scelto qualsiasi processo, incluso Docker stesso.
Quando viene terminato il server AFFiNE, il collega non visualizza un errore. Vede il ricaricamento della pagina, perché restart: unless-stopped riporta il container in esecuzione entro pochi secondi. Non fare ipotesi: verifica:
docker inspect affine_server --format '{{.State.OOMKilled}} {{.RestartCount}}'
sudo dmesg -T | grep -i -E 'out of memory|killed process'true dal primo comando, oppure una riga Killed process che indica node dal secondo comando, significa che la memoria è esaurita e non che è stato rilevato un bug. Risolvi il problema su entrambi i fronti. Aggiungi prima lo swap, così un picco dispone di un'area in cui riversarsi prima che intervenga l'OOM killer:
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 dovrebbe ora riportare un totale di swap pari a 2.0Gi. Lo swap non rende AFFiNE più veloce e non è questo il suo scopo. Offre un'area temporanea in cui assorbire un picco, rendendo molto più probabile che il picco causi un secondo di lentezza invece di un container terminato. È un buffer, non una garanzia. L'altro intervento consiste nell'impedire a Postgres di espandere la propria cache nello spazio necessario all'applicazione durante l'unione. A questo servono i limiti di memoria su un servizio Compose. Se i processi continuano a essere terminati anche dopo entrambi gli interventi, il server necessita dei 4 GB richiesti dalla pagina dei requisiti di AFFiNE per i documenti più grandi.
Lo spazio di archiviazione è molto più facile da prevedere. Queste sono le cifre pubblicate da AFFiNE nella stessa pagina:
I dati alla base di questo grafico
[
{
"label": "Server install",
"gb": 1.5
},
{
"label": "Postgres per 1,000 docs",
"gb": 0.1
},
{
"label": "Blob store per 1,000 uploads",
"gb": 10
}
]L'installazione del server occupa 1.5 GB. Mille documenti di circa mille parole ciascuno aggiungono 0.1 GB di dati Postgres, una quantità quasi trascurabile. Mille file caricati aggiungono 10 GB, che rappresentano l'intero consumo rilevante. Si tratta di valori pubblicati per la pianificazione, non di misurazioni eseguite su un'istanza in esecuzione. Considerali quindi come un'indicazione della proporzione, non come una garanzia. È la proporzione che conta: il database resta di dimensioni ridotte, mentre sono i file caricati a determinare lo spazio su disco.
Scrivi personalmente il file Compose, fissando i tag
L'installazione documentata scarica un file già pronto con curl -L -o docker-compose.yml https://github.com/toeverything/AFFiNE/releases/latest/download/docker-compose.yml. Funziona. Prima di farvi affidamento, però, è utile conoscere un dettaglio: all'8 agosto 2026 il file allegato alla release 0.27.3 leggeva ancora i percorsi da un file .env, usando ${UPLOAD_LOCATION}, ${CONFIG_LOCATION} e ${DB_DATA_LOCATION}, mentre la pagina di riferimento della documentazione mostrava una struttura più recente, che colloca lo storage e i dati PostgreSQL sotto ./data, mantiene la configurazione sotto ./config e non richiede affatto .env. La release 0.27.4 ha spostato il file allegato a questa struttura e, al 12 ottobre 2026, i due file corrispondono. Se hai installato il sistema usando il file precedente, i percorsi provengono ancora da .env. La pagina di aggiornamento di AFFiNE avverte che sostituire il file Compose senza trasferire queste impostazioni può avviare Postgres con una directory dati vuota. Scrivere personalmente il file elimina completamente questo problema. Inoltre, devi comunque modificarlo per fissare le immagini e impostare una password per il database.
mkdir -p ~/affine/config ~/affine/data
cd ~/affine
printf 'DB_PASSWORD=%s\n' "$(openssl rand -hex 24)" > .env
chmod 600 .envCompose legge autonomamente .env dalla directory del progetto e sostituisce ${DB_PASSWORD} al suo posto. In questo modo la password non compare nel file che incolleresti in una discussione di supporto. È una pratica da mantenere per ogni stack che esegui. Il motivo è spiegato in mantenere i secret fuori dal file Compose.
Ora scrivi ~/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-stoppedRispetto al file distribuito upstream ci sono quattro differenze. Ognuna ha una motivazione.
127.0.0.1:3010:3010pubblica la porta soltanto sull'indirizzo di loopback. Le versioni di Docker precedenti alla 28.0.0 consentono agli host dello stesso segmento L2 di raggiungere le porte pubblicate su localhost. Inoltre, il routing diretto configurato può esporre la porta del container nonostante la pubblicazione su loopback. Usa Docker 28.0.0 o una versione successiva e mantieni disabilitato il routing diretto durante la configurazione. L''3010:3010'distribuito upstream esegue il bind su tutte le interfacce. Nella maggior parte delle immagini VPS questo include anche l'interfaccia pubblica.POSTGRES_HOST_AUTH_METHOD: trustè stato rimosso e al suo posto viene impostata una password. L'autenticazione trust accetta qualsiasi connessione a quel database come utenteaffine, senza password. È limitata alla rete privata Compose, ma questo diventa un problema se in seguito aggiungi un altro container a quella rete o pubblichi la porta 5432 durante il troubleshooting.redis:8-alpinesostituisce un sempliceredis, che risolve inlatest. Ad agosto 2026 si tratta di Redis 8. Il pin mantiene quindi la major version verificata e impedisce che Redis 9 venga installato durante undocker compose pullnon correlato.pgvector/pgvector:pg16rimane esattamente come impostato da upstream, per il motivo indicato sopra.
POSTGRES_PASSWORD viene letto soltanto quando Postgres crea per la prima volta la directory dati. Su un'istanza già esistente, imposta la password con docker compose exec postgres psql -U affine -c "ALTER USER affine WITH PASSWORD 'yourpassword'" e poi aggiorna DATABASE_URL in modo che corrisponda.
La configurazione si trova in config/config.json
AFFiNE legge le impostazioni da config/config.json, cioè dalla directory montata in /root/.affine/config. Il file non viene creato automaticamente, quindi è necessario scriverlo prima del primo avvio. Aprire ~/affine/config/config.json in un editor e inserire questo contenuto, sostituendo il dominio di esempio con il proprio:
{
"$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 deve essere l'indirizzo che gli utenti aprono effettivamente nel browser. AFFiNE usa questo valore per creare i link di condivisione e gli inviti agli spazi di lavoro. Se viene lasciato su http://localhost:3010, l'invito inviato indirizza il destinatario alla propria macchina e non funziona. Impostarlo sull'indirizzo HTTPS pubblico prima del primo avvio, in modo che il file e il pannello di amministrazione riportino sempre lo stesso valore. Le impostazioni modificate successivamente nel pannello di amministrazione vengono salvate nel database e non vengono riscritte in questo file.
copilot controlla le funzionalità di intelligenza artificiale. copilot.byok.enabled abilita l'uso di una chiave propria e consente al proprietario di uno spazio di lavoro di inserire la chiave del proprio provider di modelli nelle impostazioni dello spazio di lavoro. L'installazione autonoma di AFFiNE non include un abbonamento per le funzionalità di intelligenza artificiale. Lasciare entrambi su false se non si desidera usarle.
Avviare lo stack:
docker compose up -d
docker compose ps --alldocker compose ps --all dovrebbe indicare affine_postgres e affine_redis come integri, affine_server come in esecuzione e affine_migration_job con lo stato exited (0). L'opzione --all è importante: senza di essa, docker compose ps mostra soltanto i container in esecuzione, quindi un job di migrazione completato correttamente non viene visualizzato. Qualsiasi altro codice di uscita del job di migrazione richiede un controllo approfondito; il relativo log indica il passaggio in cui l'esecuzione si è interrotta:
docker compose logs affine_migrationBlocca l'immagine prima di dimenticartene
stable è un tag mobile. Il flusso di rilascio di AFFiNE assegna diversi tag a ogni build stabile. Qui ne interessano due: stable, che viene riassegnato a ogni release, e stable- seguito dall'hash breve di git, che invece non cambia. Se lasci stable, un comando docker compose pull eseguito tra sei mesi scaricherà un'immagine diversa ed eseguirà le relative migrazioni sul database in un momento che non hai scelto. Blocca l'immagine esatta che hai testato:
docker compose pull
docker image inspect ghcr.io/toeverything/affine:stable --format '{{index .RepoDigests 0}}'Il comando stampa una riga simile a ghcr.io/toeverything/affine@sha256:, seguita da un hash lungo. Copia l'intera stringa nella riga image: di entrambi affine e affine_migration. I due valori devono sempre corrispondere, perché rappresentano la stessa immagine usata in due ruoli diversi. Se non corrispondono, il database viene migrato a uno schema mentre il servizio lo utilizza con un altro. L'aggiornamento diventa così un'operazione deliberata, non una sorpresa: modifica il digest, esegui il backup, docker compose pull, docker compose up -d.
Crea l'account amministratore prima di chiunque altro
Apri /admin su un'istanza appena installata: AFFiNE ti indirizza a una pagina per la creazione dell'account, perché sul server non esiste ancora alcun amministratore. In questo flusso non sono presenti né un codice di invito né un token di configurazione. La prima persona che completa la registrazione diventa l'amministratore del server, quindi la porta deve rimanere chiusa finché non hai completato la registrazione.
Per questo il file Compose precedente esegue il binding su 127.0.0.1. Raggiungilo tramite un tunnel SSH dal tuo computer:
ssh -L 3010:127.0.0.1:3010 you@your-server-ipLascia il tunnel attivo e apri http://127.0.0.1:3010/admin nel browser locale. Registrati ed esegui l'accesso, quindi chiudi il tunnel. Solo a questo punto è sicuro pubblicare l'istanza con un nome pubblico. La stessa situazione si verifica in altre applicazioni self-hosted, ed è ancora più critica quando il primo accesso crea una passkey associata al nome host. Per questo TLS e dominio definitivo devono essere configurati prima di creare il primo account quando ospiti autonomamente openGym.
Dove AFFiNE conserva i dati
Tre percorsi contengono tutti i dati e si trovano nella directory creata.
./data/postgresè la directory dei dati di Postgres: documenti, utenti, workspace, autorizzazioni e impostazioni del server salvate dal pannello di amministrazione../data/storageè montato in/root/.affine/storagenel container e contiene tutti i file caricati../configè montato in/root/.affine/confige contieneconfig.jsoneprivate.keygenerati dal job di migrazione.
Il progetto upstream usa qui bind mount invece di volumi denominati. La scelta è intenzionale: puoi archiviare e copiare questi percorsi con i normali comandi, senza dover chiedere a Docker dove li ha collocati. Lo svantaggio è che la proprietà dei file sull'host diventa una tua responsabilità. Questo è il compromesso descritto in bind mount e volumi denominati.
Come eseguire il backup di AFFiNE
È necessario eseguire il backup di due elementi, con procedure diverse. Il database è un server attivo, quindi copiarne i file mentre è in esecuzione produce una copia corrotta. È invece necessario eseguire un 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/Il dump viene eseguito all’interno del container tramite il relativo socket locale, quindi non richiede la password. Controllare le dimensioni nell’output di ls. Un file di poche centinaia di byte indica che il dump non è riuscito, anche se la shell ha creato comunque il file. Questo errore viene spesso rilevato solo sei mesi dopo. Anche -T è importante: senza questa opzione, Compose può allocare un terminale e corrompere il flusso binario.
I file caricati sono normali file, quindi è possibile archiviarli con tar:
tar czf backup/storage-$(date +%F).tgz -C data storage
tar czf backup/config-$(date +%F).tgz config docker-compose.yml .envConservare nel backup l’intera directory config, il file Compose e .env, perché il dump non li contiene. Il job di migrazione crea inoltre config/private.key, quindi copiare soltanto config.json esclude quel file. Le impostazioni salvate nel pannello di amministrazione sono memorizzate nel database, quindi il dump precedente le include già. Dal 12 ottobre 2026, la pagina di backup di AFFiNE indica inoltre che le impostazioni del server modificate possono essere esportate dal pannello di amministrazione. Copiare tutti e tre i file fuori dal server. Un backup archiviato sullo stesso disco dei dati che protegge non è un backup. Questa separazione tra dump del database e archivio tar della directory degli upload è il modello da ripetere per ogni altro container stateful in esecuzione. È lo stesso approccio che protegge la cronologia delle conversazioni e gli allegati quando si esegue il self-hosting di Chatwoot come sistema di assistenza.
Ripristino e una trappola nei passaggi pubblicati
Leggete i passaggi ufficiali per il ripristino prima che servano e controllateli con attenzione. Nella versione pubblicata ad agosto 2026 veniva copiato nel container un file chiamato affine.backup, per poi eseguire il ripristino da ./pg.backup: sono due nomi diversi. Inoltre, veniva rimossa una directory ./postgres, mentre il file Compose corrente conserva i dati in ./data/postgres. Dal 12 ottobre 2026 la pagina usa affine.backup in tutti i passaggi e specifica di conservare la vecchia directory PostgreSQL finché il ripristino non è stato verificato. Il problema è quindi stato corretto a monte, ma una copia dei passaggi salvata prima di quella data lo contiene ancora. In ogni caso, seguite i percorsi che avete effettivamente usato, non quelli presenti in uno snippet. Ecco la sequenza per la struttura descritta in questa guida:
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 -dNotate mv invece di rm. Eseguire il ripristino sopra un database di cui non avete conservato una copia è il modo in cui un comando errato può causare la perdita totale dei dati. Spostare temporaneamente la vecchia directory non costa nulla. Ripristinate anche gli upload con tar xzf backup/storage-2026-08-08.tgz -C data, altrimenti ogni documento verrà visualizzato con allegati non disponibili. Quindi accedete all'applicazione e aprite un documento che contiene un'immagine. Questo è il test. Un ripristino che non avete aperto in un browser è un file, non un backup.
Mettere AFFiNE dietro un proxy già in uso
AFFiNE usa WebSocket e non è un'opzione facoltativa. La documentazione è chiara: WebSocket è alla base del sistema di sincronizzazione e collaborazione di AFFiNE. Un proxy che non esegue l'upgrade delle connessioni lascia quindi un workspace in cui le modifiche smettono di essere sincronizzate senza messaggi evidenti. La pagina viene caricata e l'accesso funziona, ma una modifica effettuata in un browser non raggiunge l'altro. Negli strumenti per sviluppatori del browser, apri la scheda Network e filtra per WS. Una connessione che si apre e si chiude ripetutamente indica che il proxy non inoltra l'upgrade.
Se usi già Traefik per altri container, AFFiNE si aggiunge come un normale servizio. Elimina il blocco ports: dal servizio affine, quindi aggiungi:
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'e, in fondo al file, accanto a services::
networks:
proxy:
external: trueIl nome del certificate resolver deve corrispondere a quello definito nella configurazione di Traefik, mentre loadbalancer.server.port è la porta del container 3010, mai una porta dell'host. Traefik esegue il proxy delle connessioni WebSocket senza configurazione aggiuntiva, quindi non devi aggiungere altro. Se il resto dello stack è già protetto da Authentik per il single sign-on, un middleware forward auth su questo router limiterà l'accesso ad AFFiNE tramite browser. Lascialo però disattivato finché non hai testato l'app desktop, che non dispone di una sessione del browser e semplicemente non riuscirà a sincronizzarsi. La gestione di più app dietro una singola istanza è descritta in un singolo Traefik davanti a più app.
Con nginx devi richiedere esplicitamente l'upgrade:
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;
}In nginx client_max_body_size ha un valore predefinito di 1 MB. Senza quella riga, quindi, ogni upload più grande di una foto di piccole dimensioni fallisce con stato 413 e nei log di AFFiNE non compare nulla, perché la richiesta non è mai arrivata. Caddy richiede una sola riga, reverse_proxy http://127.0.0.1:3010, e gestisce autonomamente certificati e upgrade WebSocket.
Cosa esclude la build self-hosted
Prima di trasferire un team, valuta con obiettività questi limiti.
La collaborazione in tempo reale è disponibile ed è la funzionalità a cui si riferiscono tutte le indicazioni sul dimensionamento, perché la documentazione di AFFiNE attribuisce il consumo di memoria al sistema di sincronizzazione e all'unione dei documenti. La modifica offline è il motivo per cui molte persone scelgono uno strumento local-first, e l'applicazione desktop può aggiungere il server self-hosted all'elenco delle aree di lavoro ed effettuare l'accesso su quel server. Prima di procedere, verifica il comportamento offline esatto da cui dipende il team: modifica un documento nell'applicazione desktop con la rete disattivata, riconnettiti, quindi controlla il risultato su un secondo dispositivo. Gli elenchi delle funzionalità non costituiscono una prova, incluso questo elenco.
La ricerca full-text lato server è disabilitata nel file compose fornito, dove AFFINE_INDEXER_ENABLED=false è impostato sul server e sul job di migrazione. Per abilitarla devi aggiungere un container Manticore Search, che porta il numero dei servizi a cinque e aumenta il consumo di memoria. Su un server da 2 GB, questa è la modifica che fa superare il limite. La ricerca all'interno del client continua a funzionare nell'area di lavoro aperta.
Prima di invitare altre persone, considera due limiti. Un'area di lavoro self-hosted può avere al massimo 10 utenti, e per superare questo limite serve una licenza Team di AFFiNE. La documentazione descrive lo spazio di archiviazione blob illimitato e la dimensione illimitata dei blob per le istanze self-hosted come funzionalità previste ma non ancora completamente implementate, secondo la verifica effettuata a ottobre 2026. Nessuno dei due limiti è rilevante per una famiglia o per un piccolo team. Entrambi diventano rilevanti se prevedi di trasferire quaranta persone.
Aggiornamenti
Leggere prima le note di rilascio, soprattutto per un aggiornamento di versione minore come da 0.26 a 0.27, perché può introdurre modifiche incompatibili. Eseguire il backup del database e della directory di storage prima di procedere: al successivo avvio, il job di migrazione modifica lo schema e non è possibile annullare l’operazione. Modificare quindi il digest fissato, eseguire docker compose pull seguito da docker compose up -d e monitorare docker compose logs -f affine_migration finché non termina correttamente. In seguito, docker image prune rimuove i layer obsoleti. Una nota storica per chi usa un’installazione molto datata: dalla versione 0.23.0 il nome dell’immagine è cambiato da affine-graphql a affine. Di conseguenza, in un file Compose precedente a quella versione è necessario riscrivere le righe relative all’immagine prima che un pull possa trovare l’immagine. Dalla versione 0.27.4, inoltre, il template Compose ufficiale ha spostato i percorsi di Postgres, degli upload e della configurazione e ha modificato la connessione predefinita al database. Confrontare quindi il nuovo file con quello in uso invece di sovrascrivere un’installazione funzionante.
FAQ
Perché il container AFFiNE non si avvia mai?
Il servizio affine dichiara condition: service_completed_successfully per il job affine_migration. Se la migrazione termina con uno stato diverso da 0, il server non viene mai avviato e l’interfaccia Web non appare. Esegui docker compose logs affine_migration per vedere quale passaggio si è interrotto. Verifica che un file Compose modificato manualmente usi ancora pgvector/pgvector:pg16: Postgres standard non include l’estensione pgvector, dichiarata dallo schema di AFFiNE anche se v0.27.4 non definisce più i quattro modelli di embedding presenti in v0.27.3.
Quanta RAM richiede AFFiNE self-hosted?
La pagina dei requisiti di AFFiNE indica almeno 4 core CPU e 2 GB di RAM. Il requisito sale a 4 GB quando i documenti superano 10,000 parole. La pagina segnala inoltre che l’unione di un documento con 10,000 modifiche può raggiungere un picco di 1 GB. Su un server con 2 GB, il problema è questo picco, non il carico a riposo: il killer OOM del kernel interrompe un processo, molto probabilmente il server AFFiNE perché è il processo più grande, e restart: unless-stopped lo avvia di nuovo. Gli utenti vedono quindi un nuovo caricamento della pagina invece di un errore. Conferma la causa con docker inspect affine_server --format '{{.State.OOMKilled}}' e sudo dmesg -T | grep -i 'out of memory', quindi aggiungi un file di swap da 2 GB come riserva contro i picchi brevi. Passa a 4 GB di RAM se le terminazioni continuano.
Dove archivia AFFiNE i miei dati e di cosa devo eseguire il backup?
Tre percorsi sotto la directory Compose contengono tutti i dati: ./data/postgres per il database, ./data/storage per i file caricati e ./config per config.json e il private.key generato. Esegui il backup del database con docker compose exec -T postgres pg_dump --format c --username affine affine > affine.dump invece di copiare i file, perché un’istanza Postgres in esecuzione non può essere copiata in modo sicuro. Il dump include anche le impostazioni salvate nel pannello di amministrazione, perché AFFiNE le archivia nel database. Crea un archivio tar di ./data/storage per i file caricati e conserva l’intera directory config, il file Compose e .env, perché questi file non fanno parte del database.
La collaborazione in tempo reale funziona con AFFiNE self-hosted?
Sì e non è necessario abilitarla. L’unico requisito riguarda il reverse proxy, perché la sincronizzazione usa connessioni WebSocket. Con nginx questo richiede proxy_http_version 1.1 e gli header Upgrade e Connection: upgrade. Traefik e Caddy inoltrano queste connessioni senza configurazione aggiuntiva. Se il proxy non esegue l’upgrade delle connessioni, l’area di lavoro viene caricata e l’accesso funziona normalmente, ma le modifiche effettuate in un browser non vengono mai visualizzate negli altri.
Posso eseguire AFFiNE con un’immagine Postgres standard?
Usa pgvector/pgvector:pg16, che contiene Postgres 16 con l’estensione pgvector compilata. AFFiNE v0.27.4 dichiara ancora extensions = [pgvector(map: "vector")] in schema.prisma, ma non definisce più i quattro modelli con colonne di embedding vector(1024) presenti in v0.27.3. Postgres standard non include l’estensione dichiarata. Se invece colleghi AFFiNE a un server Postgres esterno, installa pgvector sul server e crea l’estensione nel database di destinazione prima di eseguire la migrazione.