SSD Nodes Learn Hosting plans →
Mwongozo Matt ConnorNa Matt Connor

Jinsi ya kuweka Chatwoot kwenye VPS kwa Docker

Jifunze kusakinisha Chatwoot kwa Docker Compose na Traefik. Mwongozo huu unashughulikia usanidi sahihi wa SMTP, nakala za akiba za Postgres, na mbinu salama za kuboresha mfumo.

Unachojenga

Ili kujiendeshea Chatwoot kwenye VPS, utaendesha kontena nne: mchakato wa wavuti wa Rails, mfanyakazi wa usuli wa Sidekiq, PostgreSQL yenye kiendelezi cha pgvector, na Redis. Chatwoot ni mfumo huria wa huduma kwa wateja, hivyo unapata kikasha cha timu kilichoshirikiwa na wijeti ya gumzo ya tovuti kwenye seva unayoimiliki. Ufungaji huchukua takriban dakika ishirini. Kila kitu kinachofuata, kama vile utumaji barua pepe, nakala za akiba (backups), maboresho, na ukubwa wa mfumo, ndicho huamua kama mfumo utaendelea kufanya kazi baada ya mwaka mmoja.

Kila kontena lina kazi moja. Rails huhudumia dashibodi ya wakala na API (application programming interface) ya wijeti. Sidekiq hufanya kazi nzito: kutuma barua pepe, kufuatilia chaneli zilizounganishwa, kuendesha sheria za otomatiki, na kuandaa ripoti. Postgres huhifadhi mazungumzo, anwani, akaunti za mawakala, na kila mpangilio unaobadilisha kwenye dashibodi. Redis huhifadhi foleni za Sidekiq na chaneli ya ActionCable ya pub/sub inayotuma ujumbe mpya kwenye dashibodi iliyo wazi bila kuhitaji kurudisha ukurasa (page reload). Redis hapa si akiba ya muda mfupi (cache), kwa sababu kuipoteza kunamaanisha kupoteza kazi zilizopo kwenye foleni.

Picha (image) ya Postgres katika faili ya compose ya upstream ni pgvector/pgvector:pg16 badala ya picha ya kawaida ya postgres, kwa sababu schema ya Chatwoot huwezesha kiendelezi cha vector kwa ajili ya vipengele vyake vya AI. Ukibadilisha na Postgres ya kawaida, hifadhidata itashindwa kufanya kazi mara ya kwanza kwa sababu ya ERROR: extension "vector" is not available, kwani faili ya udhibiti wa kiendelezi hicho haipo kwenye picha hiyo. Tumia picha inayotolewa na upstream.

Mwongozo huu unachukulia kuwa Docker na reverse proxy tayari vinafanya kazi kwenye seva yako. Ikiwa sivyo, anza na Docker Compose kwenye VPS kisha urudi hapa.

Chatwoot inayojiendesha yenyewe inahitaji VPS ya ukubwa gani?

Kufikia Oktoba 2026, ukurasa wa mahitaji ya msingi unapendekeza angalau 4 GB ya RAM na 4 CPU cores, na inakadiriwa kuhimili hadi mazungumzo 10,000 kwa siku. Inapendekeza 8 GB na 8 cores kwa hadi mazungumzo 20,000 kwa siku. Pia inahitaji angalau 1 GB ya swap, na inatoa sababu ya moja kwa moja: ili mashine isikose kumbukumbu wakati wa upgrade. Panga nafasi ya 5 GB hadi 10 GB ya diski kwa ajili ya Postgres kabla ya kuhesabu faili zilizopakiwa.

Sasa ukweli mchungu. VPS ya 2 GB itawasha Chatwoot, na inaonekana kufanya kazi vizuri ikiwa na mawakala wawili na inbox tulivu. Inafeli katika maeneo mawili. Eneo la kwanza ni Sidekiq, ambayo kulingana na vipimo vya msanidi inatumia zaidi ya 1 GB kwenye seva yenye shughuli nyingi, kwa hivyo mlipuko wa barua pepe au kazi ya ripoti husukuma mashine kupita uwezo wake wa kumbukumbu kabla ya Rails, Postgres na Redis kuchukua sehemu yao. Eneo la pili ni wakati wa upgrade, kwa sababu db:chatwoot_prepare huwasha mchakato mpya wa Rails ili kutekeleza migrations, na kuwasha Rails kwenye image hii hutumia mamia ya megabytes kabla ya kufanya kazi yoyote ya maana.

Hupati onyo la upole kwanza. Mfumo wa kernel wa out of memory killer hutuma SIGKILL kwa mchakato unaouchagua, kwa kawaida ule mkubwa zaidi, Docker huona container ikifa, na restart: always huianzisha tena. docker compose ps --all kisha huonyesha container inayoendelea kuanza upya au kukwama kwenye Exited (137), ambapo 137 inamaanisha iliuawa na signal 9. Usipotumia --all, container iliyosimamishwa haitaonekana kabisa. Exit code 137 pekee haithibitishi kuwa kumbukumbu ndiyo iliyosababisha tatizo, kwa sababu docker kill hutuma signal hiyo hiyo, kwa hivyo ithibitishe kwa sudo dmesg -T | grep -i "killed process", ambayo hutaja mchakato uliochaguliwa na kernel.

Ikiwa 4 GB iko nje ya bajeti yako, tumia mashine ya 2 GB yenye 2 GB ya swap na ukubali kuwa muda wa majibu utapungua wakati wa mzigo mkubwa. Swap ni hifadhi dhidi ya kuishiwa na kumbukumbu, si dhamana, kwa hivyo mlipuko mkubwa wa shughuli bado unaweza kusababisha container kuuawa. Kuweka kikomo cha kumbukumbu kwa kila huduma ni jambo la busara kufanya, ili worker asishushe database pamoja naye. Tazama memory limits in Docker Compose.

Upakiaji wa faili ni sehemu inayokua bila kikomo unachoweka. Kila screenshot inayotumwa na mteja hutua kwenye storage volume na kubaki hapo, kwa hivyo fuatilia docker system df -v badala ya kudhani kuwa database ndiyo iliyojaza diski.

Pakua faili ya compose na uweke tag ya toleo

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

Faili uliyopakua hivi punde ina image: chatwoot/chatwoot:latest. Badilisha hiyo kabla ya kufanya jambo lingine lolote.

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

latest inamaanisha kuwa docker compose pull inayofuata itakupa chochote kilichochapishwa asubuhi hiyo, ambacho kinaweza kuwa toleo kuu lenye mabadiliko ya database (migrations) ambayo hukuyasoma. Mabadiliko ya database ya Chatwoot hayawezi kutenduliwa kwa vitendo, kwa hivyo kuruka toleo kwa bahati mbaya kunamaanisha kurejesha data kutoka kwenye backup, siyo kutendua. Weka tag maalum na uibadilishe kwa makusudi. v4.19.1 ndilo lilikuwa toleo la sasa kufikia 25 October 2026, na maelezo yake ya toleo yanapendekeza toleo hilo kwa ajili ya marekebisho ya usalama na uimarishaji wa mfumo; angalia ukurasa wa releases kwa ajili ya tag unayopaswa kuweka leo. Ikiwa unatoka v4.18.0 au toleo la awali, soma maelezo ya v4.19.0 kwanza: Captain V1 imestaafishwa, na usakinishaji wa self-hosted unaotumia maelekezo ya V1 lazima uyahamishie kwenye V2 kabla ya kufanya upgrade. Kila kitu kinachomiliki database kinahitaji tahadhari hiyo hiyo, ndiyo maana self-hosting ya openGym workout tracker huanza kwa kuweka git tag ingawa ni programu ndogo zaidi kuliko hii.

Huduma ya base ni YAML anchor ambayo rails na sidekiq zote zinaiunganisha, kwa hivyo kubadilisha tag katika sehemu moja kunabadilisha kwa zote mbili. Ukiwa ndani ya faili hiyo, futa mstari wa version: '3' uliopo juu. Compose ya kisasa hupuuza mstari huo na kuchapisha the attribute 'version' is obsolete, it will be ignored kwenye kila amri.

Jaza faili la .env

Tengeneza siri (secret) kwanza. Upstream inahitaji thamani ya alphanumeric, kwa sababu herufi maalum huharibika thamani hiyo inapopita kwenye shell au YAML parser.

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

Kisha weka funguo hizi katika .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 na redis://redis:6379 ni majina ya huduma za Compose, ambayo hutatuliwa kwenye mtandao chaguo-msingi wa mradi. FRONTEND_URL si mapambo. Chatwoot hujenga URL ya script ya widget na kila kiungo ndani ya barua pepe inayotoka humo, kwa hivyo thamani isiyo sahihi itakupa viungo vya kubadilisha nenosiri vinavyoelekeza kwenye host isiyojibu.

Sasa kuna mtego katika faili la upstream. Huduma ya postgres haisomi .env. Inabeba block yake ya environment ikiwa na POSTGRES_PASSWORD= tupu, kwa hivyo kuweka nenosiri katika .env pekee kutaiacha database bila nenosiri na programu ikiwa nalo. Elekeza huduma hiyo kwenye variable ileile:

  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 inasoma .env kutoka kwenye saraka ya mradi kwa ajili ya uingizwaji wa ${...}, kwa hivyo pande zote mbili sasa zinapata string ileile. Ukikosea hapa, Rails itasimama na PG::ConnectionBad: FATAL: password authentication failed for user "postgres".

Tabia moja huwashangaza karibu kila mtu: image ya Postgres hutumia POSTGRES_PASSWORD tu wakati inapoanzisha saraka tupu ya data. Kubadilisha thamani hiyo baadaye hakuna athari, kwa sababu initdb haiwahi kuendeshwa mara ya pili. Ikiwa tayari umeanza stack mara moja, ibadilishe ndani ya database yenyewe.

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

ENABLE_ACCOUNT_SIGNUP=true ni ya muda. Inafungua fomu ya usajili wa umma ili uweze kuunda akaunti ya kwanza. Iweke kuwa false na uendeshe docker compose up -d tena mara tu akaunti yako itakapokuwepo, au mtu yeyote anayepata URL hiyo anaweza kujiandikisha kwenye dawati lako la usaidizi. Kuanzia hapo, mawakala hufika kwa mwaliko na nywila zao hukaa katika programu hii moja tu, jambo ambalo ni sawa hadi utakapokuwa unaendesha huduma nusu dazeni na kuchoka na orodha tofauti ya akaunti katika kila moja, ambapo identity provider inayojiendesha kama Authentik ndiyo sehemu inayozichukua nafasi hizo.

.env sasa inashikilia kila siri ambayo stack hii inayo, katika maandishi wazi (plain text), kwa hivyo iweke katika mode 600 na uizuie isingie kwenye git. Jinsi Compose inavyosoma faili za env, na mahali ambapo siri huvuja inashughulikia hatari hizi, ikiwa ni pamoja na tofauti kati ya env_file na environment.

Weka Chatwoot nyuma ya Traefik yako iliyopo

Usijenge reverse proxy ya pili kwa ajili ya programu moja. Ikiwa Traefik tayari inashughulikia TLS (transport layer security) kwa container nyingine kwenye seva hii, Chatwoot inaunganishwa kwa kutumia block ya labels. Ikiwa huna usanidi huo bado, uweke mara moja kwa kufuata Traefik mbele ya programu kadhaa za Docker Compose, kisha rudi hapa.

Weka docker-compose.yaml ya upstream ikiwa karibu na hali yake ya asili ili uweze kuilinganisha na nakala mpya baadaye, na uweke mabadiliko yako kwenye faili ya override. Compose huunganisha docker-compose.override.yaml kiotomatiki, na kugawanya Compose katika faili nyingi kunaelezea kanuni za uunganishaji huo.

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

Tumia majina yako ya entrypoint na certresolver. Container lazima iwe kwenye Docker network sawa na Traefik, jambo ambalo hufanywa na ingizo la proxy, na lazima ibaki kwenye default pia vinginevyo itapoteza muunganisho na Postgres na Redis. Hiyo ni mstari wa pili ambao watu husahau.

Acha block ya ports: kama ilivyo. Upstream huifunga kwenye 127.0.0.1:3000, ambayo ni loopback pekee, kwa hivyo haiwezi kufikiwa kutoka kwenye Internet na inabaki kuwa muhimu kwa majaribio kutoka ndani ya seva kwa kutumia curl -I http://127.0.0.1:3000.

Dashboard ya wakala huweka websocket wazi kwenye /cable kwa ajili ya utoaji wa ujumbe wa moja kwa moja. Traefik husambaza HTTP upgrade bila usanidi wa ziada, kwa hivyo hakuna cha kuongeza. Ikiwa baadaye utaweka CDN au proxy nyingine mbele ya Traefik, ruhusu websockets huko, kwa sababu dalili yake ni dashboard inayopakia kawaida wakati ujumbe mpya huonekana tu baada ya kuburudisha ukurasa (manual refresh).

Anzisha database na uwashe stack

Anza kwa kuwasha huduma za data na uiruhusu Postgres imalize mchakato wake wa kwanza.

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

Subiri database system is ready to accept connections. Kisha tengeneza schema.

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

Hii hutengeneza database ikiwa haipo, kisha hupakia schema na data za awali (seed data). Inachapisha mistari ya migration na kutoka kwa usalama. Ikiwa inakaa ikichapisha postgres:5432 - no response, entrypoint inasubiri database ambayo bado haikubali miunganisho, jambo ambalo kwenye mwanzo wa kwanza kwa kawaida humaanisha initdb bado inafanya kazi. Subiri, soma logi za Postgres, kisha iendeshe tena. Ikiwa inasimama kwenye extension ya vector, umeweka image ya kawaida ya Postgres badala ya pgvector.

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

Containers zote nne zinapaswa kusoma Up, na logi ya rails inapaswa kuishia na mstari wa Puma unaosikiliza kwenye http://0.0.0.0:3000. Kisha kagua njia ya umma (public path):

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

HTTP/2 200 inamaanisha mnyororo mzima unafanya kazi. 404 kutoka kwa Traefik inamaanisha kuwa sheria ya router haikulingana, kwa kawaida ni kosa la kuandika hostname. 502 inamaanisha Traefik ililinganisha router lakini haikuweza kufikia container, jambo ambalo karibu kila mara ni kukosekana kwa mtandao wa proxy au loadbalancer.server.port ambayo si 3000.

Fungua URL, tengeneza akaunti yako kwenye /app/auth/signup, kisha weka ENABLE_ACCOUNT_SIGNUP=false na uendeshe docker compose up -d ili kufunga fomu hiyo.

Kwa nini uwekaji upya wa nenosiri na mazungumzo ya barua pepe hushindwa bila SMTP

Chatwoot bila mipangilio ya SMTP (simple mail transfer protocol) ni dawati la usaidizi lisiloweza kutuma barua pepe, na hilo huvuruga mambo mengi zaidi ya arifa tu. Uwekaji upya wa nenosiri huacha kufanya kazi, hivyo msimamizi anayefungiwa nje hubaki akiwa amefungiwa. Mialiko ya mawakala huacha kufanya kazi, kwa sababu mwaliko ni barua pepe. Kujibu mteja katika mazungumzo ya barua pepe huacha kufanya kazi, hivyo mazungumzo huendelea upande mmoja tu. Hii ndiyo hatua ambayo watu huruka na kuigundua wakati wa wiki yao mbaya zaidi.

Utaratibu huu ni rahisi. Bila SMTP_ADDRESS kuwekwa, Chatwoot hubadilisha ActionMailer kutumia usafirishaji wa sendmail. Nyaraka za upstream zinaelezea hili kama usanidi wake wa Postfix, ambao ni chaguo-msingi tangu v2.12.0, na maelekezo yake huweka Postfix kwenye seva kwa kutumia sudo apt install -y postfix. Usanidi huu wa Docker haufanyi hivyo kamwe, kwa hivyo hakuna seva ya barua pepe iliyosanidiwa kwa ajili ya usafirishaji huo kupokea barua zako. Barua hutumwa kutoka kwa kazi ya usuli (background job), kwa hivyo hitilafu yoyote inayotokea wakati wa usafirishaji huishia kwenye logi ya Sidekiq na si kwenye logi ya Rails. Wakati huo huo, mtu anayebofya "umesahau nenosiri" huona uthibitisho wa furaha na hapokei chochote.

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

Tumia port 587 pamoja na STARTTLS, ambayo hufungua muunganisho kwa maandishi ya kawaida na kuupandisha hadhi kuwa fiche kabla ya uthibitishaji. Watoa huduma wengi wa VPS huzuia port 25 ya kutoka kwa chaguo-msingi ili kupunguza barua taka (spam). Kufikia 8 Novemba 2026, Hetzner huzuia port 25 na 465 kwa chaguo-msingi kwenye seva za cloud, huku uzuiaji ukitekelezwa kwa kila akaunti, na Vultr huzuia port 25 kwenye Compute Instances zote mpya. Wote hupitia maombi ya kuondoa uzuiaji kwa kila kisa; Hetzner inahitaji uwe mteja kwa mwezi mmoja na uwe umelipa ankara ya kwanza kabla ya kuwasilisha ombi la kuondoa kizuizi. Hakuna anayezuia 587, kwa hivyo relay kwenye 587 hufanya kazi tangu boot ya kwanza bila tiketi na bila kusubiri. SMTP_DOMAIN ni domain ambayo seva yako hutangaza wakati wa mazungumzo ya SMTP, na baadhi ya relay hukataa kutokana na kutolingana.

Tekeleza mipangilio na ufuatilie mfanyakazi (worker):

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

Anzisha uwekaji upya wa nenosiri kutoka ukurasa wa kuingia. Usafirishaji unaofanya kazi utaonyesha kazi ya mailer ikikamilika kawaida kwenye logi ya Sidekiq. Hitilafu itaonyesha darasa la ubaguzi (exception class), kisha Sidekiq ikijaribu tena na backoff inayoongezeka, ndiyo maana relay iliyoharibika hutoa hitilafu ileile kila baada ya dakika chache kwa saa nyingi.

Kukataa mara mbili ni kawaida, na hakuna hata moja kati ya hizo ni hitilafu ya Chatwoot. 535 Authentication failed inamaanisha uthibitishaji umeshindwa, kwa hivyo angalia vitambulisho, kama uthibitishaji wa SMTP umewezeshwa na kama sera ya ufikiaji inazuia. Vitambulisho sahihi pekee haviondoi uwezekano wa hitilafu hii. Baadhi ya watoa huduma wanahitaji nenosiri la programu (application password) badala ya nenosiri la akaunti. 550 Sender address rejected inamaanisha seva ilikataa anwani ya mtumaji; soma jibu kamili kabla ya kubadilisha MAILER_SENDER_EMAIL. Ruhusa za mtumaji au uthibitishaji ni sababu moja, lakini 550 5.7.27 Sender address rejected: Domain does not accept mail inaashiria domain ya mtumaji yenye rekodi ya MX tupu (null MX record).

Kupokea barua pepe kwenye mazungumzo ni kazi tofauti. Kwa ajili ya kusambaza kupitia ingress ya Chatwoot, inahitaji MAILER_INBOUND_EMAIL_DOMAIN na RAILS_INBOUND_EMAIL_SERVICE, pamoja na seva ya barua pepe inayokabidhi ujumbe unaoingia kwa Chatwoot. Unaweza pia kuunganisha kisanduku cha barua kupitia IMAP, ikijumuisha Google au Microsoft OAuth, bila kusanidi njia hiyo ya usambazaji. Kukodisha relay ndiyo njia ya haraka. Ikiwa ungependa kumiliki njia nzima ya barua pepe, kuendesha seva yako mwenyewe ya barua pepe na Mailcow inashughulikia kile ambacho ahadi hiyo inahusisha kihalisi.

Nini cha kuhifadhi (backup), na jinsi ya kuthibitisha kuwa urejeshaji (restore) unafanya kazi

Backup ya Chatwoot ina sehemu nne, na kuruka sehemu yoyote kati ya hizo kunafanya urejeshaji kuwa ujenzi upya.

  • Database ya Postgres, ambayo huhifadhi mazungumzo, anwani, akaunti za mawakala na kila mpangilio.
  • Volume ya storage_data, kwa sababu ACTIVE_STORAGE_SERVICE=local huandika faili zilizopakiwa kwenye diski na kuhifadhi tu kumbukumbu ya marejeleo (reference row) ndani ya Postgres.
  • Faili ya .env, kwa sababu inashikilia SECRET_KEY_BASE na funguo za ACTIVE_RECORD_ENCRYPTION_*.
  • Faili za compose, kwa sababu zinarekodi tag kamili ya image inayolingana na schema ya database yako.

Ukirejesha database pekee, kila mazungumzo yatarejea yakiwa na viambatisho vilivyoharibika, kwa sababu safu (rows) hizo huelekeza kwenye faili ambazo hazipo tena kwenye diski.

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

-T ni muhimu. Bila hiyo, Compose hutenga pseudo terminal, ambayo hubadilisha byte za mstari mpya (newline) kwenye mtiririko huo, hivyo unapata faili ya dump ambayo pg_restore huikataa. -Fc ni umbizo maalum, ambalo hubana data na kuruhusu pg_restore kufanya kazi kwa kuchagua.

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

Jina la volume ni jina la saraka ya mradi wako pamoja na _storage_data. Lithibitishe kwa docker volume ls | grep storage_data kabla ya kuamini amri hiyo, kwa sababu Docker hutengeneza volume tupu badala ya kutoa hitilafu unapotoa jina la volume isiyokuwepo. Utapata archive halali, tupu na bila hitilafu yoyote. Angalia ukubwa wake baadaye kwa ls -lh storage-*.tgz.

Faili zote mbili sasa ziko kwenye diski moja na kitu zinachokilinda, jambo ambalo halikupi ulinzi wowote. Zihamishe nje ya seva hiyo na uzifiche (encrypt), kwa sababu dump ya database ina kila ujumbe wa mteja katika maandishi ya kawaida (plain text). Backup zilizofichwa nje ya seva kwa kutumia restic inashughulikia upande wa upangaji ratiba na uhifadhi wa muda mrefu.

Zoezi la urejeshaji, lifanye kabla ya kulihitaji

Rejesha kwenye VPS ya pili, siyo ile inayotumika. Nakili .env, faili za compose na archives zote mbili, kisha endesha:

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 hufuta vitu vilivyopo kabla ya kupakia, kwa hivyo iweke tu kwenye database ambayo uko tayari kuipoteza. Kisha ingia na ufungue mazungumzo yenye kiambatisho. Ikiwa orodha ya ujumbe inapakia na faili inapakuliwa, basi backup hiyo ni halisi.

Urejeshaji wenye SECRET_KEY_BASE tofauti hubatilisha kila session cookie, kwa hivyo kila mtu atatolewa nje ya mfumo. Urejeshaji wenye funguo tofauti za ACTIVE_RECORD_ENCRYPTION_* ni mbaya zaidi: Chatwoot haiwezi kufungua (decrypt) safu zinazoshikilia vitambulisho vya channel na huibua ActiveRecord::Encryption::Errors::Decryption. Hiyo ndiyo sababu .env iko kwenye orodha ya backup.

Jinsi ya kupandisha toleo la Chatwoot kwenda tag mpya

Mpangilio wa hatua ni muhimu zaidi kuliko amri zenyewe.

  1. Soma maelezo ya toleo (release notes) kati ya tag yako ya sasa na ile unayolenga, ukitafuta hatua za mikono zinazohitajika.
  2. Chukua dump mpya ya database na archive ya hifadhi, kisha hakikisha ukubwa wa faili zote mbili unaonekana kuwa sahihi.
  3. Hariri tag ya image kwenye huduma ya base ndani ya docker-compose.yaml.
  4. Vuta (pull) image mpya, simamisha stack, endesha migrations, kisha uanzishe tena.
docker compose pull
docker compose down
docker compose run --rm rails bundle exec rails db:chatwoot_prepare
docker compose up -d
docker compose images

Vuta image kabla ya kufanya migration, kwa sababu migration lazima iendeshwe kutoka kwenye image mpya: image ya zamani haina faili mpya za migration. Simamisha stack kabla ya kufanya migration, kwa sababu code ya zamani na schema mpya haziendani, hivyo mchakato wa zamani wa Rails unaoendelea unaweza kutoa makosa au kuandika safu ambazo schema mpya haitakubali. Kusimamisha huduma pia kunafungua kumbukumbu (memory) inayohitajika na migration, ambayo ndiyo sababu kuu inayofanya watengenezaji wa programu hii waombe swap.

docker compose images huonyesha tag ambayo kila container inaitumia kwa sasa, jambo ambalo husaidia kubaini kama ulihariri tag lakini ukasahau kufanya pull.

Umbali unaoweza kuruka unategemea umri wa usakinishaji wako. Kwa usakinishaji ambao umechelewa kwa toleo moja au mbili, kagua maelezo ya toleo kati ya tag yako na ile unayolenga, weka tag unayolenga, na ufuate hatua zilizo hapo juu mara moja. Ni pale tu usakinishaji wako unapokuwa wa zamani sana ndipo mwongozo wa Docker wa watengenezaji unakuambia upandishe toleo hatua kwa hatua kupitia tag za kati badala ya kuruka moja kwa moja hadi kwenye image ya hivi karibuni. Katika hali hiyo, rudia hatua ya kubadilisha tag, kuvuta image, na kuandaa (prepare) kwa kila tag ya kati, kwa sababu watengenezaji huomba db:chatwoot_prepare baada ya kila upandishaji.

Ikiwa Rails itaanza kabla ya migration kuendeshwa, itakataa kuhudumia maombi na kuandika ActiveRecord::PendingMigrationError: Migrations are pending kwenye logi. Ikiwa restart: always imewekwa, container itajianzisha upya mara kwa mara, hivyo docker compose ps itaonyesha uptime inayojirekebisha kila baada ya sekunde chache. Endesha hatua ya kuandaa (prepare) na hali hiyo itatoweka.

Kurudisha toleo la zamani (rollback) kunamaanisha kurudisha tag ya zamani na kurejesha dump uliyohifadhi. Hakuna njia ya kurudisha nyuma migration (reverse migration) unayoweza kuitegemea, ndiyo maana hatua ya 2 ni muhimu.

Njia za kufeli na ujumbe utakaouona

502 Bad Gateway kutoka kwa Traefik. Router imepata njia sahihi lakini backend haikujibu. Hakikisha docker compose ps inaonyesha rails kama Up, kisha endesha docker network inspect proxy na uthibitishe kuwa container ya rails inaonekana kwenye orodha ya containers. Container ambayo haijaunganishwa haionekani kwa Traefik, kwa hivyo ombi linafanana na router lakini halina mahali pa kwenda.

Dashboard inapakia lakini ujumbe mpya unahitaji refresh. Websocket ya /cable haipiti, au FRONTEND_URL hailingani na anwani iliyo kwenye upau wa anwani wa kivinjari. Kutolingana huku kunamaanisha ukurasa unajaribu kufungua websocket kwenye asili (origin) tofauti, jambo ambalo kivinjari huzuia.

FATAL: password authentication failed for user "postgres". Nenosiri lililo kwenye .env na lile lililowekwa ndani ya volume ya data ya Postgres ni tofauti. Rekebisha hili kwa ALTER USER ndani ya container inayofanya kazi, kwa sababu kuhariri .env tena hakutabadilisha database ambayo tayari imeshaanzishwa.

NOAUTH Authentication required. Redis inafanya kazi na --requirepass lakini programu imeunganishwa bila nenosiri, kwa hivyo REDIS_PASSWORD haipo kwenye .env au haikuchukuliwa. Jaribu nenosiri ambalo Redis inatarajia moja kwa moja kwa kutumia docker compose exec redis sh -c 'redis-cli -a "$REDIS_PASSWORD" ping', ambayo inapaswa kujibu PONG. Alama za kunukuu (single quotes) ni muhimu: zinafanya variable kupanuka ndani ya container, ambayo inasoma .env, badala ya kwenye shell yako, ambapo kwa kawaida huwa tupu.

Containers zinatoka na code 137. Hiyo ni SIGKILL. Kwenye seva ndogo, mtumaji wa kawaida ni "out of memory killer" ya kernel, lakini docker kill hutuma ishara hiyo hiyo, kwa hivyo angalia sudo dmesg -T | grep -i "killed process" kabla ya kulaumu kumbukumbu (memory). Ikiwa ni suala la kumbukumbu, ongeza swap, weka mipaka ya kumbukumbu kwa kila huduma, au hamia kwenye mpango mkubwa zaidi.

FAQ

VPS ya Chatwoot inayojiendesha inahitaji RAM kiasi gani?

Kufikia Oktoba 2026, wasanidi wanapendekeza angalau 4 GB ya RAM na 4 CPU cores kwa ajili ya mazungumzo 10,000 kwa siku, na 8 GB na 8 cores kwa ajili ya mazungumzo 20,000. Ongeza angalau 1 GB ya swap, kwa sababu mchakato wa upgrade huendesha Rails process ya pili ili kutekeleza migrations, na hapo ndipo seva ndogo hukosa kumbukumbu. VPS ya 2 GB inaweza kuwaka na kufanya kazi kwa mawakala wachache, lakini Sidekiq pekee inaweza kutumia zaidi ya 1 GB ikiwa na mzigo, hivyo tarajia containers kusitishwa na exit code 137 wakati wa shughuli nyingi au wakati wa upgrades.

Kwa nini barua pepe za kubadilisha nenosiri la Chatwoot hazifiki?

Kwa sababu hakuna SMTP_ADDRESS iliyowekwa, hivyo Chatwoot hutumia utaratibu wa sendmail, ambao wasanidi wameuandaa kwa ajili ya seva ya Postfix iliyopo kwenye host, na usanidi huu wa Docker hauna hiyo. Kazi hiyo huendeshwa ndani ya Sidekiq, hivyo hitilafu yoyote ya utumaji huonekana kwenye log ya Sidekiq wakati kivinjari kinaonyesha ujumbe wa mafanikio. Weka SMTP_ADDRESS, SMTP_PORT, SMTP_USERNAME, SMTP_PASSWORD na MAILER_SENDER_EMAIL ndani ya .env, anzisha upya huduma za rails na sidekiq, kisha fuatilia docker compose logs -f sidekiq wakati unapoanzisha ombi la kubadilisha nenosiri.

Ninahitaji kuhifadhi nini ili kurejesha Chatwoot?

Database ya Postgres, Docker volume ya storage_data, faili la .env, na faili za compose. Database pekee haitoshi, kwa sababu faili zilizopakiwa zipo kwenye volume wakati Postgres inashikilia marejeleo yake tu, hivyo kurejesha database pekee kutakupa mazungumzo yenye viambatisho vilivyoharibika. .env ni muhimu kwa sababu SECRET_KEY_BASE tofauti itawatoa watumiaji wote kwenye mfumo, na funguo tofauti za ACTIVE_RECORD_ENCRYPTION_* hufanya safu zilizosimbwa (encrypted columns) zisosomeke.

Ninawezaje kufanya upgrade ya Chatwoot bila kuharibu database?

Fanya backup, soma maelezo ya toleo (release notes) kati ya tag yako ya sasa na ile unayolenga, badilisha image tag kwenye faili lako la compose, kisha endesha docker compose pull, docker compose down, docker compose run --rm rails bundle exec rails db:chatwoot_prepare na docker compose up -d. Fanya pull kwanza kwa sababu migrations lazima ziendeshwe kutoka kwenye image mpya, na simamisha stack kwanza kwa sababu code ya zamani ikifanya kazi na schema mpya husababisha hitilafu. Ni usakinishaji wa zamani sana pekee unaohitaji kupitia image tags za kati badala ya kuruka moja kwa moja hadi toleo la hivi karibuni, huku ukitekeleza hatua ya prepare baada ya kila hatua.

Je, ninaweza kutumia image ya kawaida ya postgres badala ya pgvector?

Hapana. Schema ya Chatwoot huwezesha extension ya vector, hivyo image ya kawaida ya postgres itafeli wakati wa db:chatwoot_prepare na kuleta ERROR: extension "vector" is not available, kwa sababu faili la udhibiti wa extension hiyo halipo kwenye image hiyo. Tumia pgvector/pgvector:pg16 kutoka kwenye faili la compose la wasanidi, au tumia image nyingine inayokuja na pgvector kwa ajili ya toleo lako kuu la Postgres.

Je, makala hii ilikusaidia?

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