Cara install Uptime Kuma di Docker

Apa yang Anda bangun

Sebuah kontainer kecil tunggal yang memantau server dan situs web Anda dari luar. Sistem ini akan memberi tahu Anda saat salah satu layanan berhenti merespons melalui email, Telegram, Discord, atau webhook. Uptime Kuma adalah satu proses Node yang didukung oleh file SQLite, sehingga dapat berjalan dengan lancar pada RAM 256-512 MB. Layanan ini menyediakan dashboard langsung, grafik riwayat, dan halaman status publik. Instalasi hanya memerlukan file Compose sebanyak sepuluh baris. Hal yang paling penting adalah di mana Anda menjalankannya dan apakah peringatan Anda pernah berhasil dalam pengujian. Monitor yang tidak pernah terbukti dapat menghubungi Anda lebih buruk daripada tidak ada monitor sama sekali, karena hal itu memberikan rasa aman palsu saat Anda tidak memantau apa pun.

Jalankan monitor di lokasi yang tidak terjangkau oleh gangguan

Keputusan ini menentukan keberhasilan seluruh sistem, jadi ini adalah langkah pertama. Jangan jalankan Uptime Kuma pada mesin yang sama dengan layanan yang dipantau. Jika monitor berada pada server yang sama dengan target pantauan, maka saat server tersebut mati atau kehabisan memori, monitor juga akan mati. Anda tidak akan menerima peringatan apa pun karena monitor yang mati tidak memberikan perbedaan dengan status "semua berjalan normal." Ada jebakan lain saat server masih menyala: monitor yang mengarah ke localhost berbagi penggunaan CPU dengan beban kerja utama. Lonjakan beban kerja dapat menyebabkan pemeriksaan monitor mengalami timeout dan mengubah status target menjadi down. Ini adalah alarm palsu, padahal pengguna asli masih bisa mengakses layanan dengan normal.

Oleh karena itu, jalankan Uptime Kuma pada VPS yang berbeda dari server yang dipantau. Idealnya, gunakan penyedia atau wilayah yang berbeda agar monitor menjangkau layanan Anda seperti halnya pengguna: melalui internet publik menggunakan hostname. Instance murah sudah cukup, dan satu VPS pemantau kecil dapat memantau seluruh server Anda. Untuk mendeteksi jika Kuma mati, tambahkan push heartbeat dari cron di lokasi lain.

Prerequisites and sizing

• VPS Ubuntu 24.04 baru dengan Docker Engine dan plugin Compose v2. Instal dari repositori apt resmi Docker, bukan paket distro docker.io karena versinya tertinggal.
• RAM 256 MB cukup untuk menjalankan beberapa monitor; 512 MB hingga 1 GB disarankan untuk puluhan monitor ditambah reverse proxy, dengan penggunaan CPU rendah di antara waktu pengecekan.
• Domain dan DNS A record (misalnya status.example.com yang mengarah ke VPS), hanya jika Anda memerlukan TLS dan halaman status publik. Instansi privat dapat mengabaikan DNS dan menggunakan VPN atau SSH tunnel.
• Koneksi jaringan keluar ke tujuan peringatan: SMTP ke penyedia email Anda, atau HTTPS ke Telegram dan Discord.

File Compose

Simpan ini di /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:

Jalankan dan pantau proses boot pertama:

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

Awal yang benar akan mencatat Listening on 3001 dan berhenti mencatat log. Ada tiga hal sengaja diatur dalam file tersebut.

127.0.0.1:3001:3001, bukan 3001:3001. Docker memublikasikan port menggunakan aturan DNAT yang dievaluasi sebelum ufw melihat paket tersebut. Oleh karena itu, penggunaan 3001:3001 akan membuat dashboard Anda dapat diakses melalui internet publik terlepas dari firewall Anda. Mengikat ke loopback menjaga akses tetap privat, sehingga hanya reverse proxy yang terekspos; instansi privat dapat melewati proxy dan mengakses 3001 melalui VPN WireGuard self-hosted sebagai gantinya.

Volume bernama di /app/data. Semua data yang diingat Uptime Kuma, seperti database SQLite, monitor, pengaturan notifikasi, dan logo halaman status, tersimpan di sana. Jika data ini hilang, Anda akan memulai dari layar admin yang kosong; ini adalah satu-satunya hal yang wajib Anda cadangkan.

Image dipaku pada tag versi utama, :2. Itu adalah lini stabil saat ini; periksa Docker Hub untuk versi utama terbaru sebelum menyalinnya. Jangan pernah menggunakan tag yang berubah-ubah seperti latest, karena proyek ini sudah tidak menyarankannya. Perubahan versi utama pada image ini adalah migrasi database satu arah yang harus Anda picu secara sengaja, bukan terjadi secara tidak sengaja saat melakukan pull rutin.

Satu catatan: /app/data harus berada pada sistem berkas dengan POSIX file locks. Volume Docker lokal sudah cukup; pada NFS, database SQLite akan korup dan menyebabkan SQLITE_BUSY serta database disk image is malformed, jadi jangan pernah gunakan network share.

Jalankan pertama kali: buat akun admin

Akses instance melalui proxy Anda di https://status.example.com, atau melalui SSH tunnel: jalankan ssh -L 3001:127.0.0.1:3001 user@your-vps dan buka http://localhost:3001. Halaman pertama adalah formulir pengaturan untuk username dan password administrator; tidak ada login default. Pilih password yang kuat: dashboard ini dapat melihat alamat internal dan token dari semua yang Anda pantau. Lupa password? Lakukan reset dari host, bukan dari browser:

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

Tambahkan saluran notifikasi Anda terlebih dahulu, lalu uji

Atur peringatan sebelum menambahkan monitor agar Anda dapat menyematkan saluran saat membuat setiap monitor. Buka Settings lalu Notifications lalu Setup Notification, dan gunakan tombol Test pada setiap saluran untuk memastikan pesan terkirim. Notifikasi yang tidak diuji adalah penyebab kegagalan sistem yang paling umum setelah kesalahan konfigurasi.

Email (SMTP). Isi host, port, enkripsi, username, password, From, dan To. Dua kombinasi yang berfungsi adalah 465 dengan "Secure" diatur ke TLS/SSL, atau 587 dengan STARTTLS. Untuk Gmail dan sebagian besar penyedia layanan dengan autentikasi dua faktor, Anda harus membuat app password; kata sandi akun biasa akan menghasilkan Error: Invalid login: 535-5.7.8 Username and Password not accepted.

Telegram. Kirim pesan @BotFather, kirim /newbot, lalu salin bot token. Untuk chat ID Anda, kirim pesan ke bot baru tersebut satu kali, buka https://api.telegram.org/bot<token>/getUpdates, dan baca chat.id dari JSON. Bot yang belum pernah Anda kirimi pesan akan memiliki getUpdates yang kosong sehingga tidak ada tujuan pengiriman.

Discord. Di dalam saluran, buka Edit Channel lalu Integrations lalu Webhooks lalu New Webhook, salin URL, dan tempelkan sebagai notifikasi Discord.

Generic webhook. Untuk layanan lainnya, seperti Slack incoming webhook, endpoint kustom, atau hook otomasi rumah, tipe Webhook akan mengirimkan payload JSON melalui metode POST ke URL yang Anda berikan. Integrasi Apprise yang disertakan mencakup sebagian besar dari sembilan puluh layanan lainnya dalam daftar.

Tambahkan monitor, satu per satu

Klik Add New Monitor, pilih tipe, lalu atur Friendly Name, Check Interval (60 detik adalah nilai yang wajar), Retries (jumlah kegagalan berturut-turut sebelum status menjadi "down"; gunakan 2 atau 3 agar satu paket yang hilang tidak memicu peringatan), dan notifikasi yang akan dikirim. Tipe yang akan Anda gunakan:

• HTTP(s). Sebuah URL lengkap. Status "up" berarti kode status diterima (defaultnya 200-299; perlebar rentang ini di bawah Accepted Status Codes jika 301 atau 401 adalah kondisi normal bagi Anda). Digunakan untuk situs web dan API.
• HTTP(s) - Keyword. Permintaan yang sama, tetapi status "up" juga memerlukan adanya string tertentu di dalam body (kecuali jika opsi Invert tidak dicentang). Ini berguna untuk mendeteksi situs yang mengembalikan 200 OK saat menampilkan pesan "Error establishing a database connection", yang biasanya dianggap sehat oleh pemeriksaan HTTP biasa.
• TCP Port. Koneksi TCP murni ke host dan port tertentu, untuk layanan non-HTTP: SSH pada port 22, Postgres pada port 5432, server SMTP pada port 25, atau server game.
• Ping. ICMP echo: untuk memeriksa keterjangkauan dan latensi secara ringan. Namun, banyak jaringan dan firewall cloud memblokir ICMP, sehingga monitor ping yang berwarna merah bisa berarti "host mati" atau "penyedia memblokir ping"; pastikan dengan menggunakan monitor TCP.
• DNS. Melakukan resolusi record (A, AAAA, MX, TXT, dan sebagainya) terhadap resolver yang Anda tentukan, dan dapat memverifikasi jawabannya untuk mendeteksi gangguan registrar atau DNS lebih awal.
• Push. Monitor tipe "inside-out", akan dibahas selanjutnya.

Memantau cron job dengan monitor push (heartbeat)

Setiap monitor di atas mengakses layanan Anda dari luar. Monitor push bekerja dengan cara sebaliknya: Uptime Kuma menunggu, dan job Anda memanggilnya untuk menyatakan "Saya telah berjalan." Ini adalah satu-satunya cara jujur untuk memantau backup atau cron: pemeriksaan HTTP hanya mengetahui jika sebuah URL merespons, tetapi hanya job tersebut yang mengetahui jika proses telah selesai.

Buat monitor dengan tipe Push. Uptime Kuma akan menghasilkan URL unik seperti:

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

Atur Heartbeat Interval sesuai dengan frekuensi jalannya job, ditambah sedikit waktu tambahan. Kemudian tambahkan satu baris di bagian akhir skrip, agar perintah hanya dijalankan jika berhasil:

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

Jika job gagal, set -e akan berhenti sebelum perintah curl dijalankan; jika server mati, perintah tersebut juga tidak akan berjalan. Dalam kedua kondisi tersebut, heartbeat akan berhenti, dan setelah jendela waktu interval-ditambah-retries terlampaui, Uptime Kuma akan mengubah status monitor menjadi down dan memberikan peringatan kepada Anda. Perlakukan push token tersebut sebagai rahasia: siapa pun yang memilikinya dapat memalsukan status sehat.

Membuat halaman status publik

Halaman status adalah tampilan untuk pelanggan: menampilkan layanan yang sedang aktif dan riwayat terbarunya tanpa mengekspos dashboard Anda. Buka Status Pages lalu New Status Page, berikan nama dan slug (jalur publik, seperti /status/main), masukkan monitor yang diinginkan ke dalam grup seperti "Websites" dan "APIs", tambahkan logo dan deskripsi singkat, lalu klik Save. Anda juga dapat menghubungkan halaman tersebut ke domain sendiri agar status.example.com melayaninya secara langsung.

Dua hal yang perlu diperhatikan: hanya tambahkan monitor yang bersedia Anda publikasikan, karena halaman status menunjukkan keberadaan suatu layanan dan status aktifnya; serta dashboard tetap terlindungi di balik login Anda, sementara halaman status sengaja dibuat publik dan tidak memerlukan autentikasi.

Gunakan reverse proxy dengan TLS, dan perhatikan websockets

Untuk instance publik, gunakan reverse proxy di depan container yang terikat pada loopback untuk TLS dan hostname. Detail yang sering menyebabkan kesalahan: UI Uptime Kuma adalah aplikasi Socket.IO secara langsung, sehingga proxy harus melakukan upgrade pada koneksi WebSocket. Jika tidak, halaman akan dimuat tetapi tidak pernah terhubung; dashboard akan tertahan pada status "Connecting...", pembaruan heartbeat tidak berjalan, dan konsol browser menunjukkan WebSocket connection to 'wss://.../socket.io/...' failed.

Instal nginx dan certbot, lalu buat vhost yang melakukan proxy ke port loopback. Gunakan port 80 untuk saat ini dan biarkan certbot menambahkan TLS setelahnya; tantangan, timer pembaruan, dan kegagalan sistemnya dibahas dalam issuing Let's Encrypt certificates with certbot and nginx.

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

Simpan ini sebagai /etc/nginx/sites-available/status.example.com; dua baris WebSocket adalah bagian yang paling penting:

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

Aktifkan situs, uji konfigurasi, lalu biarkan certbot menulis ulang blok tersebut untuk mendengarkan pada port 443, masukkan sertifikat, dan tambahkan pengalihan HTTP-ke-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

Pasangan Upgrade dan Connection "upgrade" adalah bagian terpenting, dan proxy_read_timeout 3600s mencegah nginx memutus koneksi socket yang berlangsung lama; certbot menyalin keduanya ke dalam blok 443 yang dibuatnya. Jika Anda sudah menjalankan beberapa container di belakang satu proxy, routing them through Traefik with automatic TLS melakukan hal yang sama menggunakan label container dan meneruskan upgrade WebSocket secara default.

Jangan gunakan basic-auth pada seluruh vhost, karena hal itu akan mengunci akses ke halaman status publik dan endpoint /api/push. Tetap gunakan login bawaan Uptime Kuma, tambahkan fail2ban watching for repeated failed logins jika terhubung ke internet, dan jika dashboard tidak perlu bersifat publik, jangan gunakan proxy dan akseslah melalui VPN.

Pemantauan masa berlaku sertifikat yang tepat

Monitor HTTP(s) dapat memberikan peringatan sebelum sertifikat TLS kedaluwarsa: centang Certificate Expiry Notification dan Uptime Kuma akan memberikan peringatan dalam jumlah hari yang telah ditentukan. Dua kesalahan menyebabkan kesalahan pembacaan. Lakukan pemantauan berdasarkan hostname, bukan IP, karena permintaan tanpa SNI akan mendapatkan sertifikat default server dan Anda akan melihat Hostname/IP does not match certificate's altnames. Selain itu, jangan centang Ignore TLS/SSL Error pada monitor yang ingin Anda pantau masa berlaku sertifikatnya: opsi tersebut digunakan untuk host internal dengan sertifikat self-signed (unable to verify the first certificate, DEPTH_ZERO_SELF_SIGNED_CERT), namun opsi tersebut akan menghentikan Uptime Kuma untuk memeriksa sertifikat sama sekali, termasuk pemeriksaan masa berlaku.

Backups: ini adalah satu direktori

Karena semua data tersimpan di /app/data, cadangan adalah salinan volume tersebut yang diambil saat kontainer sedang berhenti, sehingga file SQLite tetap konsisten:

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

Pastikan nama asli volume dengan docker volume ls | grep kuma terlebih dahulu, karena Compose menambahkan awalan nama direktori proyek. Kemudian salin file tarball ke luar server, karena cadangan di VPS yang sama hanyalah salinan, bukan cadangan yang aman. Proses pemulihan adalah kebalikannya: hentikan stack, ekstrak ke dalam volume /app/data yang kosong, lalu jalankan kembali.

Upgrades

Pembaruan dilakukan dengan menarik image:

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

Kontainer baru akan menjalankan migrasi database saat pertama kali dijalankan; pantau docker compose logs -f. Lakukan pencadangan di atas sebelum melakukan pull, dan tetaplah menggunakan tag versi mayor yang sama: perpindahan dari :1 ke :2 adalah migrasi satu arah, jadi lakukan pencadangan terlebih dahulu dan periksa catatan rilis.

Mode kegagalan, beserta string yang akan Anda lihat

Status "down" palsu pada monitor yang diarahkan ke localhost. Monitor berubah merah dengan timeout of 48000ms exceeded atau connect ETIMEDOUT, padahal layanan merespons dari laptop Anda. Jika monitor diarahkan ke host yang sama dengan tempat Uptime Kuma berjalan, lonjakan CPU atau memori menyebabkan pengecekan gagal, bukan targetnya. Pindahkan monitor ke VPS terpisah dan arahkan ke hostname publik.

connect ECONNREFUSED 127.0.0.1:443 (atau port apa pun). Tidak ada layanan yang mendengarkan pada port tersebut: layanan sedang mati, atau Anda memantau localhost dari dalam kontainer, di mana 127.0.0.1 adalah kontainer, bukan server Anda. Pantau hostname publik, bukan loopback.

Invalid login: 535-5.7.8 Username and Password not accepted pada tes email. Kredensial SMTP salah, atau penyedia layanan memerlukan kata sandi khusus aplikasi tetapi Anda menggunakan kata sandi akun. Buat kata sandi aplikasi dan tempelkan di sana.

connect ETIMEDOUT atau queryA ETIMEDOUT <host> pada tes email. Port salah, atau penyedia layanan memblokir SMTP keluar. Pastikan 465 atau 587 sesuai dengan pengaturan Secure/STARTTLS, dan lakukan pengujian dari host menggunakan nc -vz smtp.example.com 587. Banyak penyedia memblokir 25 keluar dan beberapa memblokir port submission hingga Anda mengajukan permintaan.

self signed certificate atau unable to verify the first certificate pada tes email. Server SMTP Anda menyajikan sertifikat yang tidak dipercaya oleh Node; perbaiki sertifikat mail server alih-alih mengabaikannya.

Dashboard tertahan pada "Connecting...", konsol menunjukkan WebSocket connection ... failed. Reverse proxy tidak melakukan upgrade WebSocket. Tambahkan header Upgrade dan Connection "upgrade" pada nginx, atau gunakan proxy yang meneruskan header tersebut secara default seperti Traefik atau Caddy. HTML berhasil dimuat karena itu adalah HTTP GET normal; hanya socket live yang membutuhkan upgrade.

Monitor kedaluwarsa sertifikat tidak pernah memberi peringatan, atau memberi peringatan yang salah. Opsi Ignore TLS/SSL Error tercentang, yang menonaktifkan pemeriksaan sertifikat, atau monitor diarahkan ke IP dan membaca sertifikat yang salah karena SNI hilang, sehingga menampilkan Hostname/IP does not match certificate's altnames. Hapus centang pada opsi ignore, pantau menggunakan hostname.

SQLITE_BUSY atau database disk image is malformed di dalam log. Volume /app/data berada pada filesystem tanpa penguncian file yang tepat, biasanya NFS; pindahkan ke volume Docker lokal dan pulihkan dari cadangan.

FAQ

Di mana saya harus menjalankan uptime monitor saya?

Jalankan pada server yang berbeda dari server yang dipantau. Idealnya gunakan penyedia atau wilayah lain, yang mengakses server target melalui hostname via internet publik seperti pengguna Anda. Jika monitor berada pada server yang sama dengan target, kegagalan server akan mematikan monitor juga. Selain itu, host yang kelebihan beban dapat memicu status "down" pada layanan yang sebenarnya normal. Menggunakan VPS terpisah yang kecil dapat menghindari kedua masalah tersebut.

Bagaimana cara mendapatkan peringatan di Telegram atau email?

Tambahkan saluran di bawah Settings then Notifications, lalu hubungkan ke setiap monitor. Untuk Telegram, buat bot dengan @BotFather dan baca chat.id dari https://api.telegram.org/bot<token>/getUpdates; untuk email, gunakan 465 untuk SSL atau 587 untuk STARTTLS dengan app password jika penyedia Anda menggunakan autentikasi dua faktor. Tekan Test dan pastikan pesan terkirim sebelum Anda mengandalkannya.

Bisakah Uptime Kuma memantau cron job atau skrip backup?

Bisa, gunakan monitor Push: Uptime Kuma memberikan sebuah URL dan Anda dapat melakukan curl pada akhir skrip agar peringatan hanya muncul jika berhasil. Jika tugas gagal atau server mati, heartbeat tidak akan terkirim, dan Anda akan menerima peringatan setelah interval berakhir. Ini adalah satu-satunya cara andal untuk mengetahui apakah tugas terjadwal benar-benar berjalan, karena pemeriksaan eksternal tidak dapat melihat ke dalam proses tersebut.

Uptime Kuma vs Zabbix, mana yang harus saya jalankan?

Uptime Kuma menjawab pertanyaan "apakah layanan aktif dari sisi eksternal, dan apakah peringatan terkirim" dalam sepuluh menit dengan penggunaan sumber daya yang sangat minim, ditambah dengan halaman status. Uptime Kuma tidak mengumpulkan metrik mendalam seperti tren CPU, memori, dan disk atau ambang batas seluruh armada; untuk kebutuhan tersebut, server monitoring Zabbix lengkap adalah alat berbasis agent yang lebih berat, dan banyak orang menjalankan keduanya. Masih bingung memilih apa yang harus dijalankan? rangkuman kami tentang apa yang harus di-self-host pada 2026 memberikan konteks mengenai pemantauan.