Paano gamitin ang Uptime Kuma sa Docker

Ang iyong bubuuin

Isang maliit na container na nagbabantay sa iyong mga server at website mula sa labas. Magpapadala ito ng alert sa email, Telegram, Discord, o webhook sa sandaling hindi na ito tumugon. Ang Uptime Kuma ay isang Node process na gumagamit ng SQLite file, kaya kaya itong patakbuhin sa 256-512 MB ng RAM. Nagbibigay ito ng live dashboard, history graphs, at public status page. Ang installation ay isang ten-line Compose file; ang pinakaimportante ay kung saan mo ito patatakbuhin at kung gumagana ang iyong mga alert sa isang test. Ang monitor na hindi mo nasubukan kung makakarating sa iyo ay mas malala pa sa kawalan ng monitor: nagbibigay ito ng maling pakiramdam ng seguridad habang wala ka talagang nababantayan.

Patakbuhin ang monitor sa lugar na hindi maaabot ng outage

Ang desisyong ito ang magtatakda kung gagana ang buong system, kaya dapat itong unahin. Huwag patakbuhin ang Uptime Kuma sa parehong box na binabantayan nito. Kung ang monitor ay nasa loob mismo ng server na binabantayan, ang mismong event na sinusubaybayan mo—gaya ng pagkamatay ng box o pagkaubos ng memory—ay papatay din sa monitor. Dahil dito, wala kang matatanggap na alert: ang pananahimik ng isang dead monitor ay katulad lang ng status na "everything is fine." May mas malalim na problema kahit buhay ang box: ang monitor na nakatutok sa localhost ay nakikigamit sa CPU ng workload. Ang load spike ay maaaring magdulot ng timeout sa check nito at magpalit sa target status sa down. Ito ay false alarm, kahit na maayos namang nakakapag-serve ang server sa mga totoong user.

Kaya patakbuhin ang Uptime Kuma sa isang ibang VPS mula sa server na binabantayan nito. Mas mainam kung ibang provider o ibang region ang gagamitin. Dapat itong maabot ang iyong mga service gaya ng pag-access ng iyong mga user: sa pamamagitan ng public internet at gamit ang hostname. Sapat na ang isang murang instance, at ang isang maliit na monitoring VPS ay kayang magbantay sa lahat ng iyong mga server. Para malaman kung ang Kuma mismo ang namatay, magdagdag ng push heartbeat mula sa isang cron sa ibang lokasyon.

Prerequisites and sizing

• Isang bagong Ubuntu 24.04 VPS na may Docker Engine at Compose v2 plugin. Dapat itong i-install mula sa official Docker apt repository, hindi mula sa docker.io distro package dahil luma ang bersyon nito.
• Ang 256 MB RAM ay sapat para sa iilang monitors lamang; mas mainam ang 512 MB hanggang 1 GB para sa dose-dosenang monitors kasama ang reverse proxy. Ang CPU ay halos idle lamang sa pagitan ng mga check.
• Isang domain at DNS A record (halimbawa, status.example.com na nakaturo sa VPS), kung kailangan mo ng TLS at public status page. Maaaring hindi gumamit ng DNS at gumamit na lang ng VPN o SSH tunnel para sa private instance.
• Outbound network para sa mga alerts: SMTP para sa iyong mail provider, o HTTPS para sa Telegram at Discord.

Ang Compose file

Ilagay ito sa /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:

I-run ito at i-monitor ang unang boot:

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

Kapag tama ang start, maglo-log ang Listening on 3001 at tatahimik na. May tatlong sadyang configuration sa file na iyon.

127.0.0.1:3001:3001, hindi 3001:3001. Naglalabas ang Docker ng mga port gamit ang DNAT rules na sinusuri bago pa makita ng ufw ang packet. Dahil dito, ang simpleng 3001:3001 ay maglalantad sa iyong dashboard sa public internet anuman ang firewall mo. Ang pag-bind sa loopback ay nagpapanatili nito na private, kung saan ang reverse proxy lang ang exposed; ang isang private instance ay maaaring lumaktaos sa proxy at direktang kumonekta sa 3001 gamit ang isang self-hosted WireGuard VPN.

Isang named volume sa /app/data. Dito nakaimbak ang lahat ng natatandaan ng Uptime Kuma: ang SQLite database, ang iyong mga monitor, notification settings, at status-page logos. Kapag nawala ito, magsisimula ka sa isang empty admin screen; ito lang ang tanging bagay na dapat mong i-back up.

Ang image ay naka-pin sa isang major tag, :2. Ito ang kasalukuyang stable line; i-check ang Docker Hub para sa pinakabagong major bago ito i-copy. Huwag gumamit ng moving tag gaya ng latest dahil deprecated na ito ng project. Ang major-version jump sa image na ito ay isang one-way database migration; dapat itong gawin nang sadyang desisyon, hindi dahil sa aksidenteng routine pull.

Isang babala: dapat nakalagay ang /app/data sa isang filesystem na may POSIX file locks. Ayos lang ang local Docker volume; sa NFS, magiging corrupt ang SQLite database at magkakaroon ka ng SQLITE_BUSY at database disk image is malformed, kaya huwag gumamit ng network share.

Unang pagtakbo: gumawa ng admin account

Mag-browse sa instance gamit ang iyong proxy sa https://status.example.com, o sa pamamagitan ng SSH tunnel: i-run ang ssh -L 3001:127.0.0.1:3001 user@your-vps at buksan ang http://localhost:3001. Ang unang page ay setup form para sa administrator username at password; walang default login. Pumili ng totoong password: nakikita ng dashboard na ito ang mga internal address at token ng lahat ng iyong minomonitor. Nakalimutan ito? I-reset mula sa host, hindi sa browser:

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

Idagdag muna ang iyong mga notification channel, at i-test ang mga ito

I-set up ang mga alert bago magdagdag ng mga monitor. Makakatulong ito para ma-attach agad ang channel habang gumagawa ng bawat monitor. Pumunta sa Settings then Notifications then Setup Notification, at gamitin ang Test button ng bawat channel para kumpirmahin kung natatanggap ang mensahe. Ang hindi na-test na notification ang pangalawang pinaka-karaniwang dahilan ng silent failure sa setup.

Email (SMTP). Ilagay ang host, port, encryption, username, password, From, at To. Ang dalawang gumaganang kombinasyon ay 465 na may "Secure" na TLS/SSL, o 587 na may STARTTLS. Para sa Gmail at karamihan ng providers na may two-factor auth, kailangang mag-generate ng app password; ang normal na account password ay magreresulta sa Error: Invalid login: 535-5.7.8 Username and Password not accepted.

Telegram. I-message ang @BotFather, i-send ang /newbot, at i-copy ang bot token. Para sa iyong chat ID, i-message ang bagong bot nang isang beses, buksan ang https://api.telegram.org/bot<token>/getUpdates, at basahin ang chat.id mula sa JSON. Ang bot na hindi mo muna na-message ay may bakanteng getUpdates kaya walang mapadalhan ng mensahe.

Discord. Sa channel, buksan ang Edit Channel then Integrations then Webhooks then New Webhook, i-copy ang URL, at i-paste ito bilang Discord notification.

Generic webhook. Para sa iba pang serbisyo, gaya ng Slack incoming webhook, custom endpoint, o home-automation hook, ang Webhook type ay nagpapadala ng JSON payload via POST sa URL na ibibigay mo. Sakop ng bundled Appise integration ang karamihan sa mahigit siyamnapung iba pang serbisyo sa listahan.

Magdagdag ng mga monitor, isa-isa ang bawat uri

I-click ang Add New Monitor, pumili ng uri, at i-set ang Friendly Name, ang Check Interval (ang 60 seconds ay sapat na), ang Retries (sunod-sunod na failure bago ituring na "down"; gamitin ang 2 o 3 para hindi agad mag-page sa isang dropped packet), at ang mga notification na dapat i-trigger. Ang mga uri na gagamitin mo ay:

• HTTP(s). Isang buong URL. Ang "up" ay nangangahulugang may accepted status code (200-299 by default; palawakin ito sa ilalim ng Accepted Status Codes kung ang 301 o 401 ay normal para sa iyo). Ito ang pangunahing gamit para sa mga website at API.
• HTTP(s) - Keyword. Ang parehong request, pero ang "up" ay nangangailangan din ng isang string sa body, o walang Invert na naka-check. Nakukuha nito ang mga site na nagbabalik ng 200 OK habang nag-e-error ng "Error establishing a database connection", na itinuturing na healthy ng isang plain HTTP check.
• TCP Port. Isang direktang TCP connection sa isang host at port, para sa mga bagay na hindi HTTP: SSH sa 22, Postgres sa 5432, isang SMTP server sa 25, o isang game server.
• Ping. ICMP echo: para sa reachability at latency. Ngunit maraming network at cloud firewall ang nagba-block ng ICMP, kaya ang red ping monitor ay maaaring mangahulugang "host down" o "binablock ng provider ang ping"; i-verify ito gamit ang isang TCP monitor.
• DNS. Nag-re-resolve ng record (A, AAAA, MX, TXT, atbp.) gamit ang isang resolver na iyong itinakda, at maaaring i-verify ang sagot nito upang maagang mahuli ang outage sa registrar o DNS.
• Push. Ang "inside-out" monitor, na tatalakayin sa susunod.

Pag-monitor ng cron job gamit ang push (heartbeat) monitor

Ang lahat ng monitor sa itaas ay kumukuha ng data mula sa iyong service mula sa labas. Ang push monitor ay kabaligtaran nito: naghihintay ang Uptime Kuma, at ang iyong job ang tatawag dito para sabihing "tumatakbo ako." Ito ang tanging tapat na paraan para i-monitor ang backup o cron: alam ng HTTP check kung sumasagot ang isang URL, pero ang job lang ang nakakaalam kung natapos ito nang maayos.

Gumawa ng monitor na may type na Push. Ang Uptime Kuma ay mag-ge-generate ng unique na URL gaya ng:

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

I-set ang Heartbeat Interval sa dalas ng pagtakbo ng job, dagdagan ng kaunting slack. Pagkatapos, magdagdag ng isang linya sa dulo ng script para gumana lang ito kapag success:

#!/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="

Kapag nag-fail ang job, set -e ang mag-a-abort bago ang curl; kung down ang server, hindi rin ito tatakbo. Sa alinmang senaryo, hihinto ang heartbeat, at kapag lumampas na ang interval-plus-retries window, gagawin ng Uptime Kuma na down ang monitor at magpapadala ng alert. Ituring ang push token na iyon bilang isang secret: kahit sino na may hawak nito ay maaaring gumawa ng pekeng healthy beat.

Gumawa ng public status page

Ang status page ay ang view para sa mga customer: dito makikita kung aling mga services ang up at ang kanilang recent history, nang hindi ipinapakita ang iyong dashboard. Pumunta sa Status Pages then New Status Page, magbigay ng pangalan at slug (ang public path, gaya ng /status/main), i-drag ang mga monitor na gusto mo sa mga group gaya ng "Websites" at "APIs", magdagdag ng logo at maikling description, at i-click ang Save. Maaari mo ring i-bind ang page sa sarili nitong domain para direktang i-serve ito ng status.example.com.

Dalawang paalala: magdagdag lamang ng mga monitor na handa mong gawing public, dahil ipinapakita ng status page na mayroong service at kung ito ay up; at ang dashboard ay mananatili sa likod ng iyong login habang ang status page ay sadyang public at hindi nangangailangan ng auth.

Gamitin ang reverse proxy na may TLS, at bantayan ang websockets

Para sa public instance, maglagay ng reverse proxy sa harap ng loopback-bound container para sa TLS at hostname. Ang detalye na nagpapahirap sa lahat: Ang UI ng Uptime Kuma ay isang live Socket.IO app, kaya dapat i-upgrade ng proxy ang WebSocket connection. Kapag hindi ito nagawa, maglo-load ang page pero hindi ito magkokonekta; mananatiling "Connecting..." ang dashboard, hindi mag-uupdate ang live heartbeats, at lalabas ang WebSocket connection to 'wss://.../socket.io/...' failed sa browser console.

I-install ang nginx at certbot, pagkatapos ay isulat ang vhost na mag-pro-proxy sa loopback port. Ilagay muna ito sa port 80 at hayaan ang certbot na magdagdag ng TLS pagkatapos; ang mga hamon, renewal timer, at failure modes nito ay tatalakayin sa issuing Let's Encrypt certificates with certbot and nginx.

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

I-save ito bilang /etc/nginx/sites-available/status.example.com; ang dalawang WebSocket line ang pinakaimportante:

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;
    }
}

I-enable ang site, i-test ang config, pagkatapos ay hayaan ang certbot na i-rewrite ang block para makinig sa 443, ilagay ang certificate, at magdagdag ng HTTP-to-HTTPS redirect:

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

Ang pares ng Upgrade at Connection "upgrade" ang pinakaimportante, at pinipigilan ng proxy_read_timeout 3600s ang nginx na i-terminate ang long-lived socket; kokopyahin ng certbot ang parehong ito sa 443 block na gagawin nito. Kung gumagamit ka na ng maraming container sa likod ng isang proxy, ang routing them through Traefik with automatic TLS ay gumagawa ng parehong proseso gamit ang container labels at awtomatikong nagfo-forward ng WebSocket upgrades.

Huwag lagyan ng basic-auth ang buong vhost, dahil iba-block din nito ang public status page at ang /api/push endpoint. Panatilihin ang built-in login ng Uptime Kuma, magdagdag ng fail2ban watching for repeated failed logins kung ito ay internet-facing, at kung hindi kailangang maging public ang dashboard, huwag nang gumamit ng proxy at i-access ito via VPN.

Tamang pag-monitor ng certificate-expiry

Maaaring magbigay ng babala ang HTTP(s) monitor bago mag-expire ang isang TLS certificate: i-tick ang Certificate Expiry Notification at magpapadala ang Uptime Kuma ng alerto ilang araw bago ang expiry. May dalawang pagkakamali na nagiging sanhi ng maling pagbasa nito. Mag-monitor gamit ang hostname, hindi IP, dahil ang request na walang SNI ay makakakuha ng default certificate ng server at makikita mo ang Hostname/IP does not match certificate's altnames. Huwag ding i-tick ang Ignore TLS/SSL Error sa monitor na gusto mong makatanggap ng expiry warnings: ang toggle na ito ay para sa mga self-signed internal hosts (unable to verify the first certificate, DEPTH_ZERO_SELF_SIGNED_CERT), ngunit pinatitigil nito ang pag-check ng Uptime Kuma sa certificate, kasama na ang expiry nito.

Backups: isang directory lang ito

Dahil nasa /app/data ang lahat, ang backup ay kopya ng volume na iyon habang naka-stop ang container. Ginagawa ito para maging consistent ang SQLite file:

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

I-verify muna ang real name ng volume gamit ang docker volume ls | grep kuma, dahil may prefix ang Compose mula sa project directory. Pagkatapos, i-copy ang tarball palabas ng VPS. Ang backup na nasa loob pa rin ng parehong VPS ay kopya lamang, hindi tunay na backup. Ang pag-restore ay kabaligtaran nito: i-stop ang stack, i-extract sa isang empty na /app/data volume, at i-start muli.

Upgrades

Ang mga upgrade ay isang image pull:

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

Magpapatakbo ang bagong container ng anumang database migration sa unang start nito; i-monitor ang docker compose logs -f. Gawin ang backup sa itaas bago mag-pull, at manatili sa loob ng isang major tag: ang paglipat mula :1 patungong :2 ay isang one-way migration, kaya mag-backup muna at suriin ang release notes.

Failure modes, with the strings you will see

False "down" sa monitor na nakaturo sa localhost. Nagiging pula ang monitor dahil sa timeout of 48000ms exceeded o connect ETIMEDOUT, kahit sumasagot naman ang service sa iyong laptop. Kung ang target ay ang parehong host kung saan tumatakbo ang Uptime Kuma, maaaring nagkaroon ng CPU o memory spike na nagdulot ng failure sa check, hindi ang target. Ilipat ang monitor sa isang hiwalay na VPS at ituro ang public hostname.

connect ECONNREFUSED 127.0.0.1:443 (o anumang port). Walang nakikinig sa port na iyon: maaaring down ang service, o minomonitor mo ang localhost mula sa loob ng container, kung saan ang 127.0.0.1 ay ang container, hindi ang iyong server. I-monitor ang public hostname, hindi ang loopback.

Invalid login: 535-5.7.8 Username and Password not accepted sa email test. Mali ang SMTP credentials, o nangangailangan ang provider ng app-specific password pero ang account password ang ginamit mo. Mag-generate ng app password at i-paste ito.

connect ETIMEDOUT o queryA ETIMEDOUT <host> sa email test. Mali ang port, o bina-block ng provider ang outbound SMTP. Siguraduhin na ang 465 o 587 ay tugma sa Secure/STARTTLS setting, at i-test ang host gamit ang nc -vz smtp.example.com 587. Maraming provider ang nagba-block ng outbound 25 at ang iba ay bina-block ang submission ports hangga't hindi ka nagre-request.

self signed certificate o unable to verify the first certificate sa email test. Ang iyong SMTP server ay gumagamit ng certificate na hindi pinagkakatiwalaan ng Node; ayusin ang certificate ng mail server sa halip na gumamit ng workaround.

Dashboard na stuck sa "Connecting...", at WebSocket connection ... failed sa console. Hindi na-uupgrade ng reverse proxy ang WebSocket. Idagdag ang Upgrade at Connection "upgrade" headers sa nginx, o gumamit ng proxy na default na nagfo-forward sa mga ito gaya ng Traefik o Caddy. Naglo-load ang HTML dahil ito ay normal na HTTP GET; ang live socket lamang ang nangangailangan ng upgrade.

Cert-expiry monitor na hindi nagwa-warn, o mali ang warning. Maaaring naka-tick ang Ignore TLS/SSL Error, na nag-o-off sa cert checking, o ang monitor ay nakaturo sa isang IP at binabasa ang maling certificate dahil sa kawalan ng SNI, na nagpapakita ng Hostname/IP does not match certificate's altnames. I-untick ang ignore, at i-monitor gamit ang hostname.

SQLITE_BUSY o database disk image is malformed sa logs. Ang /app/data volume ay nasa filesystem na walang tamang file locking, karaniwan ay NFS; ilipat ito sa isang local Docker volume at i-restore mula sa backup.

FAQ

Saan ko dapat patakbuhin ang aking uptime monitor?

Dapat itong patakbuhin sa ibang server mula sa mga target nito. Mas mainam kung ibang provider o region ang gamit. Dapat itong kumonekta sa mga target gamit ang hostname sa public internet, gaya ng ginagawa ng iyong mga users. Kung ang monitor ay nasa parehong server ng mga target, ang outage na magpapabagsak sa server ay magpapabagsak din sa monitor. Ang overloaded na host naman ay magbibigay ng false positive na "down" ang mga serbisyo kahit maayos ang mga ito. Ang paggamit ng maliit at hiwalay na VPS ay solusyon sa parehong problema.

Paano ako makakatanggap ng alerts sa Telegram o email?

Idagdag ang channel sa ilalim ng Settings then Notifications, pagkatapos ay i-attach ito sa bawat monitor. Para sa Telegram, gumawa ng bot gamit ang @BotFather at basahin ang chat.id mula sa https://api.telegram.org/bot<token>/getUpdates; para sa email, gamitin ang 465 para sa SSL o 587 para sa STARTTLS gamit ang app password kung gumagamit ang iyong provider ng two-factor auth. Pindutin ang Test at kumpirmahin kung dumating ang mensahe bago ito gamitin nang tuluyan.

Kaya ba ng Uptime Kuma na i-monitor ang isang cron job o backup script?

Oo, iyan ang gamit ng Push monitor: Bibigyan ka ng Uptime Kuma ng URL at i-curl ito sa dulo ng iyong script para gumana lamang ito kapag success ang execution. Kung mabigo ang job o kung down ang server, hindi darating ang heartbeat, at makakatanggap ka ng alert pagkatapos ng itinakdang interval. Ito ang tanging maaasahang paraan para malaman kung tumakbo ba talaga ang isang scheduled job, dahil hindi makikita ng isang external check ang nangyayari sa loob nito.

Uptime Kuma vs Zabbix, alin ang dapat kong patakbuhin?

Sinasagot ng Uptime Kuma ang tanong na "up ba ito mula sa labas, at nag-alert ba ito sa akin" sa loob ng sampung minuto na may napakaliit na resource usage, kasama na ang isang status page. Hindi ito kumokolekta ng deep metrics gaya ng CPU, memory, at disk trends o fleet-wide thresholds. Para sa mga iyon, ang isang full Zabbix monitoring server ay isang mas mabigat na tool na agent-based, at maraming tao ang gumagamit ng parehong system. Nagdedesisyon ka pa lang ba kung ano ang patatakbuhin? Tingnan ang aming roundup ng mga dapat i-self-host sa 2026 para sa konteksto ng monitoring.