SSD Nodes Learn Hosting plans →
تعلیمی Matt Connorتحریر: Matt Connor

Docker سے VPS پر Chatwoot self-host کرنے کا طریقہ

Docker Compose اور Traefik کے ساتھ VPS پر Chatwoot چلائیں: pinned tags، قابلِ اعتماد SMTP، Postgres اور uploads backups، اور محفوظ upgrades کی مکمل ترتیب۔

آپ کیا بنا رہے ہیں

VPS پر Chatwoot کو self-host کرنے کے لیے آپ چار containers چلاتے ہیں: Rails web process، Sidekiq background worker، PostgreSQL جس میں pgvector extension شامل ہے، اور Redis۔ Chatwoot ایک open source customer support desk ہے، اس لیے آپ کو اپنے زیرِ انتظام سرور پر shared team inbox اور website chat widget ملتا ہے۔ تنصیب میں تقریباً twenty minutes لگتے ہیں۔ اس کے بعد mail delivery، backups، upgrades اور sizing یہ طے کرتے ہیں کہ یہ سسٹم ایک سال بعد بھی چل رہا ہوگا یا نہیں۔

ہر container کا ایک کام ہے۔ Rails agent dashboard اور widget API (application programming interface) فراہم کرتا ہے۔ Sidekiq سست کام چلاتا ہے: email بھیجنا، منسلک channels کو poll کرنا، automation rules چلانا اور reports بنانا۔ Postgres conversations، contacts، agent accounts اور dashboard میں تبدیل کی جانے والی ہر setting محفوظ کرتا ہے۔ Redis Sidekiq queues اور ActionCable pub/sub channel محفوظ کرتا ہے۔ یہی channel نیا message کھلے ہوئے dashboard میں page reload کے بغیر پہنچاتا ہے۔ یہاں Redis عارضی cache نہیں ہے، کیونکہ اسے کھونے کا مطلب queued jobs کھونا ہے۔

upstream compose file میں Postgres image عام postgres image کے بجائے pgvector/pgvector:pg16 ہے، کیونکہ Chatwoot کا schema اپنی AI features کے لیے vector extension فعال کرتا ہے۔ stock Postgres استعمال کرنے سے database کی پہلی run ERROR: extension "vector" is not available پر رک جاتی ہے، کیونکہ اس image میں extension کی control file موجود نہیں ہوتی۔ وہی image استعمال کریں جو upstream release کرتا ہے۔

یہ guide فرض کرتی ہے کہ Docker اور reverse proxy پہلے سے اس server پر درست طور پر کام کر رہے ہیں۔ اگر ایسا نہیں ہے تو VPS پر Docker Compose سے شروع کریں اور پھر واپس آئیں۔

خود میزبانی شدہ Chatwoot کے لیے کتنا VPS درکار ہے؟

October 2026 تک، upstream requirements page کم از کم 4 GB RAM اور 4 CPU cores طلب کرتا ہے اور اسے روزانہ 10,000 conversations تک کے لیے کافی قرار دیتا ہے۔ اس کے مطابق 8 GB RAM اور 8 cores روزانہ 20,000 conversations تک کے لیے کافی ہیں۔ یہ کم از کم 1 GB swap بھی طلب کرتا ہے، اور وجہ بھی واضح طور پر بتاتا ہے: تاکہ upgrade کے دوران machine کی memory ختم نہ ہو۔ File uploads کو شمار کرنے سے پہلے Postgres کے لیے 5 GB سے 10 GB disk space رکھیں۔

اب واضح بات۔ 2 GB VPS پر Chatwoot boot ہو جائے گا، اور دو agents اور کم مصروف inbox کے ساتھ سب کچھ درست دکھائی دے گا۔ لیکن یہ دو مقامات پر fail ہوتا ہے۔ پہلا Sidekiq ہے، جس کے بارے میں upstream کے مطابق مصروف server پر اس کا استعمال 1 GB سے زیادہ ہو سکتا ہے۔ اس لیے email یا report job کا اچانک بوجھ Rails، Postgres اور Redis کے حصے کی memory لینے سے پہلے machine کی دستیاب memory ختم کر دیتا ہے۔ دوسرا upgrade ہے، کیونکہ db:chatwoot_prepare migrations لاگو کرنے کے لیے نیا Rails process boot کرتا ہے، اور اس image پر Rails boot کسی مفید کام سے پہلے ہی سیکڑوں megabytes استعمال کرتا ہے۔

آپ کو پہلے کوئی مؤدبانہ warning نہیں ملتی۔ Kernel کا out of memory killer منتخب کیے گئے process کو SIGKILL بھیج دیتا ہے، عموماً سب سے بڑے process کو۔ Docker container کے بند ہونے کو دیکھتا ہے، اور restart: always اسے دوبارہ start کر دیتا ہے۔ docker compose ps --all پھر ایسا container دکھاتا ہے جو بار بار restart ہو رہا ہے یا Exited (137) پر موجود ہے، جہاں 137 کا مطلب signal 9 سے kill ہونا ہے۔ --all شامل نہ کریں تو stopped container بالکل فہرست میں نہیں آتا۔ صرف exit code 137 سے یہ ثابت نہیں ہوتا کہ وجہ memory تھی، کیونکہ docker kill بھی یہی signal بھیجتا ہے۔ اس لیے sudo dmesg -T | grep -i "killed process" سے تصدیق کریں، جو اس process کا نام دکھاتا ہے جسے kernel نے منتخب کیا تھا۔

اگر 4 GB بجٹ سے باہر ہے تو 2 GB کی machine کو 2 GB swap کے ساتھ چلائیں اور یہ قبول کریں کہ load کے دوران response times زیادہ ہو جائیں گے۔ Swap memory ختم ہونے کے خلاف ایک buffer ہے، ضمانت نہیں۔ اس لیے کافی بڑا burst پھر بھی کسی container کو kill کر سکتا ہے۔ ہر service کے لیے hard memory ceiling مقرر کرنا بہرحال مفید ہے، تاکہ worker اپنے ساتھ database کو بھی down نہ کر دے۔ Docker Compose میں memory limits دیکھیں۔

File uploads وہ حصہ ہیں جو آپ کی مقرر کردہ حد کے بغیر بڑھتے رہتے ہیں۔ Customer کی منسلک کی گئی ہر screenshot storage volume میں محفوظ ہوتی ہے اور وہیں رہتی ہے۔ اس لیے یہ فرض کرنے کے بجائے کہ disk database نے بھری ہے، docker system df -v کو monitor کریں۔

Compose فائل حاصل کریں اور version tag کو pin کریں

mkdir -p ~/chatwoot && cd ~/chatwoot
wget -O .env https://raw.githubusercontent.com/chatwoot/chatwoot/develop/.env.example
wget -O docker-compose.yaml https://raw.githubusercontent.com/chatwoot/chatwoot/develop/docker-compose.production.yaml
chmod 600 .env

آپ نے ابھی جو فائل download کی ہے، اس میں image: chatwoot/chatwoot:latest درج ہے۔ مزید کچھ کرنے سے پہلے اسے تبدیل کریں۔

services:
  base: &base
    image: chatwoot/chatwoot:v4.19.1
    env_file: .env
    volumes:
      - storage_data:/app/storage

latest کا مطلب ہے کہ اگلی بار docker compose pull آپ کو اس صبح publish ہونے والی چیز فراہم کرے گا۔ یہ ایسی major version ہو سکتی ہے جس کی migrations کے بارے میں آپ نے کبھی نہیں پڑھا۔ عملی طور پر Chatwoot migrations کو واپس نہیں کیا جا سکتا، اس لیے غیر ارادی version jump کا حل undo نہیں بلکہ backup سے restore ہے۔ tag کو pin کریں اور اسے جان بوجھ کر تبدیل کریں۔ 25 October 2026 تک v4.19.1 موجودہ release تھی، اور اس کے release notes تازہ ترین security fixes اور hardening improvements کے لیے اسی کی سفارش کرتے ہیں؛ آج جس tag کو pin کرنا چاہیے، اس کے لیے releases page دیکھیں۔ اگر آپ v4.18.0 یا اس سے پہلے کی version سے upgrade کر رہے ہیں تو پہلے v4.19.0 کے notes پڑھیں: Captain V1 کو retire کر دیا گیا ہے، اور V1 instructions استعمال کرنے والی self-hosted installations کو upgrade سے پہلے V2 پر migrate کرنا ضروری ہے۔ جس چیز کے پاس database ہو، اس کے ساتھ یہی احتیاط ضروری ہے۔ اسی لیے openGym workout tracker کو self-host کرنا git tag کو pin کرنے سے شروع ہوتا ہے، حالانکہ یہ اس ایپ کے مقابلے میں بہت چھوٹی application ہے۔

base service ایک YAML anchor ہے جسے rails اور sidekiq دونوں merge کرتے ہیں۔ اس لیے ایک جگہ tag تبدیل کرنے سے دونوں کے لیے tag تبدیل ہو جاتا ہے۔ فائل میں موجود ہونے کے دوران اوپر والی version: '3' line بھی delete کر دیں۔ جدید Compose اسے ignore کرتا ہے اور ہر command پر the attribute 'version' is obsolete, it will be ignored print کرتا ہے۔

.env فائل مکمل کریں

پہلے secret generate کریں۔ Upstream alphanumeric value مانگتا ہے، کیونکہ special characters کو shell یا YAML parser سے گزرتے وقت درست طور پر parse نہیں کیا جاتا۔

head /dev/urandom | tr -dc A-Za-z0-9 | head -c 63 ; echo ''

پھر .env میں یہ keys set کریں۔

SECRET_KEY_BASE=<the 63 characters you just generated>
FRONTEND_URL=https://support.example.com
FORCE_SSL=true
DEFAULT_LOCALE=en
ENABLE_ACCOUNT_SIGNUP=true

POSTGRES_HOST=postgres
POSTGRES_USERNAME=postgres
POSTGRES_PASSWORD=<long random string>
POSTGRES_DATABASE=chatwoot

REDIS_URL=redis://redis:6379
REDIS_PASSWORD=<a different long random string>

RAILS_ENV=production
INSTALLATION_ENV=docker
ACTIVE_STORAGE_SERVICE=local

POSTGRES_HOST=postgres اور redis://redis:6379 Compose service names ہیں، جو project کے default network پر resolve ہوتے ہیں۔ FRONTEND_URL محض ظاہری configuration نہیں ہے۔ Chatwoot اسی value سے widget script URL اور outgoing email کے اندر موجود ہر link بناتا ہے۔ اس لیے غلط value سے password reset links ایسے host کی طرف جائیں گے جو جواب نہیں دیتا۔

اب upstream فائل میں موجود مسئلہ دیکھیں۔ postgres service .env کو read نہیں کرتی۔ اس کے اپنے environment block میں POSTGRES_PASSWORD= خالی ہے۔ اس لیے صرف .env میں password set کرنے سے database کے پاس password نہیں ہوگا، جبکہ application کے پاس password ہوگا۔ Service کو اسی variable کی طرف point کریں:

  postgres:
    image: pgvector/pgvector:pg16
    restart: always
    volumes:
      - postgres_data:/var/lib/postgresql/data
    environment:
      - POSTGRES_DB=chatwoot
      - POSTGRES_USER=postgres
      - POSTGRES_PASSWORD=${POSTGRES_PASSWORD}

Compose project directory سے .env read کرتا ہے تاکہ ${...} substitution ہو سکے۔ اس طرح دونوں طرف ایک ہی string استعمال ہوگی۔ اگر یہ غلط ہو تو Rails PG::ConnectionBad: FATAL: password authentication failed for user "postgres" کے ساتھ رک جاتا ہے۔

ایک رویہ تقریباً سب کو حیران کرتا ہے: Postgres image POSTGRES_PASSWORD کو صرف اس وقت apply کرتی ہے جب وہ empty data directory کو initialise کرتی ہے۔ بعد میں value تبدیل کرنے کا کوئی اثر نہیں ہوتا، کیونکہ initdb دوسری بار run نہیں ہوتا۔ اگر آپ stack پہلے ہی ایک بار start کر چکے ہیں تو اسے database کے اندر تبدیل کریں۔

docker compose exec postgres psql -U postgres -c "ALTER USER postgres WITH PASSWORD 'the-new-password';"

ENABLE_ACCOUNT_SIGNUP=true عارضی ہے۔ یہ public registration form کھولتا ہے تاکہ آپ پہلا account بنا سکیں۔ اپنا account بننے کے فوراً بعد اسے false پر set کریں اور docker compose up -d دوبارہ run کریں۔ بصورت دیگر URL تلاش کرنے والا کوئی بھی شخص آپ کے support desk پر register کر سکتا ہے۔ اس کے بعد agents invitation کے ذریعے شامل ہوں گے اور ان کے passwords صرف اسی app میں محفوظ رہیں گے۔ یہ اس وقت تک مناسب ہے جب تک آپ تقریباً آدھی درجن services نہ چلا رہے ہوں اور ہر service میں الگ account list برقرار رکھنے سے اکتا نہ جائیں۔ اس مرحلے پر Authentik جیسا self-hosted identity provider ان account lists کی جگہ لے سکتا ہے۔

.env اب اس stack کے تمام secrets plain text میں رکھتا ہے۔ اسے mode 600 پر رکھیں اور git سے باہر رکھیں۔ Compose env files کو کیسے read کرتا ہے اور secrets کہاں leak ہوتے ہیں میں اہم احتیاطیں بیان کی گئی ہیں، جن میں env_file اور environment کا فرق بھی شامل ہے۔

موجودہ Traefik کے پیچھے Chatwoot رکھیں

ایک ایپ کے لیے دوسرا reverse proxy نہ بنائیں۔ اگر Traefik پہلے ہی اس سرور پر موجود دیگر containers کے لیے TLS (transport layer security) termination کر رہا ہے تو Chatwoot ایک label block کے ذریعے اس میں شامل ہو جاتا ہے۔ اگر یہ انتظام ابھی موجود نہیں ہے تو پہلے اسے ایک بار متعدد Docker Compose ایپس کے سامنے Traefik کے مطابق ترتیب دیں، پھر یہاں واپس آئیں۔

Upstream کے docker-compose.yaml کو اصل ساخت کے قریب رکھیں تاکہ بعد میں اس کا نئے copy سے موازنہ کیا جا سکے، اور اپنی تبدیلیاں override file میں رکھیں۔ Compose خودکار طور پر docker-compose.override.yaml کو merge کرتا ہے، جبکہ Compose کو متعدد files میں تقسیم کرنا merge rules کی وضاحت کرتا ہے۔

services:
  rails:
    networks:
      - default
      - proxy
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.chatwoot.rule=Host(`support.example.com`)"
      - "traefik.http.routers.chatwoot.entrypoints=websecure"
      - "traefik.http.routers.chatwoot.tls.certresolver=letsencrypt"
      - "traefik.http.services.chatwoot.loadbalancer.server.port=3000"

networks:
  proxy:
    external: true

اپنے entrypoint اور certresolver کے نام استعمال کریں۔ Container کو Traefik کے اسی Docker network پر ہونا چاہیے؛ proxy entry یہی کام کرتی ہے۔ اسے default پر بھی برقرار رہنا چاہیے، ورنہ Postgres اور Redis سے اس کا رابطہ ختم ہو جائے گا۔ یہی وہ دوسری line ہے جسے لوگ اکثر بھول جاتے ہیں۔

ports: block میں تبدیلی نہ کریں۔ Upstream اسے 127.0.0.1:3000 سے bind کرتا ہے، جو صرف loopback ہے۔ اس لیے یہ internet سے قابل رسائی نہیں ہوتا اور curl -I http://127.0.0.1:3000 کے ذریعے اسی سرور کے اندر testing کے لیے مفید رہتا ہے۔

Agent dashboard براہ راست پیغامات کی ترسیل کے لیے /cable سے websocket connection کھلا رکھتا ہے۔ Traefik HTTP upgrade کو اضافی configuration کے بغیر forward کرتا ہے، اس لیے کچھ شامل کرنے کی ضرورت نہیں۔ اگر بعد میں Traefik کے سامنے CDN یا کوئی اور proxy رکھیں تو وہاں websockets کی اجازت دیں، کیونکہ اس کی علامت یہ ہے کہ dashboard معمول کے مطابق load ہوتا ہے، لیکن نئے messages صرف manual refresh کے بعد دکھائی دیتے ہیں۔

ڈیٹابیس شروع کریں اور stack چلائیں

پہلے data services شروع کریں اور Postgres کو پہلی بار کا عمل مکمل کرنے دیں۔

docker compose up -d postgres redis
docker compose logs postgres | tail -n 5

database system is ready to accept connections کا انتظار کریں۔ پھر schema بنائیں۔

docker compose run --rm rails bundle exec rails db:chatwoot_prepare

یہ command ڈیٹابیس موجود نہ ہونے کی صورت میں اسے بناتی ہے، پھر schema اور default seed data لوڈ کرتی ہے۔ یہ migration lines دکھا کر کامیابی سے بند ہو جاتی ہے۔ اگر یہ postgres:5432 - no response دکھاتے ہوئے رک جائے تو entrypoint ایسے ڈیٹابیس کا انتظار کر رہا ہے جو ابھی connections قبول نہیں کر رہا۔ پہلی بار عموماً اس کا مطلب ہوتا ہے کہ initdb ابھی کام کر رہا ہے۔ انتظار کریں، Postgres logs پڑھیں، پھر command دوبارہ چلائیں۔ اگر یہ vector extension پر رک جائے تو آپ نے pgvector image کو stock Postgres سے تبدیل کر دیا ہے۔

docker compose up -d
docker compose ps
docker compose logs --tail 30 rails

چاروں containers کی حالت Up ہونی چاہیے، اور rails log کا اختتام Puma کی اس line پر ہونا چاہیے جو http://0.0.0.0:3000 پر listening دکھاتی ہے۔ پھر public path چیک کریں:

curl -sI https://support.example.com | head -n 1

HTTP/2 200 کا مطلب ہے کہ پوری chain کام کر رہی ہے۔ Traefik سے 404 کا مطلب ہے کہ router rule match نہیں ہوئی، عموماً hostname میں typo کی وجہ سے۔ 502 کا مطلب ہے کہ Traefik نے router match کر لیا، لیکن container تک نہیں پہنچ سکا۔ اس کی تقریباً ہمیشہ وجہ missing proxy network یا ایسا loadbalancer.server.port ہوتا ہے جو 3000 نہیں ہے۔

URL کھولیں، /app/auth/signup پر اپنا account بنائیں، پھر ENABLE_ACCOUNT_SIGNUP=false set کریں اور form بند کرنے کے لیے docker compose up -d چلائیں۔

SMTP کے بغیر password reset اور email conversations کیوں ناکام ہو جاتی ہیں

SMTP (simple mail transfer protocol) کی settings کے بغیر Chatwoot ایسا support desk ہے جو mail نہیں بھیج سکتا، اور اس سے صرف notifications متاثر نہیں ہوتیں۔ Password reset کام کرنا بند کر دیتے ہیں، اس لیے lock out ہونے والا admin بدستور اندر نہیں جا سکتا۔ Agent invitations بھی کام نہیں کرتیں، کیونکہ invitation ایک email ہوتی ہے۔ Email conversation میں customer کو جواب دینا بھی بند ہو جاتا ہے، اس لیے conversation صرف ایک سمت میں چلتی ہے۔ لوگ یہ مرحلہ چھوڑ دیتے ہیں اور پھر اپنے مشکل ترین ہفتے کے دوران اس مسئلے کا سامنا کرتے ہیں۔

طریقہ واضح ہے۔ SMTP_ADDRESS set نہ ہونے پر Chatwoot ActionMailer کو sendmail delivery پر منتقل کر دیتا ہے۔ Upstream اسے اپنے Postfix setup کے طور پر document کرتا ہے۔ یہ v2.12.0 سے default ہے، اور اس کی ہدایات sudo apt install -y postfix کے ذریعے server پر Postfix install کرتی ہیں۔ یہ Docker setup ایسا نہیں کرتا، اس لیے اس delivery کے پاس mail حوالے کرنے کے لیے کوئی configured mail server نہیں ہوتا۔ Mail background job سے بھیجی جاتی ہے، اس لیے delivery سے پیدا ہونے والی کوئی بھی error Sidekiq log میں آتی ہے، Rails log میں نہیں۔ ادھر "forgot password" پر click کرنے والے شخص کو ایک خوش آئند confirmation دکھائی دیتی ہے، مگر اسے کچھ موصول نہیں ہوتا۔

MAILER_SENDER_EMAIL=Support <support@example.com>
SMTP_DOMAIN=example.com
SMTP_ADDRESS=smtp.example.com
SMTP_PORT=587
SMTP_USERNAME=support@example.com
SMTP_PASSWORD=<the relay password>
SMTP_AUTHENTICATION=plain
SMTP_ENABLE_STARTTLS_AUTO=true

STARTTLS کے ساتھ port 587 استعمال کریں۔ یہ connection کو plain text میں کھولتا ہے اور authentication سے پہلے اسے encrypted کر دیتا ہے۔ بہت سے VPS providers spam محدود کرنے کے لیے outbound port 25 کو default طور پر block کرتے ہیں۔ 8 November 2026 تک، Hetzner cloud servers پر ports 25 اور 465 کو default طور پر block کرتا ہے، اور blocking ہر account کے لیے نافذ ہوتی ہے۔ Vultr تمام نئے Compute Instances پر port 25 کو block کرتا ہے۔ دونوں unblock requests کا case by case جائزہ لیتے ہیں۔ Hetzner میں limit request submit کرنے سے پہلے کم از کم ایک ماہ customer رہنا اور پہلی invoice ادا کرنا ضروری ہے۔ ان دونوں providers میں سے کوئی بھی 587 کو block نہیں کرتا، اس لیے 587 پر relay پہلے boot سے، کسی ticket یا انتظار کے بغیر کام کرتا ہے۔ SMTP_DOMAIN وہ domain ہے جس کا اعلان آپ کا server SMTP conversation کے دوران کرتا ہے، اور کچھ relays mismatch کو reject کر دیتے ہیں۔

Settings لاگو کریں اور worker کو monitor کریں:

docker compose up -d rails sidekiq
docker compose logs -f sidekiq

Login page سے password reset trigger کریں۔ کام کرنے والی delivery میں mailer job Sidekiq log میں معمول کے مطابق مکمل ہوتی دکھائی دیتی ہے۔ ناکامی کی صورت میں exception class دکھائی دیتی ہے، پھر Sidekiq بڑھتے ہوئے backoff کے ساتھ retry کرتا ہے۔ اسی لیے broken relay کئی گھنٹوں تک ہر چند منٹ بعد وہی error پیدا کرتا ہے۔

دو rejections عام ہیں، اور دونوں Chatwoot bug نہیں ہیں۔ 535 Authentication failed کا مطلب ہے کہ authentication ناکام ہوئی ہے۔ Credentials، SMTP authentication کے enabled ہونے، اور اس بات کی جانچ کریں کہ آیا کوئی access policy اسے block کر رہی ہے۔ صرف درست credentials اس error کے امکان کو ختم نہیں کرتیں۔ کچھ providers account password کے بجائے application password لازمی قرار دیتے ہیں۔ 550 Sender address rejected کا مطلب ہے کہ server نے sender address reject کر دیا ہے۔ MAILER_SENDER_EMAIL تبدیل کرنے سے پہلے مکمل response پڑھیں۔ Sender permissions یا verification ایک وجہ ہو سکتی ہے، لیکن 550 5.7.27 Sender address rejected: Domain does not accept mail ایسے sender domain کی طرف اشارہ کرتا ہے جس کا MX record null ہے۔

Conversation میں email وصول کرنا ایک الگ کام ہے۔ Chatwoot کے ingress کے ذریعے forwarding کے لیے MAILER_INBOUND_EMAIL_DOMAIN اور RAILS_INBOUND_EMAIL_SERVICE درکار ہیں، اس کے علاوہ ایسا mail server بھی چاہیے جو incoming messages Chatwoot کے حوالے کرے۔ آپ forwarding path قائم کیے بغیر IMAP کے ذریعے mailbox بھی connect کر سکتے ہیں، جس میں Google یا Microsoft OAuth بھی شامل ہے۔ Relay کرائے پر لینا تیز ترین طریقہ ہے۔ اگر آپ پورا mail path خود manage کرنا چاہتے ہیں تو Mailcow کے ساتھ اپنا mail server چلانا میں بتایا گیا ہے کہ اس ذمہ داری میں حقیقتاً کیا شامل ہوتا ہے۔

کیا بیک اپ لیا جائے، اور restore کے کام کرنے کا ثبوت کیسے حاصل کریں

Chatwoot بیک اپ کے چار حصے ہوتے ہیں۔ ان میں سے کوئی ایک حصہ چھوڑنے سے restore کے بجائے دوبارہ تنصیب کرنا پڑتی ہے۔

  • Postgres database، جس میں conversations، contacts، agent accounts اور تمام settings محفوظ ہوتی ہیں۔
  • storage_data volume، کیونکہ ACTIVE_STORAGE_SERVICE=local uploaded files کو disk پر لکھتا ہے اور Postgres میں صرف ایک reference row رکھتا ہے۔
  • .env file، کیونکہ اس میں SECRET_KEY_BASE اور ACTIVE_RECORD_ENCRYPTION_* keys محفوظ ہوتی ہیں۔
  • compose files، کیونکہ ان میں وہ exact image tag درج ہوتا ہے جس سے آپ کا database schema مطابقت رکھتا ہے۔

صرف database restore کرنے سے تمام conversations واپس آ جائیں گی، لیکن attachments خراب ہوں گی، کیونکہ rows ان files کی طرف اشارہ کرتی ہیں جو اب disk پر موجود نہیں ہیں۔

cd ~/chatwoot
docker compose exec -T postgres pg_dump -U postgres -Fc chatwoot > db-$(date +%F).dump

-T اہم ہے۔ اس کے بغیر Compose ایک pseudo terminal مختص کرتا ہے، جو stream میں newline bytes کو تبدیل کر دیتا ہے۔ نتیجتاً ایسی dump file بنتی ہے جسے pg_restore مسترد کر دیتا ہے۔ -Fc custom format ہے۔ یہ compression فراہم کرتا ہے اور pg_restore کو منتخب طور پر کام کرنے دیتا ہے۔

docker run --rm -v chatwoot_storage_data:/data:ro -v "$PWD":/backup alpine \
  tar czf /backup/storage-$(date +%F).tgz -C /data .

volume کا نام آپ کے project directory name کے ساتھ _storage_data ملا کر بنتا ہے۔ اس command پر اعتماد کرنے سے پہلے docker volume ls | grep storage_data کے ذریعے اس کی تصدیق کریں، کیونکہ Docker ایسے volume کا نام دینے پر failure کے بجائے ایک empty volume بنا دیتا ہے جو موجود نہ ہو۔ آپ کو ایک درست مگر empty archive ملے گا اور کوئی error بھی نہیں آئے گا۔ اس کے بعد ls -lh storage-*.tgz سے اس کا size چیک کریں۔

اب دونوں files اسی disk پر موجود ہیں جس چیز کو وہ محفوظ کرتی ہیں۔ اس سے آپ کسی failure سے محفوظ نہیں ہوتے۔ انہیں server سے باہر منتقل کریں اور encrypt کریں، کیونکہ database dump میں ہر customer message plain text میں موجود ہوتا ہے۔ restic کے ذریعے encrypted off-site backups میں scheduling اور retention کا طریقہ بیان کیا گیا ہے۔

Restore drill: ضرورت پڑنے سے پہلے اسے چلائیں

Restore live server پر نہیں بلکہ دوسرے VPS پر کریں۔ .env، compose files اور دونوں archives وہاں copy کریں، پھر چلائیں:

docker compose up -d postgres
docker compose exec -T postgres pg_restore -U postgres -d chatwoot --clean --if-exists < db-2026-08-10.dump
docker run --rm -v chatwoot_storage_data:/data -v "$PWD":/backup alpine \
  sh -c 'rm -rf /data/* && tar xzf /backup/storage-2026-08-10.tgz -C /data'
docker compose up -d

--clean --if-exists load کرنے سے پہلے موجودہ objects کو delete کر دیتا ہے۔ اس لیے اسے صرف ایسے database پر چلائیں جسے ضائع کرنے پر آپ رضامند ہوں۔ اس کے بعد sign in کریں اور ایسی conversation کھولیں جس میں attachment موجود ہو۔ اگر message list load ہو جائے اور file download ہو جائے تو بیک اپ درست ہے۔

مختلف SECRET_KEY_BASE کے ساتھ restore کرنے سے ہر session cookie invalid ہو جاتی ہے، اس لیے تمام users sign out ہو جاتے ہیں۔ مختلف ACTIVE_RECORD_ENCRYPTION_* keys کے ساتھ restore کرنا اس سے بھی سنگین ہے: Chatwoot ان columns کو decrypt نہیں کر سکتا جن میں channel credentials محفوظ ہیں، اور ActiveRecord::Encryption::Errors::Decryption ظاہر کرتا ہے۔ اسی لیے .env بیک اپ list میں شامل ہے۔

نئے tag پر Chatwoot کو upgrade کرنے کا طریقہ

commands سے زیادہ اہم ان کی ترتیب ہے۔

  1. اپنے tag اور target کے درمیان موجود release notes پڑھیں اور مطلوبہ manual steps تلاش کریں۔
  2. تازہ database dump اور storage archive بنائیں، اور تصدیق کریں کہ دونوں file sizes معمول کے مطابق ہیں۔
  3. docker-compose.yaml میں base service کا image tag edit کریں۔
  4. نیا image pull کریں، stack روکیں، migrations چلائیں، پھر stack دوبارہ start کریں۔
docker compose pull
docker compose down
docker compose run --rm rails bundle exec rails db:chatwoot_prepare
docker compose up -d
docker compose images

Migration چلانے سے پہلے image pull کریں، کیونکہ migration نئے image سے چلنی چاہیے۔ پرانے image میں نئی migration files موجود نہیں ہوتیں۔ Migration چلانے سے پہلے stack روکیں، کیونکہ پرانا code اور نیا schema ایک دوسرے سے مطابقت نہیں رکھتے۔ اس لیے چلتا ہوا پرانا Rails process errors پیدا کر سکتا ہے یا ایسی rows لکھ سکتا ہے جنہیں نیا schema قبول نہیں کرے گا۔ Stack روکنے سے migration کے لیے درکار memory بھی آزاد ہو جاتی ہے۔ upstream کی طرف سے swap کی درخواست کی یہی بنیادی وجہ ہے۔

docker compose images ہر container کے اصل میں چلنے والے tag کو print کرتا ہے۔ اس سے وہ صورت سامنے آ جاتی ہے جس میں آپ نے tag edit کیا ہو لیکن image pull کرنا بھول گئے ہوں۔

آپ کتنے بڑے version gap کو عبور کر سکتے ہیں، اس کا انحصار install کی عمر پر ہے۔ اگر install صرف ایک یا دو releases پیچھے ہو تو اپنے tag اور target کے درمیان release notes کا جائزہ لیں، target tag set کریں، اور اوپر دیے گئے steps ایک بار چلائیں۔ صرف اس صورت میں جب installation بہت پرانی ہو، upstream کی Docker guide یہ کہتی ہے کہ latest image پر براہ راست جانے کے بجائے درمیانی image tags کے ذریعے مرحلہ وار upgrade کریں۔ ایسی صورت میں ہر intermediate tag کے لیے tag change، pull اور prepare step دہرائیں، کیونکہ upstream ہر upgrade کے بعد db:chatwoot_prepare چلانے کا تقاضا کرتا ہے۔

اگر migration چلنے سے پہلے Rails start ہو جائے تو وہ requests serve کرنے سے انکار کر دیتا ہے اور ActiveRecord::PendingMigrationError: Migrations are pending log کرتا ہے۔ restart: always set ہونے پر container بار بار restart ہوتا ہے، اس لیے docker compose ps ایسا uptime دکھاتا ہے جو ہر چند سیکنڈ بعد reset ہو جاتا ہے۔ Prepare step چلانے سے مسئلہ ختم ہو جاتا ہے۔

Rollback کے لیے پرانا tag دوبارہ set کریں اور dump restore کریں۔ ایسا قابلِ اعتماد reverse migration path موجود نہیں جس پر آپ انحصار کر سکیں۔ step 2 اسی مقصد کے لیے ہے۔

خرابی کی صورتیں اور نظر آنے والی strings

Traefik کی طرف سے 502 Bad Gateway۔ Router نے match کیا، لیکن backend نے جواب نہیں دیا۔ چیک کریں کہ docker compose ps میں rails بطور Up دکھ رہا ہے، پھر docker network inspect proxy چلائیں اور تصدیق کریں کہ rails container اس کی container list میں موجود ہے۔ جو container network سے attached نہ ہو، وہ Traefik کو نظر نہیں آتا۔ اس لیے request router سے match ہوتی ہے، لیکن آگے نہیں پہنچتی۔

Dashboard load ہوتا ہے، لیکن نئے messages کے لیے refresh ضروری ہے۔ /cable سے websocket connection کامیابی سے نہیں گزر رہا، یا FRONTEND_URL browser bar میں موجود address سے match نہیں کرتا۔ اس mismatch کا مطلب ہے کہ page کسی مختلف origin سے websocket کھولنے کی کوشش کر رہا ہے، جسے browser block کر دیتا ہے۔

FATAL: password authentication failed for user "postgres"۔ .env میں موجود password اور Postgres data volume میں محفوظ password مختلف ہیں۔ اسے running container کے اندر ALTER USER سے درست کریں، کیونکہ .env میں دوبارہ ترمیم کرنے سے پہلے سے initialised database تبدیل نہیں ہوگا۔

NOAUTH Authentication required. Redis، --requirepass کے ساتھ چل رہا ہے، لیکن application نے password کے بغیر connect کیا۔ اس لیے REDIS_PASSWORD، .env میں موجود نہیں ہے یا load نہیں ہوا۔ Redis کو درکار password کی براہِ راست docker compose exec redis sh -c 'redis-cli -a "$REDIS_PASSWORD" ping' سے جانچ کریں۔ اسے PONG جواب دینا چاہیے۔ Single quotes اہم ہیں۔ ان کی وجہ سے variable آپ کے اپنے shell کے بجائے container کے اندر expand ہوتا ہے، جہاں .env پڑھا جاتا ہے اور عموماً آپ کے اپنے shell میں یہ خالی ہوتا ہے۔

Containers code 137 کے ساتھ exit ہو رہے ہیں۔ یہ SIGKILL ہے۔ چھوٹے server پر عموماً یہ signal kernel کا out of memory killer بھیجتا ہے، لیکن docker kill بھی یہی signal بھیجتا ہے۔ اس لیے memory کو ذمہ دار ٹھہرانے سے پہلے sudo dmesg -T | grep -i "killed process" چیک کریں۔ اگر مسئلہ memory کا ہو تو swap شامل کریں، ہر service کے لیے memory limits مقرر کریں، یا بڑے plan پر منتقل ہوں۔

FAQ

self-hosted Chatwoot VPS کے لیے کتنی RAM درکار ہے؟

October 2026 تک upstream کم از کم 4 GB RAM اور 4 CPU cores طلب کرتا ہے، جو روزانہ زیادہ سے زیادہ 10,000 conversations کے لیے موزوں ہیں۔ 20,000 تک conversations کے لیے 8 GB RAM اور 8 cores درکار ہیں۔ کم از کم 1 GB swap بھی شامل کریں، کیونکہ upgrade کے دوران migrations لاگو کرنے کے لیے دوسرا Rails process چلتا ہے، اور کم وسائل والے سرور کی memory اسی مرحلے پر ختم ہوتی ہے۔ 2 GB VPS دو agents کے لیے boot ہو کر کام کر لیتا ہے، لیکن load کے دوران صرف Sidekiq ہی 1 GB سے زیادہ memory استعمال کر سکتا ہے۔ اس لیے مصروف اوقات اور upgrades کے دوران containers کے exit code 137 کے ساتھ kill ہونے کی توقع رکھیں۔

Chatwoot کی password reset emails کبھی موصول کیوں نہیں ہوتیں؟

کیونکہ کوئی SMTP_ADDRESS مقرر نہیں ہے، اس لیے Chatwoot sendmail delivery پر واپس چلا جاتا ہے۔ upstream کے مطابق اس کے لیے host پر Postfix server installed ہونا چاہیے، لیکن اس Docker setup میں ایسا server موجود نہیں ہے۔ یہ job Sidekiq میں چلتا ہے، اس لیے delivery کی کوئی بھی error Sidekiq log میں درج ہوتی ہے، جبکہ browser کامیابی کا message دکھاتا رہتا ہے۔ SMTP_ADDRESS، SMTP_PORT، SMTP_USERNAME، SMTP_PASSWORD اور MAILER_SENDER_EMAIL کو .env میں مقرر کریں، rails اور sidekiq services restart کریں، پھر reset trigger کرتے وقت docker compose logs -f sidekiq کو monitor کریں۔

Chatwoot بحال کرنے کے لیے مجھے کن چیزوں کا backup لینا ہوگا؟

Postgres database، storage_data Docker volume، .env file اور compose files کا backup لیں۔ صرف database کافی نہیں ہے، کیونکہ uploaded files volume میں محفوظ ہوتی ہیں جبکہ Postgres میں صرف ان کے references موجود ہوتے ہیں۔ اس لیے صرف database بحال کرنے سے ایسی conversations ملتی ہیں جن کے attachments خراب ہوتے ہیں۔ .env اہم ہے، کیونکہ مختلف SECRET_KEY_BASE تمام users کو sign out کر دیتا ہے، جبکہ مختلف ACTIVE_RECORD_ENCRYPTION_* keys encrypted columns کو ناقابلِ مطالعہ بنا دیتی ہیں۔

Database کو خراب کیے بغیر Chatwoot کو کیسے upgrade کروں؟

Backup لیں، اپنے tag اور target کے درمیان release notes پڑھیں، compose file میں image tag تبدیل کریں، پھر docker compose pull، docker compose down، docker compose run --rm rails bundle exec rails db:chatwoot_prepare اور docker compose up -d چلائیں۔ پہلے image pull کریں، کیونکہ migrations نئی image سے چلنی چاہییں۔ stack کو پہلے stop کریں، کیونکہ new schema کے خلاف old code چلانے سے errors پیدا ہوتی ہیں۔ صرف بہت پرانے install کو latest image پر براہِ راست جانے کے بجائے intermediate image tags سے گزرنے کی ضرورت ہوتی ہے۔ ہر tag کے بعد prepare step چلائیں۔

کیا میں pgvector کے بجائے standard postgres image استعمال کر سکتا ہوں؟

نہیں۔ Chatwoot کا schema vector extension کو enable کرتا ہے، اس لیے stock postgres image میں db:chatwoot_prepare کے دوران ERROR: extension "vector" is not available کے ساتھ failure ہوتا ہے، کیونکہ اس image میں extension کی control file موجود نہیں ہے۔ upstream compose file کا pgvector/pgvector:pg16 برقرار رکھیں، یا ایسی image استعمال کریں جو آپ کے Postgres major version کے لیے pgvector فراہم کرتی ہو۔

کیا یہ مضمون مفید تھا؟

#chatwoot#self-hosting#docker-compose#support-desk#smtp#backups