Як розгорнути Homepage на власному сервері у 2026 році: дозволені хости, віджети та конфігурація

Є дві версії «запущеної Homepage»: контейнер існує або сервіс виконує свою реальну роботу. Важлива лише друга. У цьому випадку потрібно перевірити завантаження сервісів і закладок, виклик кількох робочих віджетів, пошук і перезапуск після редагування YAML-файлу конфігурації.

Homepage призначена для такого сценарію: стартова сторінка з динамічними віджетами для self-hosted сервісів. Розгортання має зберігати всі компоненти, що забезпечують цю поведінку; порт, volume і сертифікат — це вхідні дані, а не результат.

Виберіть найменшу придатну топологію Homepage

Корисна схема Homepage показує публічний маршрут, приватний порт 3000, межу зберігання стану та всі необхідні залежності. Позначте, які стрілки передають облікові дані, а які — звичайний користувацький трафік. Зовнішня вимога Homepage — конфігурація лише для читання та облікові дані для необов’язкових сервісних віджетів. Перевірте вихідний DNS, TLS і поведінку провайдера, не публікуючи ще один вхідний сервіс.

Підтвердьте схему однією реальною дією: завантажте сервіси й закладки, викличте кілька динамічних віджетів, перевірте пошук і перезапустіть сервіс після редагування YAML-файлу конфігурації. Найімовірніше навантаження створюватимуть каскадні виклики віджетів, повільні downstream API, DNS-резолюція та частота оновлення браузерної панелі; моніторте саме цей шлях, а не сприймайте всі HTTP-запити як рівнозначні.

Оновлюйте Homepage без припущень

Перший корисний операційний показник для Homepage — здатність завантажувати сервіси й закладки, викликати кілька динамічних віджетів, виконувати пошук і перезапускатися після редагування YAML-файлу конфігурації. Додайте до нього сигнали насичення для каскадних викликів віджетів, повільних downstream API, DNS-резолюції та частоти оновлення браузерної панелі. Probe, що перевіряє лише процес, не повинен викликати дорогі залежності або перезапускати контейнер через короткочасну недоступність upstream-сервісу.

Сприймайте оновлення як зміни даних, оскільки ключі конфігурації та інтеграції віджетів можуть змінюватися, тому перед оновленням image перевіряйте YAML і поведінку провайдера. Фіксуйте версії, тестуйте оновлення на відновленому стані й зберігайте попередній image, доки rollback залишається можливим. Якщо хост відхилено або відступи в YAML не дають завантажити конфігурацію, збережіть логи до перезапуску; зазвичай саме вони містять повідомлення про причину.

Приймальна перевірка Homepage для production

До появи реальних користувачів підготуйте release-таблицю для Homepage. У ній потрібно вказати зафіксований image, порт 3000, канонічний origin, постійні шляхи та відповідального за конфігурацію лише для читання й облікові дані для необов’язкових сервісних віджетів. Додайте очікуваний результат цієї операції: завантаження сервісів і закладок, виклик кількох динамічних віджетів, перевірка пошуку та перезапуск після редагування YAML-файлу конфігурації.

Використовуйте цю таблицю після штатної заміни та після чистого відновлення. Відновлення вважається успішним лише тоді, коли повернулися сервіси, закладки, віджети й custom assets, а всі критичні віджети помітно обробляють збої downstream-залежностей. Також зберіть короткий профіль використання ресурсів, що охоплює каскадні виклики віджетів, повільні downstream API, DNS-резолюцію та частоту оновлення браузерної панелі; зберігайте його разом із release, щоб майбутні зміни capacity порівнювалися на тому самому навантаженні.

Додайте один контрольований збій: тимчасово забороніть тестовий шлях, який використовується для конфігурації лише для читання та облікових даних необов’язкових сервісних віджетів. Переконайтеся, що Homepage повідомляє про проблему на правильній межі, відновіть коректну умову та повторіть операцію. Це перевіряє видимість помилок, а не лише успішний сценарій, і не дає інтерфейсу, що виглядає справним, приховати зламаний worker, callback або підключення до бази даних.

Зробіть запуск Homepage відтворюваним

Використовуйте контейнер як замінюване середовище виконання, а не як місце зберігання істини.

docker run -d \
  --name homepage \
  --restart unless-stopped \
  -p 127.0.0.1:3000:3000 \
  -v homepage-data:/app/config \
  -e HOMEPAGE_ALLOWED_HOSTS=home.example.com \
  ghcr.io/gethomepage/homepage:latest

Дозвольте та перевірте вихідний або клієнтський шлях, необхідний для конфігурації лише для читання й облікових даних необов’язкових сервісних віджетів. Перевірте користувача контейнера, доступні для запису шляхи та прив’язаний listener до того, як відкривати сервіс назовні. Виконайте повну операцію — завантажте сервіси й закладки, викличте кілька динамічних віджетів, перевірте пошук і перезапустіть сервіс після редагування YAML-файлу конфігурації — та збережіть точне посилання на image, який дав цей результат.

Відокремте замінювані контейнери від постійних даних

До набору даних для надійного відновлення належать файли конфігурації, закладки, сервіси та custom assets. Підключіть /app/config до bootstrap, запишіть нешкідливі тестові дані та замініть контейнер, щоб довести фактичну постійність цього шляху. Volume захищає дані від заміни контейнера, але не від втрати хоста, випадкового видалення чи пошкодження на рівні застосунку.

Створюйте резервні копії з урахуванням джерела даних: за потреби використовуйте logical dump для робочих баз даних, а файли копіюйте лише зі стабільного стану. Зберігайте одну зашифровану копію окремо від хоста Homepage. Критерій успішного відновлення має бути конкретним: сервіси, закладки, віджети й custom assets повернулися, а всі критичні віджети помітно обробляють збої downstream-залежностей. У посібнику з резервного копіювання, перевіреного відновленням пояснюється, чому одного статусу успішного виконання job недостатньо.

Домени, proxy headers і порт 3000

Браузер, API-клієнт і Homepage мають використовувати один origin. Щоб цього досягти, задайте дозволені хости для точного домену та імені proxy-хоста. Зберігайте початкові host і protocol, водночас не допускаючи доступу до порту 3000 як до альтернативної публічної адреси.

Посібник із діагностики недоступного сайту допоможе відрізнити недоступний маршрут від застосунку, який відповідає. Тут це розрізнення важливе: хост відхилено або відступи в YAML не дають завантажити конфігурацію. Лише першу проблему виправляють змінами ingress; друга потребує перевірки логів Homepage, стану або навантаження.

Специфічні для Homepage рішення з безпеки

Не переносьте припущення щодо безпеки з локального tutorial. Специфічна проблема Homepage — потрапляння API-ключів віджетів до публічного repository. Тому в production потрібно точно задати дозволені хости, а API-ключі віджетів зберігати в environment або конфігурації на основі secret, а не в публічному repository.

HOMEPAGE_ALLOWED_HOSTS керує поведінкою, а не конфіденційністю; перевіряйте його тип і значення, а справжні облікові дані Homepage зберігайте окремо. Обмежте доступ до файлової системи й мережі, захистіть setup endpoints і визначте ліміти на upload, request або execution для каскадних викликів віджетів, повільних downstream API, DNS-резолюції та частоти оновлення браузерної панелі.

Як Dockup спрощує роботу з Homepage

Для Homepage Dockup найкорисніший на межі між image та постійним сервісом. Він зберігає прив’язаними маршрут до 3000, TLS, значення secret і storage під час заміни контейнерів — незалежно від того, чи належить compute Dockup, чи підключеному серверу.

Завершіть роботу з урахуванням особливостей застосунку: задайте дозволені хости для точного домену та імені proxy-хоста; дозвольте й перевірте конфігурацію лише для читання та облікові дані необов’язкових сервісних віджетів; виконайте таку перевірку: завантажте сервіси й закладки, викличте кілька динамічних віджетів, перевірте пошук і перезапустіть сервіс після редагування YAML-файлу конфігурації. Збережіть результат як deployment check, щоб наступне оновлення image оцінювалося за поведінкою, а не за статусом контейнера.

Поширені запитання

Що потрібно Homepage для розгортання в production?

Прокладіть маршрут від контейнера Homepage на порту 3000 через один HTTPS origin. Зовнішня вимога для доставки — конфігурація лише для читання та облікові дані необов’язкових сервісних віджетів. Не вважайте Homepage готовою, доки не зможете завантажити сервіси й закладки, викликати кілька динамічних віджетів, перевірити пошук і перезапустити сервіс після редагування YAML-файлу конфігурації.

Які дані Homepage потрібно включити до резервної копії?

Зберігайте /app/config і включіть файли конфігурації, закладки, сервіси та custom assets до одного manifest відновлення. Чисте відновлення Homepage вважається успішним лише тоді, коли повернулися сервіси, закладки, віджети й custom assets, а всі критичні віджети помітно обробляють збої downstream-залежностей.

Чи потрібен Homepage HTTPS за reverse proxy?

Використовуйте HTTPS для публічного origin Homepage, а порт 3000 залишайте у внутрішньому маршруті. Коректно застосуйте налаштування Homepage: задайте дозволені хости для точного домену та імені proxy-хоста. Для Homepage HTTPS захищає облікові дані або користувацький вміст під час передавання та забезпечує узгоджену поведінку клієнта, чутливу до origin.

Як тестувати оновлення Homepage?

Відновіть поточний стан Homepage в ізольованому розгортанні, застосуйте candidate version і повторіть приймальну операцію. Зверніть особливу увагу на те, що ключі конфігурації та інтеграції віджетів можуть змінюватися, тому перед оновленням image перевірте YAML і поведінку провайдера. Зберігайте попередній image Homepage, доки не буде зрозуміла межа міграції даних і rollback.