Docker Compose తో AFFiNE self-host ఎలా చేయాలి

మీరు AFFiNE ను స్వయంగా హోస్ట్ చేస్తే లభించేది

మీ నియంత్రణలో ఉన్న సర్వర్‌పై AFFiNE ను self-host చేస్తే Notion తరహా workspace లభిస్తుంది. ఇది నాలుగు containers గా నడుస్తుంది: application, ఒకసారి మాత్రమే నడిచే 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 ను సరిగ్గా నడపడం గురించి వివరిస్తుంది.

ఇక్కడి సమాచారం మొత్తం 8 August 2026 నాటి AFFiNE self-host documentation మరియు ప్రచురించిన release files ఆధారంగా పరిశీలించబడింది. ఆ తేదీ నాటికి తాజా stable release 0.27.3. ఇది 23 July 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 stock postgres కాకుండా pgvector ఎందుకు ఉంది

ఇది preference వల్ల కాదు. AFFiNE schema కారణంగా ఈ అవసరం ఏర్పడుతుంది. schema.prisma లో datasource extensions = [pgvector(map: "vector")] ను ప్రకటిస్తుంది. నాలుగు tables లో embedding column ఉంటుంది. దాని type vector(1024). మీరు AI features ను ఎప్పుడూ enable చేయకపోయినా migration job ఈ tables ను సృష్టిస్తుంది. అందువల్ల migration పూర్తయ్యే ముందు database లో extension ఇప్పటికే ఉండాలి. postgres:16 ను ఉపయోగిస్తే extension తొలగిపోతుంది. Migration ఆ columns ను సృష్టించలేను. Failed అయిన job కోసం server వేచి ఉండిపోతుంది.

AFFiNE version 0.21లో pgvector image కు మారింది. దానికంటే పాత install ఉంటే image line ను మార్చడం మాత్రమే సరిపోదు. ఏదైనా 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 మార్పు అంటే dump తీసుకుని, కొత్త data directory లో restore చేయడం.

self-hosted AFFiNE కు ఎంత CPU మరియు RAM అవసరం

AFFiNE requirements పేజీ కనీసం 4 CPU cores మరియు 2 GB RAM కోరుతుంది. మీ documents 10,000 words ను దాటినప్పుడు memory అవసరాన్ని 4 GB కు పెంచుతుంది. Memory ఎక్కడ ఉపయోగించబడుతుందో అదే పేజీ వివరిస్తుంది: sync system మరియు document merging. గుర్తుంచుకోవాల్సిన ఒక గణాంకం ఉంది: 10,000 modifications ఉన్న document ను merge చేస్తున్నప్పుడు memory వినియోగం 1 GB వరకు పెరగవచ్చు.

ఇప్పుడు దీన్ని ఇద్దరు వ్యక్తులు రాస్తున్న 2 GB plan పరిస్థితితో పోల్చి చూడండి. సాధారణ వినియోగం సమస్య కాదు. Postgres మరియు Node process limit కంటే తక్కువగా ఉంటాయి, కొంత memory మిగులుతుంది. సమస్య peak వినియోగంలో ఉంటుంది. ఇప్పటికే ఉపయోగంలో ఉన్న memoryకి అదనంగా ఒక పెద్ద merge 1 GB కోరవచ్చు. Swap లేని 2 GB serverలో kernel యొక్క out-of-memory (OOM) killer ఆ అభ్యర్థనను తీర్చడానికి పెద్ద process ను terminate చేస్తుంది. అది AFFiNE server కావచ్చు.

మీ సహోద్యోగికి error కనిపించదు. పేజీ 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 జోడించండి. అప్పుడు memory spike fatal కాకుండా నెమ్మదిగా మారుతుంది:

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 ను వేగంగా చేయదు. దాని ఉద్దేశం కూడా అది కాదు. ఇది one-second spike ను container terminate కావడానికి బదులుగా నెమ్మదిగా జరిగే second గా మారుస్తుంది. పరిష్కారంలోని మరో భాగం, merge సమయంలో application కు అవసరమైన memoryలోకి Postgres తన cache ను పెంచుకోకుండా ఆపడం. దానికోసమే Compose service పై memory limits ఉపయోగిస్తారు.

Storage అవసరాన్ని అంచనా వేయడం చాలా సులభం. అదే పేజీలో 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 జోడిస్తాయి. Storage విషయంలో ప్రధాన ప్రభావం ఇదే. ఇవి నడుస్తున్న instance నుంచి తీసిన measurements కాదు; planning కోసం ప్రచురించిన గణాంకాలు. కాబట్టి వీటిని ఖచ్చితమైన హామీగా కాకుండా వినియోగ ధోరణిగా పరిగణించండి. ముఖ్యమైన విషయం ఇదే: మీ database చిన్నదిగానే ఉంటుంది, కానీ మీ uploads మీ disk అవసరాన్ని నిర్ణయిస్తాయి.

tags ను pin చేసి, Compose ఫైల్‌ను మీరే రాయండి

డాక్యుమెంటేషన్‌లోని 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 లోని layout మరింత కొత్తది. అందులో ప్రతిదీ ./data కింద ఉంటుంది మరియు .env అవసరం ఉండదు. రెండూ సరైనవే. ఫైల్‌ను మీరే రాస్తే ఈ సందేహం తొలగుతుంది. 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 .env

Compose 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-stopped

Upstream అందించే ఫైల్‌తో పోలిస్తే ఇందులో నాలుగు తేడాలు ఉన్నాయి. ప్రతి తేడాకూ ఒక కారణం ఉంది.

• 127.0.0.1:3010:3010 port ను loopback address పై మాత్రమే publish చేస్తుంది. అందువల్ల మీరు విధానాన్ని నిర్ణయించే వరకు server వెలుపల నుంచి AFFiNE ను ఎవరూ చేరుకోలేరు. Upstream లోని '3010:3010' ప్రతి interface కు bind అవుతుంది. చాలా VPS images లో ఇందులో public interface కూడా ఉంటుంది.
• POSTGRES_HOST_AUTH_METHOD: trust తొలగించబడింది. దాని స్థానంలో password సెట్ చేయబడింది. Trust authentication ఉపయోగిస్తే, password లేకుండానే ఆ database కు వచ్చే ఏ connection అయినా affine user గా అంగీకరించబడుతుంది. ఇది private Compose network కు మాత్రమే పరిమితం. కానీ debugging సమయంలో మరో container ను ఆ network కు జతచేసినప్పుడు లేదా 5432 ను publish చేసినప్పుడు ఇది సమస్య అవుతుంది.
• Bare redis స్థానంలో redis:8-alpine ఉపయోగించబడింది. ఇది latest కు resolve అవుతుంది. August 2026 నాటికి అది Redis 8. ఈ pin మీరు పరీక్షించిన major version ను కొనసాగిస్తుంది. సంబంధం లేని docker compose pull సమయంలో భవిష్యత్తులో Redis 9 స్వయంగా రావడాన్ని నిరోధిస్తుంది.
• pgvector/pgvector:pg16 ను upstream లో ఉన్న విధంగానే ఉంచారు. దీనికి కారణం పైన వివరించబడింది.

Postgres మొదటిసారి data directory ను సృష్టించినప్పుడు మాత్రమే POSTGRES_PASSWORD చదవబడుతుంది. ఇప్పటికే ఉన్న instance లో password ను docker compose exec postgres psql -U affine -c "ALTER USER affine WITH PASSWORD 'yourpassword'" తో సెట్ చేసి, ఆ తర్వాత సరిపడేలా DATABASE_URL ను update చేయండి.

config/config.jsonలో configuration ఉంటుంది

AFFiNE తన settings ను 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లో వాస్తవంగా open చేసే address అయి ఉండాలి. AFFiNE share links మరియు workspace invitations ను ఆ value ఆధారంగా రూపొందిస్తుంది. కాబట్టి అది http://localhost:3010 గా మిగిలితే, మీరు పంపిన invitation అందుకునే వ్యక్తిని వారి స్వంత machine వద్దకు పంపుతుంది. అక్కడ అది పనిచేయదు. మొదటి start కు ముందే దీన్ని public HTTPS addressగా set చేయండి. అప్పుడు file మరియు admin panel రెండింటిలోనూ అదే address ఉంటుంది.

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

docker compose ps లో affine_postgres మరియు affine_redis healthyగా, affine_server runningగా, అలాగే affine_migration_job state exited (0) తో కనిపించాలి. Migration jobలో కనిపించే ఇతర exit codeను తప్పక పరిశీలించాలి. ఆ job log ఆగిపోయిన step పేరును చూపిస్తుంది:

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 పేజీకి పంపుతుంది. కారణం, ఆ serverలో ఇంకా administrator లేరు. ఆ ప్రక్రియలో invitation code లేదా setup token ఉండదు. ఆ పేజీని మొదట load చేసే వ్యక్తే మీ 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 చేసి log in అయిన తర్వాత tunnelను మూసివేయండి. అప్పుడే instanceను public nameపై ఉంచడం సురక్షితం.

AFFiNE మీ డేటాను ఎక్కడ ఉంచుతుంది

మీరు సృష్టించిన directory లోపల ఉన్న మూడు paths లో మొత్తం డేటా ఉంటుంది.

• ./data/postgres Postgres data directory. ఇందులో documents, users, workspaces, permissions ఉంటాయి.
• ./data/storage container లోని /root/.affine/storage వద్ద mount అవుతుంది. ఇందులో upload చేసిన ప్రతి file ఉంటుంది.
• ./config /root/.affine/config వద్ద mount అవుతుంది. ఇందులో config.json ఉంటుంది.

ఇక్కడ upstream named volumes బదులుగా bind mounts ఉపయోగిస్తుంది. ఇది ఉద్దేశపూర్వక నిర్ణయం. Docker ఈ paths ను ఎక్కడ ఉంచిందో తెలుసుకోవాల్సిన అవసరం లేకుండా, సాధారణ commands తో వీటిని tar చేసి copy చేయవచ్చు. అయితే host లోని file ownership ను ఇప్పుడు మీరే నిర్వహించాలి. ఇదే trade-off గురించి bind mounts మరియు named volumes లో వివరించబడింది.

AFFiNE ను ఎలా బ్యాకప్ చేయాలి

బ్యాకప్ చేయాల్సినవి రెండు ఉన్నాయి. వాటిని వేర్వేరు విధానాల్లో బ్యాకప్ చేయాలి. Database ఒక live server. అది నడుస్తున్నప్పుడు దాని files ను copy చేస్తే corrupt 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 కోసం prompt చూపించదు. ఆ ls output లో size ను తనిఖీ చేయండి. కొన్ని వందల bytes పరిమాణం ఉన్న file అంటే dump విఫలమైంది, కానీ shell file ను సృష్టించింది. ఈ వైఫల్యాన్ని సాధారణంగా ఆరు నెలల తర్వాత గుర్తిస్తారు. -T కూడా ముఖ్యం. అది లేకపోతే Compose terminal ను allocate చేసి binary stream ను corrupt చేయవచ్చు.

Uploaded files సాధారణ files మాత్రమే. కాబట్టి వాటిని tar చేయండి:

tar czf backup/storage-$(date +%F).tgz -C data storage
cp config/config.json backup/config-$(date +%F).json

config.json ను మీ backup లో తప్పనిసరిగా ఉంచండి. August 2026లో తనిఖీ చేసినప్పుడు, admin panel నుంచి configuration export ఇంకా అమలు కాలేదని AFFiNE documentation పేర్కొంటోంది. అందువల్ల disk పై ఉన్న file మీ settings కు ఏకైక copy. ఈ మూడు files ను server వెలుపలికి copy చేయండి. రక్షించాల్సినదే ఉన్న disk పై backup ఉంచితే, అది backup కాదు.

ప్రచురిత దశల్లోని పునరుద్ధరణ విధానం మరియు ఒక పొరపాటు

అవసరం ఏర్పడకముందే అధికారిక restore దశలను చదవండి. వాటిని జాగ్రత్తగా పరిశీలించండి. August 2026లో ప్రచురించిన విధానంలో affine.backup అనే ఫైల్‌ను containerలోకి copy చేసి, తరువాత ./pg.backup నుంచి restore చేస్తారు. ఇవి రెండు వేర్వేరు పేర్లు. అలాగే ప్రస్తుత compose file తన dataను ./data/postgresలో ఉంచుతున్నప్పటికీ, ./postgres directoryని తొలగిస్తారు. Snippetలో ఉన్న మార్గాలను అనుసరించకుండా, మీరు వాస్తవంగా ఉపయోగించిన 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 -d

rm కాకుండా mvను ఉపయోగించడాన్ని గమనించండి. copyని ఉంచని databaseపై restore చేయడం వల్ల ఒక తప్పు command పూర్తిస్థాయి data lossగా మారుతుంది. పాత directoryని పక్కకు తరలించడం వల్ల ఎలాంటి ఖర్చు ఉండదు. tar xzf backup/storage-2026-08-08.tgz -C dataతో uploadsను కూడా restore చేయండి. లేకపోతే ప్రతి 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: true

Certificate 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 ను అది స్వయంగా నిర్వహిస్తుంది.

స్వయంగా నిర్వహించే build లో లేని అంశాలు

బృందాన్ని దీనికి మార్చే ముందు ఈ విషయంపై మీతో మీరు నిజాయితీగా ఉండండి.

Real-time collaboration అందుబాటులో ఉంది. పరిమాణ అంచనాలకు సంబంధించిన మొత్తం సలహా ఈ feature చుట్టూనే ఉంటుంది. AFFiNE documentation ప్రకారం memory వినియోగం sync system మరియు document merging వల్ల జరుగుతుంది. Offline editing కారణంగానే చాలామంది local-first tool ను కోరుకుంటారు. Desktop application మీ self-hosted server ను workspace list కు జోడించి, దానిపై login చేయగలదు. మీరు ఆధారపడే ఖచ్చితమైన offline ప్రవర్తనను commit చేయడానికి ముందు పరీక్షించండి: network ఆపివేసి desktop app లో edit చేయండి, మళ్లీ connect చేయండి, తరువాత రెండో device లో ఫలితాన్ని పరిశీలించండి. Feature lists ఆధారం కావు. ఈ జాబితా కూడా దీనికి మినహాయింపు కాదు.

Shipped compose file లో server-side full-text search ఆపివేయబడి ఉంటుంది. అందులో AFFINE_INDEXER_ENABLED=false server పై మరియు migration job పై set చేయబడుతుంది. దీన్ని ఆన్ చేయాలంటే Manticore Search container ను జోడించాలి. అప్పుడు ఇది ఐదవ service అవుతుంది, memory అవసరం కూడా పెరుగుతుంది. 2 GB box లో పరిమితిని దాటించే మార్పు ఇదే. Client లోని search మాత్రం మీరు ప్రస్తుతం open చేసి ఉన్న workspace లో పనిచేస్తుంది.

వ్యక్తులను ఆహ్వానించే ముందు రెండు పరిమితులు తెలుసుకోవాలి. Self-hosted workspace కు గరిష్ఠంగా 10 seats మాత్రమే ఇవ్వవచ్చు. దీనిని మించాలంటే AFFiNE నుంచి Team license అవసరం. Self-hosted instances కోసం unlimited blob storage మరియు unlimited blob size ఉద్దేశించినవిగా ఉన్నప్పటికీ, ఇంకా పూర్తిగా అమలు కాలేదని August 2026 లో documentation లో పేర్కొన్నారు. Household లేదా చిన్న team కు వీటిలో ఏదీ ప్రభావం చూపదు. నలభై మందిని మార్చాలని మీరు ప్రణాళిక వేసి ఉంటే, రెండూ ముఖ్యమైనవే.

అప్‌గ్రేడ్లు

ముందుగా release notes చదవండి. ముఖ్యంగా 0.26 నుంచి 0.27 వంటి minor version bump సమయంలో ఇది అవసరం. ఈ మార్పుల్లో 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 లోని image lines ను మార్చాలి. లేకపోతే pull సమయంలో image కనుగొనబడదు.

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 స్థానంలో సాధారణ postgres image ఉండటం. AFFiNE schema, pgvector extension ను ప్రకటిస్తుంది. అలాగే plain Postgres సృష్టించలేని vector(1024) columns తో tables ను సృష్టిస్తుంది.

self-hosted AFFiNE కు ఎంత RAM అవసరం?

AFFiNE requirements page కనీసం 4 CPU cores మరియు 2 GB RAM అవసరమని చెబుతుంది. Documents 10,000 words దాటితే అవసరం 4 GB వరకు పెరుగుతుంది. 10,000 modifications ఉన్న document ను merge చేసేటప్పుడు memory వినియోగం 1 GB వరకు పెరగవచ్చని కూడా అందులో పేర్కొంది. 2 GB server లో సమస్య idle load కాదు; ఆ peak memory వినియోగమే సమస్య. Kernel out-of-memory killer AFFiNE process ను ఆపుతుంది. తరువాత restart: unless-stopped దాన్ని మళ్లీ ప్రారంభిస్తుంది. అందువల్ల users కు error బదులుగా page reload కనిపిస్తుంది. దీనిని docker inspect affine_server --format '{{.State.OOMKilled}}' మరియు sudo dmesg -T | grep -i 'out of memory' తో నిర్ధారించండి. తరువాత 2 GB swap file జోడించండి. అప్పుడు memory spike fatal కాకుండా నెమ్మదిగా ఉంటుంది.

AFFiNE నా data ను ఎక్కడ నిల్వ చేస్తుంది? నేను ఏవి backup చేయాలి?

మీ compose directory కింద ఉన్న మూడు paths లో మొత్తం data ఉంటుంది: database కోసం ./data/postgres, uploaded files కోసం ./data/storage, మరియు config.json కోసం ./config. Files ను copy చేయకుండా docker compose exec -T postgres pg_dump --format c --username affine affine > affine.dump తో database ను backup చేయండి. Running Postgres ను సురక్షితంగా copy చేయలేరు. Uploads కోసం ./data/storage ను tar చేయండి. config.json ను మాన్యువల్‌గా ప్రత్యేకంగా భద్రపరచండి. ఎందుకంటే August 2026 నాటికి admin panel నుంచి configuration export అమలు కాలేదని documentation లో పేర్కొంది.

self-hosted AFFiNE లో real-time collaboration పనిచేస్తుందా?

అవును. దీని కోసం ఏదీ enable చేయాల్సిన అవసరం లేదు. మీ reverse proxy సరిగ్గా configured ఉండటం మాత్రమే అవసరం. ఎందుకంటే 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 లో కనిపించవు.

సాధారణ Postgres image తో AFFiNE ను నడపవచ్చా?

లేదు. AFFiNE యొక్క schema.prisma, extensions = [pgvector(map: "vector")] ను ప్రకటిస్తుంది. అలాగే vector(1024) type కలిగిన embedding column తో నాలుగు tables ను నిర్వచిస్తుంది. AI features off చేసినా migration job ఈ tables ను సృష్టిస్తుంది. pgvector/pgvector:pg16 ను ఉపయోగించండి. ఇది ఆ extension ను ముందుగానే compile చేసిన Postgres 16. బదులుగా AFFiNE ను external Postgres server కు point చేస్తే, ఆ server లో pgvector ను install చేయండి. Migration అమలు చేయడానికి ముందు target database లో extension ను create చేయండి.