Homepage

Обзор

Homepage — стартовая страница для домашнего сервера. Она группирует сервисы и закладки, ищет их через Quick Launch и показывает дополнительные виджеты интеграций. Подойдёт тем, кому удобнее редактировать YAML, чем обслуживать портал с базой данных.

Начальные ссылки ведут на панель и официальную публичную документацию. Замените их своими адресами в config/services.yaml; сами приложения по этим ссылкам не устанавливаются. Панель дополняет мониторинг сервисов.

Начиная с v2 upstream поддерживает пароль и OIDC. Рецепт включает один общий пароль и случайный секрет сессий. OIDC не настроен. Раздельных прав пользователей, нативных SAML и MFA в рецепте нет; MFA можно получить у внешнего провайдера идентификации.

YAML панели, custom CSS/JavaScript и логи находятся в подключённом каталоге конфигурации. Не нужны база данных, Docker socket, Kubernetes, API-ключи или облачный аккаунт. Виджеты ресурсов видят окружение контейнера. Отправка поискового запроса может обращаться к выбранному поисковому сервису.

Для домашней инфраструктуры Homepage заменяет часть start.me со ссылками на сервисы, но не повторяет облачную совместную работу. В репозитории upstream находится GPL версии 3; метка образа всё ещё указывает Apache-2.0, поэтому источником лицензии на странице служит LICENSE репозитория.

Официальные источники: установка и вход, конфигурация, Docker, исходники v2.7.0.

Оценка безопасности (2026-10-24): включён пароль, loopback, процесс без root и нет Docker socket. Публичному доступу всё ещё нужны HTTPS и внешняя защита входа. Это разбор конфигурации, а не скан уязвимостей образа.

Пошаговая инструкция

Ubuntu и Debian

Подойдут Ubuntu 24.04 LTS или Debian 12/13, Docker Engine и Docker Compose >=2.24.0. Установите Docker из официального репозитория вместе с Compose plugin. Скачайте рецепт целиком, включая config/.

cp .env.example .env
chmod 600 .env
openssl rand -hex 24
openssl rand -hex 32

Первое случайное значение впишите в HOMEPAGE_AUTH_PASSWORD, второе — в HOMEPAGE_AUTH_SECRET. Замените значения CHANGE_ME; пустые значения недопустимы. Укажите URL и разрешённые Host, затем запустите:

docker compose config --quiet
docker compose pull
docker compose up -d --wait
docker compose ps

Откройте http://localhost:3000, введите пароль и настройте YAML в config/. Инициализатор меняет владельца на UID/GID 1000; при необходимости редактируйте через sudo. После изменений перезапускайте homepage. Все вошедшие посетители видят общую конфигурацию.

VPS

Нужны домен, HTTPS, firewall и зашифрованные внешние backup. Оставьте порт 3000 на loopback, наружу выставляйте только прокси. Закройте вход VPN/списком IP либо настройте ограничение попыток на внешнем прокси: встроенного лимита нет. Пример Nginx включает ограничение; для Caddy и Traefik его нужно организовать отдельно.

Доверенная LAN или VPN

По умолчанию доступ только через loopback. Предпочтительны SSH-туннель (ssh -L 3000:127.0.0.1:3000 user@server) или VPN/прокси. Для прямой LAN явно поменяйте опубликованный адрес Compose и ограничьте доступ firewall. В HOMEPAGE_EXTERNAL_URL укажите точный адрес браузера, в HOMEPAGE_ALLOWED_HOSTS — его host:port. Не используйте *.

Домен и HTTPS

Для https://home.example.com задайте HOMEPAGE_EXTERNAL_URL=https://home.example.com и HOMEPAGE_ALLOWED_HOSTS=home.example.com, затем пересоздайте сервис. URL определяет защищённые cookies сессии и должен совпадать с реальным адресом браузера.

Caddy

Подключите proxy/Caddyfile на хосте после настройки DNS. Caddy получает TLS автоматически. Добавьте VPN/ограничение IP или отдельно настроенный лимит попыток входа.

Nginx

Используйте proxy/nginx.conf, предварительно получите сертификаты и проверьте sudo nginx -t. limit_req_zone располагается в контексте http. Обработчик пароля ограничен пятью запросами в минуту с burst пять; подберите значения для своих пользователей и наблюдения.

Traefik

Загрузите proxy/traefik.yaml через file provider с entry point websecure и resolver letsencrypt. Пример предполагает Traefik на хосте; контейнер не видит loopback хоста без подходящей сети. Добавьте VPN/ограничение IP либо защиту входа на внешнем прокси.

Данные и окружение

HOMEPAGE_CONFIG_DIR (по умолчанию ./config) подключён к /app/config: настройки, сервисы, закладки, виджеты, custom-файлы и логи. При переносе рецепта используйте абсолютный путь и не делите его с другим приложением. Базы данных нет. Сохраняйте пользовательские иконки внутри этого каталога, если они нужны конфигурации.

Все параметры .env.example:

Для смены пароля или секрета поправьте .env и пересоздайте сервис. Не помещайте секреты в custom CSS/JavaScript и статику: они публичны. Ключам виджетов выдавайте минимум прав. Docker/Kubernetes discovery и OIDC в рецепте не включены.

Резервная копия

bash backup.sh

Скрипт останавливает запись, сохраняет весь каталог конфигурации, .env и Compose, затем возвращает прежнее состояние запуска. Права архивов — 600. Копируйте их за пределы сервера и шифруйте: внутри могут быть API-ключи и секреты входа. Временный кеш образа и local storage браузера не входят в backup. Внешние пользовательские ресурсы вне config сохраняйте отдельно.

Восстановление

Восстановление заменяет всю конфигурацию. Используйте только собственный доверенный архив. Один раз запустите рецепт для создания контейнера и mount, вручную сравните архивную configuration.env с текущей .env и согласуйте версию. Архивное окружение не исполняется и не активируется автоматически.

bash restore.sh /safe/path/homepage-backup.tar

Скрипт проверяет обязательные файлы до остановки, делает страховочный backup, заменяет каталог конфигурации и ждёт health. При ошибке распаковки сервис остаётся остановлен. Войдите и проверьте ссылки и закладки. Возврат старого секрета может снова разрешить ещё действующие старые cookies; при необходимости смените секрет.

Обновление

Прочтите release notes, сделайте backup, установите новый явный HOMEPAGE_VERSION и выполните docker compose pull && docker compose up -d --wait. Не используйте latest. Проверьте вход и каждую интеграцию. Для текущего рецепта это замена образа на месте; перед будущими major-релизами изучайте отдельные инструкции.

Откат

Остановите homepage, верните прежний фиксированный тег в .env, скачайте и один раз запустите его, затем восстановите соответствующий архив до обновления через restore.sh. Сверьте окружение и проверьте вход/виджеты. Миграций БД в рецепте нет, но новые параметры YAML могут не поддерживаться старым образом: возвращайте соответствующую конфигурацию.

Остановка и удаление

docker compose down удаляет контейнеры и сети, сохраняя bind-каталог. Для полного удаления сначала выгрузите backup, выполните docker compose down --volumes и отдельно удалите только выбранный HOMEPAGE_CONFIG_DIR и закрытую .env, проверив абсолютные пути. Это уничтожит настройки и ключи внутри. DNS, прокси и ненужные backup удаляются отдельно.

Официальное руководство по доступу описывает пароль/OIDC, публичную статику, проверку Host и отсутствие встроенного лимита входа.

Сообщить о проблеме с рецептом

Рассказать, как прошло на вашем сервере

Откроется предзаполненный issue на GitHub. Нужен аккаунт GitHub; после отправки сообщение будет публичным.

Диагностика

Диагностика

docker compose ps
docker compose logs --tail=100 homepage
docker compose config --quiet
curl -fsS http://127.0.0.1:3000/api/healthcheck

Host validation failed: разрешите точный адрес браузера с портом в HOMEPAGE_ALLOWED_HOSTS. Не ставьте wildcard. Health с внутренним Host 127.0.0.1:3000 не доказывает доступность внешнего адреса.

Вход зацикливается или cookie не сохраняется: HOMEPAGE_EXTERNAL_URL должен совпадать со схемой и адресом браузера. Для HTTPS cookie защищённая и не работает через HTTP. После изменения .env пересоздайте контейнер.

Ошибка YAML или нет ссылок: проверяйте отступы в settings/services/bookmarks/widgets. Закладки содержат дополнительный список с href, сервисы — объект. Перезапустите приложение. Неверная конфигурация может сломать панель даже при успешном health.

Permission denied: каталог config и logs должны быть доступны UID/GID 1000. Инициализатор меняет владельца рекурсивно; не указывайте системную или чужую папку. При NFS/root-squash настройте права на стороне хранилища.

Виджет не работает: URL должен быть доступен из контейнера; localhost указывает на сам Homepage. Проверьте минимальные права токена. Рецепт не подключает Docker socket и Kubernetes и не устанавливает связанные приложения.

Слишком много попыток входа: ограничивайте обработчик пароля на прокси или используйте VPN/IP. В логах есть Failed password sign-in attempt; не публикуйте дампы конфигурации с секретами.

Backup/restore: запускайте из полного рецепта с его .env; для другого env используйте FOSSARY_ENV_FILE. Архив сохраняет секреты. При неудачной распаковке сервис остаётся остановлен: проверьте логи, свободное место, права и страховочный архив перед повтором. На чистой машине сначала запустите рецепт один раз.