Jinsi ya kutumia Uptime Kuma kwenye Docker

Unachojenga

Konteiner moja ndogo inayokagua seva na tovuti zako kutoka nje. Inakujulisha mara moja seva inapochukua muda mrefu kujibu kupitia email, Telegram, Discord, au webhook. Uptime Kuma ni mchakato mmoja wa Node unaotumia faili ya SQLite. Inafanya kazi vizuri kwa kutumia RAM ya MB 256-512. Inakupa dashboard ya moja kwa moja, grafu za historia, na ukurasa wa hadhi wa hadhara. Usakinishaji ni faili ya Compose ya mistari kumi; sehemu muhimu ni mahali unapoiendesha na kama taarifa zako za onyo zimefanya kazi wakati wa majaribio. Kifaa cha ufuatiliaji ambacho hukukithibitisha kinaweza kukufikia ni kibaya zaidi kuliko kutokuwa nacho: kinakufanya uhisi umechomwa kinga wakati hufuatilii chochote.

Run the monitor somewhere the outage cannot reach it

Uamuzi huu ni muhimu kwa mafanikio ya mfumo mzima. Usisandike Uptime Kuma kwenye seva inayofuatiliwa. Ikiwa mfuatiliaji (monitor) upo kwenye seva inayofuatiliwa, tukio la seva hiyo kuzimika au kuishiwa memory litauua mfuatiliaji pia. Hii itasababisha usipate taarifa yoyote; ukimya kutoka kwa mfuatiliaji aliyekufa unafanana na hali ya "kila kitu kiko sawa." Kuna hatari nyingine wakati seva bado inaishi: mfuatiliaji anayoelekezwa kwenye localhost anashiriki CPU na kazi nyingine. Hali hii inaweza kusababisha ongezeko la mzigo (load spike) kuchelewesha ukaguzi na kuweka lengo katika hali ya down. Hii ni taarifa ya uongo wakati watumiaji wa kweli wanaendelea kutumika vizuri.

Hivyo, sandika Uptime Kuma kwenye VPS tofauti na ile inayofuatiliwa. Ni bora kutumia mtoa huduma au eneo (region) tofauti. Mfuatiliaji anapaswa kufikia huduma zako kama watumiaji wako: kupitia internet ya umma, kwa kutumia hostname. Instance ya bei rahisi inatosha, na VPS moja ndogo ya ufuatiliaji inaweza kufuatilia seva zako zote. Ili kugundua ikiwa Kuma imekufa, ongeza push heartbeat kutoka kwenye cron mahali pengine.

Mahitaji ya awali na ukubwa wa mfumo

• VPS mpya ya Ubuntu 24.04 yenye Docker Engine na plugin ya Compose v2. Sakinisha kutoka kwenye repository ya Docker, usitumie package ya distro ya docker.io kwa sababu ina toleo la zamani.
• RAM ya 256 MB inatosha kwa kutoa ufuatiliaji (monitors) wachache; RAM ya 512 MB hadi 1 GB ni nzuri kwa mamia ya ufuatiliaji pamoja na reverse proxy, wakati CPU inakuwa imetulia kati ya ukaguzi.
• Domain na rekodi ya DNS A (kwa mfano status.example.com inayoelekeza kwenye VPS), ikiwa tu unataka TLS na ukurasa wa hali ya juu (status page) unaofikika hadharani. Instance ya ndani inaweza kuruka DNS na kutumia VPN au SSH tunnel.
• Mtandao wa kutoa (outbound) kuelekea mahali ambapo taarifa za tahadhari (alerts) zinatumwa: SMTP kwenda kwa mtoa huduma wako wa barua pepe, au HTTPS kwenda Telegram na Discord.

Faili ya Compose

Weka hii kwenye /srv/uptime-kuma/compose.yaml.

services:
  uptime-kuma:
    image: louislam/uptime-kuma:2
    container_name: uptime-kuma
    restart: unless-stopped
    ports:
      - "127.0.0.1:3001:3001"
    volumes:
      - kuma-data:/app/data

volumes:
  kuma-data:

Iwashe na uangalie wakati wa kuanza mara ya kwanza:

sudo mkdir -p /srv/uptime-kuma
# save the file above as /srv/uptime-kuma/compose.yaml, then:
cd /srv/uptime-kuma && sudo docker compose up -d
sudo docker compose logs -f uptime-kuma

Kuanza kwa usahihi hutoa logi ya Listening on 3001 na kisha hutulia. Mambo matatu kwenye faili hiyo yamepangwa kwa makusudi.

127.0.0.1:3001:3001, si 3001:3001. Docker huchapisha port kwa kutumia sheria za DNAT ambazo hutevaliuatiwa kabla ya ufw kuona paketi, hivyo 3001:3001 pekee huweka dashboard yako kwenye mtandao wa umma bila kujali firewall yako. Kufunga (binding) kwenye loopback huifanya iwe ya siri, ambapo reverse proxy pekee ndiyo inayowaziwa; instance ya siri inaweza kuruka proxy na kufikia 3001 kupitia a self-hosted WireGuard VPN badala yake.

Volume yenye jina kwenye /app/data. Kila kitu ambacho Uptime Kuma kinakumbuka, ikiwemo SQLite database, monita yako, mipangilio ya arifa, na nembo za ukurasa wa hali, huishi hapo. Ukipoteza volume hiyo, utaanza na skrini ya admin ikiwa tupu; ndiyo kitu pekee unachopaswa kufanya backup.

Picha (image) imefungwa kwenye tag kuu, :2. Hiyo ndiyo mstari wa sasa wa utulivu; kagua Docker Hub kwa toleo jipya la tag kuu kabla ya kunakili, na usifuate tag inayobadilika kama latest, ambayo mradi unaitenga. Mabadiliko ya toleo kuu kwenye picha hii ni uhamishaji wa database (database migration) wa upande mmoja ambao unapaswa kuuanzisha kwa makusudi, si kukutana nao kwa bahati wakati wa pull ya kawaida.

Angalizo moja: /app/data lazima iwe kwenye filesystem yenye POSIX file locks. Docker volume ya ndani ni sawa; kwenye NFS, SQLite database huharibika na unapata SQLITE_BUSY na database disk image is malformed, hivyo usitumie kamwe network share.

Wakati wa kwanza: tengeneza akaunti ya admin

Fungua instance kupitia proxy yako kwenye https://status.example.com, au kupitia SSH tunnel: run ssh -L 3001:127.0.0.1:3001 user@your-vps na ufungue http://localhost:3001. Ukurasa wa kwanza ni fomu ya usanidi kwa ajili ya jina la mtumiaji na nywila ya msimamizi; hakuna login ya kiserikali. Chagua nywila halisi: dashboard hii inaona anwani za ndani na token za kila kitu unachofuatilia. Ukaisahau baadaye? Iweze upya (reset) kutoka kwenye host, siyo kwenye kivinjari:

sudo docker compose exec uptime-kuma npm run reset-password

Ongeza njia zako za arifa kwanza, kisha uzijaribu

Sanidi arifa kabla ya kuongeza ufuatiliaji (monitors), ili uweze kuunganisha njia wakati unatengeneza kila mmoja. Nenda kwenye Settings kisha Notifications kisha Setup Notification, na utumie kitufe cha Test cha kila njia ili kuthibitisha ujumbe unafikia, kwa sababu arifa ambayo haijajaribiwa ndiyo njia ya pili inayofanya mfumo kushindwa bila kuonyesha kosa.

Email (SMTP). Jaza host, port, encryption, username, password, From, na To. Mchanganyiko mbili unaofanya kazi ni 465 ukiwa na "Secure" imewekwa kuwa TLS/SSL, au 587 ukiwa na STARTTLS. Kwa Gmail na wasimamizi wengi wenye uthibitisho wa hatua mbili (two-factor auth), lazima utengeneze app password; nywila ya kawaida ya akaunti itatoa Error: Invalid login: 535-5.7.8 Username and Password not accepted.

Telegram. Tuma ujumbe @BotFather, tuma /newbot, kisha nakili bot token. Kwa chat ID yako, tumia bot mpya mara moja, fungua https://api.telegram.org/bot<token>/getUpdates, na usome chat.id kutoka kwenye JSON. Bot ambayo haujawahi kuitumia haina getUpdates na haina mahali pa kutuma ujumbe.

Discord. Ndani ya chaneli, fungua Edit Channel kisha Integrations kisha Webhooks kisha New Webhook, nakili URL, na ubandike kama arifa ya Discord.

Generic webhook. Kwa kitu kingine chochote, kama Slack incoming webhook, endpoint maalum, au home-automation hook, aina ya Webhook hutuma JSON payload kwa URL unayotoa, na uunganishaji wa Apprise unashughulikia huduma nyingi nyingine takriban tisini kwenye orodha hiyo.

Ongeza monita, aina moja baada ya nyingine

Bofya Add New Monitor, chagua aina, kisha weka Friendly Name, Check Interval (sekunde 60 ni sahihi), Retries (idadi ya kushindwa mfululizo kabla ya kuashiria "down"; tumia 2 au 3 ili pakiti moja iliyopotea isisababishe taarifa), na arifa za kutuma. Aina utakazotumia ni:

• HTTP(s). URL kamili. "Up" inamaanisha kodi ya hali iliyokubaliwa (200-299 kwa kimawazo; panua ikiwa 301 au 401 ni kawaida kwako chini ya Accepted Status Codes). Hii ndiyo njia kuu kwa tovuti na API.
• HTTP(s) - Keyword. Ombi lilelile, lakini "up" pia inahitaji maandishi fulani yapo kwenye mwili wa ujumbe (isipokuwa kama Invert imechaguliwa). Hii inakamatia tovuti inayorudisha 200 OK huku ikionyesha "Error establishing a database connection", hali ambayo ukaguzi wa kawaida wa HTTP utaitambua kama salama.
• TCP Port. Unganisho la TCP kwenda kwenye host na port fulani, kwa vitu ambavyo si HTTP: SSH kwenye 22, Postgres kwenye 5432, seva ya SMTP kwenye 25, au seva ya mchezo.
• Ping. ICMP echo: njia rahisi ya kuangalia ufikiaji na latency. Lakini mitandao mingi na firewalls za cloud huzuia ICMP, hivyo monita ya ping nyekundu inaweza kumaanisha "host down" au "mtoa huduma anazuia ping"; thibitisha kwa kutumia monita ya TCP.
• DNS. Inatafuta rekodi (A, AAAA, MX, TXT na kadhalika) kupitia resolver unayoiweka, na inaweza kuhakikisha jibu ni sahihi, ikikamatia hitilafu ya msajili au DNS mapema.
• Push. Monita ya ndani kwenda nje, itakayofafanuliwa baadaye.

Kufuatilia cron job kwa kutumia push (heartbeat) monitor

Kila monitor iliyotajwa hapo juu hufikia huduma yako kutoka nje. Push monitor hufanya kazi kinyume: Uptime Kuma husubiri, na job yako huipigia simu kusema "Nimefanya kazi." Hii ndiyo njia pekee ya uhakika ya kufuatilia backup au cron: HTTP check inajua kama URL inaitikia, lakini ni job pekee inayojua kama imekamilika.

Tengeneza monitor ya aina Push. Uptime Kuma hutengeneza URL ya kipekee kama:

https://status.example.com/api/push/j8Xa2Kd9Qe?status=up&msg=OK&ping=

Weka Heartbeat Interval kulingana na muda ambao job inafanya kazi, ukiongeza muda kidogo wa ziada. Kisha ongeza mstari mmoja mwishoni mwa script, ili itumbe tu ikiwa imefanikiwa:

#!/usr/bin/env bash
set -euo pipefail
# ... your backup or job runs here; set -e aborts on any failure ...
curl -fsS --retry 3 "https://status.example.com/api/push/j8Xa2Kd9Qe?status=up&msg=backup+ok&ping="

Ikiwa job itafeli, set -e itasimama kabla ya curl; ikiwa kompyuta imezimwa, haitafanya kazi pia. Katika hali zote mbili, heartbeat itasimama, na muda wa interval-plus-retries utakapopita, Uptime Kuma itabadilisha monitor kuwa down na kukupa taarifa. Chukulia push token hiyo kama siri: mtu yeyote mwenye token hiyo anaweza kutengeneza heartbeat ya uongo.

Unde mfanano wa hali ya juu (public status page)

Mfanano wa hali ni muonekano unaowasilishwa kwa mteja: huduma gani zipo na historia yake ya hivi karibuni, bila kuonyesha dashboard yako. Nenda kwenye Status Pages kisha New Status Page, ipe jina na slug (njia ya umma, kama /status/main), vuta monita unazotaka kwenye vikundi kama "Websites" na "APIs", ongeza nembo na maelezo mafupi, kisha Save. Unaweza pia kuunganisha ukurasa huo na domain yake mwenyewe ili status.example.com iutoe moja kwa moja.

Tahadhari mbili: ongeza tu monita ambazo uko tayari kuzifanya kuwa za umma, kwa sababu mfanano wa hali unaonyesha kuwa huduma fulani ipo na kama inafanya kazi; na dashboard inabaki nyuma ya login yako wakati mfanano wa hali umewekwa kuwa wa umma na hauhitaji auth.

Iweke nyuma ya reverse proxy yenye TLS, na zingatia websockets

Kwa instance ya hadhara, weka reverse proxy mbele ya container iliyounganishwa kwenye loopback kwa ajili ya TLS na hostname. Jambo linalowachanganya wengi: UI ya Uptime Kuma ni Socket.IO app inayofanya kazi live, hivyo proxy lazima iweke (upgrade) muunganisho wa WebSocket. Ukikosa hili, ukurasa utafunguka lakini hautatafuta muunganisho; dashboard itabaki kwenye "Connecting...", na taarifa za live (heartbeats) hazitafanya kazi, na console ya kivinjari itaonyesha WebSocket connection to 'wss://.../socket.io/...' failed.

Install nginx na certbot, kisha andika vhost inayopitisha (proxy) kwenye loopback port. Iweke kwenye port 80 kwa sasa na uache certbot iongeze TLS baadaye; changamoto, muda wa kurejesha (renewal timer) na sababu za kushindwa vimeelezwa kwenye issuing Let's Encrypt certificates with certbot and nginx.

sudo apt install -y nginx certbot python3-certbot-nginx

Hifadhi hii kama /etc/nginx/sites-available/status.example.com; mistari miwili ya WebSocket ndiyo muhimu zaidi:

server {
    listen 80;
    server_name status.example.com;

    location / {
        proxy_pass http://127.0.0.1:3001;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_read_timeout 3600s;
    }
}

Washa site, jaribu config, kisha uache certbot iandike upya block ili isikilize kwenye 443, iweke certificate na uongeze redirect ya HTTP-to-HTTPS:

sudo ln -s /etc/nginx/sites-available/status.example.com /etc/nginx/sites-enabled/
sudo nginx -t && sudo systemctl reload nginx
sudo certbot --nginx -d status.example.com

Pair ya Upgrade na Connection "upgrade" ndiyo muhimu zaidi, na proxy_read_timeout 3600s inazuia nginx kuondoa socket inayodumu kwa muda mrefu; certbot hunakili zote mbili kwenye block ya 443 inayozalisha. Kama tayari unatumia container nyingi nyuma ya proxy moja, routing them through Traefik with automatic TLS hufanya hivyo kwa kutumia container labels na huruhusu WebSocket upgrades kwa kimawazo (default).

Usitumie basic-auth kwenye vhost nzima, kwa sababu hiyo itafunga ukurasa wa hadhara wa status na endpoint ya /api/push. Tumia login ya ndani ya Uptime Kuma, ongeza fail2ban watching for repeated failed logins ikiwa inaingiawezekana kupitia internet, na ikiwa dashboard haihitaji kuwa ya hadhara, toa proxy na uifikie kupitia VPN.

Usimamizi wa mwisho wa muda wa cheti (Certificate-expiry monitoring)

Msimamizi wa HTTP(s) anaweza kukutaarifu kabla ya cheti cha TLS kuisha muda wake: weka alama kwenye Certificate Expiry Notification na Uptime Kuma itatoa taarifa siku fulani kabla. Makosa mawili husababisha usomaji wa kosa. Simamia kwa hostname, siyo IP, vinginevyo ombi bila SNI litapata cheti cha kawaida cha seva na utaona Hostname/IP does not match certificate's altnames. Pia, usichague Ignore TLS/SSL Error kwenye msimamizi unayotaka upate taarifa za mwisho wa muda: chaguo hilo ni kwa ajili ya host za ndani zenye cheti cha kujisaini (unable to verify the first certificate, DEPTH_ZERO_SELF_SIGNED_CERT), lakini huzuia Uptime Kuma kuangalia cheti kabisa, ikiwemo mwisho wa muda wake.

Backups: ni directory moja

Kwa sababu kila kitu kipo kwenye /app/data, backup ni nakala ya volume hiyo inayochukuliwa wakati container imesimama, ili faili ya SQLite iwe na data sahihi:

cd /srv/uptime-kuma
sudo docker compose stop
sudo docker run --rm \
  -v uptime-kuma_kuma-data:/data \
  -v /var/backups/kuma:/backup \
  alpine tar czf /backup/kuma-$(date -u +%Y%m%dT%H%M%SZ).tgz -C /data .
sudo docker compose start

Kwanza thibitisha jina halisi la volume kwa kutumia docker volume ls | grep kuma, kwa sababu Compose huongeza jina la directory ya mradi mbele yake. Kisha nakili tarball hiyo nje ya VPS, kwa sababu backup iliyopo kwenye VPS ile ile ni nakala tu, siyo backup ya kweli. Kurejesha (restore) ni mchakato wa kinyume: simamisha stack, extract kwenye volume tupu ya /app/data, kisha iwashe.

Upgrades

Upgrades ni mchakato wa kuvuta picha (image pull):

cd /srv/uptime-kuma
sudo docker compose pull
sudo docker compose up -d

Container mpya itafanya mchakato wowote wa database migration wakati inapoanza kwa mara ya kwanza; angalia docker compose logs -f. Fanya backup iliyotajwa hapo juu kabla ya kuvuta picha, na baki ndani ya major tag: kuhama kutoka :1 kwenda :2 ni uhamisho wa upande mmoja, hivyo fanya backup kwanza na kagua maelezo ya toleo (release notes).

Hali za kushindili, pamoja na maandishi utakayoyaona

"Down" ya uongo kwenye monitor inayolenga localhost. Monitor inakuwa nyekundu ikiwa na timeout of 48000ms exceeded au connect ETIMEDOUT, lakini huduma inajibu kutoka kwenye laptop yako. Ikiwa inalenga host ile ile ambayo Uptime Kuma inafanya kazi, ongezeko la CPU au memory limezuia ukaguzi, siyo lengo. Hamisha monitor kwenye VPS tofauti na ulingeze hostname ya umma.

connect ECONNREFUSED 127.0.0.1:443 (au port yoyote). Hakuna kilichokuwa kinasikiliza kwenye port hiyo: ama huduma imezimika, au ulichunguza localhost kutoka ndani ya container, ambapo 127.0.0.1 ni container, siyo server yako. Lingeza hostname ya umma, siyo loopback.

Invalid login: 535-5.7.8 Username and Password not accepted kwenye jaribio la barua pepe. Credential za SMTP ni zisizo sahihi, au mtoa huduma anahitaji password maalum ya app na amepata password ya akaunti yako. Tengeneza app password na ubandike hiyo.

connect ETIMEDOUT au queryA ETIMEDOUT <host> kwenye jaribio la barua pepe. Port siyo sahihi, au mtoa huduma anazuia SMTP ya kutuma. Hakikisha 465 au 587 inafanana na mipangilio ya Secure/STARTTLS, na ufanye jaribio kutoka kwenye host kwa kutumia nc -vz smtp.example.com 587. Watoa huduma wengi huzuia 25 na baadhi huzuia port za utumaji mpaka uombe ruhusa.

self signed certificate au unable to verify the first certificate kwenye jaribio la barua pepe. Server yako ya SMTP inatoa cheti ambacho Node haitaamini; sahihisha cheti cha server ya mail badala ya kulifunika.

Dashboard imekwama kwenye "Connecting...", console inaonyesha WebSocket connection ... failed. Reverse proxy haipandishi (upgrading) WebSocket. Ongeza header za Upgrade na Connection "upgrade" kwenye nginx, au tumia proxy inayozituma kwa kimawazo kama Traefik au Caddy. HTML inapakia kwa sababu hiyo ni HTTP GET ya kawaida; ni socket ya moja kwa moja pekee inayohitaji upgrade.

Monitor ya muda wa kuisha kwa cert haitoi tahadhari, au inatoa tahadhari isiyo sahihi. Ama Ignore TLS/SSL Error imewekwa, ambayo inazima ukaguzi wa cert, au monitor inalenga IP na inasoma cheti kisicho sahihi kwa sababu ya kukosekana kwa SNI, ikionyesha Hostname/IP does not match certificate's altnames. Ondoa alama ya ignore, lingeza kwa hostname.

SQLITE_BUSY au database disk image is malformed kwenye logs. Volume ya /app/data iko kwenye filesystem isiyo na file locking inayofaa, mara nyingi NFS; ihamishe kwenye Docker volume ya ndani na urejeshe kutoka kwenye backup.

FAQ

Ni wapi nianze kuendesha uptime monitor yangu?

Kwenye seva tofauti na zile unazozifuatilia. Ni bora kutumia mtoa huduma au eneo lingine, ukizifikia kwa hostname kupitia internet ya umma kama watumiaji wako wanavyofanya. Ikiwa monitor itashiriki seva moja na malengo yake, hitilafu itakayozima seva itazima na monitor pia. Pia, seva iliyozidiwa itatoa taarifa ya "down" hata kama huduma ni sawa. Kutumia VPS ndogo na tofauti kuepuka matatizo haya yote.

Ninawezaje kupata taarifa (alerts) kwenye Telegram au email?

Ongeza chaneli chini ya Settings then Notifications, kisha iunganishe na kila monitor. Kwa Telegram, tengeneza bot kwa kutumia @BotFather na usome chat.id kutoka https://api.telegram.org/bot<token>/getUpdates; kwa email, tumia 465 kwa SSL au 587 kwa STARTTLS ukitumia app password ikiwa mtoa huduma wako unatumia two-factor auth. Bonyeza Test na uthibitishe ujumbe umefika kabla ya kuutegemea.

Je, Uptime Kuma inaweza kufuatilia cron job au backup script?

Ndiyo, hiyo ni monitor ya Push: Uptime Kuma inakupa URL na wewe curl mwishoni mwa script ili itumbe taarifa ikiwa imefanikiwa tu. Ikiwa kazi itafeli au seva itazimika, heartbeat haitafika, na utapata taarifa baada ya muda uliowekwa kupita. Hii ndiyo njia pekee ya kuaminika kujua kama kazi iliyopangwa imekimbia kweli, kwa sababu ukaguzi wa nje hauwezi kuona ndani yake.

Uptime Kuma vs Zabbix, niipi nianze kutumia?

Uptime Kuma inajibu "je, ipo, kutoka nje, na je imenipa taarifa" ndani ya dakika kumi kwa kutumia rasilimali kidogo sana, pamoja na ukurasa wa hali (status page). Haitatunza vipimo vya ndani kama CPU, memory na mienendo ya disk au viwango vya ulimwengu mzima; kwa ajili hiyo, a full Zabbix monitoring server ni zana nzito zaidi inayotumia agent, na watu wengi hutumia zote mbili. Bado unaamua nini cha kutumia? our roundup of what to self-host in 2026 inakupa muktadha wa ufuatiliaji.