SSD Nodes Learn Hosting plans →
Rehberler Matt ConnorYazan Matt Connor

Docker ile VPS uzerinde Chatwoot kurulumu rehberi

Docker Compose ve Traefik kullanarak Chatwoot kurulumu yapin. SMTP ayarlarini yapilandirma, Postgres yedekleme stratejileri ve guvenli surum yukseltme adimlarini ogrenin.

Ne inşa ediyorsunuz

Chatwoot'u bir VPS üzerinde self-host etmek için dört container çalıştırırsınız: bir Rails web süreci, bir Sidekiq arka plan işçisi, pgvector eklentisine sahip PostgreSQL ve Redis. Chatwoot açık kaynaklı bir müşteri destek masasıdır; bu sayede kontrolünüz altındaki bir sunucuda paylaşımlı bir ekip gelen kutusuna ve web sitesi sohbet widget'ına sahip olursunuz. Kurulum yaklaşık yirmi dakika sürer. Kurulumdan sonraki her şey; posta gönderimi, yedeklemeler, yükseltmeler ve boyutlandırma, sistemin bir yıl sonra hala çalışıp çalışmayacağını belirleyen unsurlardır.

Her container'ın tek bir görevi vardır. Rails, temsilci panelini ve widget API'sini (uygulama programlama arayüzü) sunar. Sidekiq yavaş işleri yürütür: e-posta gönderme, bağlı kanalları sorgulama, otomasyon kurallarını çalıştırma ve rapor oluşturma. Postgres; konuşmaları, kişileri, temsilci hesaplarını ve panelde değiştirdiğiniz her ayarı tutar. Redis, Sidekiq kuyruklarını ve yeni bir mesajı sayfa yenilemeye gerek kalmadan açık bir panele ileten ActionCable pub/sub kanalını tutar. Redis burada geçici bir önbellek değildir; çünkü onu kaybetmek, kuyruktaki işlerin kaybedilmesi anlamına gelir.

Upstream compose dosyasındaki Postgres imajı, standart postgres imajı yerine pgvector/pgvector:pg16 imajıdır; çünkü Chatwoot şeması, yapay zeka özellikleri için vector eklentisini etkinleştirir. Standart Postgres ile değiştirirseniz, eklentinin kontrol dosyası o imajda bulunmadığı için ilk veritabanı çalıştırma işlemi ERROR: extension "vector" is not available hatasıyla durur. Upstream'in sunduğu imajı kullanın.

Bu kılavuz, Docker ve bir reverse proxy'nin sunucuda halihazırda çalıştığını varsayar. Eğer çalışmıyorlarsa, Docker Compose on a VPS ile başlayın ve ardından geri dönün.

Kendi kendine barındırılan Chatwoot için ne kadar VPS gerekir?

Ekim 2026 itibarıyla upstream gereksinim sayfasında minimum değer olarak 4 GB RAM ve 4 CPU çekirdeği isteniyor. Bu kapasite, günde en fazla 10,000 konuşma için yeterli kabul ediliyor. 8 GB RAM ve 8 CPU çekirdeği ise günde en fazla 20,000 konuşma için belirtiliyor. Ayrıca en az 1 GB swap isteniyor. Gerekçe doğrudan belirtilmiş: yükseltme sırasında makinenin belleğinin tükenmemesi. Dosya yüklemeleri hesaba katılmadan önce Postgres için 5 GB ile 10 GB arasında disk alanı planlanmalıdır.

Şimdi gerçekçi değerlendirme yapılmalıdır. 2 GB RAM'e sahip bir VPS Chatwoot'u başlatır. İki agent ve düşük yoğunluklu bir gelen kutusuyla sistem sorunsuz görünebilir. Ancak iki noktada sorun çıkar. İlki Sidekiq'tir. Upstream, yoğun bir sunucuda Sidekiq kullanımını 1 GB'ın üzerinde ölçüyor. Bu nedenle kısa süreli bir e-posta yoğunluğu veya rapor görevi, Rails, Postgres ve Redis kendi paylarını almadan önce sunucunun bellek sınırını aşabilir. İkincisi yükseltmedir. Çünkü db:chatwoot_prepare migration işlemlerini uygulamak için yeni bir Rails süreci başlatır. Bu imajda Rails başlatma işlemi, yararlı bir iş yapmaya başlamadan önce yüzlerce megabayt bellek tüketir.

Önce kullanıcıya anlaşılır bir uyarı verilmez. Kernel'in out of memory killer bileşeni seçtiği sürece SIGKILL gönderir. Genellikle en büyük bellek tüketimine sahip süreç seçilir. Docker container'ın durduğunu görür ve restart: always container'ı yeniden başlatır. docker compose ps --all daha sonra sürekli yeniden başlayan veya Exited (137) durumunda kalan bir container gösterir. Burada 137, sürecin signal 9 tarafından sonlandırıldığı anlamına gelir. --all eklenmezse durmuş bir container listelenmez. Tek başına 137 çıkış kodu, nedenin kesin olarak bellek yetersizliği olduğunu kanıtlamaz. Çünkü docker kill aynı sinyali gönderir. Bu nedenle sudo dmesg -T | grep -i "killed process" ile doğrulama yapılmalıdır. Bu komut, kernel'in seçtiği sürecin adını gösterir.

4 GB bütçeyi aşıyorsa 2 GB RAM'e sahip bir sunucu, 2 GB swap ile çalıştırılabilir. Ancak yük altında yanıt sürelerinin uzayacağı kabul edilmelidir. Swap, belleğin tükenmesine karşı bir tampon görevi görür; garanti sağlamaz. Yeterince büyük bir yoğunlukta yine de bir container sonlandırılabilir. Her durumda servis başına sabit bir bellek sınırı belirlemek yararlıdır. Böylece worker, veritabanını da beraberinde durduramaz. Docker Compose içinde bellek sınırları bölümüne bakılmalıdır.

Dosya yüklemeleri, belirlenen bir sınır olmadan büyüyen bileşendir. Bir müşterinin eklediği her ekran görüntüsü storage volume içine yazılır ve orada kalır. Bu nedenle diski dolduran bileşenin veritabanı olduğunu varsaymak yerine docker system df -v izlenmelidir.

Compose dosyasını edinin ve bir sürüm etiketi sabitleyin

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

Az önce indirdiğiniz dosya image: chatwoot/chatwoot:latest ifadesini içeriyor. Başka bir işlem yapmadan önce bunu değiştirin.

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

latest kullanımı, bir sonraki docker compose pull komutunda o sabah yayınlanan herhangi bir sürümün çekilmesine neden olur; bu da hakkında hiçbir şey okumadığınız büyük bir sürüm güncellemesi veya veritabanı migrasyonu içerebilir. Chatwoot migrasyonları pratikte geri alınamaz; bu nedenle yanlışlıkla yapılan bir sürüm yükseltmesi, geri alma işlemi değil, yedekten dönme gerektirir. Etiketi sabitleyin ve değişikliği bilinçli bir şekilde yapın. 25 Ekim 2026 itibarıyla güncel sürüm v4.19.1'dir ve sürüm notları, en son güvenlik yamaları ve sıkılaştırma iyileştirmeleri için bu sürümü önermektedir; bugün sabitlemeniz gereken etiket için sürüm sayfasını kontrol edin. Eğer v4.18.0 veya daha eski bir sürümden geçiş yapıyorsanız, önce v4.19.0 notlarını okuyun: Captain V1 kullanımdan kaldırılmıştır ve V1 talimatlarını kullanan self-hosted kurulumların, yükseltme yapmadan önce bunları V2'ye taşıması gerekir. Veritabanı kullanan her uygulama aynı dikkati hak eder; bu yüzden openGym antrenman takipçisini self-host etmek rehberi, bu uygulamadan çok daha küçük olmasına rağmen bir git etiketini sabitleyerek başlar.

base servisi, rails ve sidekiq servislerinin her ikisinin de birleştirdiği bir YAML çapasıdır (anchor); bu nedenle etiketi tek bir yerde değiştirmek her ikisi için de geçerli olur. Dosya içerisindeyken, en üstteki version: '3' satırını silin. Modern Compose bu satırı yok sayar ve her komutta the attribute 'version' is obsolete, it will be ignored uyarısını yazdırır.

.env dosyasını doldurun

Önce gizli anahtarı oluşturun. Upstream, alfanümerik bir değer talep eder; çünkü özel karakterler, değer bir shell veya YAML ayrıştırıcısından geçerken bozulabilir.

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

Ardından bu anahtarları .env içinde ayarlayın.

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 ve redis://redis:6379, projenin varsayılan ağı üzerinde çözümlenen Compose servis isimleridir. FRONTEND_URL bir süsleme değildir. Chatwoot, widget betiği URL'sini ve giden her e-postanın içindeki bağlantıları bu değerle oluşturur; bu nedenle yanlış bir değer, parola sıfırlama bağlantılarının yanıt vermeyen bir ana bilgisayara yönlenmesine neden olur.

Şimdi upstream dosyasındaki tuzağa gelelim. postgres servisi .env dosyasını okumaz. Kendi environment bloğunu taşır ve bu blokta POSTGRES_PASSWORD= boş bırakılmıştır; bu yüzden parolayı sadece .env içinde ayarlamak, veritabanını parolasız, uygulamayı ise parolalı bırakır. Servisi aynı değişkene yönlendirin:

  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, ${...} ikamesi için proje dizinindeki .env dosyasını okur, böylece her iki taraf da aynı dizgiyi alır. Bunu yanlış yaparsanız Rails, PG::ConnectionBad: FATAL: password authentication failed for user "postgres" hatasıyla durur.

Bir davranış neredeyse herkesi şaşırtır: Postgres imajı, POSTGRES_PASSWORD değerini yalnızca boş bir veri dizinini başlatırken uygular. Değeri daha sonra değiştirmek bir etki yaratmaz, çünkü initdb asla ikinci kez çalışmaz. Yığını zaten bir kez başlattıysanız, değişikliği veritabanının içinden yapın.

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

ENABLE_ACCOUNT_SIGNUP=true geçicidir. İlk hesabı oluşturabilmeniz için herkese açık kayıt formunu açar. Hesabınız oluşur oluşmaz değeri false olarak ayarlayın ve docker compose up -d komutunu tekrar çalıştırın; aksi takdirde URL'yi bulan herkes destek masanıza kayıt olabilir. O andan itibaren temsilciler davetiye ile gelir ve parolaları yalnızca bu uygulamada saklanır. Bu durum, yarım düzine servis çalıştırıp her birinde ayrı bir hesap listesi tutmaktan yorulduğunuz ana kadar sorunsuzdur; o noktada Authentik gibi self-hosted bir kimlik sağlayıcı bunların yerini alan parçadır.

.env artık bu yığındaki tüm gizli bilgileri düz metin olarak tutar, bu yüzden dosya modunu 600 olarak ayarlayın ve git dışında tutun. Compose'un env dosyalarını nasıl okuduğu ve gizli bilgilerin nerede sızdığı, env_file ve environment arasındaki fark da dahil olmak üzere kritik noktaları kapsar.

Chatwoot'u mevcut Traefik'inizin arkasına konumlandırma

Tek bir uygulama için ikinci bir reverse proxy kurmayın. Eğer Traefik bu sunucudaki diğer container'lar için halihazırda TLS (transport layer security) termination yapıyorsa, Chatwoot'u bir label bloğu ile buna dahil edin. Eğer henüz böyle bir yapınız yoksa, birden fazla Docker Compose uygulamasının önünde Traefik kurulumunu bir kez yapın ve ardından buraya geri dönün.

Upstream'e ait docker-compose.yaml dosyasını orijinal haline yakın tutun; böylece daha sonra yeni bir kopyasıyla karşılaştırma (diff) yapabilir ve değişikliklerinizi bir override dosyasında toplayabilirsiniz. Compose, docker-compose.override.yaml dosyalarını otomatik olarak birleştirir; Compose dosyasını birden fazla dosyaya bölme rehberi birleştirme kurallarını açıklar.

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

Kendi entrypoint ve certresolver isimlerinizi kullanın. Container, Traefik ile aynı Docker ağı üzerinde bulunmalıdır; proxy girdisi bunu sağlar. Ayrıca container, default ağında da kalmalıdır, aksi takdirde Postgres ve Redis bağlantısını kaybeder. İkinci satır, genellikle unutulan kısımdır.

ports: bloğuna dokunmayın. Upstream bunu yalnızca loopback olan 127.0.0.1:3000 adresine bağlar; bu sayede internetten erişilemez kalır ve sunucu içinden curl -I http://127.0.0.1:3000 ile test yapmak için kullanılabilir durumda olur.

Temsilci paneli, canlı mesaj iletimi için /cable adresine bir websocket bağlantısı açık tutar. Traefik, HTTP upgrade işlemini ek bir yapılandırma gerektirmeden iletir. Eğer daha sonra Traefik'in önüne bir CDN veya başka bir proxy koyarsanız, websocket trafiğine izin verin; aksi takdirde panel normal şekilde yüklenir ancak yeni mesajlar yalnızca manuel yenileme yapıldığında görünür.

Veritabanını başlatın ve yığını çalıştırın

Önce veri servislerini ayağa kaldırın ve Postgres'in ilk çalıştırma işlemini tamamlamasına izin verin.

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

database system is ready to accept connections işleminin tamamlanmasını bekleyin. Ardından şemayı oluşturun.

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

Bu komut, veritabanı mevcut değilse oluşturur, ardından şemayı ve varsayılan başlangıç verilerini yükler. İşlem, migrasyon satırlarını yazdırır ve sorunsuz bir şekilde sonlanır. Eğer postgres:5432 - no response çıktısını yazdırmaya devam ediyorsa, giriş noktası (entrypoint) henüz bağlantı kabul etmeyen bir veritabanını bekliyordur; bu durum ilk çalıştırmada genellikle initdb işleminin hala devam ettiği anlamına gelir. Bekleyin, Postgres günlüklerini okuyun ve ardından komutu tekrar çalıştırın. Eğer vector eklentisinde duruyorsa, pgvector imajını standart Postgres imajı ile değiştirmişsiniz demektir.

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

Dört container'ın tamamı Up durumunu göstermeli ve rails günlüğü, http://0.0.0.0:3000 üzerinde dinleme yapan bir Puma satırı ile bitmelidir. Ardından genel yolu kontrol edin:

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

HTTP/2 200 yanıtı, tüm zincirin çalıştığı anlamına gelir. Traefik'ten gelen 404 hatası, yönlendirici kuralının eşleşmediğini gösterir; bu genellikle bir alan adı yazım hatasıdır. 502 hatası ise Traefik'in yönlendirici ile eşleştiğini ancak container'a ulaşamadığını gösterir; bu durum neredeyse her zaman eksik proxy ağından veya 3000 olmayan bir loadbalancer.server.port değerinden kaynaklanır.

URL'yi açın, /app/auth/signup adresinden hesabınızı oluşturun, ardından ENABLE_ACCOUNT_SIGNUP=false ayarını yapın ve formu kapatmak için docker compose up -d komutunu çalıştırın.

SMTP olmadan parola sıfırlama ve e-posta görüşmeleri neden başarısız olur?

SMTP (Simple Mail Transfer Protocol) ayarları yapılmamış bir Chatwoot, e-posta gönderemeyen bir destek masasıdır ve bu durum sadece bildirimlerden fazlasını bozar. Parola sıfırlama işlemleri çalışmaz; bu nedenle kilitlenen bir yönetici sistem dışında kalır. Temsilci davetleri çalışmaz, çünkü bir davet e-posta yoluyla gönderilir. Bir e-posta görüşmesinde müşteriye yanıt vermek imkansız hale gelir, böylece görüşme tek taraflı kalır. Bu, insanların atladığı ve en kötü zamanlarında fark ettikleri adımdır.

Mekanizma basittir. SMTP_ADDRESS ayarlanmadığında, Chatwoot ActionMailer'ı sendmail teslimatına geçirir. Upstream belgeleri bunu v2.12.0 sürümünden beri varsayılan olan Postfix kurulumu olarak tanımlar ve bunun için sunucuya sudo apt install -y postfix ile Postfix kurulmasını önerir. Bu Docker kurulumu bunu yapmaz, dolayısıyla e-postayı teslim edecek yapılandırılmış bir posta sunucusu yoktur. Posta, arka plan işi olarak gönderilir; bu nedenle teslimatın ürettiği hata Rails günlüğüne değil, Sidekiq günlüğüne düşer. Bu sırada "parolamı unuttum" butonuna tıklayan kişi neşeli bir onay mesajı görür ancak eline hiçbir şey ulaşmaz.

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

Bağlantıyı düz metin olarak başlatan ve kimlik doğrulamadan önce şifreli hale getiren STARTTLS ile 587 numaralı portu kullanın. Birçok VPS sağlayıcısı, spam'i sınırlamak için varsayılan olarak 25 numaralı giden portu engeller. 8 Kasım 2026 itibarıyla Hetzner, bulut sunucularında 25 ve 465 numaralı portları varsayılan olarak engeller ve bu engelleme hesap bazında uygulanır; Vultr ise tüm yeni Compute Instance'larda 25 numaralı portu engeller. Her iki sağlayıcı da engeli kaldırma taleplerini vaka bazında inceler; Hetzner, limit artırma talebi gönderebilmeniz için bir ay müşteri olmanızı ve ilk faturayı ödemenizi şart koşar. İkisi de 587 numaralı portu engellemez, bu nedenle 587 üzerinden bir relay, bilet açmaya veya beklemeye gerek kalmadan ilk açılıştan itibaren çalışır. SMTP_DOMAIN, sunucunuzun SMTP görüşmesi sırasında duyurduğu alan adıdır ve bazı relay'ler uyumsuzluk durumunda bağlantıyı reddeder.

Ayarları uygulayın ve işleyiciyi izleyin:

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

Giriş sayfasından bir parola sıfırlama işlemi tetikleyin. Çalışan bir teslimat, Sidekiq günlüğünde posta işinin normal şekilde tamamlandığını gösterir. Bir hata durumunda ise istisna sınıfı görünür ve Sidekiq artan bir bekleme süresiyle yeniden deneme yapar; bozuk bir relay'in saatlerce her birkaç dakikada bir aynı hatayı üretmesinin nedeni budur.

İki tür reddetme yaygındır ve bunların hiçbiri Chatwoot hatası değildir. 535 Authentication failed, kimlik doğrulamanın başarısız olduğu anlamına gelir; bu nedenle kimlik bilgilerini, SMTP kimlik doğrulamasının etkin olup olmadığını ve bir erişim politikasının bunu engelleyip engellemediğini kontrol edin; yalnızca doğru kimlik bilgileri bu hatayı ortadan kaldırmaz. Bazı sağlayıcılar hesap parolası yerine uygulama özelinde bir parola gerektirir. 550 Sender address rejected, sunucunun gönderen adresini reddettiği anlamına gelir; MAILER_SENDER_EMAIL değerini değiştirmeden önce yanıtın tamamını okuyun. Gönderen izinleri veya doğrulaması bir nedendir, ancak 550 5.7.27 Sender address rejected: Domain does not accept mail, null MX kaydına sahip bir gönderen alan adına işaret eder.

Bir görüşmeye e-posta almak ayrı bir iştir. Chatwoot girişi üzerinden yönlendirme yapmak için MAILER_INBOUND_EMAIL_DOMAIN ve RAILS_INBOUND_EMAIL_SERVICE değerlerine, ayrıca gelen iletileri Chatwoot'a teslim eden bir posta sunucusuna ihtiyaç vardır. Ayrıca, bu yönlendirme yolunu kurmadan, Google veya Microsoft OAuth dahil olmak üzere IMAP üzerinden bir posta kutusu bağlayabilirsiniz. Bir relay kiralamak hızlı yoldur. Tüm posta yoluna sahip olmak isterseniz, Mailcow ile kendi posta sunucunuzu çalıştırmak rehberi, bu taahhüdün gerçekte neleri içerdiğini açıklar.

Nelerin yedekleneceği ve geri yüklemenin çalıştığının nasıl doğrulanacağı

Bir Chatwoot yedeği dört parçadan oluşur; bunlardan herhangi birini atlamak, geri yükleme işlemini bir yeniden inşa sürecine dönüştürür.

  • Konuşmaları, kişileri, temsilci hesaplarını ve tüm ayarları barındıran Postgres veritabanı.
  • storage_data birimi; çünkü ACTIVE_STORAGE_SERVICE=local, yüklenen dosyaları diske yazar ve Postgres içinde yalnızca bir referans satırı tutar.
  • .env dosyası; çünkü SECRET_KEY_BASE ve ACTIVE_RECORD_ENCRYPTION_* anahtarlarını içerir.
  • Compose dosyaları; çünkü veritabanı şemanızın uyumlu olduğu tam imaj etiketini bunlar kaydeder.

Veritabanını tek başına geri yüklerseniz, tüm konuşmalar bozuk eklerle geri gelir; çünkü satırlar artık diskte bulunmayan dosyaları işaret etmektedir.

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

-T önemlidir. Bu bayrak olmadan Compose, akış içindeki satır başı baytlarını yeniden yazan bir sözde terminal (pseudo terminal) ayırır; bu da pg_restore tarafından reddedilen bir döküm dosyasıyla sonuçlanır. -Fc, sıkıştırma sağlayan ve pg_restore aracının seçici çalışmasına olanak tanıyan özel formattır.

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

Birim adı, proje dizininizin adıyla birlikte _storage_data ifadesinden oluşur. Bu komuta güvenmeden önce docker volume ls | grep storage_data ile birim adını doğrulayın; çünkü Docker, var olmayan bir isim verdiğinizde hata vermek yerine boş bir birim oluşturur. Bu durumda hiçbir hata almadan geçerli ancak boş bir arşiv elde edersiniz. İşlem sonrasında boyutu ls -lh storage-*.tgz ile kontrol edin.

Her iki dosya da şu an korudukları şeyle aynı diskte durmaktadır, bu da sizi hiçbir şeye karşı korumaz. Veritabanı dökümü tüm müşteri mesajlarını düz metin olarak içerdiğinden, bu dosyaları sunucudan dışarı aktarın ve şifreleyin. restic ile şifreli sunucu dışı yedeklemeler bölümü, zamanlama ve saklama tarafını ele almaktadır.

Geri yükleme tatbikatı: İhtiyaç duymadan önce deneyin

Geri yüklemeyi canlı sunucuya değil, ikinci bir VPS üzerine yapın. .env dosyasını, compose dosyalarını ve her iki arşivi kopyaladıktan sonra şu komutu çalıştırın:

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, yükleme yapmadan önce mevcut nesneleri siler, bu nedenle bu komutu yalnızca kaybetmeyi göze aldığınız bir veritabanı üzerinde kullanın. Ardından giriş yapın ve bir eki olan bir konuşmayı açın. Mesaj listesi yükleniyor ve dosya indirilebiliyorsa, yedekleme gerçektir.

Farklı bir SECRET_KEY_BASE ile yapılan geri yükleme, tüm oturum çerezlerini geçersiz kılar ve herkesin oturumu kapatılır. Farklı ACTIVE_RECORD_ENCRYPTION_* anahtarlarıyla yapılan bir geri yükleme ise daha kötüdür: Chatwoot, kanal kimlik bilgilerini tutan sütunların şifresini çözemez ve ActiveRecord::Encryption::Errors::Decryption hatası verir. .env dosyasının yedekleme listesinde yer almasının nedeni budur.

Chatwoot sürümünü yeni bir etikete yükseltme

Sıralama, komutların kendisinden daha önemlidir.

  1. Mevcut etiketiniz ile hedef etiket arasındaki sürüm notlarını okuyun ve gerekli manuel adımları kontrol edin.
  2. Veritabanının güncel bir yedeğini ve depolama arşivini alın; her iki dosya boyutunun da normal göründüğünden emin olun.
  3. docker-compose.yaml dosyasındaki base servisine ait imaj etiketini düzenleyin.
  4. Yeni imajı çekin, stack'i durdurun, migrasyonları çalıştırın ve ardından tekrar başlatın.
docker compose pull
docker compose down
docker compose run --rm rails bundle exec rails db:chatwoot_prepare
docker compose up -d
docker compose images

Migrasyonu çalıştırmadan önce imajı çekin; çünkü migrasyon işlemi yeni imaj üzerinden yürütülmelidir: eski imaj yeni migrasyon dosyalarını içermez. Migrasyon öncesinde stack'i durdurun; çünkü eski kod ile yeni şema uyumsuzdur ve çalışan eski bir Rails süreci hatalara yol açabilir veya yeni şemanın kabul etmeyeceği satırlar yazabilir. Durdurma işlemi ayrıca migrasyonun ihtiyaç duyduğu belleği serbest bırakır; upstream tarafının swap istemesinin temel nedeni budur.

docker compose images komutu, her container'ın halihazırda çalıştırdığı etiketi yazdırır; bu, etiketi düzenleyip imajı çekmeyi unuttuğunuz durumları tespit etmenizi sağlar.

Ne kadar ileriye atlayabileceğiniz, kurulumun ne kadar eski olduğuna bağlıdır. Bir veya iki sürüm geride olan bir kurulum için mevcut etiketiniz ile hedef arasındaki sürüm notlarını inceleyin, hedef etiketi ayarlayın ve yukarıdaki adımları bir kez uygulayın. Yalnızca kurulumunuz çok eskiyse, upstream tarafının Docker rehberi sizi doğrudan en son imaja atlamak yerine ara imaj etiketleri üzerinden kademeli olarak yükseltmeye yönlendirir. Bu durumda, etiket değiştirme, çekme ve hazırlama adımlarını her ara sürüm için tekrarlayın; çünkü upstream her yükseltmeden sonra db:chatwoot_prepare çalıştırılmasını ister.

Rails, migrasyon çalıştırılmadan önce başlarsa servis vermeyi reddeder ve ActiveRecord::PendingMigrationError: Migrations are pending hatasını günlüğe yazar. restart: always ayarlıysa container döngüye girer ve docker compose ps çıktısında çalışma süresinin her birkaç saniyede bir sıfırlandığı görülür. Hazırlık adımını çalıştırdığınızda bu durum düzelir.

Geri alma işlemi, eski etiketi tekrar ayarlamak ve yedeği geri yüklemek anlamına gelir. Güvenebileceğiniz bir ters migrasyon yolu yoktur; 2. adımın amacı da budur.

Hata türleri ve görülecek dizeler

Traefik kaynaklı 502 Bad Gateway. Router eşleşti, ancak backend yanıt vermedi. docker compose ps çıktısında rails servisinin Up olarak göründüğünü kontrol edin. Ardından docker network inspect proxy komutunu çalıştırın ve rails container'ının container listesinde yer aldığını doğrulayın. Bir ağa bağlanmamış container Traefik tarafından görünmez. Bu nedenle istek bir router ile eşleşir, ancak devam edemez.

Dashboard yükleniyor, ancak yeni mesajları görmek için yenileme gerekiyor. /cable adresine açılan websocket bağlantısı ulaşmıyor olabilir veya FRONTEND_URL değeri tarayıcı adres çubuğundaki adresle eşleşmiyor olabilir. Eşleşme olmadığında sayfa farklı bir origin'e websocket bağlantısı açmaya çalışır. Tarayıcı bu bağlantıyı engeller.

FATAL: password authentication failed for user "postgres". .env içindeki parola ile Postgres data volume içine yazılmış parola farklıdır. Çalışan container içinde ALTER USER komutunu kullanarak düzeltin. .env dosyasını yeniden düzenlemek, zaten başlatılmış bir veritabanını değiştirmez.

NOAUTH Authentication required. Redis, --requirepass ile çalışıyor, ancak uygulama parola kullanmadan bağlanmış. Bu nedenle REDIS_PASSWORD değeri .env içinde eksik olabilir veya okunmamış olabilir. Redis'in beklediği parolayı doğrudan docker compose exec redis sh -c 'redis-cli -a "$REDIS_PASSWORD" ping' ile test edin. Komutun PONG yanıtını vermesi gerekir. Tek tırnaklar önemlidir. Değişkenin kendi shell'inizde değil, .env değerini okuyan container içinde genişletilmesini sağlar. Kendi shell'inizde bu değişken genellikle boştur.

137 koduyla sonlanan container'lar. Bu, SIGKILL sinyalidir. Küçük bir sunucuda bu sinyali genellikle kernel'in out of memory killer bileşeni gönderir. Ancak docker kill de aynı sinyali gönderir. Bu nedenle belleği sorumlu tutmadan önce sudo dmesg -T | grep -i "killed process" değerini kontrol edin. Sorun bellekse swap ekleyin, servis başına bellek limitleri belirleyin veya daha büyük bir plana geçin.

FAQ

Kendi kendine barındırılan bir Chatwoot VPS ne kadar RAM'e ihtiyaç duyar?

Ekim 2026 itibarıyla, upstream minimum 4 GB RAM ve 4 CPU çekirdeği önermektedir; bu yapılandırma günde 10.000 görüşmeye kadar destek verir. 20.000 görüşmeye kadar olan yükler için ise 8 GB RAM ve 8 çekirdek gereklidir. En az 1 GB swap alanı eklenmelidir; çünkü yükseltme işlemleri sırasında migrasyonları uygulamak için ikinci bir Rails süreci çalıştırılır ve düşük bellekli sunucular bu noktada bellek yetersizliği yaşar. 2 GB RAM'li bir VPS, birkaç temsilci için çalışabilir ancak Sidekiq tek başına yük altında 1 GB belleği aşabilir. Bu nedenle yoğun dönemlerde ve yükseltmeler sırasında container'ların 137 çıkış koduyla sonlandırılmasını beklemelisiniz.

Chatwoot şifre sıfırlama e-postaları neden ulaşmıyor?

Çünkü herhangi bir SMTP_ADDRESS ayarlanmamıştır. Bu durumda Chatwoot, sunucuda yüklü bir Postfix servisinin varlığını varsayan sendmail teslimatına geri döner; ancak bu Docker kurulumunda böyle bir servis bulunmamaktadır. İşlem Sidekiq içinde yürütüldüğü için tarayıcıda başarı mesajı görünse bile teslimat hataları Sidekiq günlüklerine düşer. .env dosyasında SMTP_ADDRESS, SMTP_PORT, SMTP_USERNAME, SMTP_PASSWORD ve MAILER_SENDER_EMAIL değişkenlerini yapılandırın, rails ve sidekiq servislerini yeniden başlatın ve ardından sıfırlama işlemini tetiklerken docker compose logs -f sidekiq dosyasını izleyin.

Chatwoot'u geri yüklemek için neleri yedeklemeliyim?

Postgres veritabanını, storage_data Docker volume'unu, .env dosyasını ve compose dosyalarını yedeklemelisiniz. Yalnızca veritabanı yeterli değildir; yüklenen dosyalar volume içinde tutulurken Postgres sadece bunlara ait referansları saklar. Bu nedenle sadece veritabanı yedeği, bozuk ekli görüşmelerle sonuçlanır. .env önemlidir; çünkü farklı bir SECRET_KEY_BASE tüm kullanıcıların oturumunu kapatır ve farklı ACTIVE_RECORD_ENCRYPTION_* anahtarları şifrelenmiş sütunların okunamaz hale gelmesine neden olur.

Veritabanını bozmadan Chatwoot'u nasıl yükseltebilirim?

Yedek alın, mevcut sürümünüz ile hedef sürüm arasındaki sürüm notlarını okuyun, compose dosyanızdaki image etiketini değiştirin ve ardından docker compose pull, docker compose down, docker compose run --rm rails bundle exec rails db:chatwoot_prepare ve docker compose up -d komutlarını çalıştırın. Önce image'ı çekin (pull), çünkü migrasyonlar yeni image üzerinden çalışmalıdır. Stack'i önceden durdurun; çünkü eski kodun yeni şema üzerinde çalışması hatalara yol açar. Sadece çok eski kurulumlar, doğrudan en son sürüme geçmek yerine ara sürümler üzerinden ilerlemeyi ve her adımda hazırlık (prepare) aşamasını çalıştırmayı gerektirebilir.

pgvector yerine standart postgres image'ını kullanabilir miyim?

Hayır. Chatwoot şeması vector eklentisini etkinleştirir. Bu nedenle standart postgres image'ı, eklentinin kontrol dosyası bulunmadığı için db:chatwoot_prepare sırasında ERROR: extension "vector" is not available hatası vererek başarısız olur. Upstream compose dosyasındaki pgvector/pgvector:pg16 değerini koruyun veya Postgres ana sürümünüz için pgvector içeren başka bir image kullanın.

Bu yazı işinize yaradı mı?