Как разместить Homarr самостоятельно в 2026 году: дашборды, секреты и live-тайлы
Практическое руководство по самостоятельному размещению Homarr: Docker, порты, постоянное хранение данных, TLS, безопасность, резервное копирование и проблемы, которые мешают использовать сервис в production. Пошаговая инструкция.
Контейнер Homarr может работать без ошибок, даже если главная пользовательская функция сломана. Для Homarr такая скрытая проблема обычно заключается в том, что виджеты не могут подключиться к сервисам, потому что используют локальные адреса хоста. В этом руководстве критерий приёмки сформулирован так: «создать дашборд, добавить плитку сервиса, настроить одну интеграцию с учётными данными и после перезапуска убедиться, что live-статус и поиск работают». Архитектура развёртывания строится от этого результата в обратную сторону.
У Homarr есть конкретная роль в стеке: searchable dashboard с live-тайлами для self-hosted-сервисов. Поэтому в production важно не то, отвечает ли порт 7575 один раз, а то, продолжают ли состояние, зависимости и публичный адрес согласованно работать после перезапуска, обновления и восстановления.
Сначала определите критерии успеха для Homarr
Не позволяйте образу Homarr случайно определять production-архитектуру. Образ предоставляет процесс на порту 7575, но для хранения данных, маршрутизации и внешних требований всё равно нужны продуманные жизненные циклы. Локальное требование среды выполнения — постоянные данные приложения и учётные данные для live-интеграций. Это должно быть отражено в плане ресурсов и монтирования: с назначенным владельцем и измеримым лимитом.
Развёртывание готово к углублённому тестированию, когда оно позволяет создать дашборд, добавить плитку сервиса, настроить одну интеграцию с учётными данными и после перезапуска подтвердить работу live-статуса и поиска. Отслеживайте эту транзакцию в логах и наблюдайте за количеством запросов виджетов, задержкой downstream API, размером данных приложения и числом одновременных клиентов дашборда. Эти наблюдения покажут, изолирует ли текущая топология нужный компонент.
Отрепетируйте рискованное изменение Homarr
Работающий контейнер необходим, но недостаточен. Индикатором уровня сервиса служит успешное выполнение операции «создать дашборд, добавить плитку сервиса, настроить одну интеграцию с учётными данными и после перезапуска подтвердить работу live-статуса и поиска», а наиболее вероятные сигналы нагрузки — количество запросов виджетов, задержка downstream API, размер данных приложения и число одновременных клиентов дашборда.
Контроль изменений важен, поскольку миграции схемы Homarr и сохранение encryption key могут повлиять на сохранённые учётные данные интеграций. Сохраните старый образ, протестируйте миграции на копии состояния и задокументируйте, поддерживается ли откат после изменения схемы. Если виджеты не могут подключиться к сервисам из-за использования локальных адресов хоста, найдите первую границу, которая отличается от рабочего окружения.
Зафиксируйте заведомо работающее развёртывание Homarr
Не используйте первый пользовательский трафик как критерий приёмки Homarr. Подготовьте безопасное тестовое состояние и выполните полную операцию «создать дашборд, добавить плитку сервиса, настроить одну интеграцию с учётными данными и после перезапуска подтвердить работу live-статуса и поиска». Зафиксируйте точный публичный URL, результат, ссылку на образ и интервал логирования, связанные с этим запуском.
Замените контейнер и повторите проверку без пересоздания данных. Затем восстановите сервис на пустом хосте; условие восстановления — возвращение дашбордов, пользователей, интеграций и custom assets, а также повторное подключение виджетов с учётными данными. На каждом этапе наблюдайте за количеством запросов виджетов, задержкой downstream API, размером данных приложения и числом одновременных клиентов дашборда. Настройте alert на ухудшение транзакции, а не на метрики бездействующего контейнера.
Одна финальная проверка должна намеренно завершиться ошибкой: отправьте безопасные тестовые данные около ресурсного или форматного лимита, связанного с этой границей: виджеты не могут подключиться к сервисам из-за использования локальных адресов хоста. Убедитесь, что сообщение Homarr указывает на соответствующую границу, а не приводит к удалению данных или бесконечному перезапуску. Верните корректное состояние и подтвердите, что та же тестовая транзакция снова выполняется успешно. Включите эту короткую проверку в 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 и следите за логами, пока создаёте дашборд, добавляете плитку сервиса, настраиваете одну интеграцию с учётными данными и после перезапуска подтверждаете работу live-статуса и поиска. Такая последовательность помогает отличить ошибку команды запуска образа от проблемы с зависимостью или правами доступа.
Volumes — только первый уровень восстановления
Для Homarr безопасность пересоздания начинается с дашбордов, пользователей, интеграций, секретов и custom assets. Подключите /appdata до начальной настройки, запишите безопасные тестовые данные и замените контейнер, чтобы доказать фактическую постоянность этого пути. Проверьте путь заменой контейнера, пока безопасные тестовые данные ещё существуют: это выявит монтирование на директорию уровнем выше или ниже нужной.
Затем протестируйте аварийное восстановление на чистом хосте. При необходимости используйте export базы данных, согласованный с состоянием приложения, и убедитесь, что дашборды, пользователи, интеграции и custom assets возвращаются, а виджеты с учётными данными снова подключаются. В руководстве по резервному копированию базы данных с проверенным восстановлением задана более строгая цель, чем простая проверка факта создания файла архива.
Не позволяйте успеху proxy скрывать сбой приложения
Браузер, API-клиент и Homarr должны использовать один и тот же origin. Для этого задайте внешний HTTPS-хост и разрешённые origins. Сохраняйте исходные host и protocol, при этом не оставляйте порт 7575 доступным как конкурирующий публичный адрес.
Руководство по диагностике недоступного сайта помогает отличить недоступный маршрут от приложения, которое отвечает, но работает неправильно. Здесь это различие особенно важно: виджеты не могут подключиться к сервисам из-за использования локальных адресов хоста. Изменения ingress исправляют только первую проблему; для второй нужны проверка логов Homarr, состояния или workload.
Закройте временный доступ, использованный при настройке
Безопасное развёртывание Homarr начинается с удаления лишних полномочий. Не меняйте encryption key после сохранения секретов интеграций; вместо этого оставьте SECRET_ENCRYPTION_KEY неизменным, защитите редактирование дашбордов и ограничьте права каждого credential для виджета.
Сгенерируйте SECRET_ENCRYPTION_KEY один раз, не храните его в Git и сохраните вместе с recovery manifest, поскольку его изменение может сделать зашифрованное или подписанное состояние приложения недействительным. Ограничьте административные маршруты, используйте private DNS для зависимостей и проверьте каждое bind mount. Если логи отправляются в централизованную систему, отфильтруйте секреты и приватное содержимое до их отправки за пределы сервера.
Перенесите повторяемую инфраструктурную работу в Dockup
Для Homarr Dockup особенно полезен на границе между образом и постоянным сервисом. Он сохраняет маршрут к 7575, TLS, значения секретов и хранилище при замене контейнеров — независимо от того, вычислительные ресурсы находятся в Dockup или на подключённом сервере.
Завершите настройку с учётом особенностей приложения: задайте внешний HTTPS-хост и разрешённые origins; подтвердите локальное требование — постоянные данные приложения и учётные данные для live-интеграций; затем выполните проверку: создайте дашборд, добавьте плитку сервиса, настройте одну интеграцию с учётными данными и после перезапуска убедитесь, что live-статус и поиск работают. Сохраните результат как deployment check, чтобы следующее обновление образа оценивалось по поведению, а не по статусу контейнера.
Часто задаваемые вопросы
Что нужно Homarr для production-развёртывания?
Направьте контейнер Homarr через порт 7575 к одному HTTPS-origin. Локальное требование среды выполнения — постоянные данные приложения и учётные данные для live-интеграций. Не считайте Homarr готовым, пока не сможете создать дашборд, добавить плитку сервиса, настроить одну интеграцию с учётными данными и после перезапуска подтвердить работу live-статуса и поиска.
Какие данные Homarr нужно включать в резервную копию?
Сохраняйте /appdata и включайте дашборды, пользователей, интеграции, секреты и custom assets в один recovery manifest. Восстановление Homarr можно считать успешным только тогда, когда дашборды, пользователи, интеграции и custom assets возвращаются, а виджеты с учётными данными снова подключаются.
Требуется ли Homarr HTTPS за reverse proxy?
Используйте HTTPS для публичного origin Homarr, а порт 7575 оставьте во внутреннем маршруте. Корректно примените настройку Homarr: задайте внешний HTTPS-хост и разрешённые origins. Для Homarr HTTPS защищает учётные данные и пользовательский контент при передаче и обеспечивает согласованное поведение клиента, зависящее от origin.
Как тестировать обновление Homarr?
Восстановите текущее состояние Homarr в изолированном развёртывании, примените кандидатную версию и повторите приёмочную транзакцию. Уделите особое внимание тому, что миграции схемы Homarr и сохранение encryption key могут повлиять на сохранённые учётные данные интеграций. Сохраняйте предыдущий образ Homarr, пока не будут понятны границы миграции данных и отката.