Instalacja Uptime Kuma w Docker

Cel projektu

Pojedynczy, lekki kontener monitorujący inne serwery i witryny z zewnątrz. System powiadamia o braku odpowiedzi za pomocą wiadomości e-mail, komunikatorów Telegram, Discord lub poprzez webhook. Uptime Kuma to proces Node.js oparty na pliku SQLite. Aplikacja wymaga od 256 do 512 MB pamięci RAM. Zapewnia panel sterowania w czasie rzeczywistym, wykresy historyczne oraz publiczną stronę statusu. Instalacja wymaga jedynie dziesięciolinijnego pliku Compose. Kluczowe znaczenie ma lokalizacja uruchomienia oraz przetestowanie poprawności działania powiadomień. Monitor, którego zdolność do dostarczania alertów nie została zweryfikowana, jest bezużyteczny, ponieważ daje fałszywe poczucie bezpieczeństwa.

Uruchom monitor w miejscu, do którego awaria nie ma dostępu

Ta decyzja determinuje skuteczność całego rozwiązania, dlatego jest kluczowa. Nie należy uruchamiać Uptime Kuma na tym samym serwerze, który jest monitorowany. Jeśli monitor znajduje się na monitorowanym serwerze, to awaria tego serwera (np. brak zasilania lub brak pamięci RAM) uniemożliwi działanie monitora. Brak powiadomienia w takiej sytuacji jest błędnie interpretowany jako stan prawidłowy. Istnieje również inny problem: monitor skierowany na localhost współdzieli zasoby CPU z obciążeniem systemu. Nagły wzrost obciążenia może spowodować przekroczenie czasu odpowiedzi (timeout) i błędne oznaczenie celu jako down, mimo że usługa działa poprawnie dla użytkowników.

Należy uruchomić Uptime Kuma na innym VPS niż monitorowane usługi. Najlepiej wybrać innego dostawcę lub inny region, aby monitor sprawdzał usługi tak, jak robią to użytkownicy: przez publiczny internet, przy użyciu nazwy hosta. Wystarczy tania instancja; jeden mały VPS monitorujący może nadzorować wszystkie serwery. Aby wykryć awarię samego narzędzia Kuma, należy skonfigurować mechanizm push heartbeat za pomocą zadania cron na innym urządzeniu.

Wymagania wstępne i parametry sprzętowe

• Nowy serwer VPS z systemem Ubuntu 24.04, zainstalowany z oficjalnego repozytorium apt Docker (Docker Engine oraz plugin Compose v2). Nie należy używać pakietów z dystrybucji docker.io, ponieważ są one nieaktualne.
• 256 MB RAM wystarcza do obsługi kilku monitorów. 512 MB do 1 GB zapewnia stabilną pracę przy kilkudziesięciu monitorach oraz reverse proxy, przy czym obciążenie CPU pozostaje minimalne między cyklami sprawdzania.
• Domena oraz rekord DNS A (np. status.example.com wskazujący na adres VPS), wyłącznie jeśli wymagane jest TLS oraz publiczna strona statusu. W przypadku instalacji prywatnej można zrezygnować z DNS na rzecz połączenia VPN lub tunelu SSH.
• Dostęp do sieci wychodnej do usług powiadomień: protokół SMTP dla dostawcy poczty lub HTTPS dla usług Telegram i Discord.

Plik Compose

Umieść poniższą zawartość w /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:

Uruchom usługę i obserwuj proces pierwszego uruchomienia:

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

Poprawne uruchomienie generuje logi Listening on 3001 i kończy proces logowania. Trzy elementy w tym pliku są celowe.

127.0.0.1:3001:3001, a nie 3001:3001. Docker publikuje porty za pomocą reguł DNAT, które są sprawdzane przed ufw. Z tego powodu samo 3001:3001 wystawia panel sterowania na publiczny internet, niezależnie od konfiguracji firewalla. Wiązanie do loopback zapewnia prywatność, wystawiając jedynie reverse proxy; prywatna instancja może pominąć proxy i łączyć się z 3001 poprzez własny serwer WireGuard VPN.

Nazwany wolumen w /app/data. Wszystkie dane Uptime Kuma, w tym baza danych SQLite, monitory, ustawienia powiadomień oraz logotypy stron statusu, są przechowywane w tym miejscu. Utrata tych danych skutkuje pustym panelem administracyjnym; jest to jedyny element wymagający kopii zapasowej.

Obraz jest przypisany do głównej wersji :2. Jest to aktualna stabilna linia; przed skopiowaniem sprawdź na Docker Hub najnowszą wersję główną. Nie należy używać tagów typu moving tag, takich jak latest, które są uznawane przez projekt za przestarzałe. Skok wersji głównej w tym obrazie powoduje jednokierunkową migrację bazy danych; należy ją wywołać celowo, a nie przypadkowo podczas rutynowego pobierania obrazu.

Uwaga: /app/data musi znajdować się na systemie plików obsługującym blokady plików POSIX. Lokalny wolumen Docker jest odpowiedni; na systemie NFS baza danych SQLite ulega uszkodzeniu, co powoduje błędy SQLITE_BUSY oraz database disk image is malformed, dlatego nie należy używać udziałów sieciowych.

Pierwsze uruchomienie: utworzenie konta administratora

Należy przejść do instancji za pośrednictwem proxy pod adresem https://status.example.com lub poprzez tunel SSH: należy uruchomić ssh -L 3001:127.0.0.1:3001 user@your-vps i otworzyć http://localhost:3001. Pierwsza strona to formularz konfiguracji nazwy użytkownika oraz hasła administratora; brak domyślnych danych logowania. Należy wybrać silne hasło: panel sterowania ma dostęp do wewnętrznych adresów oraz tokenów wszystkich monitorowanych obiektów. W przypadku utraty hasła: reset należy przeprowadzić na hoście, a nie w przeglądarce:

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

Najpierw dodaj kanały powiadomień, a następnie przetestuj je

Skonfiguruj alerty przed dodawaniem monitorów, aby móc przypisać kanał podczas tworzenia każdego z nich. Przejdź do Settings then Notifications then Setup Notification i użyj przycisku Test dla każdego kanału, aby potwierdzić dotarcie wiadomości. Niesprawdzone powiadomienie jest drugą najczęstszą przyczyną cichych błędów konfiguracji.

Email (SMTP). Wypełnij pola host, port, encryption, username, password oraz pola From i To. Dwie poprawne kombinacje to 465 z ustawieniem "Secure" na TLS/SSL lub 587 z STARTTLS. W przypadku Gmail oraz większości dostawców z uwierzytelnianiem dwuskładnikowym należy wygenerować app password; zwykłe hasło do konta zwraca błąd Error: Invalid login: 535-5.7.8 Username and Password not accepted.

Telegram. Wyślij wiadomość @BotFather, wyślij /newbot i skopiuj bot token. Aby uzyskać chat ID, wyślij wiadomość do nowego bota, otwórz https://api.telegram.org/bot<token>/getUpdates i odczytaj chat.id z pliku JSON. Bot, do którego nigdy nie wysłano pierwszej wiadomości, ma pusty getUpdates i nie posiada celu wysyłki.

Discord. W kanale wybierz Edit Channel then Integrations then Webhooks then New Webhook, skopiuj URL i wklej go jako powiadomienie typu Discord.

Generic webhook. Dla pozostałych usług, takich jak Slack incoming webhook, niestandardowe punkty końcowe (endpoints) czy integracje home-automation, typ Webhook wysyła ładunek JSON metodą POST na podany URL. Zintegrowana biblioteka Apprise obsługuje większość pozostałych dziewięćdziesięciu usług z listy.

Dodawanie monitorów, jeden typ naraz

Należy kliknąć Add New Monitor, wybrać typ oraz ustawić Friendly Name, Check Interval (zalecane 60 sekund), Retries (liczba kolejnych błędów przed uznaniem usługi za "down"; zaleca się 2 lub 3, aby pojedynczy utracony pakiet nie wywoływał powiadomienia) oraz powiadomienia. Dostępne typy:

• HTTP(s). Pełny adres URL. Status "up" oznacza kod odpowiedzi w zakresie 200-299 (domyślnie; można rozszerzyć zakres w sekcji Accepted Status Codes, jeśli 301 lub 401 jest w danym przypadku prawidłowe). Podstawowe narzędzie do sprawdzania witryn internetowych i API.
• HTTP(s) - Keyword. Takie samo zapytanie, lecz status "up" wymaga również obecności określonego ciągu znaków w treści odpowiedzi (chyba że zaznaczono opcję Invert). Pozwala to wykryć błąd, gdy strona zwraca 200 OK, wyświetlając jednocześnie komunikat "Error establishing a database connection", co przy zwykłym sprawdzaniu HTTP zostałoby uznane za status prawidłowy.
• TCP Port. Nawiązanie połączenia TCP z hostem i portem dla usług innych niż HTTP: SSH na porcie 22, Postgres na porcie 5432, serwer SMTP na porcie 25 lub serwer gier.
• Ping. ICMP echo: niskokosztowe sprawdzanie dostępności i opóźnień. Wiele sieci oraz firewalli w chmurze blokuje protokół ICMP, zatem czerwony status monitora ping może oznaczać zarówno "host jest niedostępny", jak i "dostawca blokuje ping"; w takim przypadku należy zweryfikować status za pomocą monitora TCP.
• DNS. Rozwiązuje rekord (A, AAAA, MX, TXT itd.) przy użyciu wskazanego resolvera i może weryfikować otrzymaną odpowiedź, co pozwala na wczesne wykrycie awarii rejestratora lub serwera DNS.
• Push. Monitor typu "inside-out", opisany w kolejnej sekcji.

Monitorowanie zadania cron za pomocą monitora typu push (heartbeat)

Każdy powyższy monitor łączy się z usługą z zewnątrz. Monitor typu push działa odwrotnie: Uptime Kuma oczekuje na sygnał, a zadanie wysyła zapytanie potwierdzające wykonanie. Jest to jedyna wiarygodna metoda monitorowania kopii zapasowych lub zadań cron: sprawdzenie HTTP weryfikuje jedynie dostępność adresu URL, natomiast tylko samo zadanie wie, czy zostało pomyślnie zakończone.

Utwórz monitor typu Push. Uptime Kuma wygeneruje unikalny adres URL, na przykład:

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

Ustaw parametr Heartbeat Interval na wartość odpowiadającą częstotliwości uruchamiania zadania, uwzględniając niewielki zapas czasu. Następnie dodaj jedną linię na końcu skryptu, aby sygnał był wysyłany tylko w przypadku sukcesu:

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

W przypadku błędu zadania, set -e przerywa działanie przed wywołaniem polecenia curl; jeśli serwer jest wyłączony, polecenie również nie zostanie wykonane. W obu przypadkach sygnał heartbeat przestaje być wysyłany. Po upływie czasu określonego jako interwał plus liczba ponowień, Uptime Kuma zmieni status monitora na down i wyśle powiadomienie. Token push należy traktować jako poufny; każda osoba posiadająca ten token może fałszować status poprawnego działania.

Tworzenie publicznej strony statusu

Strona statusu to widok przeznaczony dla klientów. Przedstawia ona dostępność usług oraz ich ostatnią historię, nie udostępniając przy tym panelu administracyjnego. Należy przejść do sekcji Status Pages, wybrać New Status Page, nadać stronie nazwę oraz slug (publiczną ścieżkę, np. /status/main). Następnie należy przeciągnąć wybrane monitory do grup, takich jak "Websites" lub "APIs", dodać logo oraz krótki opis, a następnie wybrać Save. Można również przypisać stronie własną domenę, dzięki czemu status.example.com będzie ją serwować bezpośrednio.

Dwie uwagi: należy dodawać tylko te monitory, które mają zostać upublicznione, ponieważ strona statusu informuje o istnieniu usługi oraz jej aktualnym stanie; panel administracyjny pozostaje chroniony logowaniem, natomiast strona statusu jest celowo publiczna i nie wymaga uwierzytelniania.

Skonfiguruj reverse proxy z TLS i zwróć uwagę na websockets

W przypadku instancji publicznej należy umieścić reverse proxy przed kontenerem działającym na adresie loopback, aby zapewnić obsługę TLS oraz nazwy hosta. Kluczowy szczegół: interfejs użytkownika Uptime Kuma to aplikacja Socket.IO działająca w czasie rzeczywistym, zatem proxy musi obsługiwać upgrade połączenia WebSocket. Brak tej konfiguracji powoduje, że strona się ładuje, ale nie nawiązuje połączenia; panel sterowania wyświetla komunikat "Connecting...", dane nie są aktualizowane, a w konsoli przeglądarki pojawia się błąd WebSocket connection to 'wss://.../socket.io/...' failed.

Należy zainstalować nginx oraz certbot, a następnie utworzyć plik vhost przekierowujący ruch na port loopback. Na początku należy użyć portu 80, a następnie pozwolić narzędziu certbot na dodanie TLS; kwestie wyzwań, harmonogramu odnawiania oraz błędów procesu opisano w wydawaniu certyfikatów Let's Encrypt za pomocą certbot i nginx.

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

Zapisz plik jako /etc/nginx/sites-available/status.example.com; kluczowe są dwie linie dotyczące WebSocket:

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

Należy aktywować witrynę, przetestować konfigurację, a następnie pozwolić narzędziu certbot na przepisanie bloku w celu obsługi portu 443, dodać certyfikaty oraz przekierowanie 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

Para Upgrade i Connection "upgrade" jest niezbędna, a proxy_read_timeout 3600s zapobiega zrywaniu długotrwałych połączeń socket przez nginx; certbot kopiuje obie te opcje do generowanego bloku 443. Jeśli w jednej instancji proxy działają już inne kontenery, routing przez Traefik z automatycznym TLS realizuje to samo za pomocą etykiet kontenerów i domyślnie przekazuje upgrade połączeń WebSocket.

Nie należy stosować basic-auth dla całego vhost, ponieważ blokuje to publiczną stronę statusu oraz endpoint /api/push. Należy pozostawić wbudowane logowanie Uptime Kuma, a w przypadku wystawienia na publiczny internet zaleca się instalację fail2ban monitorującego powtarzające się nieudane logowania. Jeśli panel sterowania nie musi być publiczny, należy zrezygnować z proxy i uzyskać do niego dostęp przez VPN.

Prawidłowe monitorowanie wygaśnięcia certyfikatów

Monitor HTTP(s) może ostrzegać przed wygaśnięciem certyfikatu TLS: po zaznaczeniu opcji Certificate Expiry Notification Uptime Kuma wysyła alerty z określoną liczbą dni wyprzedzenia. Błędna konfiguracja wynika z dwóch najczęstszych błędów. Monitoruj za pomocą nazwy hosta (hostname), a nie adresu IP; zapytanie bez SNI pobiera domyślny certyfikat serwera, co skutkuje błędem Hostname/IP does not match certificate's altnames. Nie należy również zaznaczać opcji Ignore TLS/SSL Error w monitorach, dla których wymagane są ostrzeżenia o wygaśnięciu: funkcja ta służy do obsługi wewnętrznych hostów z certyfikatami self-signed (unable to verify the first certificate, DEPTH_ZERO_SELF_SIGNED_CERT), lecz całkowicie wyłącza sprawdzanie certyfikatu przez Uptime Kuma, w tym weryfikację daty ważności.

Backups: to jest jeden katalog

Ponieważ wszystkie dane znajdują się w /app/data, kopia zapasowa jest kopią tego wolumenu wykonaną podczas zatrzymanego kontenera. Zapewnia to spójność pliku SQLite:

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

Najpierw należy potwierdzić rzeczywistą nazwę wolumenu za pomocą docker volume ls | grep kuma, ponieważ Compose dodaje prefiks z nazwy katalogu projektu. Następnie należy skopiować plik tar poza serwer, ponieważ kopia zapasowa na tym samym VPS to jedynie duplikat, a nie pełnoprawna kopia zapasowa. Proces przywracania jest odwrotny: należy zatrzymać stos, wypakować dane do pustego wolumenu /app/data, a następnie uruchomić stos.

Upgrades

Aktualizacje polegają na pobraniu obrazu:

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

Nowy kontener uruchamia migrację bazy danych przy pierwszym starcie; należy monitorować docker compose logs -f. Przed pobraniem należy wykonać kopię zapasową opisaną powyżej. Należy trzymać się wersji w ramach tej samej głównej wersji (major tag). Przejście z :1 do :2 jest migracją jednokierunkową, dlatego należy najpierw wykonać kopię zapasową i sprawdzić informacje o wydaniu (release notes).

Tryby awarii i wyświetlane komunikaty

Błędny status "down" dla monitora skierowanego na localhost. Monitor wyświetla czerwony kolor z komunikatem timeout of 48000ms exceeded lub connect ETIMEDOUT, mimo że usługa odpowiada na zapytania z laptopa. Jeśli monitor wskazuje ten sam host, na którym działa Uptime Kuma, przyczyną jest nagły wzrost zużycia CPU lub pamięci, który uniemożliwił wykonanie sprawdzenia. Należy przenieść monitor na oddzielny serwer VPS i wskazać publiczną nazwę hosta.

connect ECONNREFUSED 127.0.0.1:443 (lub dowolny inny port). Brak usługi nasłuchującej na tym porcie: usługa jest wyłączona lub monitorowanie localhost odbywa się wewnątrz kontenera, gdzie 127.0.0.1 to kontener, a nie serwer. Należy monitorować publiczną nazwę hosta, a nie adres loopback.

Invalid login: 535-5.7.8 Username and Password not accepted podczas testu e-mail. Dane uwierzytelniające SMTP są nieprawidłowe lub dostawca wymaga hasła aplikacji, a podano hasło do konta. Należy wygenerować hasło aplikacji i użyć go.

connect ETIMEDOUT lub queryA ETIMEDOUT <host> podczas testu e-mail. Nieprawidłowy port lub dostawca blokuje wychodzący ruch SMTP. Należy sprawdzić, czy 465 lub 587 jest zgodne z ustawieniem Secure/STARTTLS, oraz przeprowadzić test z hosta za pomocą nc -vz smtp.example.com 587. Wielu dostawców blokuje wychodzący 25, a niektórzy blokują porty submission do momentu zgłoszenia prośby.

self signed certificate lub unable to verify the first certificate podczas testu e-mail. Serwer SMTP przedstawia certyfikat, któremu Node nie ufa; należy naprawić certyfikat serwera pocztowego zamiast stosować obejścia.

Dashboard zatrzymany na stanie "Connecting...", konsola wyświetla WebSocket connection ... failed. Reverse proxy nie dokonuje upgrade'u protokołu WebSocket. Należy dodać nagłówki Upgrade oraz Connection "upgrade" w konfiguracji nginx lub użyć proxy, które przekazuje je domyślnie, np. Traefik lub Caddy. Plik HTML ładuje się poprawnie, ponieważ jest to standardowe żądanie HTTP GET; tylko gniazdo (socket) wymaga upgrade'u.

Monitor wygaśnięcia certyfikatu nigdy nie ostrzega lub ostrzega błędnie. Albo zaznaczono opcję Ignore TLS/SSL Error, co wyłącza sprawdzanie certyfikatu, albo monitor wskazuje adres IP i odczytuje niewłaściwy certyfikat z powodu braku SNI, wyświetlając Hostname/IP does not match certificate's altnames. Należy odznaczyć opcję ignorowania błędów i monitorować przez nazwę hosta.

SQLITE_BUSY lub database disk image is malformed w logach. Wolumen /app/data znajduje się na systemie plików bez odpowiedniego blokowania plików, zazwyczaj NFS; należy przenieść go na lokalny wolumen Docker i przywrócić z kopii zapasowej.

FAQ

Gdzie należy uruchomić monitor uptime?

Na innym serwerze niż monitorowane jednostki. Najlepiej u innego dostawcy lub w innym regionie, łącząc się z nimi za pomocą nazwy hosta przez publiczny internet, w taki sam sposób jak użytkownicy. Jeśli monitor znajduje się na tym samym serwerze co cele, awaria serwera spowoduje jednocześnie awarię monitora. Przeciążony host może błędnie zgłosić status "down" dla sprawnych usług. Mały, oddzielny VPS eliminuje oba te problemy.

Jak otrzymywać powiadomienia przez Telegram lub e-mail?

Należy dodać kanał w sekcji Settings then Notifications, a następnie przypisać go do każdego monitora. W przypadku Telegrama należy utworzyć bota za pomocą @BotFather i odczytać chat.id z https://api.telegram.org/bot<token>/getUpdates; w przypadku e-mail należy użyć 465 dla SSL lub 587 dla STARTTLS wraz z hasłem aplikacji, jeśli dostawca korzysta z uwierzytelniania dwuskładnikowego. Przed rozpoczęciem korzystania z powiadomień należy nacisnąć Test i potwierdzić dotarcie wiadomości.

Czy Uptime Kuma może monitorować zadania cron lub skrypty backupowe?

Tak, służy do tego monitor typu Push: Uptime Kuma generuje adres URL, który należy wysłać za pomocą curl na końcu skryptu, aby powiadomienie wysłano tylko po sukcesie. Jeśli zadanie zakończy się błędem lub serwer będzie niedostępny, sygnał heartbeat nie zostanie odebrany, co spowoduje powiadomienie po upływie zdefiniowanego interwału. Jest to jedyny niezawodny sposób na sprawdzenie, czy zaplanowane zadanie faktycznie zostało wykonane, ponieważ zewnętrzna weryfikacja nie ma wglądu w procesy wewnętrzne.

Uptime Kuma vs Zabbix, co należy uruchomić?

Uptime Kuma w dziesięć minut, przy minimalnym zużyciu zasobów, odpowiada na pytania: "czy usługa działa z zewnątrz" oraz "czy wysłano powiadomienie", oferując dodatkowo stronę statusu. Narzędzie to nie zbiera szczegółowych metryk, takich jak trendy użycia CPU, pamięci RAM lub dysku, ani nie obsługuje progów dla całej floty urządzeń. Do tych celów pełny serwer monitorujący Zabbix jest bardziej rozbudowanym narzędziem opartym na agentach; wielu użytkowników korzysta z obu rozwiązań jednocześnie. Wciąż nie można zdecydować, co uruchomić? nasze zestawienie rozwiązań do self-hostingu w 2026 przedstawia monitoring w szerszym kontekście.