Docker Compose తో AFFiNE self-host ఎలా చేయాలి
ఒక VPSలో Docker Composeతో AFFiNE నడపండి: నాలుగు containers, pinned image tags, data నిల్వ స్థానం, backups, అలాగే 2 GB RAM వాస్తవంగా సరిపడే పరిమితులు తెలుసుకోండి.
self-host AFFiNE చేసినప్పుడు మీకు లభించేది
self-hosting AFFiNE ద్వారా మీరు నియంత్రించే server పై Notion తరహా workspace లభిస్తుంది. ఇది నాలుగు containers గా నడుస్తుంది: application, one-shot migration job, Postgres, మరియు Redis. Real-time collaboration కూడా ఉంటుంది. self-hosted workspace కు default గా లభించే 10 seats వరకు ఇది మద్దతు ఇస్తుంది. Installation కోసం ఒక compose file మరియు ఒక JSON config file సరిపోతాయి. అయితే image tags, disk layout, memory ceiling, అలాగే ముందుభాగంలో ఉంచే proxy గురించి నిర్ణయాలు తీసుకోవాలి.
AFFiNE ఒకే workspace లో document editor మరియు infinite canvas ను అందిస్తుంది. అందువల్ల ఒక page ను document గా చదవవచ్చు లేదా whiteboard లా విస్తరించవచ్చు. మీరు ఇంకా ఏది నడపాలో నిర్ణయించకపోతే ముందుగా self-hosted Notion ప్రత్యామ్నాయాల పోలిక చదవండి. ఈ guide లో ఎంపిక ఇప్పటికే పూర్తయిందని భావిస్తున్నాం. మళ్లీ పోల్చడం కాకుండా AFFiNE ను సక్రమంగా నడపడం గురించి ఇది వివరిస్తుంది.
ఇక్కడి సమాచారం మొత్తం AFFiNE self-host documentation మరియు 8 August 2026 న ప్రచురించబడిన release files ఆధారంగా తనిఖీ చేయబడింది. ఆ తేదీన తాజా stable release 0.27.3. ఇది 23 July 2026 న ప్రచురించబడింది. తరువాతి తేదీ ఉన్న కింది వివరాలను 12 October 2026 న వాటి primary sources ఆధారంగా మళ్లీ తనిఖీ చేశాం. ఆ సమయంలో తాజా stable release 0.27.4. ఇది 18 August 2026 న ప్రచురించబడింది.
నాలుగు containers వాస్తవంగా చేసే పని
affine ఒకే imageలో server మరియు web client రెండింటినీ అందిస్తుంది. ఇది port 3010పై listening చేస్తుంది.
affine_migration ఒకసారి మాత్రమే అమలయ్యే job. ఇది node ./scripts/self-host-predeploy.js ను అమలు చేసి, database migrations ను వర్తింపజేసి, ఆపై exit అవుతుంది. Application ఈ jobపై condition: service_completed_successfully ను ప్రకటిస్తుంది. అందువల్ల migration non-zero statusతో exit అయితే affine అసలు start కాదు. Web interface ప్రారంభం కాకపోతే, ముందుగా ఆ job యొక్క logను చూడాలి.
postgres మీ documents, users, workspaces మరియు permissions ను నిల్వ చేస్తుంది. అందించబడిన image pgvector/pgvector:pg16. ఇందులో pgvector extension compile చేసి ఉన్న సాధారణ Postgres 16 ఉంటుంది. pgvector Postgresకు vector column typeను జోడిస్తుంది. Textను అర్థం ఆధారంగా శోధించేందుకు embeddingsను నిల్వ చేసే numeric రూపం ఇదే.
redis hard dependency. Server మరియు migration job రెండూ start కావడానికి ముందు దాని health check కోసం వేచి ఉంటాయి. అందించబడిన compose file Redisకు volume ఇవ్వదని గమనించండి. అందువల్ల docker compose down తర్వాత దానిలోని ఏదీ మిగలదు. మీకు చెందిన content ఏదీ అందులో నిల్వ ఉండదని, దానికి backup అవసరం లేదని ఇది స్పష్టంగా చెబుతుంది.
Postgres image ఎందుకు pgvector, stock postgres ఎందుకు కాదు
ఈ అవసరం ఒక preference వల్ల కాదు; AFFiNE schema వల్ల వచ్చింది. v0.27.4లో schema.prisma ఇప్పటికీ extensions = [pgvector(map: "vector")] ను ప్రకటిస్తుంది, కానీ embedding columns ఏవీ కలిగి ఉండదు. v0.27.3లో vector(1024) రకంగా టైప్ చేసిన embedding columns కలిగిన నాలుగు models, v0.27.4లో లేవు. అందించిన pgvector/pgvector:pg16 image ను అలాగే ఉంచండి. Extension ఇప్పటికీ ప్రకటించబడింది, కానీ stock postgres:16 లో అది ఉండదు.
అధికారిక v0.27.4 template pgvector image ను ఉపయోగిస్తుంది. v0.21.0 template మాత్రం ఇప్పటికీ postgres:16 ను ఉపయోగించింది. పాత install లో image line ను మార్చడం మాత్రమే upgrade కు సరిపోదు. ఏదైనా pull చేయడానికి ముందు AFFiNE self-host docs లోని upgrade page చదవండి.
ఆ tag గురించి మరో విషయం. pg16 అంటే Postgres 16. Postgres major version ను సాధారణ సంఖ్యలా పెంచలేరు. ఇప్పటికే ఉన్న data directory పై దాన్ని pg17 గా మార్చితే Postgres ప్రారంభం కావడానికి నిరాకరిస్తుంది. అప్పుడు docker compose logs postgres లో The data directory was initialized by PostgreSQL version 16, which is not compatible with this version 17 వంటి line కనిపిస్తుంది. Major version మార్పుకు PostgreSQL 17 release notes పేర్కొన్న మూడు మార్గాల్లో ఒకటి అవసరం: dump తీసుకుని కొత్త data directory లో restore చేయడం, pg_upgrade, లేదా logical replication. ఒకే Compose install లో dump మరియు restore సాధారణంగా సులభమైన మార్గం. ఎందుకంటే pg_upgrade కు పాత మరియు కొత్త server binaries ఒకేసారి పక్కపక్కనే అవసరం.
self-hosted AFFiNE కు ఎంత CPU మరియు RAM అవసరం
AFFiNE requirements page కనీసం 4 CPU cores మరియు 2 GB RAM కోరుతుంది. మీ documents 10,000 words ను మించితే అవసరమైన memoryని 4 GBకు పెంచాలని కూడా అది చెబుతుంది. Memory ఎక్కడ వినియోగమవుతుందో అదే page వివరిస్తుంది: sync system మరియు document merging. గుర్తుంచుకోవాల్సిన ఒక సంఖ్యను అది ఇస్తుంది: 10,000 modifications ఉన్న documentను merge చేస్తున్నప్పుడు memory వినియోగం గరిష్ఠంగా 1 GBకు చేరవచ్చు.
ఇప్పుడు ఇద్దరు వ్యక్తులు రాస్తున్న 2 GB planతో దీన్ని పోల్చండి. సగటు వినియోగం సమస్య కాదు. Postgres మరియు Node process పరిమితి కంటే తక్కువ memoryని ఉపయోగిస్తాయి, కొంత memory మిగులుతుంది. సమస్య peak సమయంలో వస్తుంది. ఒక పెద్ద merge వల్ల server memory వినియోగం సుమారు 1 GB peakకు చేరవచ్చు. Swap లేని 2 GB serverలో ఆ peakతో పాటు Postgres మరియు memoryలో ఉన్న ఇతర processes కలిస్తే మొత్తం memory ఖాళీ అయిపోవచ్చు. అప్పుడు kernel memoryని విడుదల చేయడానికి out-of-memory (OOM) killer ద్వారా ఒక processను terminate చేస్తుంది. AFFiNE server పెద్ద process కావడంతో సాధారణంగా అదే victim అయ్యే అవకాశం ఉంది. అయితే Docker documentation ప్రకారం Dockerతో సహా ఏ processనైనా ఎంచుకోవచ్చు.
AFFiNE server terminate అయినప్పుడు మీ సహోద్యోగికి error కనిపించదు. Page reload అవుతుంది, ఎందుకంటే restart: unless-stopped కొన్ని secondsలో containerను తిరిగి ప్రారంభిస్తుంది. దీన్ని ఊహించకుండా నిర్ధారించండి:
docker inspect affine_server --format '{{.State.OOMKilled}} {{.RestartCount}}'
sudo dmesg -T | grep -i -E 'out of memory|killed process'మొదటి command నుంచి true లేదా రెండో command నుంచి node పేరును చూపించే Killed process line కనిపిస్తే, మీరు bugను కనుగొనలేదు; memory అయిపోయింది. దీన్ని రెండు వైపులా పరిష్కరించండి. ముందుగా swapను జోడించండి. అప్పుడు OOM killer పనిచేయడానికి ముందు spikeను swapలోకి తరలించడానికి buffer ఉంటుంది:
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 మొత్తం 2.0Gi swapను చూపాలి. Swap AFFiNEను వేగంగా చేయదు; దాని ఉద్దేశం కూడా అది కాదు. ఇది తాత్కాలిక spikeకు స్థలం ఇస్తుంది. అందువల్ల dead container కంటే slow second మాత్రమే ఎదురయ్యే అవకాశం ఎక్కువ. ఇది buffer మాత్రమే, guarantee కాదు. పరిష్కారంలోని మరో భాగం merge సమయంలో applicationకు అవసరమైన memoryని Postgres cache కోసం మొత్తం వినియోగించకుండా ఆపడం. Compose serviceపై memory limits ఇందుకోసమే. రెండింటినీ చేసిన తర్వాత కూడా kills కొనసాగితే, పెద్ద documents కోసం AFFiNE requirements page కోరుతున్న 4 GB server అవసరం.
Storageను అంచనా వేయడం చాలా సులభం. అదే pageలో AFFiNE ప్రచురించిన గణాంకాలు ఇవి:
ఈ చార్ట్ వెనుక ఉన్న డేటా
[
{
"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 installకు 1.5 GB అవసరం. సుమారు 1,000 words ఉన్న 1,000 documents జోడిస్తే Postgres dataలో 0.1 GB చేరుతుంది. ఇది దాదాపు ఏమీ కాదు. 1,000 uploaded files జోడిస్తే 10 GB చేరుతుంది. Disk వినియోగాన్ని నిర్ణయించేది ఇదే. ఇవి నడుస్తున్న instance నుంచి తీసిన measurements కాకుండా ప్రచురించిన planning figures. కాబట్టి వీటిని ఖచ్చితమైన హామీగా కాకుండా సాధారణ పరిమాణ అంచనాగా చూడండి. ముఖ్యమైన విషయం ఇదే: మీ database చిన్నగానే ఉంటుంది, కానీ మీ uploads disk వినియోగాన్ని నిర్ణయిస్తాయి.
మీరు స్వయంగా compose ఫైల్ రాయండి మరియు tags కు version pin చేయండి
పత్రాల్లో ఇచ్చిన install విధానం curl -L -o docker-compose.yml https://github.com/toeverything/AFFiNE/releases/latest/download/docker-compose.yml తో సిద్ధంగా ఉన్న ఫైల్ను download చేస్తుంది. అది పనిచేస్తుంది. అయితే దానిపై ఆధారపడే ముందు ఒక విషయం తెలుసుకోవాలి: 8 August 2026 నాటికి release 0.27.3 కు జతచేసిన ఫైల్ తన paths ను .env file నుంచి చదివేది. అందుకు ${UPLOAD_LOCATION}, ${CONFIG_LOCATION} మరియు ${DB_DATA_LOCATION} ఉపయోగించేది. అదే సమయంలో documentation reference page storage మరియు PostgreSQL data ను ./data కింద ఉంచే, configuration ను ./config కింద ఉంచే, .env అవసరం లేని కొత్త layout ను చూపించింది. Release 0.27.4 లో జతచేసిన ఫైల్ ఆ layout కు మార్చబడింది. 12 October 2026 నాటికి రెండూ ఒకే విధంగా ఉన్నాయి. మీరు పాత ఫైల్ నుంచి install చేసి ఉంటే, మీ paths ఇప్పటికీ .env నుంచి వస్తాయి. ఆ settings ను ముందుకు తీసుకెళ్లకుండా compose file ను భర్తీ చేస్తే Postgres ఖాళీ data directory తో ప్రారంభమవుతుందని AFFiNE upgrade page హెచ్చరిస్తుంది. ఫైల్ను మీరే రాస్తే ఈ సమస్య పూర్తిగా తప్పుతుంది. Images కు pin చేయడం మరియు database password సెట్ చేయడం కోసం మీరు ఆ ఫైల్ను ఏమైనా edit చేయాల్సిందే.
mkdir -p ~/affine/config ~/affine/data
cd ~/affine
printf 'DB_PASSWORD=%s\n' "$(openssl rand -hex 24)" > .env
chmod 600 .envCompose project directory నుంచి స్వయంగా .env ను చదివి, మీ కోసం ${DB_PASSWORD} ను substitute చేస్తుంది. అందువల్ల support thread లో paste చేసే ఫైల్లో password కనిపించదు. మీరు నిర్వహించే ప్రతి stack లో ఈ పద్ధతిని పాటించడం మంచిది. దీని కారణం compose file నుంచి secrets ను బయట ఉంచడం లో వివరించబడింది.
ఇప్పుడు ~/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-stoppedUpstream అందించే ఫైల్తో పోలిస్తే ఇందులో నాలుగు మార్పులు ఉన్నాయి. ప్రతి మార్పుకూ ఒక కారణం ఉంది.
127.0.0.1:3010:3010port ను loopback address కు మాత్రమే publish చేస్తుంది. Docker 28.0.0 కంటే ముందు versions లో, అదే L2 segment లోని hosts localhost-published ports ను చేరుకోగలవు. Configured direct routing ఉంటే loopback publishing ఉన్నప్పటికీ container port బయటపడవచ్చు. Docker 28.0.0 లేదా కొత్త version ఉపయోగించండి. Setup సమయంలో direct routing ను disabled గా ఉంచండి. Upstream లోని'3010:3010'ప్రతి interface కు bind అవుతుంది. చాలా VPS images లో అందులో public interface కూడా ఉంటుంది.POSTGRES_HOST_AUTH_METHOD: trustతొలగించబడింది. దాని బదులుగా password సెట్ చేయబడింది. Trust authentication ఉపయోగిస్తే password లేకుండానే ఆ database కు వచ్చే ఏ connection అయినాaffineuser గా అంగీకరించబడుతుంది. ఇది private Compose network కు మాత్రమే పరిమితం అవుతుంది. అయితే తరువాత మీరు అదే network కు మరో container ను జోడించినప్పుడు లేదా debugging సమయంలో 5432 ను publish చేసినప్పుడు ఇది సమస్య కావచ్చు.- Bare
redisస్థానంలోredis:8-alpineఉపయోగించబడింది. Bareredis,latestకు resolve అవుతుంది. August 2026 నాటికి అది Redis 8. అందువల్ల ఈ pin మీరు పరీక్షించిన major version ను నిలుపుతుంది. సంబంధం లేనిdocker compose pullసమయంలో భవిష్యత్తులో Redis 9 install కావడాన్ని నిరోధిస్తుంది. pgvector/pgvector:pg16upstream లో ఉన్నట్లుగానే ఉంచబడింది. కారణం పైన ఇచ్చినదే.
Postgres మొదటిసారి data directory ను సృష్టించినప్పుడు మాత్రమే POSTGRES_PASSWORD చదవబడుతుంది. ఇప్పటికే ఉన్న instance లో password ను docker compose exec postgres psql -U affine -c "ALTER USER affine WITH PASSWORD 'yourpassword'" తో సెట్ చేసి, తరువాత సరిపడేలా DATABASE_URL ను update చేయండి.
Configuration అనేది config/config.json లో ఉంటుంది
AFFiNE తన సెట్టింగ్లను config/config.json నుంచి చదువుతుంది. మీరు /root/.affine/config వద్ద mount చేసిన directory ఇదే. ఈ file ను మీ కోసం ఏదీ సృష్టించదు. అందువల్ల మొదటి start కు ముందు దీన్ని రాయాలి. editor లో ~/affine/config/config.json ను తెరిచి, ఉదాహరణలోని domain స్థానంలో మీ స్వంత domain ను ఉంచి ఈ content ఇవ్వండి:
{
"$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 అనేది మీ users browser లో వాస్తవంగా తెరిచే address అయి ఉండాలి. AFFiNE share links మరియు workspace invitations ను ఆ విలువ ఆధారంగా రూపొందిస్తుంది. అందువల్ల అది http://localhost:3010 వద్దే ఉంటే, మీరు పంపే invitation recipient యొక్క స్వంత machine కు చూపిస్తుంది మరియు అక్కడ విఫలమవుతుంది. మొదటి start కు ముందే దీన్ని public HTTPS address కు సెట్ చేయండి. అప్పుడు file మరియు admin panel లోని విలువ ఎప్పుడూ విభేదించవు. తరువాత admin panel లో మార్చే settings database లో సేవ్ అవుతాయి. అవి ఈ file లోకి తిరిగి రాయబడవు.
copilot AI features ను నియంత్రిస్తుంది. copilot.byok.enabled అనేది bring-your-own-key switch. దీని ద్వారా workspace owner తమ స్వంత model provider key ను workspace settings లో paste చేయవచ్చు. AFFiNE ను self-host చేయడం వల్ల AI subscription అందదు. మీకు AI features అవసరం లేకపోతే రెండింటినీ false గా ఉంచండి.
Stack ను start చేయండి:
docker compose up -d
docker compose ps --alldocker compose ps --all లో affine_postgres మరియు affine_redis healthy గా, affine_server running గా, అలాగే affine_migration_job state exited (0) తో కనిపించాలి. --all ముఖ్యమైనది. అది లేకపోతే docker compose ps ప్రస్తుతం running లో ఉన్న containers ను మాత్రమే చూపిస్తుంది. అందువల్ల సరిగ్గా పూర్తైన migration job అసలు కనిపించదు. Migration job కు వచ్చిన ఇతర exit code ను తప్పక పరిశీలించాలి. ఆగిపోయిన step ఏదో దాని log లో కనిపిస్తుంది:
docker compose logs affine_migrationమీరు మర్చిపోకముందే image ను నిర్దిష్టంగా pin చేయండి
stable ఒక మారుతూ ఉండే tag. AFFiNE విడుదల workflow ప్రతి stable build కు అనేక tags ను సూచిస్తుంది. ఇక్కడ వాటిలో రెండు ముఖ్యమైనవి: ప్రతి release సమయంలో మళ్లీ సూచించబడే stable, మరియు దాని తరువాత ఉన్న git short hash తో కూడిన stable-. రెండవది మారదు. stable ను అలాగే ఉంచితే, ఇప్పటి నుంచి ఆరు నెలల తరువాత ఒక docker compose pull వేరే image ను fetch చేసి, మీరు ఎంచుకోని సమయంలో మీ database పై దాని migrations ను అమలు చేస్తుంది. మీరు పరీక్షించిన ఖచ్చితమైన image ను pin చేయండి:
docker compose pull
docker image inspect ghcr.io/toeverything/affine:stable --format '{{index .RepoDigests 0}}'ఇది ghcr.io/toeverything/affine@sha256: వంటి line ను, దాని తరువాత పొడవైన hash తో print చేస్తుంది. ఆ మొత్తం string ను affine మరియు **affine_migration రెండింటిలోని image: line లో paste చేయండి. ఆ రెండింటిలో image ఎల్లప్పుడూ ఒకటే ఉండాలి, ఎందుకంటే అవి ఒకే image ను రెండు పాత్రల్లో ఉపయోగిస్తాయి. అవి సరిపోలకపోతే database ను ఒక schema కు migrate చేసి, దానిని వేరే schema తో serve చేసే పరిస్థితి ఏర్పడుతుంది. తరువాత upgrade అనేది అనుకోని మార్పు కాకుండా ఉద్దేశపూర్వక edit అవుతుంది: digest ను మార్చండి, backup తీసుకోండి, docker compose pull, docker compose up -d.
ఇతరులు చేయకముందే admin account సృష్టించండి
కొత్త instanceలో /admin తెరిస్తే AFFiNE మిమ్మల్ని account creation pageకి పంపుతుంది. దీనికి కారణం serverలో ఇంకా administrator లేకపోవడం. ఆ flowలో invitation code లేదా setup token ఏదీ ఉండదు. Registration పూర్తి చేసే మొదటి వ్యక్తి మీ serverకు administrator అవుతారు. అందువల్ల మీరు registration పూర్తి చేసే వరకు ఆ port మూసి ఉంచాలి.
అందుకే పై compose file 127.0.0.1 కు bind చేస్తుంది. మీ స్వంత machine నుంచి SSH tunnel ద్వారా దాన్ని చేరుకోండి:
ssh -L 3010:127.0.0.1:3010 you@your-server-ipఆ tunnelను నడుస్తూనే ఉంచి, మీ local browserలో http://127.0.0.1:3010/admin తెరవండి. Register చేసి login అవ్వండి. తరువాత tunnelను మూసివేయండి. ఇప్పుడు మాత్రమే instanceను public nameపై ఉంచడం సురక్షితం. ఇదే race ఇతర self-hosted appsలో కూడా ఉంటుంది. మొదటి login సమయంలో hostnameకు bound అయిన passkey సృష్టించే appsలో ఈ సమస్య మరింత తీవ్రమవుతుంది. అందుకే మీరు self-host openGym చేసినప్పుడు, మొదటి account సృష్టించే ముందే TLS మరియు final domainను ఖరారు చేయాలి.
AFFiNE మీ డేటాను ఎక్కడ ఉంచుతుంది
మీరు సృష్టించిన directory లోపల ఉన్న మూడు paths లో మొత్తం డేటా నిల్వ ఉంటుంది.
./data/postgresఅనేది Postgres data directory. ఇందులో documents, users, workspaces, permissions, అలాగే admin panel నుంచి సేవ్ చేసిన server settings ఉంటాయి../data/storagecontainer లోని/root/.affine/storageవద్ద mount చేయబడుతుంది. ఇందులో upload చేసిన ప్రతి file ఉంటుంది../configను/root/.affine/configవద్ద mount చేస్తారు. ఇందులో migration job రూపొందించినconfig.jsonమరియుprivate.keyఉంటాయి.
ఇక్కడ upstream, named volumes కు బదులుగా bind mounts ను ఉపయోగిస్తుంది. ఇది ఉద్దేశపూర్వక నిర్ణయం. Docker ఈ paths ను ఎక్కడ ఉంచిందో తెలుసుకోవాల్సిన అవసరం లేకుండా, సాధారణ commands తో వీటిని tar చేసి copy చేయవచ్చు. అయితే host పై file ownership ను మీరు స్వయంగా నిర్వహించాలి. ఇదే trade-off ను bind mounts మరియు named volumes లో వివరించాం.
AFFiNE ను ఎలా బ్యాకప్ చేయాలి
బ్యాకప్ చేయాల్సినవి రెండు ఉన్నాయి. వాటిని వేర్వేరు విధానాల్లో బ్యాకప్ చేయాలి. Database నడుస్తున్న server కాబట్టి, అది నడుస్తున్న సమయంలో దాని files ను copy చేస్తే copy పాడవుతుంది. అందుకు బదులుగా 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/Dump container లోని local socket ద్వారా నడుస్తుంది కాబట్టి password అడగదు. ఆ ls output లో size ను పరిశీలించండి. Shell file ను సృష్టించినప్పటికీ dump విఫలమైతే, file పరిమాణం కొన్ని వందల bytes మాత్రమే ఉంటుంది. ఆ వైఫల్యాన్ని సాధారణంగా ఆరు నెలల తర్వాత గుర్తిస్తారు. -T కూడా ముఖ్యమే. అది లేకపోతే Compose terminal ను allocate చేసి binary stream ను పాడుచేయవచ్చు.
Uploaded files సాధారణ files మాత్రమే కాబట్టి, వాటిని tar చేయాలి:
tar czf backup/storage-$(date +%F).tgz -C data storage
tar czf backup/config-$(date +%F).tgz config docker-compose.yml .envమీ backup లో మొత్తం config directory, Compose file మరియు .env ఉంచండి. Dump లో ఇవి ఉండవు. Migration job config/private.key ను కూడా సృష్టిస్తుంది. కాబట్టి config.json ను మాత్రమే copy చేస్తే ఆ file backup లో ఉండదు. Admin panel లో save చేసిన settings database లో నిల్వ ఉంటాయి. అందువల్ల పై dump లో అవి ఇప్పటికే ఉంటాయి. 12 October 2026 నాటికి, AFFiNE backup page modified server settings ను admin panel నుంచి export చేయవచ్చని కూడా పేర్కొంటుంది. మూడు files ను server వెలుపలికి copy చేయండి. రక్షించాల్సిన data ఉన్న అదే disk పై ఉంచిన backup నిజమైన backup కాదు. Database dump మరియు uploads directory యొక్క tar కలయికను మీరు నడిపే ప్రతి stateful container కోసం ఇదే విధంగా ఉపయోగించాలి. support desk గా self-host Chatwoot చేసినప్పుడు conversation history మరియు attachments ను సురక్షితంగా ఉంచే విధానం కూడా ఇదే.
పునరుద్ధరణ, అలాగే ప్రచురించిన దశల్లోని ఒక పొరపాటు
అవసరం ఏర్పడకముందే అధికారిక పునరుద్ధరణ దశలను చదవండి. వాటిని జాగ్రత్తగా పరిశీలించండి. August 2026లో ప్రచురించిన విధానంలో affine.backup అనే ఫైల్ను containerలోకి కాపీ చేసి, తరువాత ./pg.backup నుంచి పునరుద్ధరించారు. ఇవి రెండు వేర్వేరు పేర్లు. అలాగే ప్రస్తుత compose file తన డేటాను ./data/postgresలో ఉంచుతున్నప్పటికీ, వారు ./postgres directoryని తొలగించారు. 12 October 2026 నాటికి ఆ పేజీ అంతటా affine.backupనే ఉపయోగిస్తోంది. పునరుద్ధరణ ధృవీకరించబడే వరకు పాత Postgres directoryని ఉంచాలని కూడా చెబుతోంది. కాబట్టి ఈ పొరపాటు upstreamలో సరిచేశారు. అయితే అంతకుముందు సేవ్ చేసిన దశల కాపీలో అది ఇంకా ఉండవచ్చు. ఏ సందర్భంలోనైనా, snippetలో ఉన్న pathsకు బదులుగా మీరు వాస్తవంగా ఉపయోగించిన pathsనే అనుసరించండి. ఈ guideలోని layoutకు వర్తించే క్రమం ఇదీ:
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 -drmకు బదులుగా mv ఉపయోగించడాన్ని గమనించండి. మీ వద్ద కాపీగా ఉంచని databaseపై పునరుద్ధరణ చేయడం వల్ల ఒక తప్పు command మొత్తం data lossకు దారితీయవచ్చు. పాత directoryని పక్కకు తరలించడానికి ఎలాంటి ఖర్చు లేదు. tar xzf backup/storage-2026-08-08.tgz -C dataతో uploadsను కూడా పునరుద్ధరించండి. లేకపోతే ప్రతి documentలో attachments విరిగినట్లుగా కనిపిస్తాయి. తరువాత login చేసి image ఉన్న documentను తెరవండి. అదే పరీక్ష. Browserలో తెరవని restore ఒక file మాత్రమే, backup కాదు.
ఇప్పటికే నడుపుతున్న proxy వెనుక AFFiNE ను ఉంచడం
AFFiNE WebSocket ను ఉపయోగిస్తుంది. ఇది ఐచ్ఛికం కాదు. AFFiNE sync మరియు collaboration వ్యవస్థకు WebSocket పునాది అని documentation స్పష్టంగా చెబుతుంది. అందువల్ల ఆ connections ను upgrade చేయని proxy ఉంటే, editing నిశ్శబ్దంగా sync కాకుండా workspace మిగిలిపోతుంది. Page లోడ్ అవుతుంది. Login పనిచేస్తుంది. కానీ ఒక browser లో చేసిన edit మరొక browser కు చేరదు. మీ browser developer tools లో Network tab తెరిచి, WS కు filter చేయండి. మళ్లీ మళ్లీ open మరియు close అయ్యే connection ఉంటే, proxy upgrade ను pass చేయడం లేదని అర్థం.
మీరు ఇప్పటికే ఇతర containers కోసం Traefik నడుపుతున్నట్లయితే, AFFiNE ను సాధారణ service గా అందులో చేర్చవచ్చు. affine service నుంచి ports: block ను తొలగించి, తరువాత దీనిని జోడించండి:
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'File దిగువన, services: పక్కన:
networks:
proxy:
external: trueCertificate resolver పేరు మీ Traefik configuration లో నిర్వచించిన పేరుతో సరిపోవాలి. loadbalancer.server.port అనేది container port 3010. ఇది ఎప్పుడూ host port కాదు. Traefik అదనపు configuration లేకుండానే WebSocket connections ను proxy చేస్తుంది. కాబట్టి మరేమీ జోడించాల్సిన అవసరం లేదు. మీ stack లోని మిగతా services ఇప్పటికే single sign-on కోసం Authentik వెనుక ఉంటే, ఈ router పై forward auth middleware ఉంచడం ద్వారా AFFiNE కు browser access ను నియంత్రించవచ్చు. అయితే desktop app ను పరీక్షించే వరకు దాన్ని enable చేయకండి. Desktop app లో browser session ఉండదు. అందువల్ల అది sync చేయడంలో విఫలమవుతుంది. ఒకే instance వెనుక అనేక apps ను నడపడం గురించి అనేక apps ముందు ఒకే Traefik లో వివరించారు.
nginx లో 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;
}nginx లో client_max_body_size default గా 1 MB ఉంటుంది. ఆ line లేకపోతే చిన్న photo కంటే పెద్ద ప్రతి upload 413 status తో విఫలమవుతుంది. AFFiNE logs లో ఏమీ కనిపించదు, ఎందుకంటే request అక్కడికి చేరలేదు. Caddy కు reverse_proxy http://127.0.0.1:3010 అనే ఒక line మాత్రమే అవసరం. Certificates మరియు WebSocket upgrades ను అది స్వయంగా నిర్వహిస్తుంది.
Self-hosted build లో లేని అంశాలు
ఒక బృందాన్ని దీనికి మార్చే ముందు ఈ విషయాన్ని మీతో మీరు నిజాయితీగా పరిశీలించండి.
Real-time collaboration అందుబాటులో ఉంది. పరిమాణ నిర్ణయానికి సంబంధించిన సూచనలన్నీ ఈ feature చుట్టూనే ఉన్నాయి, ఎందుకంటే AFFiNE documentation ప్రకారం memory వినియోగం sync system మరియు document merging వల్ల వస్తుంది. చాలామంది local-first tool కోరడానికి offline editing ప్రధాన కారణం. Desktop application మీ self-hosted server ను workspace list కు జోడించి, దానితో login చేయగలదు. మీరు ఆధారపడే ఖచ్చితమైన offline ప్రవర్తనను commit చేయడానికి ముందు పరీక్షించండి: network ఆపివేసి desktop app లో edit చేయండి, మళ్లీ connect చేయండి, తరువాత రెండవ device లో ఫలితాన్ని పరిశీలించండి. Feature lists ఆధారాలు కావు. ఈ జాబితా కూడా మినహాయింపు కాదు.
Server-side full-text search shipped compose file లో off గా ఉంది. అక్కడ AFFINE_INDEXER_ENABLED=false ను server పై మరియు migration job పై set చేశారు. దీన్ని on చేయాలంటే Manticore Search container ను జోడించాలి. అప్పుడు ఇది ఐదవ service అవుతుంది మరియు మరింత memory అవసరం. 2 GB box పై మిమ్మల్ని పరిమితి దాటించే మార్పు ఇదే. మీరు open చేసిన workspace లో client లోని search మాత్రం పనిచేస్తుంది.
వ్యక్తులను ఆహ్వానించే ముందు రెండు పరిమితులు తెలుసుకోవాలి. Self-hosted workspace కు గరిష్ఠంగా 10 seats మాత్రమే కేటాయించవచ్చు. ఆ పరిమితిని దాటాలంటే AFFiNE నుండి Team license అవసరం. Self-hosted instances కోసం unlimited blob storage మరియు unlimited blob size ఉద్దేశించినవిగా ఉన్నప్పటికీ, అవి ఇంకా పూర్తిగా అమలు కాలేదని October 2026 లో documentation లో పేర్కొన్నారు. ఇంటి వినియోగం లేదా చిన్న బృందానికి వీటిలో ఏదీ ముఖ్యమైనది కాదు. నలభై మందిని తరలించాలని మీరు అనుకుంటే రెండూ ముఖ్యమైనవే.
అప్గ్రేడ్లు
ముందుగా release notes చదవండి. ముఖ్యంగా 0.26 నుంచి 0.27 వంటి minor version మార్పుల్లో breaking changes వస్తాయి. ఏదైనా మార్చే ముందు database మరియు storage directory కి backup తీసుకోండి. ఎందుకంటే తదుపరి start సమయంలో migration job మీ schema ను మారుస్తుంది. ఆ మార్పును తిరిగి రద్దు చేయలేరు. తరువాత pinned digest మార్చి, docker compose pull ను అమలు చేసి, ఆపై docker compose up -d ను అమలు చేయండి. అది పూర్తిగా విజయవంతంగా ముగిసే వరకు docker compose logs -f affine_migration ను monitor చేయండి. ఆ తరువాత docker image prune పాత layers ను తొలగిస్తుంది. చాలా పాత install ఉపయోగిస్తున్నవారికి ఒక ముఖ్యమైన చారిత్రక సమాచారం: version 0.23.0 నుంచి image name affine-graphql నుంచి affine కు మారింది. అందువల్ల అంతకంటే పాత compose file లో pull ఏదీ కనుగొనాలంటే ముందుగా దానిలోని image lines ను మార్చాలి. అలాగే version 0.27.4 నుంచి అధికారిక compose template లో Postgres, upload మరియు configuration paths మారాయి. Default database connection కూడా మారింది. కాబట్టి పని చేస్తున్న install పై కొత్త file ను నేరుగా కాపీ చేయకుండా, దాన్ని మీ file తో పోల్చండి.
FAQ
AFFiNE container ఎందుకు ఎప్పుడూ ప్రారంభం కాదు?
affine service, affine_migration job పై condition: service_completed_successfully ను ప్రకటిస్తుంది. అందువల్ల migration 0 కాకుండా ఏదైనా status తో ముగిస్తే server ఎప్పుడూ ప్రారంభం కాదు. Web interface కూడా కనిపించదు. ఏ దశలో ఆగిందో చూడటానికి docker compose logs affine_migration ను అమలు చేయండి. చేతితో సవరించిన compose file లో కూడా pgvector/pgvector:pg16 ఉపయోగిస్తున్నారో నిర్ధారించండి. Stock Postgres లో pgvector extension ఉండదు. అయితే AFFiNE schema లో అది ఇప్పటికీ ప్రకటించబడి ఉంటుంది. ఎందుకంటే v0.27.4 లో v0.27.3 లో ఉన్న నాలుగు embedding models ఇక నిర్వచించబడలేదు.
self-hosted AFFiNE కు ఎంత RAM అవసరం?
AFFiNE requirements page ప్రకారం కనీసం 4 CPU cores మరియు 2 GB RAM అవసరం. Documents 10,000 words దాటితే అవసరం 4 GB వరకు పెరుగుతుంది. 10,000 modifications ఉన్న document ను merge చేస్తే usage 1 GB వరకు పెరగవచ్చని కూడా అందులో ఉంది. 2 GB server లో idle load సమస్య కాదు. ఆ peak usage సమస్యకు కారణం. Kernel out-of-memory killer ఒక process ను ఆపడానికి ఎంచుకుంటుంది. ఎక్కువ memory ఉపయోగించే AFFiNE server ఎంచుకోబడే అవకాశం ఎక్కువ. తరువాత restart: unless-stopped దాన్ని మళ్లీ ప్రారంభిస్తుంది. అందువల్ల users కు error బదులుగా page reload కనిపిస్తుంది. docker inspect affine_server --format '{{.State.OOMKilled}}' మరియు sudo dmesg -T | grep -i 'out of memory' తో దీన్ని నిర్ధారించండి. స్వల్పకాలిక spikes ను తట్టుకోవడానికి 2 GB swap file ను జోడించండి. Processes ఆగడం కొనసాగితే RAM ను 4 GB కు పెంచండి.
AFFiNE నా data ను ఎక్కడ నిల్వ చేస్తుంది? నేను ఏవి backup చేయాలి?
మీ compose directory లోని మూడు paths అన్నింటినీ కలిగి ఉంటాయి: database కోసం ./data/postgres, uploaded files కోసం ./data/storage, అలాగే config.json మరియు generated private.key కోసం ./config. Files ను copy చేయడం బదులుగా docker compose exec -T postgres pg_dump --format c --username affine affine > affine.dump తో database ను back up చేయండి. Running Postgres ను files గా copy చేయడం సురక్షితం కాదు. Admin panel లో save చేసిన settings కూడా ఆ dump లో ఉంటాయి. AFFiNE వాటిని database లో నిల్వ చేస్తుంది. Uploads కోసం ./data/storage ను tar చేయండి. మొత్తం config directory, Compose file మరియు .env ను కూడా భద్రపరచండి. ఈ files database లో భాగం కావు.
self-hosted AFFiNE లో real-time collaboration పనిచేస్తుందా?
అవును. దీని కోసం ఏదీ enable చేయాల్సిన అవసరం లేదు. మీ reverse proxy సరిగ్గా పనిచేయడం మాత్రమే అవసరం. Sync WebSocket connections ద్వారా జరుగుతుంది. nginx లో దీనికి proxy_http_version 1.1 తో పాటు Upgrade మరియు Connection: upgrade headers అవసరం. Traefik మరియు Caddy ఈ connections ను అదనపు configuration లేకుండా pass through చేస్తాయి. Proxy ఈ connections ను upgrade చేయకపోతే workspace సాధారణంగా load అవుతుంది, login కూడా అవుతుంది. కానీ ఒక browser లో చేసిన edits మరొక browser లో కనిపించవు.
Stock Postgres image తో AFFiNE ను అమలు చేయవచ్చా?
pgvector/pgvector:pg16 ను ఉపయోగించండి. ఇందులో pgvector extension compile చేసి ఉంటుంది మరియు ఇది Postgres 16. AFFiNE v0.27.4 ఇప్పటికీ schema.prisma లో extensions = [pgvector(map: "vector")] ను ప్రకటిస్తుంది. అయితే v0.27.3 లో ఉన్న vector(1024) embedding columns కలిగిన నాలుగు models ను ఇక నిర్వచించదు. Stock Postgres లో ప్రకటించిన extension ఉండదు. బదులుగా AFFiNE ను external Postgres server కు అనుసంధానిస్తే, ఆ server లో pgvector ను install చేయండి. Migration అమలు చేయడానికి ముందు target database లో extension ను create చేయండి.