SSD Nodes Learn Hosting plans →
Przewodniki Matt ConnorAutor: Matt Connor

Własny serwer Chatwoot na VPS z Docker Compose

Instrukcja samodzielnego hostowania Chatwoot na VPS przy użyciu Docker Compose i Traefik. Poradnik obejmuje konfigurację SMTP, PostgreSQL, kopii zapasowych oraz bezpieczne aktualizacje.

Co budujesz

W celu samodzielnego hostowania Chatwoot na VPS uruchamia się cztery kontenery: proces webowy Rails, proces przetwarzania w tle Sidekiq, PostgreSQL z rozszerzeniem pgvector oraz Redis. Chatwoot to otwartoźródłowe narzędzie typu customer support desk, zapewniające współdzieloną skrzynkę odbiorczą zespołu oraz widget czatu na stronie WWW na serwerze pod Twoją kontrolą. Instalacja zajmuje około dwudziestu minut. Wszystkie późniejsze działania, takie jak dostarczanie poczty, kopie zapasowe, aktualizacje i skalowanie, decydują o tym, czy rozwiązanie będzie działać po roku.

Każdy kontener pełni jedną funkcję. Rails obsługuje panel agenta oraz API (application programming interface) widgetu. Sidekiq wykonuje zadania wymagające czasu: wysyłkę e-maili, odpytywanie podłączonych kanałów, uruchamianie reguł automatyzacji oraz generowanie raportów. Postgres przechowuje konwersacje, kontakty, konta agentów oraz wszystkie ustawienia zmieniane w panelu. Redis obsługuje kolejki Sidekiq oraz kanał pub/sub ActionCable, który przesyła nową wiadomość do otwartego panelu bez konieczności odświeżania strony. Redis nie pełni tu roli tymczasowej pamięci podręcznej, ponieważ jego utrata oznacza utratę zakolejkowanych zadań.

Obraz Postgres w dostarczonym pliku compose to pgvector/pgvector:pg16, a nie standardowy obraz postgres, ponieważ schemat bazy danych Chatwoot wymaga rozszerzenia vector dla funkcji AI. Użycie standardowego obrazu Postgres spowoduje zatrzymanie pierwszego uruchomienia bazy danych z błędem ERROR: extension "vector" is not available, ponieważ plik kontrolny rozszerzenia nie znajduje się w tym obrazie. Należy używać obrazu dostarczonego przez twórców oprogramowania.

Ten przewodnik zakłada, że Docker oraz reverse proxy są już skonfigurowane na serwerze. Jeśli tak nie jest, rozpocznij od Docker Compose na VPS, a następnie wróć do tego materiału.

Jakie zasoby VPS są wymagane dla samodzielnie hostowanego Chatwoot?

Według stanu na październik 2026 r. oficjalna dokumentacja wymaga minimum 4 GB pamięci RAM oraz 4 rdzeni CPU, co ma wystarczyć do obsługi 10 000 konwersacji dziennie. Konfiguracja z 8 GB RAM i 8 rdzeniami CPU pozwala na obsługę do 20 000 konwersacji dziennie. Wymagane jest również co najmniej 1 GB przestrzeni swap, co ma zapobiegać brakom pamięci podczas procesu aktualizacji. Należy zaplanować od 5 GB do 10 GB miejsca na dysku dla Postgres, nie wliczając w to miejsca na przesyłane pliki.

W kwestii technicznej: VPS z 2 GB RAM uruchomi Chatwoot i przy dwóch agentach oraz niewielkim ruchu będzie działał poprawnie. System zawiedzie jednak w dwóch przypadkach. Pierwszym jest Sidekiq, który według dokumentacji zajmuje ponad 1 GB pamięci na obciążonym serwerze. Nagły wzrost liczby wiadomości e-mail lub generowanie raportów spowoduje przekroczenie dostępnej pamięci, zanim Rails, Postgres i Redis otrzymają swój przydział. Drugim przypadkiem jest aktualizacja, ponieważ db:chatwoot_prepare uruchamia nowy proces Rails w celu wykonania migracji, a sam start Rails w tym obrazie zużywa setki megabajtów pamięci przed wykonaniem jakichkolwiek zadań.

System nie wysyła ostrzeżeń. Mechanizm out of memory killer jądra systemu wysyła sygnał SIGKILL do wybranego procesu, zazwyczaj tego, który zajmuje najwięcej pamięci. Docker wykrywa zatrzymanie kontenera, a restart: always uruchamia go ponownie. docker compose ps --all wykaże wtedy kontener, który ciągle się restartuje lub znajduje się w stanie Exited (137), gdzie kod 137 oznacza zakończenie sygnałem 9. Bez użycia --all zatrzymany kontener nie będzie widoczny na liście. Sam kod wyjścia 137 nie potwierdza, że przyczyną był brak pamięci, ponieważ docker kill wysyła ten sam sygnał. Należy to zweryfikować za pomocą sudo dmesg -T | grep -i "killed process", który wskaże proces wybrany przez jądro.

Jeśli budżet nie pozwala na 4 GB RAM, można uruchomić serwer z 2 GB RAM i 2 GB swap, akceptując spadek wydajności pod obciążeniem. Swap stanowi bufor, a nie gwarancję dostępności pamięci, więc nagły skok obciążenia nadal może spowodować zabicie kontenera. Warto w każdym przypadku ustawić sztywne limity pamięci dla każdej usługi, aby proces roboczy nie spowodował awarii bazy danych. Szczegóły znajdują się w limity pamięci w Docker Compose.

Przesyłane pliki to element, którego rozmiar rośnie w sposób niekontrolowany. Każdy zrzut ekranu załączony przez klienta trafia do wolumenu pamięci masowej i tam pozostaje, dlatego należy monitorować docker system df -v, zamiast zakładać, że to baza danych zapełniła dysk.

Pobranie pliku compose i przypięcie wersji

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

Pobrany przed chwilą plik zawiera image: chatwoot/chatwoot:latest. Zmień to, zanim przejdziesz do dalszych działań.

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

latest oznacza, że kolejne docker compose pull dostarczy wersję opublikowaną danego dnia, co może być wydaniem głównym z migracjami, o których nie czytałeś. Migracje Chatwoot w praktyce nie są odwracalne, więc przypadkowa aktualizacja oznacza konieczność przywracania danych z kopii zapasowej, a nie cofnięcie zmian. Przypnij tag i zmieniaj go w sposób świadomy. Wersja v4.19.1 była aktualnym wydaniem na dzień 25 października 2026, a jej informacje o wydaniu zalecają ją ze względu na najnowsze poprawki bezpieczeństwa i usprawnienia; sprawdź stronę wydań, aby dowiedzieć się, jaki tag przypiąć dzisiaj. Jeśli aktualizujesz system z wersji v4.18.0 lub starszej, najpierw przeczytaj notatki do v4.19.0: Captain V1 został wycofany, a instalacje self-hosted korzystające z instrukcji V1 muszą zostać zmigrowane do V2 przed aktualizacją. Każde oprogramowanie zarządzające bazą danych wymaga takiej samej ostrożności, dlatego self-hosting trackera treningów openGym rozpoczyna się od przypięcia tagu git, mimo że jest to znacznie mniejsza aplikacja niż ta.

Usługa base to kotwica YAML, którą rails oraz sidekiq integrują, więc zmiana tagu w jednym miejscu zmienia go dla obu. Będąc w pliku, usuń linię version: '3' na samej górze. Nowoczesny Compose ignoruje ją i wyświetla the attribute 'version' is obsolete, it will be ignored przy każdym poleceniu.

Wypełnianie pliku .env

Najpierw wygeneruj klucz tajny. Producent wymaga wartości alfanumerycznej, ponieważ znaki specjalne mogą zostać błędnie zinterpretowane podczas przekazywania wartości przez powłokę lub parser YAML.

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

Następnie ustaw poniższe klucze w .env.

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 oraz redis://redis:6379 to nazwy usług w Compose, które są rozpoznawane w domyślnej sieci projektu. FRONTEND_URL nie jest elementem dekoracyjnym. Chatwoot używa tej wartości do budowania adresu URL skryptu widgetu oraz każdego odnośnika w wychodzących wiadomościach e-mail. Błędna wartość spowoduje, że linki do resetowania hasła będą wskazywać na hosta, który nie odpowiada.

Oto pułapka w pliku dostarczonym przez producenta. Usługa postgres nie odczytuje .env. Posiada ona własny blok environment z pozostawionym pustym polem POSTGRES_PASSWORD=, więc ustawienie hasła wyłącznie w .env sprawi, że baza danych pozostanie bez hasła, a aplikacja będzie próbowała użyć własnego. Wskaż usłudze tę samą zmienną:

  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 odczytuje .env z katalogu projektu w celu podstawienia ${...}, dzięki czemu obie strony otrzymują ten sam ciąg znaków. Błąd w tym miejscu spowoduje zatrzymanie Rails z błędem PG::ConnectionBad: FATAL: password authentication failed for user "postgres".

Jedno zachowanie zaskakuje niemal każdego: obraz Postgres stosuje POSTGRES_PASSWORD tylko podczas inicjalizacji pustego katalogu danych. Późniejsza zmiana wartości nie przynosi efektu, ponieważ initdb nigdy nie uruchamia się ponownie. Jeśli stos został już raz uruchomiony, zmień hasło bezpośrednio w bazie danych.

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

ENABLE_ACCOUNT_SIGNUP=true jest tymczasowe. Otwiera ono publiczny formularz rejestracji, umożliwiając utworzenie pierwszego konta. Ustaw tę wartość na false i uruchom ponownie docker compose up -d natychmiast po utworzeniu konta, w przeciwnym razie każdy, kto znajdzie adres URL, będzie mógł zarejestrować się w Twoim systemie zgłoszeń. Od tego momentu agenci będą dodawani przez zaproszenia, a ich hasła będą przechowywane wyłącznie w tej aplikacji. Jest to akceptowalne do momentu, gdy zarządzasz kilkoma usługami i chcesz uniknąć utrzymywania osobnej listy kont w każdej z nich; wtedy rozwiązaniem staje się samodzielnie hostowany dostawca tożsamości, taki jak Authentik.

.env zawiera teraz wszystkie sekrety tego stosu w postaci czystego tekstu, dlatego należy ustawić dla niego uprawnienia 600 i nie umieszczać go w git. Artykuł Jak Compose odczytuje pliki env i gdzie wyciekają sekrety omawia potencjalne zagrożenia, w tym różnicę między env_file a environment.

Konfiguracja Chatwoot za istniejącym Traefik

Nie należy budować drugiego reverse proxy dla pojedynczej aplikacji. Jeśli Traefik już obsługuje terminację TLS (transport layer security) dla innych kontenerów na tym serwerze, Chatwoot dołącza do niego za pomocą bloku etykiet. Jeśli taka konfiguracja jeszcze nie istnieje, należy ją najpierw przygotować zgodnie z Traefik przed kilkoma aplikacjami Docker Compose, a następnie wrócić do tego miejsca.

Należy zachować plik docker-compose.yaml dostarczony przez producenta w stanie zbliżonym do oryginału, aby umożliwić późniejsze porównywanie zmian (diff) z nowszymi wersjami, a własne modyfikacje umieścić w pliku nadpisującym. Compose automatycznie scala docker-compose.override.yaml, a zasady tego procesu opisano w dzieleniu Compose na wiele plików.

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

Należy użyć własnych nazw entrypoint oraz certresolver. Kontener musi znajdować się w tej samej sieci Docker co Traefik, co zapewnia wpis proxy, a także musi pozostać w default, w przeciwnym razie utraci dostęp do Postgres i Redis. To właśnie ten drugi wiersz jest najczęściej pomijany.

Blok ports: należy pozostawić bez zmian. Producent wiąże go z 127.0.0.1:3000, co oznacza adresację wyłącznie loopback, dzięki czemu usługa nie jest dostępna z Internetu, a jednocześnie pozostaje użyteczna do testów z poziomu serwera za pomocą curl -I http://127.0.0.1:3000.

Panel agenta utrzymuje otwarte połączenie websocket do /cable w celu dostarczania wiadomości w czasie rzeczywistym. Traefik przekazuje żądanie HTTP upgrade bez dodatkowej konfiguracji, więc nie ma potrzeby wprowadzania zmian. Jeśli w przyszłości przed Traefik zostanie umieszczona sieć CDN lub inne proxy, należy tam zezwolić na obsługę websocketów, ponieważ w przeciwnym razie panel będzie ładował się poprawnie, ale nowe wiadomości pojawią się dopiero po ręcznym odświeżeniu strony.

Inicjalizacja bazy danych i uruchomienie stosu

Najpierw uruchom usługi danych i pozwól Postgres zakończyć pierwsze uruchomienie.

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

Poczekaj na database system is ready to accept connections. Następnie utwórz schemat.

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

To polecenie tworzy bazę danych, jeśli jej brakuje, a następnie ładuje schemat i domyślne dane początkowe. Wyświetla ono wiersze migracji i kończy działanie w sposób prawidłowy. Jeśli proces zatrzyma się na wyświetlaniu postgres:5432 - no response, punkt wejścia oczekuje na bazę danych, która jeszcze nie akceptuje połączeń, co przy pierwszym uruchomieniu zazwyczaj oznacza, że initdb wciąż pracuje. Należy poczekać, sprawdzić logi Postgres, a następnie uruchomić polecenie ponownie. Jeśli proces zatrzyma się na rozszerzeniu vector, oznacza to, że obraz pgvector został zastąpiony standardowym obrazem Postgres.

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

Wszystkie cztery kontenery powinny wskazywać Up, a log rails powinien kończyć się wierszem Puma nasłuchującym na http://0.0.0.0:3000. Następnie sprawdź ścieżkę publiczną:

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

HTTP/2 200 oznacza, że cały łańcuch działa poprawnie. Błąd 404 z Traefik oznacza, że reguła routera nie została dopasowana, co zazwyczaj wynika z literówki w nazwie hosta. Błąd 502 oznacza, że Traefik dopasował router, ale nie mógł nawiązać połączenia z kontenerem, co niemal zawsze wynika z braku sieci proxy lub portu loadbalancer.server.port innego niż 3000.

Otwórz adres URL, utwórz konto pod /app/auth/signup, a następnie ustaw ENABLE_ACCOUNT_SIGNUP=false i uruchom docker compose up -d, aby zamknąć formularz.

Dlaczego resetowanie haseł i konwersacje e-mail nie działają bez SMTP

Chatwoot bez skonfigurowanych ustawień SMTP (Simple Mail Transfer Protocol) to system obsługi zgłoszeń, który nie może wysyłać wiadomości, co powoduje problemy wykraczające poza same powiadomienia. Resetowanie haseł przestaje działać, więc administrator, który utracił dostęp, nie może go odzyskać. Zaproszenia dla agentów również nie działają, ponieważ zaproszenie jest wiadomością e-mail. Odpowiadanie klientowi w ramach konwersacji e-mailowej przestaje funkcjonować, przez co komunikacja staje się jednostronna. Jest to krok, który użytkownicy często pomijają, a jego brak odkrywają w najmniej odpowiednim momencie.

Mechanizm jest prosty. Bez ustawionego SMTP_ADDRESS, Chatwoot przełącza ActionMailer na dostarczanie przez sendmail. Dokumentacja upstream opisuje to jako konfigurację Postfix, domyślną od wersji v2.12.0, a instrukcje instalują Postfix na serwerze za pomocą sudo apt install -y postfix. Ta konfiguracja Docker tego nie robi, więc nie ma skonfigurowanego serwera pocztowego, któremu można przekazać wiadomość. Poczta wychodzi z zadania w tle, więc każdy błąd dostarczania trafia do dziennika Sidekiq, a nie do dziennika Rails. W tym samym czasie osoba klikająca "zapomniałem hasła" widzi komunikat z potwierdzeniem, ale nie otrzymuje żadnej wiadomości.

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

Należy użyć portu 587 z STARTTLS, który otwiera połączenie w tekście jawnym i aktualizuje je do szyfrowanego przed uwierzytelnieniem. Wielu dostawców VPS domyślnie blokuje wychodzący port 25, aby ograniczyć spam. Według stanu na 8 listopada 2026, Hetzner domyślnie blokuje porty 25 i 465 na serwerach chmurowych, przy czym blokada jest egzekwowana na poziomie konta, a Vultr blokuje port 25 na wszystkich nowych instancjach Compute. Obaj dostawcy rozpatrują wnioski o odblokowanie indywidualnie; Hetzner wymaga bycia klientem przez miesiąc i opłacenia pierwszej faktury przed złożeniem wniosku o zmianę limitów. Żaden z nich nie blokuje portu 587, więc przekaźnik (relay) na porcie 587 działa od pierwszego uruchomienia bez konieczności otwierania zgłoszeń i oczekiwania. SMTP_DOMAIN to domena, którą serwer ogłasza podczas sesji SMTP, a niektóre przekaźniki odrzucają połączenia w przypadku niezgodności.

Zastosuj ustawienia i monitoruj proces roboczy:

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

Wywołaj reset hasła ze strony logowania. Poprawne dostarczenie wiadomości oznacza, że zadanie mailera kończy się normalnie w dzienniku Sidekiq. Błąd powoduje wyświetlenie klasy wyjątku, a następnie Sidekiq ponawia próbę z rosnącym opóźnieniem, dlatego uszkodzony przekaźnik generuje ten sam błąd co kilka minut przez wiele godzin.

Dwa rodzaje odrzuceń są powszechne i żaden z nich nie jest błędem Chatwoot. 535 Authentication failed oznacza, że uwierzytelnienie nie powiodło się, więc należy sprawdzić dane logowania, czy uwierzytelnianie SMTP jest włączone oraz czy polityka dostępu go nie blokuje; poprawne dane logowania nie wykluczają tego błędu. Niektórzy dostawcy wymagają hasła aplikacji zamiast hasła do konta. 550 Sender address rejected oznacza, że serwer odrzucił adres nadawcy; przed zmianą MAILER_SENDER_EMAIL należy przeczytać pełną treść odpowiedzi. Uprawnienia nadawcy lub weryfikacja są jedną z przyczyn, ale 550 5.7.27 Sender address rejected: Domain does not accept mail wskazuje na domenę nadawcy z rekordem MX o wartości null.

Odbieranie wiadomości e-mail w ramach konwersacji to oddzielne zadanie. Do przekazywania przez mechanizm wejściowy Chatwoot wymagane są MAILER_INBOUND_EMAIL_DOMAIN i RAILS_INBOUND_EMAIL_SERVICE oraz serwer pocztowy, który przekazuje przychodzące wiadomości do Chatwoot. Można również połączyć skrzynkę pocztową przez IMAP, w tym z użyciem Google lub Microsoft OAuth, bez konfigurowania ścieżki przekazywania. Wynajęcie przekaźnika to najszybsza droga. Jeśli wolisz zarządzać całą ścieżką poczty samodzielnie, uruchomienie własnego serwera pocztowego z Mailcow opisuje, co faktycznie wiąże się z takim zobowiązaniem.

Co należy archiwizować i jak zweryfikować poprawność przywracania

Kopia zapasowa Chatwoot składa się z czterech części. Pominięcie którejkolwiek z nich sprawia, że przywracanie staje się procesem odbudowy systemu od zera.

  • Baza danych Postgres, która przechowuje konwersacje, kontakty, konta agentów oraz wszystkie ustawienia.
  • Wolumen storage_data, ponieważ ACTIVE_STORAGE_SERVICE=local zapisuje przesłane pliki na dysku, przechowując w Postgres jedynie odniesienia do nich.
  • Plik .env, ponieważ zawiera on SECRET_KEY_BASE oraz klucze ACTIVE_RECORD_ENCRYPTION_*.
  • Pliki Compose, ponieważ rejestrują one dokładną wersję (tag) obrazu, z którą zgodny jest schemat bazy danych.

Przywrócenie samej bazy danych spowoduje, że wszystkie konwersacje będą miały uszkodzone załączniki, ponieważ rekordy wskazują na pliki, których nie ma już na dysku.

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

-T ma kluczowe znaczenie. Bez tego parametru Compose przydziela pseudo-terminal, który nadpisuje bajty nowej linii w strumieniu, co prowadzi do powstania pliku zrzutu odrzucanego przez pg_restore. -Fc to format niestandardowy, który zapewnia kompresję i pozwala pg_restore na selektywne działanie.

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

Nazwa wolumenu składa się z nazwy katalogu projektu oraz _storage_data. Potwierdź ją za pomocą docker volume ls | grep storage_data, zanim zaufasz temu poleceniu, ponieważ Docker tworzy pusty wolumen zamiast zgłosić błąd, gdy podana nazwa nie istnieje. W rezultacie otrzymasz poprawne, ale puste archiwum bez żadnego komunikatu o błędzie. Po zakończeniu sprawdź rozmiar pliku za pomocą ls -lh storage-*.tgz.

Oba pliki znajdują się teraz na tym samym dysku, co chronione dane, co nie zapewnia żadnej ochrony. Prześlij je poza serwer i zaszyfruj, ponieważ zrzut bazy danych zawiera wszystkie wiadomości klientów w postaci jawnej. Szyfrowane kopie zapasowe poza serwerem z użyciem restic opisuje kwestie harmonogramowania i retencji danych.

Ćwiczenie przywracania danych – wykonaj je, zanim będzie potrzebne

Przywracaj dane na drugim serwerze VPS, a nie na działającej instancji produkcyjnej. Skopiuj .env, pliki Compose oraz oba archiwa, a następnie wykonaj:

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 usuwa istniejące obiekty przed załadowaniem danych, dlatego używaj tego polecenia tylko w odniesieniu do bazy danych, której utrata jest akceptowalna. Następnie zaloguj się i otwórz konwersację zawierającą załącznik. Jeśli lista wiadomości się wczyta, a plik pobierze, kopia zapasowa jest poprawna.

Przywrócenie danych z innym SECRET_KEY_BASE unieważnia wszystkie ciasteczka sesji, co powoduje wylogowanie wszystkich użytkowników. Przywrócenie danych z innymi kluczami ACTIVE_RECORD_ENCRYPTION_* jest bardziej problematyczne: Chatwoot nie może odszyfrować kolumn zawierających dane uwierzytelniające kanałów i zgłasza ActiveRecord::Encryption::Errors::Decryption. Dlatego .env znajduje się na liście elementów do archiwizacji.

Jak zaktualizować Chatwoot do nowej wersji (tagu)

Kolejność działań jest ważniejsza niż same polecenia.

  1. Zapoznaj się z informacjami o wydaniu (release notes) dla wersji pomiędzy aktualnie używaną a docelową, zwracając uwagę na wymagane kroki ręczne.
  2. Wykonaj kopię zapasową bazy danych oraz archiwum plików i sprawdź, czy rozmiary plików są poprawne.
  3. Zmień tag obrazu dla usługi base w pliku docker-compose.yaml.
  4. Pobierz nowy obraz, zatrzymaj stos, uruchom migracje, a następnie ponownie uruchom usługę.
docker compose pull
docker compose down
docker compose run --rm rails bundle exec rails db:chatwoot_prepare
docker compose up -d
docker compose images

Pobierz obraz przed uruchomieniem migracji, ponieważ migracja musi zostać wykonana z poziomu nowego obrazu: stary obraz nie zawiera nowych plików migracji. Zatrzymaj stos przed migracją, ponieważ stary kod i nowy schemat bazy danych są ze sobą niezgodne; działający proces Rails może generować błędy lub zapisywać wiersze, których nowy schemat nie zaakceptuje. Zatrzymanie usług zwalnia również pamięć niezbędną do przeprowadzenia migracji, co jest głównym powodem, dla którego twórcy oprogramowania zalecają posiadanie swap.

docker compose images wyświetla tag, na którym aktualnie działa każdy kontener, co pozwala wykryć sytuację, w której zmieniono tag w konfiguracji, ale zapomniano pobrać nowy obraz.

Zakres aktualizacji zależy od wieku instalacji. W przypadku instalacji opóźnionej o jedną lub dwie wersje, należy przejrzeć informacje o wydaniu pomiędzy posiadaną a docelową wersją, ustawić docelowy tag i wykonać powyższe kroki jednorazowo. Tylko w przypadku bardzo starych instalacji dokumentacja Docker zaleca aktualizację iteracyjną przez pośrednie tagi obrazów zamiast bezpośredniego przejścia do najnowszej wersji. W takim przypadku należy powtarzać kroki zmiany tagu, pobierania i przygotowania dla każdego pośredniego tagu, ponieważ twórcy wymagają wykonania db:chatwoot_prepare po każdej aktualizacji.

Jeśli Rails uruchomi się przed wykonaniem migracji, odmówi obsługi żądań i zapisze w dzienniku ActiveRecord::PendingMigrationError: Migrations are pending. Przy ustawionej opcji restart: always kontener będzie się restartował, przez co docker compose ps pokaże czas pracy (uptime), który resetuje się co kilka sekund. Uruchomienie kroku przygotowawczego rozwiązuje ten problem.

Wycofanie zmian (rollback) polega na przywróceniu starego tagu i odtworzeniu kopii zapasowej bazy danych. Nie istnieje niezawodna ścieżka odwrotnej migracji, dlatego krok 2 jest kluczowy.

Tryby awarii i komunikaty, które zobaczysz

502 Bad Gateway z Traefik. Router dopasował żądanie, ale backend nie odpowiedział. Sprawdź, czy docker compose ps wskazuje na rails jako Up, a następnie uruchom docker network inspect proxy i potwierdź, że kontener rails znajduje się na liście kontenerów. Kontener, który nie jest podłączony, jest niewidoczny dla Traefik, więc żądanie trafia do routera, a następnie donikąd.

Panel sterowania ładuje się, ale nowe wiadomości wymagają odświeżenia. Połączenie websocket do /cable nie przechodzi lub FRONTEND_URL nie pasuje do adresu w pasku przeglądarki. Niedopasowanie oznacza, że strona próbuje otworzyć websocket do innego źródła, co przeglądarka blokuje.

FATAL: password authentication failed for user "postgres". Hasło w .env różni się od tego zapisanego w wolumenie danych Postgres. Napraw to za pomocą ALTER USER wewnątrz uruchomionego kontenera, ponieważ ponowna edycja .env nie zmieni już zainicjowanej bazy danych.

NOAUTH Authentication required. Redis działa z --requirepass, ale aplikacja połączyła się bez hasła, więc REDIS_PASSWORD brakuje w .env lub nie zostało wczytane. Przetestuj hasło, którego oczekuje Redis, bezpośrednio za pomocą docker compose exec redis sh -c 'redis-cli -a "$REDIS_PASSWORD" ping', co powinno zwrócić PONG. Pojedyncze cudzysłowy mają znaczenie: powodują one rozwinięcie zmiennej wewnątrz kontenera, który odczytuje .env, zamiast w Twojej powłoce, gdzie jest ona zazwyczaj pusta.

Kontenery kończące pracę z kodem 137. Jest to sygnał SIGKILL. Na małym serwerze zazwyczaj wysyła go mechanizm out of memory killer jądra systemu, ale docker kill wysyła ten sam sygnał, więc sprawdź sudo dmesg -T | grep -i "killed process", zanim obwinisz brak pamięci. Jeśli przyczyną jest pamięć, dodaj swap, ustaw limity pamięci dla poszczególnych usług lub przejdź na większy plan.

FAQ

Ile pamięci RAM potrzebuje VPS z samodzielnie hostowanym Chatwoot?

Według stanu na październik 2026, wymagania minimalne określone przez twórców to 4 GB pamięci RAM i 4 rdzenie procesora, co pozwala na obsługę do 10 000 konwersacji dziennie. Dla 20 000 konwersacji zaleca się 8 GB RAM i 8 rdzeni. Należy dodać co najmniej 1 GB partycji swap, ponieważ proces aktualizacji uruchamia drugą instancję Rails w celu wykonania migracji, co w przypadku małych maszyn prowadzi do wyczerpania pamięci. VPS z 2 GB RAM uruchomi się i obsłuży kilku agentów, jednak sam Sidekiq pod obciążeniem może przekroczyć 1 GB zużycia pamięci. Należy spodziewać się, że kontenery będą kończone z kodem wyjścia 137 w okresach wzmożonego ruchu oraz podczas aktualizacji.

Dlaczego e-maile z resetem hasła do Chatwoot nie docierają?

Przyczyną jest brak ustawienia SMTP_ADDRESS, przez co Chatwoot korzysta z domyślnego mechanizmu sendmail. Jest on przeznaczony dla serwera Postfix zainstalowanego na hoście, którego w tej konfiguracji Docker nie ma. Zadanie jest wykonywane w Sidekiq, więc wszelkie błędy dostarczania trafiają do logów Sidekiq, podczas gdy przeglądarka wyświetla komunikat o sukcesie. Należy ustawić SMTP_ADDRESS, SMTP_PORT, SMTP_USERNAME, SMTP_PASSWORD oraz MAILER_SENDER_EMAIL w pliku .env, zrestartować usługi rails i sidekiq, a następnie monitorować docker compose logs -f sidekiq podczas wyzwalania procedury resetu.

Co należy zabezpieczyć, aby przywrócić Chatwoot?

Bazę danych Postgres, wolumen Docker storage_data, plik .env oraz pliki compose. Sama baza danych nie wystarczy, ponieważ przesłane pliki znajdują się w wolumenie, a Postgres przechowuje jedynie odniesienia do nich. Przywrócenie samej bazy spowoduje, że konwersacje będą zawierać niedziałające załączniki. Plik .env jest istotny, ponieważ zmiana SECRET_KEY_BASE spowoduje wylogowanie wszystkich użytkowników, a inne klucze ACTIVE_RECORD_ENCRYPTION_* uniemożliwią odczyt zaszyfrowanych kolumn.

Jak zaktualizować Chatwoot bez uszkodzenia bazy danych?

Wykonaj kopię zapasową, zapoznaj się z informacjami o wydaniu (release notes) dla wersji pomiędzy obecną a docelową, zmień tag obrazu w pliku compose, a następnie wykonaj docker compose pull, docker compose down, docker compose run --rm rails bundle exec rails db:chatwoot_prepare oraz docker compose up -d. Najpierw pobierz obrazy, ponieważ migracje muszą być uruchamiane z nowego obrazu. Najpierw zatrzymaj stos, ponieważ uruchomienie starego kodu na nowym schemacie bazy danych wywoła błędy. Tylko w przypadku bardzo starych instalacji konieczne może być przechodzenie przez pośrednie wersje obrazów zamiast bezpośredniego skoku do najnowszej, wykonując krok przygotowawczy po każdej z nich.

Czy można użyć standardowego obrazu postgres zamiast pgvector?

Nie. Schemat Chatwoot wymaga rozszerzenia vector, więc standardowy obraz postgres spowoduje błąd podczas db:chatwoot_prepare o treści ERROR: extension "vector" is not available, ponieważ plik kontrolny rozszerzenia nie znajduje się w tym obrazie. Należy zachować pgvector/pgvector:pg16 z oryginalnego pliku compose lub użyć innego obrazu, który zawiera pgvector dla danej wersji głównej Postgres.

Czy ten artykuł był przydatny?