AFFiNE خود host کریں: Docker Compose مکمل رہنما
AFFiNE کو ایک VPS پر Docker Compose سے چلائیں: 4 containers، pinned image tags، data کی جگہ، backups، اور 2 GB RAM میں عملی طور پر کیا ممکن ہے۔
جب آپ AFFiNE کو خود میزبانی کرتے ہیں تو کیا ملتا ہے
AFFiNE کی خود میزبانی سے آپ کو اپنے زیرِ کنٹرول سرور پر Notion جیسا workspace ملتا ہے۔ یہ چار containers کے طور پر چلتا ہے: application، one-shot migration job، Postgres، اور Redis۔ Real-time collaboration شامل ہے، اور self-hosted workspace میں بطورِ ڈیفالٹ زیادہ سے زیادہ 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 alternatives کا موازنہ پڑھیں۔ یہ guide اس مفروضے پر مبنی ہے کہ انتخاب ہو چکا ہے، اور دوبارہ موازنہ کرنے کے بجائے AFFiNE کو درست طریقے سے چلانے کا طریقہ بیان کرتی ہے۔
یہاں موجود تمام معلومات 8 August 2026 کو AFFiNE کی self-host documentation اور شائع شدہ release files کے مطابق جانچی گئی تھیں۔ اس تاریخ کو newest stable release 0.27.3 تھا، جو 23 July 2026 کو شائع ہوا تھا۔ ذیل میں جن دعووں کے ساتھ بعد کی تاریخ دی گئی ہے، انہیں 12 October 2026 کو ان کے primary sources کے خلاف دوبارہ جانچا گیا۔ اس وقت newest stable release 0.27.4 تھا، جو 18 August 2026 کو شائع ہوا تھا۔
چار کنٹینرز عملاً کیا کرتے ہیں
affine ایک ہی image میں server اور web client فراہم کرتا ہے۔ یہ port 3010 پر listening کرتا ہے۔
affine_migration ایک one-shot job ہے جو node ./scripts/self-host-predeploy.js چلاتا ہے، database migrations نافذ کرتا ہے، اور پھر exit ہو جاتا ہے۔ application اس job پر condition: service_completed_successfully کا اعلان کرتی ہے، اس لیے non-zero status کے ساتھ ختم ہونے والی migration کا مطلب ہے کہ 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 شامل کرتا ہے۔ یہ embeddings محفوظ کرنے کے لیے استعمال ہونے والی عددی صورت ہے، تاکہ text کو اس کے مفہوم کے مطابق search کیا جا سکے۔
redis ایک سخت dependency ہے: server اور migration job، دونوں start ہونے سے پہلے اس کے health check کا انتظار کرتے ہیں۔ غور کریں کہ فراہم کردہ compose file Redis کو کیا نہیں دیتی: volume۔ اس کے اندر موجود کوئی چیز docker compose down کے بعد برقرار نہیں رہتی۔ اس سے واضح ہے کہ اس میں آپ کا کوئی content محفوظ نہیں ہوتا اور اس کا backup ضروری نہیں ہے۔
Postgres image، stock postgres کی بجائے pgvector کیوں ہے
یہ ضرورت AFFiNE کے schema سے آتی ہے، کسی ترجیح کی وجہ سے نہیں۔ v0.27.4 میں schema.prisma اب بھی extensions = [pgvector(map: "vector")] declare کرتا ہے، لیکن اس میں embedding columns موجود نہیں ہیں۔ v0.27.3 میں embedding columns رکھنے والے چار models، جن کی type vector(1024) تھی، v0.27.4 میں موجود نہیں ہیں۔ فراہم کردہ pgvector/pgvector:pg16 image ہی استعمال کریں: extension اب بھی declared ہے، جبکہ stock postgres:16 میں یہ شامل نہیں ہے۔
سرکاری v0.27.4 template میں pgvector image استعمال ہوتی ہے؛ v0.21.0 template میں اب بھی postgres:16 استعمال ہوتا تھا۔ پرانی installation میں image line تبدیل کرنا مکمل upgrade نہیں ہے، اس لیے کچھ بھی pull کرنے سے پہلے AFFiNE self-host docs میں upgrade page پڑھیں۔
اس tag کے بارے میں ایک اور بات اہم ہے۔ pg16 سے مراد Postgres 16 ہے، اور Postgres major version ایسی number نہیں جسے صرف bump کیا جا سکے۔ موجودہ data directory پر اسے pg17 میں تبدیل کریں تو Postgres start ہونے سے انکار کر دیتا ہے، اور 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 میں بیان کردہ تین میں سے ایک طریقہ درکار ہے: fresh data directory میں dump اور restore، pg_upgrade، یا logical replication۔ Single Compose installation میں dump اور restore عموماً سب سے آسان طریقہ ہوتا ہے، کیونکہ pg_upgrade کے لیے پرانے اور نئے server binaries بیک وقت درکار ہوتے ہیں۔
خود میزبان AFFiNE کو کتنے CPU اور RAM کی ضرورت ہے
AFFiNE کا requirements page کم از کم 4 CPU cores اور 2 GB RAM طلب کرتا ہے، اور جب آپ کی دستاویزات 10,000 الفاظ سے تجاوز کر جائیں تو memory کو 4 GB تک بڑھانے کی ہدایت دیتا ہے۔ اسی page پر یہ بھی بتایا گیا ہے کہ memory کہاں استعمال ہوتی ہے: sync system اور document merging میں۔ اس میں یاد رکھنے کے قابل ایک عدد دیا گیا ہے: 10,000 modifications والی دستاویز کو merge کرتے وقت memory کا استعمال عارضی طور پر 1 GB تک پہنچ سکتا ہے۔
اب اسے 2 GB plan پر دو افراد کے لکھنے کے تناظر میں دیکھیں۔ اوسط استعمال میں مسئلہ نہیں ہوتا۔ Postgres اور Node process limit سے کم رہتے ہیں اور کچھ memory باقی رہتی ہے۔ مسئلہ peak استعمال ہے۔ ایک بڑا merge server کی memory کو عارضی طور پر تقریباً 1 GB تک پہنچا سکتا ہے۔ 2 GB کے ایسے server پر جس میں swap نہ ہو، یہ peak، Postgres اور memory میں موجود دیگر processes مل کر ساری memory ختم کر سکتے ہیں۔ اس کے بعد kernel کا out-of-memory (OOM) killer memory خالی کرنے کے لیے کسی process کو ختم کر دیتا ہے۔ AFFiNE server سب سے بڑا process ہونے کی وجہ سے غالباً متاثر ہوتا ہے، اگرچہ Docker کی documentation واضح کرتی ہے کہ کسی بھی process کو منتخب کیا جا سکتا ہے، حتیٰ کہ Docker خود بھی۔
جب AFFiNE server ختم ہوتا ہے تو آپ کے ساتھی کو کوئی 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، اس بات کی علامت ہے کہ memory ختم ہوئی تھی، نہ کہ کوئی bug ملا تھا۔ اسے دونوں سمتوں سے درست کریں۔ پہلے swap شامل کریں، تاکہ OOM killer کے فعال ہونے سے پہلے memory spike کو عارضی طور پر وہاں منتقل کیا جا سکے:
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 total رپورٹ کرنا چاہیے۔ Swap AFFiNE کو fast نہیں بناتا، اور اس کا مقصد بھی یہ نہیں ہے۔ یہ عارضی memory spike کے لیے جگہ فراہم کرتا ہے، اس لیے اس spike کے نتیجے میں container کے ختم ہونے کے بجائے صرف چند seconds کی سست روی کا امکان زیادہ ہوتا ہے۔ یہ buffer ہے، guarantee نہیں۔ اصلاح کا دوسرا حصہ یہ ہے کہ Postgres کو اپنا cache اتنا بڑھانے سے روکیں کہ merge کے وقت application کے لیے درکار memory ختم ہو جائے۔ اسی مقصد کے لیے Compose service پر memory limits استعمال کیے جاتے ہیں۔ اگر دونوں اقدامات کے بعد بھی processes ختم ہوتے رہیں تو server کو وہ 4 GB درکار ہے جو AFFiNE کا requirements page بڑی دستاویزات کے لیے طلب کرتا ہے۔
Storage کا اندازہ لگانا کہیں آسان ہے۔ AFFiNE اسی page پر یہ اعداد شائع کرتا ہے:
اس چارٹ کے پیچھے کا ڈیٹا
[
{
"label": "Server install",
"gb": 1.5
},
{
"label": "Postgres per 1,000 docs",
"gb": 0.1
},
{
"label": "Blob store per 1,000 uploads",
"gb": 10
}
]Server installation کے لیے 1.5 GB درکار ہیں۔ تقریباً 1,000 الفاظ پر مشتمل 1,000 دستاویزات Postgres data میں 0.1 GB شامل کرتی ہیں، جو تقریباً کچھ بھی نہیں۔ 1,000 uploaded files 10 GB شامل کرتی ہیں، اور اصل صورت حال یہی طے کرتی ہیں۔ یہ اعداد running instance کی measurements کے بجائے شائع شدہ planning figures ہیں، اس لیے انہیں حتمی وعدہ نہیں بلکہ عمومی اندازہ سمجھیں۔ اہم بات عمومی تناسب ہے: database چھوٹا رہتا ہے، جبکہ disk کا استعمال آپ کی uploads طے کرتی ہیں۔
خود compose فائل لکھیں اور image tags کو pin کریں
دستاویزی installation 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 فائل سے پڑھتی تھی، جس میں ${UPLOAD_LOCATION}، ${CONFIG_LOCATION} اور ${DB_DATA_LOCATION} استعمال ہوتے تھے۔ دوسری طرف documentation کے reference page پر نیا layout دکھایا گیا تھا۔ اس layout میں storage اور PostgreSQL data کو ./data کے تحت رکھا جاتا ہے، configuration کو ./config کے تحت رکھا جاتا ہے، اور .env کی ضرورت نہیں ہوتی۔ Release 0.27.4 نے منسلک فائل کو اسی layout پر منتقل کر دیا۔ 12 October 2026 تک دونوں ایک دوسرے سے مطابقت رکھتے ہیں۔ اگر آپ نے پرانی فائل سے installation کی تھی تو آپ کے paths اب بھی .env سے آتے ہیں۔ AFFiNE کا upgrade page خبردار کرتا ہے کہ ان settings کو منتقل کیے بغیر compose فائل replace کرنے سے Postgres خالی data directory کے ساتھ شروع ہو سکتا ہے۔ فائل خود لکھنے سے یہ مسئلہ مکمل طور پر ختم ہو جاتا ہے۔ ویسے بھی images کو pin کرنے اور database password مقرر کرنے کے لیے فائل میں ترمیم کرنا ضروری ہے۔
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 کر دیتا ہے۔ اس طرح password اس فائل میں ظاہر نہیں ہوتا جسے آپ support thread میں paste کریں گے۔ یہ عادت ہر اس stack میں برقرار رکھیں جسے آپ چلاتے ہیں۔ اس کی وجہ secrets کو compose فائل سے باہر رکھنے میں بیان کی گئی ہے۔
اب ~/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:3010port کو صرف loopback address پر publish کرتا ہے۔ Docker کے 28.0.0 سے پہلے کے versions میں اسی L2 segment پر موجود hosts localhost-published ports تک پہنچ سکتے ہیں۔ Configured direct routing بھی loopback publishing کے باوجود container port کو expose کر سکتی ہے۔ 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 اس database سے ہونے والی ہر connection کوaffineuser کے طور پر، password کے بغیر، قبول کرتی ہے۔ یہ صرف private Compose network تک محدود ہے۔ یہ اس دن تک قابل قبول ہے جب تک آپ اس network میں ایک اور container شامل نہ کریں یا debugging کے دوران 5432 publish نہ کریں۔redis:8-alpineایک سادہredisکی جگہ استعمال ہوتا ہے، جوlatestپر resolve ہوتا ہے۔ August 2026 تک یہ Redis 8 ہے۔ اس لیے یہ pin tested major version برقرار رکھتا ہے اور کسی غیر متعلقہdocker compose pullکے دوران مستقبل کا Redis 9 آنے سے روکتا ہے۔pgvector/pgvector:pg16بالکل اسی طرح برقرار رہتا ہے جیسے upstream نے مقرر کیا ہے، اور اس کی وجہ اوپر بیان کی گئی ہے۔
POSTGRES_PASSWORD صرف اس وقت پڑھا جاتا ہے جب Postgres پہلی بار اپنی data directory بناتا ہے۔ جو instance پہلے سے موجود ہو، اس میں docker compose exec postgres psql -U affine -c "ALTER USER affine WITH PASSWORD 'yourpassword'" کے ذریعے password مقرر کریں، پھر DATABASE_URL کو اسی password کے مطابق update کریں۔
Configuration config/config.json میں موجود ہوتی ہے
AFFiNE اپنی settings config/config.json سے پڑھتا ہے۔ یہ وہ directory ہے جسے آپ نے /root/.affine/config پر mount کیا ہے۔ یہ file خود نہیں بنتی، اس لیے پہلی بار start کرنے سے پہلے اسے بنائیں۔ کسی editor میں ~/affine/config/config.json کھولیں اور اس میں یہ content لکھیں۔ مثال میں موجود domain کی جگہ اپنا domain دیں:
{
"$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 وہ address ہونا چاہیے جسے آپ کے users واقعی browser میں کھولتے ہیں۔ AFFiNE اسی value سے share links اور workspace invitations بناتا ہے۔ اگر یہ http://localhost:3010 پر رہ جائے تو آپ کی بھیجی ہوئی invitation وصول کنندہ کی اپنی machine کی طرف اشارہ کرے گی اور وہاں ناکام ہو جائے گی۔ پہلی بار start کرنے سے پہلے اسے public HTTPS address پر set کریں، تاکہ file اور admin panel میں اس کے بارے میں اختلاف نہ ہو۔ بعد میں admin panel میں تبدیل کی جانے والی settings database میں محفوظ ہوتی ہیں، اس file میں واپس نہیں لکھی جاتیں۔
copilot AI features کو control کرتا ہے۔ copilot.byok.enabled اپنا key استعمال کرنے کا switch ہے۔ اس سے workspace owner، workspace settings میں اپنے model provider کا key paste کر سکتا ہے۔ AFFiNE کو self-host کرنے میں AI subscription شامل نہیں ہوتی۔ اگر آپ یہ feature نہیں چاہتے تو دونوں 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 توجہ طلب مسئلہ ہے۔ اس کے log میں وہ step درج ہوتا ہے جہاں عمل رک گیا:
docker compose logs affine_migrationیاد آنے سے پہلے image کو pin کریں
stable ایک متحرک tag ہے۔ AFFiNE کا release workflow ہر stable build کے لیے کئی tags مقرر کرتا ہے، اور یہاں ان میں سے دو اہم ہیں: stable، جسے ہر release پر دوبارہ مقرر کیا جاتا ہے، اور stable- جس کے بعد git short hash ہوتا ہے، اور اسے تبدیل نہیں کیا جاتا۔ اگر stable برقرار رہے تو چھ ماہ بعد چلنے والا docker compose pull مختلف image حاصل کرے گا اور آپ کے database پر migrations ایسے وقت میں چلائے گا جس کا آپ نے انتخاب نہیں کیا تھا۔ آپ نے جس exact image کی جانچ کی ہے اسے pin کریں:
docker compose pull
docker image inspect ghcr.io/toeverything/affine:stable --format '{{index .RepoDigests 0}}'اس سے ghcr.io/toeverything/affine@sha256: کے بعد ایک طویل hash والی سطر ظاہر ہوتی ہے۔ پوری string کو دونوں affine اور affine_migration کی image: سطر میں paste کریں۔ ان دونوں کی values ہمیشہ یکساں ہونی چاہییں، کیونکہ یہ ایک ہی image کو دو کرداروں میں استعمال کرتے ہیں۔ عدم مطابقت کا مطلب ہے کہ database کو ایک schema میں migrate کیا جا رہا ہے، جبکہ اسے دوسرے schema کے ساتھ serve کیا جا رہا ہے۔ اس کے بعد upgrade ایک سوچی سمجھی ترمیم بن جاتا ہے، اچانک پیش آنے والا واقعہ نہیں: digest تبدیل کریں، backup لیں، docker compose pull، docker compose up -d۔
سب سے پہلے منتظم اکاؤنٹ بنائیں
نئی instance پر /admin کھولنے پر AFFiNE آپ کو اکاؤنٹ بنانے کے صفحے پر لے جاتا ہے، کیونکہ سرور پر ابھی کوئی administrator موجود نہیں ہوتا۔ اس عمل میں invitation code یا setup token نہیں ہوتا۔ رجسٹریشن مکمل کرنے والا پہلا شخص آپ کے سرور کا administrator بن جاتا ہے، اس لیے رجسٹریشن مکمل ہونے تک port بند رہنا چاہیے۔
اسی وجہ سے اوپر والی compose file 127.0.0.1 سے bind ہوتی ہے۔ اپنی مشین سے SSH tunnel کے ذریعے اس تک رسائی حاصل کریں:
ssh -L 3010:127.0.0.1:3010 you@your-server-ipاس tunnel کو چلتا رہنے دیں اور اپنے مقامی browser میں http://127.0.0.1:3010/admin کھولیں۔ رجسٹر کریں اور login کریں، پھر tunnel بند کر دیں۔ اب instance کو public name پر رکھنا محفوظ ہے۔ یہی race دیگر self-hosted apps میں بھی موجود ہوتی ہے۔ ان apps میں مسئلہ زیادہ سنگین ہوتا ہے جہاں پہلی login hostname سے منسلک passkey بناتی ہے۔ اسی لیے پہلے account سے پہلے TLS اور حتمی domain طے کرنا ضروری ہے، جب آپ openGym کو خود host کرتے ہیں۔
AFFiNE آپ کا ڈیٹا کہاں محفوظ رکھتا ہے
تین paths میں تمام ڈیٹا موجود ہوتا ہے، اور یہ تینوں آپ کی بنائی ہوئی directory کے اندر رہتے ہیں۔
./data/postgres، Postgres کی data directory ہے۔ اس میں documents، users، workspaces، permissions، اور admin panel سے محفوظ کی گئی server settings شامل ہوتی ہیں۔./data/storage، container میں/root/.affine/storageپر mount ہوتا ہے اور تمام uploaded files رکھتا ہے۔./config،/root/.affine/configپر mount ہوتا ہے اور اس میںconfig.jsonاور migration job کے ذریعے تیار کردہprivate.keyمحفوظ ہوتے ہیں۔
Upstream یہاں named volumes کے بجائے bind mounts استعمال کرتا ہے، اور یہ انتخاب دانستہ ہے: آپ عام commands کے ذریعے ان paths کو tar اور copy کر سکتے ہیں، اور Docker سے یہ پوچھنے کی ضرورت نہیں ہوتی کہ اس نے انہیں کہاں رکھا ہے۔ اس کا نقصان یہ ہے کہ 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 دیکھیں۔ چند سو bytes کی file کا مطلب ہے کہ dump ناکام ہو گیا، جبکہ shell نے file پھر بھی بنا دی۔ یہی خرابی لوگ چھ ماہ بعد دریافت کرتے ہیں۔ -T بھی اہم ہے: اس کے بغیر Compose terminal allocate کر سکتا ہے اور binary stream خراب ہو سکتی ہے۔
Uploaded files صرف files ہیں، اس لیے ان کا tar archive بنائیں:
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 شامل نہیں ہوگی۔ Admin panel میں محفوظ کی گئی settings database میں stored ہوتی ہیں، اس لیے اوپر والا dump انہیں پہلے ہی شامل کر لیتا ہے۔ 12 October 2026 تک AFFiNE کا backup page یہ سہولت بھی فراہم کرتا ہے کہ تبدیل شدہ server settings کو admin panel سے export کیا جا سکے۔ تینوں files کو server سے باہر copy کریں۔ جس چیز کو محفوظ کرنا ہو، اسی disk پر موجود backup، backup نہیں ہوتا۔ Database dump اور uploads directory کے tar archive پر مشتمل یہ طریقہ ہر دوسرے stateful container کے لیے بھی اپنائیں۔ یہی طریقہ اس وقت بھی conversation history اور attachments کو محفوظ رکھتا ہے جب آپ Chatwoot کو support desk کے طور پر self-host کریں۔
بحالی، اور شائع شدہ مراحل میں ایک غلطی
ضرورت پڑنے سے پہلے سرکاری restore کے مراحل پڑھیں، اور انہیں غور سے پڑھیں۔ August 2026 میں شائع شدہ ہدایات میں affine.backup نام کی file کو container میں copy کیا گیا تھا، پھر ./pg.backup سے restore کیا گیا؛ یہ دونوں مختلف نام ہیں۔ ان ہدایات میں ./postgres directory بھی ہٹا دی گئی تھی، جبکہ موجودہ compose file اپنا data ./data/postgres میں رکھتی ہے۔ 12 October 2026 تک صفحہ ہر جگہ affine.backup استعمال کرتا ہے اور کہتا ہے کہ restore کی تصدیق ہونے تک پرانی Postgres directory محفوظ رکھی جائے۔ اس لیے upstream میں یہ غلطی درست ہو چکی ہے، لیکن اس سے پہلے محفوظ کی گئی ہدایات کی copy میں یہ مسئلہ اب بھی موجود ہو سکتا ہے۔ دونوں صورتوں میں، کسی بھی snippet میں دیے گئے paths کے بجائے وہ paths استعمال کریں جو آپ نے حقیقت میں استعمال کیے تھے۔ اس guide کے layout کے مطابق sequence یہ ہے:
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 کی copy محفوظ نہ رکھی گئی ہو، اس پر restore کرنا ایک غلط command کو مکمل data loss میں بدل سکتا ہے۔ پرانی directory کو عارضی طور پر دوسری جگہ منتقل کرنے میں کوئی لاگت نہیں آتی۔ uploads بھی tar xzf backup/storage-2026-08-08.tgz -C data کے ذریعے restore کریں، ورنہ ہر document کے attachments خراب دکھائی دیں گے۔ پھر login کریں اور ایسی document کھولیں جس میں image موجود ہو۔ یہی test ہے۔ جس restore کو آپ نے browser میں کھول کر نہیں دیکھا، وہ backup نہیں بلکہ صرف ایک file ہے۔
پہلے سے چلنے والے proxy کے پیچھے AFFiNE رکھنا
AFFiNE WebSocket استعمال کرتا ہے، اور یہ اختیاری نہیں ہے۔ دستاویزات میں اس بارے میں واضح ہدایت ہے: WebSocket، AFFiNE کے sync اور collaboration system کی بنیاد ہے۔ اس لیے جو proxy ان connections کو upgrade نہ کرے، اس میں workspace کی editing خاموشی سے sync ہونا بند ہو جاتی ہے۔ page کھلتا ہے، login کام کرتا ہے، لیکن ایک browser میں کی گئی edit دوسرے browser تک نہیں پہنچتی۔ اپنے browser کے developer tools میں Network tab کھولیں اور WS پر filter کریں۔ جو connection بار بار کھلے اور بند ہو، وہ اس proxy کی نشانی ہے جو upgrade کو آگے منتقل نہیں کر رہا۔
اگر آپ دوسرے 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 میں defined ہے، اور loadbalancer.server.port container port 3010 ہے، host port نہیں۔ Traefik WebSocket connections کو اضافی configuration کے بغیر proxy کرتا ہے، اس لیے مزید کچھ شامل کرنے کی ضرورت نہیں۔ اگر آپ کے stack کی باقی apps پہلے ہی single sign-on کے لیے Authentik کے پیچھے ہیں تو اس router پر forward auth middleware کے ذریعے AFFiNE تک browser access محدود کیا جا سکتا ہے، لیکن desktop app کی testing مکمل ہونے تک اسے فعال نہ کریں۔ 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 کے لیے صرف ایک line، reverse_proxy http://127.0.0.1:3010، درکار ہے؛ یہ certificates اور WebSocket upgrades خود manage کرتا ہے۔
Self-hosted build میں کیا شامل نہیں ہے
ٹیم منتقل کرنے سے پہلے اس بارے میں حقیقت پسند رہیں۔
Real-time collaboration موجود ہے، اور sizing سے متعلق تمام مشورے اسی feature کے بارے میں ہیں، کیونکہ AFFiNE کی اپنی documentation کے مطابق memory use sync system اور document merging کی وجہ سے ہوتا ہے۔ Offline editing وہ وجہ ہے جس کی بنا پر بہت سے لوگ local-first tool چاہتے ہیں، اور desktop application آپ کے self-hosted server کو اپنی workspace list میں شامل کر کے اسی کے خلاف login کر سکتی ہے۔ عہد کرنے سے پہلے اپنی ٹیم کے لیے ضروری exact offline behaviour کو test کریں: network بند کر کے desktop app میں edit کریں، دوبارہ connect کریں، پھر دوسرے device پر نتیجہ check کریں۔ 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 اس workspace پر اب بھی کام کرتی ہے جو آپ نے کھولی ہوئی ہے۔
لوگوں کو invite کرنے سے پہلے دو limits جاننا ضروری ہیں۔ Self-hosted workspace میں زیادہ سے زیادہ 10 seats دی جاتی ہیں، اور اس سے زیادہ کے لیے AFFiNE کا Team license درکار ہوتا ہے۔ Self-hosted instances کے لیے unlimited blob storage اور unlimited blob size کو documentation میں مطلوبہ، مگر ابھی مکمل طور پر implemented نہ ہونے کی حیثیت سے بیان کیا گیا ہے؛ یہ صورت حال October 2026 میں check کی گئی تھی۔ Household یا small team کے لیے ان میں سے کوئی بات اہم نہیں۔ دونوں باتیں اس وقت اہم ہیں جب آپ 40 افراد کو منتقل کرنے کا منصوبہ بنا رہے ہوں۔
اپ گریڈز
پہلے release notes پڑھیں، خاص طور پر معمولی version bump کے وقت، جیسے 0.26 سے 0.27، کیونکہ 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 کریں جب تک یہ صاف طور پر exit نہ ہو جائے۔ اس کے بعد docker image prune پرانی layers صاف کرتا ہے۔ بہت پرانی installation استعمال کرنے والوں کے لیے ایک تاریخی نکتہ: version 0.23.0 سے image name affine-graphql سے تبدیل ہو کر affine ہو گیا تھا، اس لیے اس version سے پرانی compose file میں image lines دوبارہ لکھنی ہوں گی، ورنہ pull کو مطلوبہ image نہیں ملے گی۔ version 0.27.4 سے official compose template میں Postgres، upload اور configuration paths منتقل کر دیے گئے، اور default database connection بھی تبدیل کر دیا گیا۔ اس لیے نئی file کو اپنی file کے ساتھ compare کریں؛ اسے چلتی ہوئی installation پر براہ راست copy نہ کریں۔
FAQ
AFFiNE کا container شروع کیوں نہیں ہوتا؟
affine service، affine_migration job پر condition: service_completed_successfully کا انحصار ظاہر کرتی ہے۔ اس لیے اگر migration، 0 کے علاوہ کسی بھی status کے ساتھ ختم ہو، تو server کبھی شروع نہیں ہوتا اور web interface بھی ظاہر نہیں ہوتا۔ یہ دیکھنے کے لیے docker compose logs affine_migration چلائیں کہ کون سا مرحلہ رک گیا۔ تصدیق کریں کہ ہاتھ سے edit کی گئی compose file اب بھی pgvector/pgvector:pg16 استعمال کرتی ہے۔ stock Postgres میں pgvector extension شامل نہیں ہوتی، جبکہ AFFiNE کا schema اب بھی اسے ظاہر کرتا ہے۔ اگرچہ v0.27.4 میں v0.27.3 میں موجود چار embedding models اب define نہیں کیے جاتے۔
self-hosted AFFiNE کے لیے کتنی RAM درکار ہے؟
AFFiNE کے requirements page کے مطابق کم از کم 4 CPU cores اور 2 GB RAM درکار ہے۔ جب documents 10,000 الفاظ سے تجاوز کریں تو ضرورت 4 GB تک بڑھ جاتی ہے۔ اس میں یہ بھی بتایا گیا ہے کہ 10,000 modifications والے document کو merge کرتے وقت RAM استعمال 1 GB تک پہنچ سکتا ہے۔ 2 GB server پر مسئلہ idle load نہیں بلکہ یہ peak استعمال ہے۔ kernel کا out-of-memory killer کسی process کو بند کر دیتا ہے۔ زیادہ امکان ہے کہ وہ AFFiNE server ہو، کیونکہ وہ سب سے بڑا process ہے۔ پھر restart: unless-stopped اسے دوبارہ شروع کر دیتی ہے۔ اس لیے users کو error کے بجائے page reload دکھائی دیتا ہے۔ docker inspect affine_server --format '{{.State.OOMKilled}}' اور sudo dmesg -T | grep -i 'out of memory' سے اس کی تصدیق کریں۔ مختصر مدتی spikes کے لیے buffer کے طور پر 2 GB کی swap file شامل کریں۔ اگر processes کا بند ہونا جاری رہے تو RAM کو 4 GB تک بڑھا دیں۔
AFFiNE میرا data کہاں محفوظ کرتا ہے، اور مجھے کس چیز کا backup لینا چاہیے؟
آپ کی compose directory کے اندر موجود 3 paths میں تمام data محفوظ ہوتا ہے: database کے لیے ./data/postgres، uploaded files کے لیے ./data/storage، اور config.json اور generated private.key کے لیے ./config۔ database کا backup files copy کرنے کے بجائے docker compose exec -T postgres pg_dump --format c --username affine affine > affine.dump سے لیں، کیونکہ چلتے ہوئے Postgres کو محفوظ طریقے سے copy نہیں کیا جا سکتا۔ اس dump میں admin panel میں محفوظ کی گئی settings بھی شامل ہوتی ہیں، کیونکہ AFFiNE انہیں database میں محفوظ کرتا ہے۔ uploads کے لیے ./data/storage کو tar کریں۔ پوری config directory، Compose file اور .env بھی محفوظ رکھیں، کیونکہ یہ files database کا حصہ نہیں ہیں۔
کیا self-hosted AFFiNE پر real-time collaboration کام کرتی ہے؟
جی ہاں، اور اسے فعال کرنے کے لیے کچھ بھی enable کرنے کی ضرورت نہیں ہے۔ واحد requirement آپ کا 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 میں ظاہر نہیں ہوتیں۔
کیا میں AFFiNE کو stock Postgres image کے ساتھ چلا سکتا ہوں؟
pgvector/pgvector:pg16 استعمال کریں۔ یہ Postgres 16 ہے جس میں pgvector extension compile کی گئی ہے۔ AFFiNE v0.27.4 اب بھی schema.prisma میں extensions = [pgvector(map: "vector")] ظاہر کرتا ہے، لیکن v0.27.3 میں موجود vector(1024) embedding columns والے 4 models اب define نہیں کرتا۔ stock Postgres میں ظاہر کی گئی extension شامل نہیں ہوتی۔ اگر اس کے بجائے AFFiNE کو external Postgres server سے connect کریں تو اس پر pgvector install کریں اور migration چلانے سے پہلے target database میں extension بنائیں۔