Uptime Kuma в Docker для homelab: розгортання і Telegram-сповіщення

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

Щоб Uptime Kuma Docker переживав оновлення і перезапуски, потрібен окремий volume для даних. Без цього після перевстановлення контейнера зникнуть монітори, токени і налаштування сповіщень.

Найпростіше підняти сервіс через Docker Compose. Для homelab цього вистачає: одна служба, один volume, один опублікований порт.

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

volumes:
  uptime-kuma-data:

Після запуску інтерфейс буде доступний на порту 3001. Якщо зовні стоїть reverse proxy, публікацію порту можна залишити тільки у внутрішній мережі Docker або винести доступ через окремий hostname.

docker compose up -d

На практиці bind mount замість named volume теж працює, але саме тут частіше ловлять проблеми з правами на файловій системі хоста. Для одного контейнера named volume менш крихкий варіант.

Що налаштувати одразу після першого запуску

Після відкриття веб-інтерфейсу треба створити обліковий запис адміністратора, а далі – додати монітори під конкретні сервіси. Для homelab зазвичай починають з HTTP(S), TCP ping і звичайного ICMP ping, якщо вузол відповідає на нього.

Не варто додавати все підряд. Спершу має сенс поставити кілька критичних точок:

• reverse proxy або головну веб-точку входу;
• router або firewall, якщо він доступний для перевірки;
• NAS або backup host;
• VPN endpoint;
• Docker-host, на якому крутяться основні сервіси.

Якщо сервіс працює за reverse proxy, моніторити краще зовнішній URL, а не внутрішній контейнерний порт. Інакше перевірка покаже, що контейнер живий, хоча реальний вхід зламаний сертифікатом, DNS або проксі-маршрутизацією.

Як налаштувати Telegram-сповіщення

Uptime Kuma Docker підтримує Telegram-сповіщення через бота. Робоча схема проста: створюється bot token, визначається chat ID, після чого цей канал додається в налаштування сповіщень Uptime Kuma і прив’язується до потрібних моніторів.

Спочатку в Telegram треба створити бота через BotFather і отримати token. Потім – написати цьому боту хоча б одне повідомлення. Без цього чат часто не визначається коректно, і тестове сповіщення не проходить.

Щоб дізнатися chat ID, зручно викликати Bot API після повідомлення боту:

https://api.telegram.org/bot<BOT_TOKEN>/getUpdates

У відповіді буде chat ID приватного чату або групи. Далі в інтерфейсі Uptime Kuma треба додати новий notification type для Telegram, вставити token і chat ID, зберегти налаштування і виконати тестову відправку.

Для груп чат працює не завжди з першої спроби. Часто проблема банальна: бота не додали в групу або не дали йому права на відправку повідомлень. Ще одна типова історія – використання неправильного chat ID після міграції звичайної групи в supergroup.

Перевірка: чи доходять алерти і чи відновлюється статус

Після налаштування Uptime Kuma Docker перевіряти треба не кнопку test, а повний цикл події: падіння сервісу, спрацювання алерта, повернення сервісу в online і повторне повідомлення про recovery. Лише так видно, що схема зібрана правильно.

Нормальна перевірка виглядає так:

1. Створити HTTP-монітор на сервіс, який легко тимчасово зупинити.
2. Прив’язати до нього Telegram-сповіщення.
3. Зупинити контейнер або закрити порт на кілька інтервалів перевірки.
4. Дочекатися аварійного повідомлення.
5. Повернути сервіс у робочий стан.
6. Переконатися, що прийшло повідомлення про відновлення.

Якщо надходить тільки перший алерт, але немає recovery, проблема часто не в Telegram, а в параметрах самого монітора – таймауті, інтервалі або логіці повторних перевірок. У невеликих homelab це легко пропустити, бо ручний тест зазвичай короткий.

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

Найчастіше Uptime Kuma Docker ламається не на старті контейнера, а після першого оновлення, переносу на інший хост або зміни мережевої схеми. Саме тому persistent storage і зрозумілий доступ до сервісу важливіші за швидкий перший запуск.

Немає даних після перезапуску

Причина майже завжди в volume. Або він не підключений, або контейнер створили заново з іншим шляхом до даних. Якщо після рестарту відкривається чистий інтерфейс початкового налаштування – треба дивитися, куди реально монтується /app/data.

Контейнер працює, але Telegram мовчить

Тут типовий набір причин короткий: неправильний token, неправильний chat ID, бот не отримував повідомлення від користувача, бот не доданий у групу, outbound-доступ контейнера до Telegram API заблокований firewall або DNS.

Монітор green, а сервіс фактично недоступний

Таке трапляється, коли перевіряється внутрішній порт контейнера замість реальної точки входу. Для сервісів за reverse proxy монітор без зовнішнього URL дає хибне відчуття контролю. Особливо якщо падає TLS, cloud tunnel або правило маршрутизації.

Забагато алертів

Якщо додати десятки слабко важливих перевірок, Telegram швидко перетвориться на шум. У homelab це стандартна пастка. Краще моніторити точки відмови, а не кожен контейнер окремо, якщо від них немає оперативної користі.

Коли Uptime Kuma Docker вже тісний

Для кількох десятків перевірок і простих сповіщень Uptime Kuma Docker закриває задачу добре. Але коли потрібні залежності між сервісами, складні правила ескалації, довгі retention-періоди або нормальна робота з метриками, починається межа цього підходу.

У такій точці логічно лишити Uptime Kuma як front-facing uptime monitor, а глибший моніторинг винести в окремий стек. Це нормальне розділення ролей: Uptime Kuma показує, що впало для користувача, а Prometheus-подібна система пояснює чому.

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