Uptime Kuma Docker में कैसे setup करें

आप क्या बना रहे हैं

एक छोटा container जो आपके अन्य servers और websites को बाहर से monitor करता है। जैसे ही कोई service respond करना बंद करती है, यह आपको email, Telegram, Discord या webhook के माध्यम से सूचित करता है। Uptime Kuma एक Node process है जो SQLite file का उपयोग करता है। यह 256-512 MB RAM में आसानी से चल सकता है। यह आपको live dashboard, history graphs और एक public status page प्रदान करता है। इसका installation एक ten-line Compose file है। सबसे महत्वपूर्ण बात यह है कि आप इसे कहाँ run करते हैं और क्या आपने test के दौरान alerts प्राप्त किए हैं। यदि आपने यह prove नहीं किया है कि monitor आपको सूचना भेज सकता है, तो वह monitor बेकार है। यह आपको सुरक्षा का भ्रम देता है जबकि वह वास्तव में कुछ भी monitor नहीं कर रहा होता है।

Monitor को ऐसी जगह चलाएं जहाँ outage का उस तक पहुँचना संभव न हो

यह एक निर्णय पूरे सिस्टम की सफलता तय करता है, इसलिए इसे सबसे पहले करें। Uptime Kuma को उसी machine पर न चलाएं जिसे यह monitor कर रहा है। यदि monitor उसी server पर है जिसे वह monitor कर रहा है, तो वही घटना (जैसे server का बंद होना या memory खत्म होना) monitor को भी खत्म कर देगी। ऐसी स्थिति में आपको कोई alert नहीं मिलेगा: एक dead monitor की चुप्पी "सब कुछ ठीक है" के समान ही होती है। एक सूक्ष्म समस्या तब भी हो सकती है जब server चालू हो: localhost पर केंद्रित monitor workload के साथ CPU साझा करता है। इसलिए, load बढ़ने पर monitor का अपना check timeout हो सकता है और target को down दिखा सकता है। यह एक false alarm होगा, जबकि वास्तविक users को सेवाएँ सही मिल रही होंगी।

इसलिए Uptime Kuma को उस VPS से अलग चलाएं जिसे वह monitor कर रहा है। आदर्श रूप से, यह एक अलग provider या region होना चाहिए, जो आपके services तक वैसे ही पहुँचे जैसे आपके users पहुँचते हैं: public internet के माध्यम से, hostname द्वारा। एक सस्ता instance पर्याप्त है, और एक छोटा monitoring VPS आपके सभी servers को monitor कर सकता है। यदि Kuma स्वयं बंद हो जाए, तो उसे पकड़ने के लिए कहीं और से cron के माध्यम से push heartbeat का उपयोग करें।

Prerequisites and sizing

• Ek naya Ubuntu 24.04 VPS jisme Docker Engine aur Compose v2 plugin installed ho. Ise Docker ke apne apt repository se install karein, docker.io distro package se nahi, kyunki woh purana hota hai.
• 256 MB RAM se kuch hi monitors chalenge; dozens monitors aur reverse proxy ke liye 512 MB se 1 GB RAM behtar hai. Checks ke beech mein CPU idle rehta hai.
• Ek domain aur DNS A record (jaise status.example.com jo VPS ko point kare), sirf tab agar aapko TLS aur public status page chahiye. Private instance ke liye DNS ki zaroorat nahi hai; aap VPN ya SSH tunnel ka upyog kar sakte hain.
• Alerts bhejne ke liye outbound network: SMTP aapke mail provider ke liye, ya Telegram aur Discord ke liye HTTPS.

Compose file

इसे /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:

इसे शुरू करें और पहली बार 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

सही तरीके से शुरू होने पर Listening on 3001 log बनता है और प्रक्रिया शांत हो जाती है। उस file में तीन चीजें जानबूझकर की गई हैं।

127.0.0.1:3001:3001, 3001:3001 नहीं। Docker ports को DNAT rules के साथ publish करता है जो ufw द्वारा packet देखे जाने से पहले evaluate होते हैं। इसलिए, बिना किसी configuration के 3001:3001 करने पर आपका dashboard firewall के बावजूद public internet पर उपलब्ध हो जाता है। Loopback पर bind करने से यह private रहता है, और केवल reverse proxy ही exposed रहता है; एक private instance proxy को छोड़कर self-hosted WireGuard VPN के माध्यम से 3001 तक पहुँच सकता है।

/app/data पर एक named volume। Uptime Kuma की सभी यादें—SQLite database, आपके monitors, notification settings और status-page logos—वहीं रहते हैं। यदि यह खो जाता है, तो आपको एक खाली admin screen से शुरुआत करनी होगी; यह एकमात्र चीज़ है जिसका आपको backup लेना चाहिए।

Image को एक major tag, :2, पर pin किया गया है। यह वर्तमान stable line है; कॉपी करने से पहले Docker Hub पर नवीनतम major version चेक करें। कभी भी latest जैसे moving tag का उपयोग न करें, क्योंकि project इसे deprecate करता है। इस image पर major-version jump एक one-way database migration है जिसे आपको जानबूझकर trigger करना चाहिए, न कि routine pull के दौरान गलती से होने देना चाहिए।

एक चेतावनी: /app/data को ऐसे filesystem पर होना चाहिए जिसमें POSIX file locks हों। Local Docker volume सही है; NFS पर SQLite database corrupt हो जाता है जिससे SQLITE_BUSY और database disk image is malformed की समस्या आती है, इसलिए कभी भी network share का उपयोग न करें।

पहली बार चलाना: admin account बनाएँ

https://status.example.com पर अपने proxy के माध्यम से, या SSH tunnel के ज़रिए instance पर जाएँ: ssh -L 3001:127.0.0.1:3001 user@your-vps चलाएँ और http://localhost:3001 खोलें। पहला पेज administrator username और password के लिए setup form है; कोई default login नहीं है। एक असली password चुनें: यह dashboard आपके द्वारा monitor किए जाने वाले सभी चीज़ों के internal addresses और tokens देख सकता है। क्या बाद में भूल गए? Browser के बजाय host से reset करें:

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

पहले अपने notification channels जोड़ें, और उनका परीक्षण करें

Monitors जोड़ने से पहले alerts सेटअप करें, ताकि आप प्रत्येक monitor बनाते समय एक channel जोड़ सकें। Settings then Notifications then Setup Notification पर जाएँ, और प्रत्येक channel के Test button का उपयोग करके पुष्टि करें कि message प्राप्त हो रहा है। बिना परीक्षण वाला notification setup के चुपचाप विफल होने का दूसरा सबसे बड़ा कारण है।

Email (SMTP). host, port, encryption, username, password, From और To भरें। दो सही combinations 465 (जहाँ "Secure" TLS/SSL पर सेट हो) और 587 (STARTTLS के साथ) हैं। Gmail और two-factor auth वाले अधिकांश providers के लिए आपको एक app password जनरेट करना होगा; सामान्य account password Error: Invalid login: 535-5.7.8 Username and Password not accepted लौटाता है।

Telegram. @BotFather को message करें, /newbot भेजें, और bot token कॉपी करें। अपने chat ID के लिए, नए bot को एक बार message करें, https://api.telegram.org/bot<token>/getUpdates खोलें, और JSON से chat.id पढ़ें। जिस bot को आपने पहले message नहीं किया है, उसका getUpdates खाली होता है और उसके पास भेजने के लिए कोई स्थान नहीं होता।

Discord. channel में, Edit Channel then Integrations then Webhooks then New Webhook खोलें, URL कॉपी करें, और इसे Discord notification के रूप में paste करें।

Generic webhook. अन्य किसी भी चीज़ के लिए, जैसे Slack incoming webhook, custom endpoint, या home-automation hook; Webhook type आपके द्वारा दिए गए URL पर एक JSON payload POST करता है। इसमें शामिल Apprise integration सूची में दिए गए नब्बे के करीब अन्य services को कवर करता है।

एक बार में एक प्रकार के मॉनिटर जोड़ें

Add New Monitor पर क्लिक करें, एक प्रकार चुनें, और Friendly Name, Check Interval (60 seconds एक उचित विकल्प है), Retries ( "down" घोषित करने से पहले लगातार होने वाली विफलताओं की संख्या; 2 या 3 रखें ताकि एक पैकेट ड्रॉप होने पर अलर्ट न मिले), और नोटिफिकेशन सेट करें। आप इन प्रकारों का उपयोग करेंगे:

• HTTP(s). एक पूरा URL। "Up" का अर्थ है एक स्वीकार्य status code (डिफ़ॉल्ट रूप से 200-299; यदि 301 या 401 आपके लिए सामान्य है, तो Accepted Status Codes के अंतर्गत इसे बदलें)। यह वेबसाइटों और APIs के लिए मुख्य टूल है।
• HTTP(s) - Keyword. वही अनुरोध, लेकिन "up" होने के लिए body में एक विशिष्ट string का होना आवश्यक है, बशर्ते Invert विकल्प अनचेक हो। यह तब काम आता है जब साइट 200 OK रिटर्न करती है और "Error establishing a database connection" प्रदर्शित करती है, जिसे एक साधारण HTTP चेक 'healthy' मान लेता है।
• TCP Port. किसी host और port के लिए एक सीधा TCP connection, उन चीज़ों के लिए जो HTTP नहीं हैं: 22 पर SSH, 5432 पर Postgres, 25 पर SMTP server, या एक game server।
• Ping. ICMP echo: reachability और latency की जांच के लिए सरल तरीका। लेकिन कई networks और cloud firewalls ICMP को drop कर देते हैं, इसलिए एक red ping monitor का अर्थ "host down" या "provider blocks ping" हो सकता है; इसकी पुष्टि TCP monitor से करें।
• DNS. आपके द्वारा नामित resolver के विरुद्ध एक record (A, AAAA, MX, TXT आदि) को resolve करता है। यह registrar या DNS outage का जल्दी पता लगाने में मदद करता है।
• Push. "Inside-out" मॉनिटर, जिसके बारे में आगे बताया गया है।

Push (heartbeat) monitor के साथ cron job को monitor करना

ऊपर दिए गए सभी monitors आपके service के बाहर से उसे check करते हैं। Push monitor इसके विपरीत काम करता है: Uptime Kuma इंतज़ार करता है, और आपका job उसे यह बताने के लिए call करता है कि "मैं चल गया हूँ।" Backup या cron को watch करने का यह एकमात्र सही तरीका है: HTTP check को केवल यह पता चलता है कि URL respond कर रहा है, लेकिन केवल job को ही पता होता है कि वह पूरा हो गया है।

Push type का monitor बनाएँ। Uptime Kuma एक unique URL generate करेगा, जैसे:

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

Heartbeat Interval को job के चलने के समय के अनुसार सेट करें, और उसमें थोड़ा extra समय (slack) जोड़ें। फिर script के अंत में एक line जोड़ें, ताकि यह केवल success होने पर ही fire हो:

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

यदि job fail होता है, तो curl से पहले set -e abort हो जाता है; यदि server down है, तो यह कभी run भी नहीं होगा। दोनों ही स्थितियों में heartbeat रुक जाएगी, और जैसे ही interval-plus-retries window समाप्त होगी, Uptime Kuma monitor को down कर देगा और आपको alert भेजेगा। इस push token को एक secret की तरह रखें: जिसके पास भी यह होगा, वह fake healthy beat भेज सकता है।

एक public status page बनाएँ

Status page ग्राहकों के लिए एक view है: यह आपके dashboard को दिखाए बिना बताता है कि कौन सी services चल रही हैं और उनका recent history क्या है। Status Pages पर जाएँ और फिर New Status Page चुनें। इसे एक name और slug (public path, जैसे /status/main) दें। जिन monitors को आप दिखाना चाहते हैं, उन्हें "Websites" और "APIs" जैसे groups में drag करें। एक logo और short description जोड़ें, और फिर Save करें। आप इस page को अपने स्वयं के domain से भी bind कर सकते हैं ताकि status.example.com इसे directly serve कर सके।

दो सावधानियाँ: केवल उन्हीं monitors को जोड़ें जिन्हें आप public करना चाहते हैं, क्योंकि status page यह reveal करता है कि कोई service मौजूद है और क्या वह up है; और dashboard आपके login के पीछे सुरक्षित रहता है, जबकि status page जानबूझकर public रखा जाता है और इसे auth की आवश्यकता नहीं होती है।

इसे TLS के साथ reverse proxy के पीछे रखें, और websockets का ध्यान रखें

Public instance के लिए, TLS और hostname प्राप्त करने हेतु loopback-bound container के आगे एक reverse proxy लगाएँ। एक महत्वपूर्ण विवरण जो समस्या पैदा करता है: Uptime Kuma का UI एक live Socket.IO app है, इसलिए proxy को WebSocket connection को upgrade करना होगा। यदि आप ऐसा नहीं करते हैं, तो page लोड तो होगा लेकिन connect नहीं होगा; dashboard "Connecting..." पर अटका रहेगा, live heartbeats update नहीं होंगे, और browser console में WebSocket connection to 'wss://.../socket.io/...' failed दिखाई देगा।

nginx और certbot install करें, फिर loopback port पर proxy करने वाला vhost लिखें। अभी इसे port 80 पर रखें और बाद में TLS जोड़ने के लिए certbot का उपयोग करें; इसके बारे में विस्तार से issuing Let's Encrypt certificates with certbot and nginx में बताया गया है।

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

इसे /etc/nginx/sites-available/status.example.com के रूप में save करें; दो WebSocket lines सबसे महत्वपूर्ण हैं:

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

Site को enable करें, config को test करें, फिर certbot को 443 पर listen करने के लिए block rewrite करने दें, certificate डालें और 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

Upgrade और Connection "upgrade" का pair सबसे महत्वपूर्ण है, और proxy_read_timeout 3600s nginx को long-lived socket को बंद करने से रोकता है; certbot इन दोनों को generate किए गए 443 block में copy कर देता है। यदि आप पहले से ही एक proxy के पीछे कई containers चला रहे हैं, तो routing them through Traefik with automatic TLS container labels के साथ यही काम करता है और default रूप से WebSocket upgrades को forward करता है।

पूरे vhost पर basic-auth न लगाएँ, क्योंकि इससे public status page और /api/push endpoint भी block हो जाएगा। Uptime Kuma का built-in login ही रहने दें, यदि यह internet-facing है तो fail2ban watching for repeated failed logins जोड़ें, और यदि dashboard को public करने की आवश्यकता नहीं है, तो proxy हटा दें और VPN के माध्यम से इसे एक्सेस करें।

Certificate-expiry monitoring का सही तरीका

HTTP(s) monitor आपको TLS certificate के समाप्त होने से पहले चेतावनी दे सकता है: Certificate Expiry Notification को टिक करें और Uptime Kuma निर्धारित दिनों पहले अलर्ट भेज देगा। दो गलतियों के कारण यह गलत परिणाम दे सकता है। हमेशा hostname से monitor करें, IP से नहीं, अन्यथा बिना SNI वाले request को server का default certificate प्राप्त होगा और आपको Hostname/IP does not match certificate's altnames दिखाई देगा। साथ ही, जिस monitor के लिए आपको expiry warnings चाहिए, उस पर Ignore TLS/SSL Error को टिक न करें: यह toggle self-signed internal hosts (unable to verify the first certificate, DEPTH_ZERO_SELF_SIGNED_CERT) के लिए है, लेकिन यह Uptime Kuma को certificate की जांच करने से पूरी तरह रोक देता है, जिसमें expiry की जांच भी शामिल है।

Backups: यह एक directory है

चूंकि सब कुछ /app/data में रहता है, इसलिए backup उस volume की एक copy है जिसे container के stopped होने पर लिया जाता है। इससे SQLite file consistent रहती है:

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

सबसे पहले docker volume ls | grep kuma से volume का real name confirm करें, क्योंकि Compose इसके आगे project directory का prefix लगा देता है। इसके बाद tarball को server से बाहर copy करें, क्योंकि उसी VPS पर backup रखना केवल एक copy रखना है, backup नहीं। Restore करने की प्रक्रिया इसके विपरीत है: stack को stop करें, उसे एक खाली /app/data volume में extract करें, और फिर start करें।

Upgrades

Upgrades का अर्थ image pull करना है:

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

नया container पहली बार start होने पर सभी database migration चलाता है; docker compose logs -f पर नज़र रखें। Image pull करने से पहले ऊपर दिया गया backup लें, और major tag के भीतर ही रहें: :1 से :2 पर जाना एक one-way migration है, इसलिए पहले backup लें और release notes चेक करें।

Failure modes, with the strings you will see

localhost पर पॉइंट किए गए monitor पर False "down" दिखना। monitor timeout of 48000ms exceeded या connect ETIMEDOUT के साथ लाल हो जाता है, फिर भी service आपके laptop से जवाब देती है। यदि monitor उसी host को target कर रहा है जिस पर Uptime Kuma चल रहा है, तो target के बजाय CPU या memory spike के कारण check विफल हुआ है। monitor को एक अलग VPS पर ले जाएँ और public hostname को target करें।

connect ECONNREFUSED 127.0.0.1:443 (या कोई भी port)। उस port पर कुछ भी listen नहीं कर रहा था: या तो service down है, या आपने container के अंदर से localhost को monitor किया है, जहाँ 127.0.0.1 आपका container है, न कि आपका server। loopback के बजाय public hostname को monitor करें।

Email test पर Invalid login: 535-5.7.8 Username and Password not accepted। SMTP credentials गलत हैं, या provider को app-specific password चाहिए और आपने अपने account password का उपयोग किया है। एक app password generate करें और उसे paste करें।

Email test पर connect ETIMEDOUT या queryA ETIMEDOUT <host>। गलत port, या provider outbound SMTP को block कर रहा है। Confirm करें कि 465 या 587 Secure/STARTTLS setting से मेल खाता है, और host से nc -vz smtp.example.com 587 के साथ test करें। कई providers outbound 25 को block करते हैं और कुछ submission ports को तब तक block रखते हैं जब तक आप request न करें।

Email test पर self signed certificate या unable to verify the first certificate। आपका SMTP server ऐसा certificate पेश करता है जिसे Node trust नहीं करेगा; certificate की समस्या को छिपाने के बजाय mail server के certificate को ठीक करें।

Dashboard "Connecting..." पर अटक गया है, console में WebSocket connection ... failed दिख रहा है। reverse proxy WebSocket को upgrade नहीं कर रहा है। nginx पर Upgrade और Connection "upgrade" headers जोड़ें, या Traefik या Caddy जैसा proxy उपयोग करें जो उन्हें default रूप से forward करता है। HTML load हो जाता है क्योंकि वह एक normal HTTP GET है; केवल live socket को upgrade की आवश्यकता होती है।

Cert-expiry monitor कभी चेतावनी नहीं देता, या गलत चेतावनी देता है। या तो Ignore TLS/SSL Error पर tick लगा है, जो cert checking को disable कर देता है, या monitor एक IP को target कर रहा है और missing SNI के कारण गलत certificate पढ़ रहा है, जिससे Hostname/IP does not match certificate's altnames दिख रहा है। ignore को untick करें, hostname द्वारा monitor करें।

Logs में SQLITE_BUSY या database disk image is malformed। /app/data volume ऐसे filesystem पर है जिसमें proper file locking नहीं है, आमतौर पर NFS; इसे local Docker volume पर ले जाएँ और backup से restore करें।

FAQ

मुझे अपना uptime monitor कहाँ चलाना चाहिए?

इसे उन servers से अलग server पर चलाएँ जिनकी आप निगरानी कर रहे हैं। आदर्श रूप से, इसे किसी अन्य provider या region में रखें। इसे public internet पर hostname के माध्यम से उसी तरह एक्सेस करें जैसे आपके users करते हैं। यदि monitor और target एक ही box साझा करते हैं, तो server डाउन होने पर monitor भी डाउन हो जाएगा। इसके अलावा, overloaded host के कारण सही services के लिए भी "down" alert आ सकता है। एक छोटा और अलग VPS इन दोनों समस्याओं से बचाता है।

मुझे Telegram या email पर alerts कैसे मिलेंगे?

Settings then Notifications के अंतर्गत channel जोड़ें, फिर इसे प्रत्येक monitor से जोड़ें। Telegram के लिए, @BotFather का उपयोग करके एक bot बनाएँ और https://api.telegram.org/bot<token>/getUpdates से chat.id प्राप्त करें; email के लिए, SSL हेतु 465 या STARTTLS हेतु 587 का उपयोग करें (यदि आपका provider two-factor auth का उपयोग करता है, तो app password का उपयोग करें)। Test बटन दबाएँ और सुनिश्चित करें कि message प्राप्त हो रहा है।

क्या Uptime Kuma किसी cron job या backup script की निगरानी कर सकता है?

हाँ, इसके लिए Push monitor का उपयोग करें: Uptime Kuma आपको एक URL देता है और आप script के अंत में curl करते हैं ताकि यह केवल success होने पर ही trigger हो। यदि job fail होता है या server down होता है, तो heartbeat प्राप्त नहीं होता है, और interval समाप्त होने के बाद आपको alert मिल जाता है। यह यह जानने का एकमात्र विश्वसनीय तरीका है कि scheduled job वास्तव में चला है, क्योंकि external check इसके अंदर की स्थिति नहीं देख सकता।

Uptime Kuma vs Zabbix, मुझे कौन सा चलाना चाहिए?

Uptime Kuma लगभग बिना किसी resource के दस मिनट में यह बताता है कि "क्या service बाहर से उपलब्ध है और क्या इसने alert भेजा", साथ ही यह एक status page भी देता है। यह CPU, memory और disk trends जैसे deep metrics या fleet-wide thresholds को collect नहीं करता है; इसके लिए a full Zabbix monitoring server एक भारी, agent-based tool है, और कई लोग दोनों का उपयोग करते हैं। अभी भी तय नहीं कर पाए कि क्या चलाना है? our roundup of what to self-host in 2026 आपको सही निर्णय लेने में मदद करेगा।