Як розгорнути Homarr на власному сервері у 2026 році: дашборди, секрети та live tiles

Контейнер Homarr може бути в зеленому стані, навіть якщо потрібна користувачам функція не працює. Для Homarr прихована проблема зазвичай полягає в тому, що віджети не можуть підключитися до сервісів, оскільки використовують локальні адреси хоста. У цьому посібнику сценарій «створити дошку, додати плитку сервісу, налаштувати одну інтеграцію з обліковими даними та після перезапуску підтвердити актуальний статус і пошук» використовується як acceptance test, а розгортання будується від цього результату у зворотному напрямку.

Homarr має чітко визначену роль у стеку: searchable dashboard із live tiles для self-hosted сервісів. Тому production-питання полягає не в тому, чи відповідає порт 7575 один раз, а в тому, чи продовжують узгоджено працювати стан, залежності та публічна адреса після перезапуску, оновлення й відновлення.

Спочатку визначте критерії успіху для Homarr

Не дозволяйте образу Homarr випадково визначити production-архітектуру. Образ надає процес на порту 7575, але для storage, routing і зовнішніх вимог усе одно потрібні продумані lifecycle. Локальна runtime-вимога — постійні дані застосунку та облікові дані для live-інтеграцій. Це має бути частиною плану ресурсів і монтувань із відповідальним власником та вимірюваним лімітом.

Розгортання готове до глибшого тестування, коли воно може створити дошку, додати плитку сервісу, налаштувати одну інтеграцію з обліковими даними та після перезапуску підтвердити актуальний статус і пошук. Відстежуйте транзакцію в логах, а також fan-out запитів віджетів, latency downstream API, розмір даних застосунку та кількість одночасних клієнтів дашборда. Ці спостереження покажуть, чи ізолює поточна топологія потрібний компонент.

Відрепетируйте ризиковану зміну Homarr

Зелений контейнер необхідний, але недостатній. Service-level indicator — успішне виконання сценарію «створити дошку, додати плитку сервісу, налаштувати одну інтеграцію з обліковими даними та після перезапуску підтвердити актуальний статус і пошук», тоді як імовірними сигналами навантаження є fan-out запитів віджетів, latency downstream API, розмір даних застосунку та кількість одночасних клієнтів дашборда.

Контроль змін важливий, оскільки міграції схеми Homarr і безперервність encryption key можуть впливати на збережені облікові дані інтеграцій. Збережіть попередній образ, протестуйте міграції на копії стану та задокументуйте, чи підтримується rollback після зміни схеми. Якщо віджети не можуть підключитися до сервісів, оскільки використовують локальні адреси хоста, діагностуйте першу межу, яка відрізняється від робочого середовища.

Зафіксуйте перевірене розгортання Homarr

Не використовуйте трафік перших користувачів як acceptance test для Homarr. Підготуйте безпечний тестовий стан і виконайте повний сценарій «створити дошку, додати плитку сервісу, налаштувати одну інтеграцію з обліковими даними та після перезапуску підтвердити актуальний статус і пошук». Занотуйте точну публічну URL-адресу, результат, посилання на образ і інтервал логування, пов’язаний із цим запуском.

Замініть контейнер і повторіть тест, не перебудовуючи дані. Потім відновіть систему на порожньому хості; умовою відновлення є повернення дошок, користувачів, інтеграцій і custom assets та повторне підключення віджетів з обліковими даними. На кожному проході спостерігайте за fan-out запитів віджетів, latency downstream API, розміром даних застосунку та кількістю одночасних клієнтів дашборда і налаштуйте alert на погіршення транзакції, а не на метрики простою контейнера.

Остання перевірка має навмисно завершитися помилкою: надішліть безпечне тестове введення поблизу ліміту ресурсу або формату, пов’язаного з цією межею: віджети не можуть підключитися до сервісів, оскільки використовують локальні адреси хоста. Переконайтеся, що повідомлення Homarr вказує на відповідну межу, а не запускає видалення даних чи нескінченний перезапуск. Відновіть коректну умову та підтвердьте, що та сама тестова транзакція виконується успішно. Додайте цю коротку перевірку до release checklist.

Запустіть перший інстанс у production-подібному середовищі

Перший контейнер має бути простим для видалення та повторного створення. Зберігайте дані не у writable layer, прив’яжіть порт 7575 лише там, де його може досягти proxy, і передавайте конфігурацію під час запуску.

docker run -d \
  --name homarr \
  --restart unless-stopped \
  -p 127.0.0.1:7575:7575 \
  -v homarr-data:/appdata \
  -e SECRET_ENCRYPTION_KEY=replace-with-a-long-random-value \
  ghcr.io/homarr-labs/homarr:latest

Після початкового тесту зафіксуйте версію образу. Читайте найпершу помилку запуску, а не фінальне повідомлення про перезапуск, перевірте кожне монтування за допомогою docker inspect і стежте за логами, поки створюєте дошку, додаєте плитку сервісу, налаштовуєте одну інтеграцію з обліковими даними та після перезапуску підтверджуєте актуальний статус і пошук. Ця послідовність допомагає відрізнити неправильну команду запуску образу від проблеми із залежністю або дозволами.

Volumes — лише перший рівень відновлення

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

Потім протестуйте disaster recovery на порожньому хості. За потреби використовуйте узгоджений зі станом застосунку database export і переконайтеся, що дошки, користувачі, інтеграції та custom assets повертаються, а віджети з обліковими даними повторно підключаються. Посібник із резервного копіювання баз даних, для якого ви перевіряли відновлення задає кращу ціль, ніж проста перевірка факту створення archive-файлу.

Не дозволяйте успішному proxy приховувати збій застосунку

Браузер, API-клієнт і Homarr мають узгоджено використовувати один origin. Щоб цього досягти, налаштуйте зовнішній HTTPS hostname і дозволені origins. Зберігайте оригінальні host і protocol, водночас не допускаючи використання порту 7575 як конкуруючої публічної адреси.

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

Закрийте тимчасовий доступ для налаштування

Безпечне розгортання Homarr починається з обмеження повноважень. Не змінюйте encryption key після збереження секретів інтеграцій; натомість підтримуйте стабільне значення SECRET_ENCRYPTION_KEY, захищайте редагування дошок і обмежуйте права кожного облікового запису віджета.

Згенеруйте SECRET_ENCRYPTION_KEY один раз, не зберігайте його в Git і додайте до recovery manifest, оскільки його зміна може зробити недійсним зашифрований або підписаний стан застосунку. Обмежте адміністративні маршрути, використовуйте private DNS для залежностей і перевірте кожне bind mount. Якщо логи передаються до централізованої системи, відфільтруйте секрети та приватний вміст до того, як вони залишать сервер.

Перенесіть повторювані інфраструктурні операції до Dockup

Для Homarr Dockup найкорисніший на межі між образом і durable service. Він зберігає маршрут до 7575, TLS, значення секретів і storage прив’язаними під час заміни контейнерів — незалежно від того, чи належить обчислювальна інфраструктура Dockup, чи підключеному серверу.

Завершіть налаштування на рівні застосунку: задайте зовнішній HTTPS hostname і дозволені origins; підтвердьте локальну вимогу — постійні дані застосунку та облікові дані для live-інтеграцій; і виконайте цю перевірку: створіть дошку, додайте плитку сервісу, налаштуйте одну інтеграцію з обліковими даними та після перезапуску підтвердьте актуальний статус і пошук. Збережіть результат як deployment check, щоб наступне оновлення образу оцінювалося за поведінкою, а не за статусом контейнера.

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

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

Маршрутизуйте контейнер Homarr через порт 7575 і один HTTPS origin. Локальна runtime-вимога — постійні дані застосунку та облікові дані для live-інтеграцій. Не вважайте Homarr готовим, доки не зможете створити дошку, додати плитку сервісу, налаштувати одну інтеграцію з обліковими даними та після перезапуску підтвердити актуальний статус і пошук.

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

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

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

Використовуйте HTTPS для публічного origin Homarr, а порт 7575 залиште у внутрішньому маршруті. Правильно застосуйте налаштування Homarr: задайте зовнішній HTTPS hostname і дозволені origins. Для Homarr HTTPS захищає облікові дані або користувацький вміст під час передавання та забезпечує узгоджену поведінку клієнта, чутливу до origin.

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

Відновіть поточний стан Homarr в ізольованому розгортанні, застосуйте candidate version і повторіть acceptance transaction. Зверніть особливу увагу на те, що міграції схеми Homarr і безперервність encryption key можуть впливати на збережені облікові дані інтеграцій. Зберігайте попередній образ Homarr, доки не зрозумієте межі міграції даних і rollback.