Как развернуть Homepage на своём сервере в 2026 году: разрешённые хосты, виджеты и конфигурация

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

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

Выберите минимально необходимую топологию Homepage

Полезная схема Homepage показывает публичный маршрут, приватный порт 3000, границу состояния и все вспомогательные требования. Отметьте, какие стрелки передают credentials, а какие обозначают обычный пользовательский трафик. Внешнее требование Homepage — конфигурация только для чтения и credentials для опциональных виджетов сервисов. Проверьте исходящие DNS-запросы, TLS и поведение провайдера, не публикуя ещё один входящий сервис.

Подтвердите схему одним реальным действием: загрузите сервисы и закладки, вызовите несколько рабочих виджетов, протестируйте поиск и перезапустите сервис после редактирования YAML-файла конфигурации. Основная нагрузка, скорее всего, будет связана с fan-out виджетов, медленными downstream API, разрешением DNS и частотой обновления браузерного dashboard. Отслеживайте именно этот путь, а не рассматривайте все HTTP-запросы как равноценные.

Обновляйте Homepage без догадок

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

Рассматривайте обновления как изменения данных: ключи конфигурации и интеграции виджетов могут меняться, поэтому перед обновлением image проверяйте YAML и поведение провайдера. Фиксируйте версии, проводите репетицию на восстановленном состоянии и сохраняйте предыдущий image, пока rollback остаётся возможным. Если хост отклоняется или отступы в YAML не позволяют загрузить конфигурацию, сохраните логи до перезапуска: обычно именно в них находится сообщение с причиной.

Приёмочные проверки Homepage перед использованием в production

До появления реальных пользователей подготовьте release worksheet для Homepage. В нём должны быть указаны зафиксированный image, порт 3000, canonical origin, постоянные пути и владелец конфигурации только для чтения и credentials для опциональных виджетов сервисов. Добавьте ожидаемый результат этой операции: загрузку сервисов и закладок, вызов нескольких рабочих виджетов, проверку поиска и перезапуск после редактирования YAML-файла конфигурации.

Используйте worksheet после обычной замены и после чистого восстановления. Восстановление считается успешным только в том случае, если возвращаются сервисы, закладки, виджеты и custom assets, а все критически важные виджеты заметно обрабатывают сбои downstream-сервисов. Также соберите короткий resource trace, охватывающий fan-out виджетов, медленные downstream API, разрешение DNS и частоту обновления браузерного dashboard. Храните его рядом с release, чтобы будущие изменения capacity сравнивались на одинаковой нагрузке.

Добавьте один контролируемый сбой: временно запретите тестовый путь, используемый конфигурацией только для чтения и credentials для опциональных виджетов сервисов. Убедитесь, что Homepage сообщает о проблеме на правильной границе, восстановите корректное состояние и повторно выполните операцию. Это проверяет не только успешный сценарий, но и видимость ошибок, не позволяя внешне исправному интерфейсу скрывать сломанный worker, callback или подключение к базе данных.

Сделайте запуск Homepage воспроизводимым

Используйте контейнер как заменяемый runtime, а не как источник истины.

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

Разрешите и проверьте исходящий или client-side путь, необходимый для конфигурации только для чтения и credentials для опциональных виджетов сервисов. Перед публикацией сервиса проверьте пользователя контейнера, доступные для записи пути и привязанный listener. Выполните полное действие — загрузите сервисы и закладки, вызовите несколько рабочих виджетов, протестируйте поиск и перезапустите сервис после редактирования YAML-файла конфигурации — и сохраните точную ссылку на image, с которым был получен результат.

Отделите заменяемые контейнеры от постоянных данных

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

Создавайте backup с учётом источника данных: при необходимости используйте logical dump для работающих баз данных, а файлы копируйте только из согласованного состояния. Храните одну зашифрованную копию отдельно от хоста Homepage. Критерий успешного восстановления должен быть конкретным: сервисы, закладки, виджеты и custom assets возвращаются, а все критически важные виджеты заметно обрабатывают сбои downstream-сервисов. В руководстве по backup с проверенным восстановлением объясняется, почему одного успешного выполнения job недостаточно.

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

Браузер, API-клиент и Homepage должны использовать один origin. Чтобы добиться этого, укажите разрешённые хосты для точного домена и proxy hostname. Сохраняйте исходные host и protocol, не делая порт 3000 конкурирующим публичным адресом.

Руководство по устранению проблемы с недоступным сайтом помогает отличить недоступный маршрут от приложения, которое отвечает. В данном случае это различие важно: хост отклоняется или отступы в YAML не позволяют загрузить конфигурацию. Изменения ingress исправляют только первый случай; во втором нужно проверять логи Homepage, состояние или workload.

Решения по безопасности, специфичные для Homepage

Не переносите предположения о безопасности из локального tutorial. Специфическая проблема Homepage — публикация API keys виджетов в открытом repository. Поэтому в production следует точно задать разрешённые хосты, а API keys виджетов хранить в environment или config на основе secrets, а не в открытом repository.

HOMEPAGE_ALLOWED_HOSTS управляет поведением, но не обеспечивает конфиденциальность; проверьте его тип и значение, а настоящие credentials Homepage храните отдельно. Ограничьте доступ к файловой системе и сети, защитите setup endpoints и задайте лимиты на upload, requests или execution для fan-out виджетов, медленных downstream API, разрешения DNS и частоты обновления браузерного dashboard.

Как Dockup упрощает работу с Homepage

Для Homepage Dockup особенно полезен на границе между image и постоянным сервисом. Он сохраняет маршрут к 3000, TLS, значения secrets и storage при замене контейнеров независимо от того, где находится compute — в Dockup или на подключённом сервере.

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

Часто задаваемые вопросы

Что нужно Homepage для развёртывания в production?

Направьте контейнер Homepage через порт 3000 на один HTTPS origin. Внешнее требование для delivery — конфигурация только для чтения и credentials для опциональных виджетов сервисов. Не объявляйте Homepage готовой, пока не сможете загрузить сервисы и закладки, вызвать несколько рабочих виджетов, протестировать поиск и перезапустить сервис после редактирования YAML-файла конфигурации.

Какие данные Homepage нужно включать в backup?

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

Нужен ли Homepage HTTPS за reverse proxy?

Используйте HTTPS для публичного origin Homepage, а порт 3000 оставьте во внутреннем маршруте. Корректно примените настройку Homepage: укажите разрешённые хосты для точного домена и proxy hostname. Для Homepage HTTPS защищает credentials или пользовательский контент при передаче и обеспечивает согласованное поведение клиента, зависящее от origin.

Как тестировать обновление Homepage?

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