Как установить и настроить Homepage на VPS

MAATRIX

Когда на сервере крутится десяток сервисов — Portainer, Traefik, пара веб-приложений, мониторинг, — держать все адреса и логины в закладках браузера быстро надоедает. Homepage решает это одной статичной страницей: карточки сервисов, живые виджеты статуса, поиск и закладки в одном месте. Ставится через Docker за десять минут, настраивается текстовыми YAML-файлами без базы данных и без сборки — ниже пошагово, как поднять его на VPS и подключить к реальным сервисам.

Что такое Homepage и когда он нужен

Homepage (gethomepage/homepage) — открытый дашборд-стартовая страница, написанный на Next.js. В отличие от старых аналогов вроде Heimdall, он не хранит данные в базе — вся конфигурация в YAML-файлах на диске, поэтому дашборд легко переносить между серверами и версионировать в git. У него есть встроенные интеграции («виджеты») с десятками сервисов: Portainer, Traefik, Docker-контейнерами напрямую, Uptime Kuma, Pi-hole, *arr-приложениями, системными метриками сервера и т.д. — виджет тянет живые данные (статус, версию, использование ресурсов) прямо на карточку.

Смысл ставить его именно на VPS, а не локально: если у вас один сервер с несколькими сервисами за Traefik или Caddy, Homepage становится точкой входа — заходите по одному адресу и видите статус и ссылки на всё сразу, а не держите их в голове. Для домашней лаборатории на десяток контейнеров это особенно ощутимо, но и на «боевом» VPS с 3-5 сервисами удобство того стоит.

Подготовка сервера: Docker и рабочая директория

Homepage официально распространяется как Docker-образ, поэтому сначала нужен установленный Docker и Docker Compose. Если Docker ещё не стоит — процесс для Ubuntu 24.04 подробно разобран в статье про установку Docker с нуля, здесь только минимальная проверка:

docker --version
docker compose version

Если обе команды отвечают версией, а не ошибкой — можно двигаться дальше. Создайте рабочую директорию под дашборд и подпапку под конфиги:

mkdir -p /opt/homepage/config
cd /opt/homepage

Все настройки Homepage — это YAML-файлы, которые монтируются внутрь контейнера как том. Файлы, отсутствующие при первом запуске, контейнер создаёт сам с дефолтными значениями, так что стартовать можно с пустой папки.

Установка через Docker Compose

Создайте docker-compose.yml в /opt/homepage:

services:
  homepage:
    image: ghcr.io/gethomepage/homepage:latest
    container_name: homepage
    restart: unless-stopped
    ports:
      - "3000:3000"
    volumes:
      - ./config:/app/config
      - /var/run/docker.sock:/var/run/docker.sock:ro
    environment:
      - HOMEPAGE_ALLOWED_HOSTS=dashboard.example.com,localhost:3000

Пара нюансов, на которых спотыкаются в первый раз:

• Docker-сокет монтируется в режиме :ro — этого достаточно, чтобы Homepage читал список контейнеров и их статус для виджетов и автообнаружения по label’ам. Писать в сокет дашборду не нужно.
• HOMEPAGE_ALLOWED_HOSTS обязателен. Актуальные версии Homepage проверяют заголовок Host входящего запроса и отклоняют его, если домен не в списке разрешённых — это защита от подмены хоста. Забыли добавить сюда свой домен — получите ошибку 500 при открытии страницы. Перечисляйте через запятую все адреса, по которым будете заходить (домен, localhost:3000 для проверки, IP при необходимости).

Поднимаем:

cd /opt/homepage
docker compose up -d

Проверить, что контейнер жив и без рестартов:

docker compose ps
docker compose logs -f homepage

Открываем http://IP_сервера:3000 — если в HOMEPAGE_ALLOWED_HOSTS указан IP или вы зашли через localhost по SSH-туннелю, увидите дефолтную страницу с пустыми блоками виджетов ресурсов и одной группой сервисов-заглушек.

Конфигурация: где какие файлы и за что отвечают

После первого запуска в /opt/homepage/config появляются несколько YAML-файлов — с ними и работаем дальше:

Минимальный settings.yaml для старта:

title: Панель сервера
theme: dark
color: slate
layout:
  Инфраструктура:
    style: row
    columns: 3
  Приложения:
    style: row
    columns: 4

После правки любого YAML-файла Homepage подхватывает изменения на лету в большинстве случаев — обновление страницы в браузере достаточно, перезапуск контейнера не требуется. Если что-то не применилось — проверьте docker compose logs -f homepage: YAML чувствителен к отступам, и ошибка парсинга обычно там же и всплывает с указанием строки.

Карточки сервисов и виджеты статуса

Основная ценность Homepage — не список ссылок, а живой статус. Пример services.yaml для типичного набора VPS-сервисов:

- Инфраструктура:
    - Portainer:
        href: https://panel.example.com
        icon: portainer.png
        description: Управление контейнерами
        widget:
          type: portainer
          url: https://panel.example.com
          env: 1
          key: ptr_eyJhbGciOi...

    - Traefik:
        href: https://traefik.example.com
        icon: traefik.png
        description: Reverse proxy
        widget:
          type: traefik
          url: http://traefik:8080

- Приложения:
    - Nextcloud:
        href: https://cloud.example.com
        icon: nextcloud.png
        description: Файловое хранилище
        widget:
          type: nextcloud
          url: https://cloud.example.com
          username: admin
          password: app-password-here

Иконки Homepage подтягивает из встроенной библиотеки [walkxcode/dashboard-icons] по имени файла (portainer.png, traefik.png и т.д.) — искать и загружать их вручную не нужно, достаточно правильного имени. Для сервисов без готовой иконки можно указать прямую ссылку на PNG/SVG или использовать иконки из набора Material Design Icons через префикс mdi-.

Ключи и токены для виджетов (как key у Portainer) генерируются в самом сервисе — в Portainer это Access Token в настройках пользователя. Хранить их прямо в services.yaml не лучшая практика для публичного репозитория, но для локальной конфигурации на своём сервере это стандартный подход самого Homepage; если конфиги лежат в git — используйте .env-переменные внутри YAML ({{HOMEPAGE_VAR_PORTAINER_KEY}}) вместо значений в открытом виде.

Альтернатива ручному описанию каждого сервиса — автообнаружение через Docker-label’ы. Добавьте в docker-compose.yml нужного сервиса такие метки:

labels:
  - homepage.group=Приложения
  - homepage.name=Nextcloud
  - homepage.icon=nextcloud.png
  - homepage.href=https://cloud.example.com
  - homepage.description=Файловое хранилище

Homepage сам найдёт контейнер через смонтированный Docker-сокет и добавит карточку — удобно, если сервисов много и они регулярно пересобираются: не нужно синхронизировать services.yaml вручную.

Системные виджеты и публикация в интернет

В widgets.yaml настраивается верхняя информационная панель — она не про конкретный сервис, а про сам сервер и общую сводку:

- resources:
    cpu: true
    memory: true
    disk: /
    label: Сервер

- search:
    provider: duckduckgo
    target: _blank

- datetime:
    text_size: lg
    format:
      timeStyle: short
      dateStyle: long

Виджет resources с disk: / покажет загрузку CPU, RAM и свободное место на корневом разделе прямо на дашборде — полезно, чтобы не заходить по SSH ради df -h каждый раз.

Для выхода в интернет дашборд нужно спрятать за reverse-proxy с HTTPS — открывать порт 3000 напрямую в мир не стоит: у Homepage нет встроенной авторизации, кто угодно с адресом увидит все карточки и статусы сервисов. Через Caddy (конфигурация описана в статье про Caddy с авто-SSL) проксирование выглядит так:

dashboard.example.com {
    reverse_proxy localhost:3000
    basicauth {
        admin $2a$14$хэш_пароля_bcrypt
    }
}

Директива basicauth — это минимальная защита паролем на уровне прокси, раз своей авторизации у Homepage нет. Если сервисы уже проксируются через Traefik (см. настройку Traefik на VPS), добавьте к контейнеру homepage лейблы с middleware базовой аутентификации — принцип тот же, что и для остальных внутренних панелей вроде Portainer. Для более серьёзного сценария — SSO, 2FA, единый вход во все внутренние панели — ставят перед дашбордом Authelia или Authentik, но для одного личного дашборда basic-auth через прокси обычно достаточно.

Частые вопросы