Uptime Kuma z alertami na Telegramie — heartbeat z homelabu

Masz serwer w Oracle Cloud z Dockerem i rekordem status.prywatnylab.pl wskazującym na jego adres. Teraz uruchomisz na nim Uptime Kumę — self-hosted monitoring z czytelnym panelem — i połączysz ją z Telegramem, żeby każda awaria domowego labu trafiała na Twój telefon w ciągu kilku minut.

Uptime Kuma w docker compose z Caddy

Caddy pełni rolę reverse proxy: sam pobiera i odnawia certyfikat Let’s Encrypt i przekierowuje HTTP na HTTPS. Kuma nie publikuje żadnego portu — jest dostępna wyłącznie przez Caddy.

services:
  uptime-kuma:
    image: louislam/uptime-kuma:2
    container_name: uptime-kuma
    restart: unless-stopped
    volumes:
      - ./kuma-data:/app/data
    networks:
      - web

  caddy:
    image: caddy:2
    container_name: caddy
    restart: unless-stopped
    ports:
      - '80:80'
      - '443:443'
      - '443:443/udp'
    environment:
      KUMA_DOMAIN: ${KUMA_DOMAIN}
    volumes:
      - ./Caddyfile:/etc/caddy/Caddyfile:ro
      - caddy-data:/data
      - caddy-config:/config
    networks:
      - web

networks:
  web:

volumes:
  caddy-data:
  caddy-config:

{$KUMA_DOMAIN} {
  encode zstd gzip
  reverse_proxy uptime-kuma:3001
}

KUMA_DOMAIN=status.prywatnylab.pl

sudo mkdir -p /opt/monitoring && sudo chown ubuntu:ubuntu /opt/monitoring
cd /opt/monitoring
# (utwórz trzy pliki powyżej)
docker compose up -d
docker compose logs -f caddy

W logach Caddy szukaj linii certificate obtained successfully. Jeśli widzisz błędy wyzwania ACME, sprawdź obie warstwy firewalla z poprzedniej części oraz to, czy rekord DNS nie jest przepuszczany przez proxy Cloudflare.

Po zalogowaniu włącz w Settings → Security uwierzytelnianie dwuskładnikowe (2FA).

Bot Telegrama

Telegram udostępnia darmowe API dla botów. Twój bot będzie jedynie wysyłał wiadomości do Ciebie.

1. W Telegramie otwórz rozmowę z @BotFather i wyślij /newbot.
2. Podaj nazwę wyświetlaną (np. PrywatnyLab Monitor) i unikalną nazwę użytkownika kończącą się na bot (np. prywatnylab_monitor_bot).
3. BotFather odpowie tokenem w formacie 123456789:AA…. To hasło do bota — nie publikuj go.
4. Otwórz rozmowę ze swoim botem i wyślij mu dowolną wiadomość (np. /start). Bez tego bot nie może napisać do Ciebie jako pierwszy.

Teraz odczytaj identyfikator czatu i wyślij testową wiadomość przez API. Na maszynie OCI:

sudo apt install -y jq
read -rsp 'Token bota: ' TG_TOKEN; echo

# Identyfikator czatu z ostatniej wiadomości wysłanej do bota
TG_CHAT_ID=$(curl -s "https://api.telegram.org/bot${TG_TOKEN}/getUpdates" | jq -r '.result[-1].message.chat.id')
echo "Chat ID: ${TG_CHAT_ID}"

curl -s -X POST "https://api.telegram.org/bot${TG_TOKEN}/sendMessage" \
  -d chat_id="${TG_CHAT_ID}" \
  -d text="✅ Test z Oracle Cloud: bot działa" | jq '.ok'

Jeśli Chat ID wychodzi null, wyślij botowi jeszcze jedną wiadomość i powtórz polecenie. Wynik true i wiadomość na telefonie oznaczają, że wszystko działa.

Powiadomienia Telegram w Uptime Kuma

Settings → Notifications → Setup Notification:

Kliknij Test — na telefonie powinna pojawić się wiadomość od Kumy.

Monitor 1: heartbeat z domu

Add New Monitor:

Po zapisaniu Kuma wyświetli Push URL w postaci https://status.prywatnylab.pl/api/push/Xk3…?status=up&msg=OK&ping=. Skopiuj go.

Heartbeat będzie wysyłany z hosta Proxmox. Jeśli on działa, działa prąd, łącze i sam serwer. Na hoście Proxmox:

# Push URL z Uptime Kumy (w cudzysłowie — zawiera znaki & i ?)
KUMA_PUSH_URL="https://status.prywatnylab.pl/api/push/Xk3pQ9vL2m?status=up&msg=OK&ping="

[Unit]
Description=Heartbeat homelabu do Uptime Kuma (Oracle Cloud)
Wants=network-online.target
After=network-online.target

[Service]
Type=oneshot
EnvironmentFile=/etc/kuma-heartbeat.env
ExecStart=/usr/bin/curl --fail --silent --show-error --max-time 10 --retry 2 --output /dev/null ${KUMA_PUSH_URL}
# Proces nie potrzebuje żadnych uprawnień
DynamicUser=yes
ProtectSystem=strict
ProtectHome=yes
PrivateTmp=yes
NoNewPrivileges=yes

[Unit]
Description=Heartbeat do Uptime Kuma co 60 sekund

[Timer]
OnBootSec=1min
OnUnitActiveSec=60s
AccuracySec=5s

[Install]
WantedBy=timers.target

chmod 600 /etc/kuma-heartbeat.env
systemctl daemon-reload
systemctl enable --now kuma-heartbeat.timer

# Sprawdzenie: ostatnie wywołania i ich wynik
systemctl list-timers kuma-heartbeat.timer
journalctl -u kuma-heartbeat.service -n 5 --no-pager

Zapis ${KUMA_PUSH_URL} w ExecStart systemd zastępuje wartością zmiennej jako jeden argument, bez udziału powłoki. Znaki & i ? w adresie nie wymagają więc dodatkowego cytowania.

W panelu Kumy monitor powinien zmienić się na zielony w ciągu minuty.

Monitor 2: usługi przez Cloudflare Tunnel

Heartbeat nie wykryje sytuacji, w której dom działa, ale tunel albo aplikacja nie. Dodaj monitor HTTP dla każdej publicznej usługi:

Endpoint /alive Vaultwardena zwraca kod 200, gdy aplikacja i baza działają. To lepszy wskaźnik niż strona główna, która może się wyświetlić z cache Cloudflare. Opcja Certificate Expiry Notification ostrzeże Cię przed wygaśnięciem certyfikatu — domyślnie 21, 14 i 7 dni wcześniej.

Monitor strony z wyłączonym proxy (np. samego https://status.prywatnylab.pl) warto dodać z drugiej, domowej instancji Kumy — tak działa opisany w przewodniku monitoring odwrotny.

Test awarii

Nie ufaj alertom, dopóki nie zobaczysz ich w akcji. Zasymuluj awarię:

systemctl stop kuma-heartbeat.timer
# Odczekaj ~3 minuty: 60 s interwału + 2 powtórzenia po 60 s

Na telefonie powinien pojawić się alert 🔴 Down dla monitora Dom — łącze i zasilanie. Przywróć:

systemctl start kuma-heartbeat.timer

Po minucie przyjdzie ✅ Up. Jeśli oba komunikaty dotarły, monitoring działa od początku do końca.

Okna serwisowe

Planujesz aktualizację Proxmoxa z restartem? W Kumie Maintenance → Schedule Maintenance wybierz monitory, których dotyczy przerwa, i ustaw czas. W tym oknie Kuma nie wyśle alertów, a na stronie statusu pokaże informację o pracach.

Kopia zapasowa

Cała konfiguracja Kumy — monitory, historia i ustawienia powiadomień — leży w katalogu kuma-data. Kopia na wypadek utraty maszyny:

ssh ubuntu@status.prywatnylab.pl 'cd /opt/monitoring && docker compose stop uptime-kuma >&2 && tar czf - kuma-data Caddyfile compose.yaml; docker compose start uptime-kuma >&2' \
  > "kuma-backup-$(date +%F).tar.gz"

Zatrzymanie kontenera na kilka sekund gwarantuje spójną kopię bazy SQLite, a przekierowanie >&2 pilnuje, żeby komunikaty Dockera nie trafiły do archiwum.

Podsumowanie

Masz teraz monitoring, który:

• działa niezależnie od domowego prądu, łącza i routera,
• wykrywa awarię całego domu (heartbeat) i pojedynczych usług (HTTP),
• pilnuje ważności certyfikatów,
• powiadamia na telefon w ciągu około 3 minut i informuje o powrocie usług,
• nic nie kosztuje.

Kolejny krok to monitoring odwrotny i uzupełnienie Kumy o metryki z wnętrza labu — ale to już temat na osobną serię.