Uptime Kuma в Docker: self-hosted моніторинг доступності з Telegram і HTTPS

Що має вийти в кінці

Фінальний стан простий: Uptime Kuma працює в окремому контейнері, дані зберігаються у persistent volume, веб-інтерфейс відкривається через HTTPS, а при падінні сервісу або відновленні приходить повідомлення в Telegram. Це і є базовий моніторинг доступності для homelab без зайвого стеку.

• контейнер з Uptime Kuma у Docker Compose;
• публікація через reverse proxy з TLS;
• Telegram notifications для alerting;
• набір моніторів для внутрішніх і зовнішніх сервісів;
• окремий блок перевірки після запуску.

Розгортання Uptime Kuma в Docker Compose

Найпростіший варіант – не виставляти контейнер напряму в інтернет, а віддати його за reverse proxy. Сам контейнер має жити в окремій мережі Docker, з volume для даних. Для невеликого homelab це нормальна межа простоти: конфіг короткий, оновлення контрольоване, rollback теж не проблема.

Структура каталогу може бути такою:

mkdir -p ~/docker/uptime-kuma
cd ~/docker/uptime-kuma

Базовий docker-compose.yml:

services:
  uptime-kuma:
    image: louislam/uptime-kuma:1
    container_name: uptime-kuma
    restart: unless-stopped
    volumes:
      - ./data:/app/data
    ports:
      - 3001:3001

Запуск:

docker compose up -d

Після першого старту веб-інтерфейс буде доступний на порту 3001. Якщо далі планується HTTPS через окремий проксі, пряме відкриття цього порту назовні краще прибрати. У локальній мережі він ще терпимий, на WAN – зайвий ризик.

Коли попереду стоїть Traefik, Nginx Proxy Manager або звичайний Nginx, контейнер логічніше перевести на внутрішню мережу без host port. Саме такий варіант чистіший для моніторинг доступності, якщо інстанс має працювати постійно і без ручного підкручування після кожного оновлення proxy-правил.

HTTPS через reverse proxy, а не всередині контейнера

Для Uptime Kuma HTTPS найкраще термінувати на reverse proxy. Контейнеру достатньо внутрішнього HTTP, а сертифікати, renew і HSTS нехай живуть в одному місці. Так простіше підтримувати кілька self-hosted сервісів і не плодити TLS-логіку в кожному окремо.

Приклад для схеми з внутрішньою Docker-мережею:

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

networks:
  proxy:
    external: true

Далі вже сам reverse proxy маршрутизує трафік на контейнер. Якщо використовується Nginx, критичні місця – заголовки Host, X-Forwarded-For і X-Forwarded-Proto. Без останнього застосунок іноді поводиться так, ніби працює по HTTP: некоректні редіректи, змішані URL або дивна генерація посилань у сповіщеннях.

Для Nginx базовий location виглядає так:

server {
    server_name kuma.example.com;

    location / {
        proxy_pass http://uptime-kuma:3001;
        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 https;
    }
}

Сертифікат випускається на стороні проксі. Якщо в інфраструктурі вже є Let’s Encrypt, додаткової логіки в контейнері не потрібно.

Тут є одна неочевидна межа. Коли Uptime Kuma стоїть за кількома проксі або Cloudflare-подібним шаром, моніторинг доступності може показувати сервіс як живий, хоча upstream вже частково мертвий. Reverse proxy відповідає 200, а бекенд деградує всередині. Для критичних сервісів краще мати окремий HTTP-монітор на health endpoint і окремий TCP або ping на сам вузол.

Як підключити Telegram-сповіщення

Telegram у Uptime Kuma закриває нормальний сценарій аварійних повідомлень без SMTP, окремого mail relay і боротьби зі spam policy. Потрібен bot token і chat ID, після чого сповіщення підв’язуються до конкретних моніторів. Це швидше за email і майже завжди достатньо для homelab.

Послідовність така:

1. Створити бота через BotFather у Telegram.
2. Отримати token.
3. Додати бота в потрібний чат або використовувати особистий діалог.
4. Визначити chat ID.
5. У веб-інтерфейсі Uptime Kuma створити notification-канал Telegram.

Щоб швидко перевірити bot token, зручно звернутися до Bot API:

curl https://api.telegram.org/botTELEGRAM_BOT_TOKEN/getMe

Для пошуку chat ID зазвичай достатньо надіслати повідомлення боту та подивитися updates:

curl https://api.telegram.org/botTELEGRAM_BOT_TOKEN/getUpdates

У відповіді буде ідентифікатор чату. Далі цей token і chat ID вносяться в notification-канал Uptime Kuma. Після збереження варто одразу натиснути тестову відправку.

Частий збій тут банальний: бот існує, token правильний, але повідомлення не йдуть, бо бот не має контексту чату. Для груп це особливо типово. Поки бот не доданий у групу або не бачив повідомлення, chat ID або не з’являється, або сповіщення мовчки не доставляються.

Які монітори створювати першими

Починати краще не з усього підряд, а з вузлів, через які проходить решта трафіку. Для моніторинг доступності це reverse proxy, DNS, маршрутизатор, VPN-вхід, NAS і кілька зовнішніх endpoint’ів. Якщо впаде один з них, решта алертів лише створить шум.

Раціональний стартовий набір такий:

• HTTP або HTTPS-монітор для reverse proxy.
• HTTP-монітор для status endpoint критичних веб-сервісів.
• TCP-монітор для баз даних або нестандартних портів.
• Ping для хостів у локальній мережі.
• DNS або HTTP-запит до зовнішнього ресурсу, щоб бачити проблеми з uplink.

Не варто зводити все до ping. Хост може відповідати на ICMP і при цьому віддавати битий веб-інтерфейс, завислий login або таймаути на API. Зворотна ситуація теж буває: ICMP закритий політикою фаєрвола, але сервіс живий. Для кожного класу цілей потрібен свій тип перевірки.

Перевірка після запуску

Після розгортання важливо перевірити не тільки те, що відкривається веб-інтерфейс. Потрібно пройти весь ланцюг: контейнер, proxy, HTTPS, монітор, алерт, відновлення після збою. Інакше моніторинг доступності існує лише формально.

1. Переконатися, що контейнер працює.
2. Відкрити веб-інтерфейс по HTTPS і перевірити сертифікат.
3. Створити тестовий HTTP-монітор на власний сервіс.
4. Примусово зупинити цільовий контейнер.
5. Дочекатися alert у Telegram.
6. Підняти сервіс назад і перевірити recovery notification.

Команди для перевірки контейнера:

docker ps
docker logs --tail=100 uptime-kuma

Якщо монітор не спрацьовує, але сервіс точно недоступний, спершу дивляться на інтервал перевірки, timeout і retry policy. Надто м’які значення роблять алерти повільними. Надто агресивні – дають фальшиві спрацювання, особливо на слабких ARM-хостах або на нестабільному uplink.

Де зазвичай все ламається

Найчастіше проблеми не в Docker Compose. Вони в мережевому контурі навколо нього: DNS, reverse proxy, неправильний URL і Telegram API. Якщо інтерфейс відкривається, це ще не означає, що весь моніторинг доступності працює коректно.

HTTPS є, але застосунок поводиться як по HTTP

Майже завжди бракує X-Forwarded-Proto або проксі віддає не той Host. У результаті з’являються криві редіректи, некоректні callback URL або попередження браузера.

Telegram test не доходить

Перевіряються token, chat ID і сам факт, що бот уже взаємодіяв з чатом. Для груп ще спрацьовує дрібний, але неприємний нюанс: бот доданий, але права або режим групи блокують доставку.

Після оновлення контейнера інтерфейс піднявся, а частина історії зникла

Причина зазвичай у volume. Якщо дані були не змонтовані на хост або шлях змінився, контейнер стартує чистим. Для self-hosted сервісів такого класу persistent storage – не опція, а основа.

Монітори сиплять фальшиві падіння

Це буває на домашніх каналах з нестабільною затримкою або коли всі перевірки йдуть з того ж вузла, що і сам сервіс. Uptime Kuma бачить локальну деградацію як глобальну. До певного масштабу це нормально, але для дійсно критичних сервісів потрібна друга точка перевірки поза локальною мережею.

Коли цього вже мало

Uptime Kuma добре закриває моніторинг доступності, але не замінює повний observability stack. Він показує факт недоступності, базову затримку і стан endpoint’а. Якщо потрібні метрики процесів, дисків, контейнерів і довга історія, доведеться дивитися в бік Prometheus, Grafana та окремого alerting.

У homelab це нормальний поділ ролей. Uptime Kuma відповідає за швидкий сигнал, що щось впало. Метрики відповідають на інше питання – чому саме це сталося. Змішувати ці задачі в одному інструменті зазвичай невигідно.

Що реально варто зробити одразу

Для старту достатньо підняти Uptime Kuma у Docker, сховати його за HTTPS-проксі і підв’язати Telegram. Після цього додати кілька правильних моніторів: reverse proxy, DNS, VPN і один критичний веб-сервіс. Такий моніторинг доступності вже дає користь у перший день, без важкого стека і без залежності від зовнішніх платформ.

Офіційний сайт проєкту: Uptime Kuma. Код і релізи: GitHub repository.