Homarr в Docker Compose: готовый файл

MAATRIX

Когда на сервере крутится десяток сервисов — Portainer на одном порту, Nextcloud на другом, Grafana где-то ещё — держать в голове адреса и логиниться в каждый по отдельности быстро надоедает. Homarr решает это одной страницей: карточки всех приложений, статус контейнеров и нужные виджеты в одном месте, а настраивается всё мышкой, без правки YAML при каждом изменении. Ниже — рабочий docker-compose.yml, который поднимается за пять минут, и что делать дальше, чтобы дашборд не превратился в очередной неухоженный сервис на сервере.

Что такое Homarr и когда он лучше Homepage

Homarr — self-hosted дашборд-агрегатор: единая страница со ссылками на все ваши сервисы, сгруппированные по бордам и секциям, плюс виджеты (погода, календарь, RSS, заметки, статус Docker-контейнеров, интеграции с *arr-стеком и медиасерверами). Ключевое отличие от популярного конкурента Homepage — интерфейс редактирования. В Homepage конфигурация живёт в YAML-файлах (services.yaml, widgets.yaml и так далее), и любое изменение — это правка текста и перезапуск. В Homarr борд редактируется прямо в браузере: перетащили карточку, изменили размер плитки, добавили виджет через поиск — и всё сохранилось сразу, без доступа к серверу.

Это удобно, если дашбордом пользуется не только вы (например, помогаете с сервером ещё кому-то) или если вы просто не хотите держать конфиги в голове. Плата за удобство — Homarr тяжелее: у него есть собственная база данных (SQLite по умолчанию, можно вынести на внешний PostgreSQL) и авторизация со своими пользователями, тогда как Homepage — это, по сути, статический рендер YAML почти без состояния.

Если нужна максимально лёгкая read-only страница без базы и без множественных пользователей — присмотритесь к Homepage. Если хочется редактировать борд руками из браузера, показывать статус контейнеров и завести отдельные логины для домашних — берите Homarr.

Готовый docker-compose.yml

Актуальная ветка Homarr (v1 и новее) собрана на едином образе с встроенной базой — отдельный контейнер для БД не нужен, если вы согласны на SQLite (для одного-двух пользователей этого достаточно с большим запасом). Создайте рабочую директорию и сгенерируйте ключ шифрования — он обязателен, без него контейнер откажется стартовать:

mkdir -p /opt/homarr/{data,configs,icons}
cd /opt/homarr
openssl rand -hex 32

Скопируйте вывод команды — это будет SECRET_ENCRYPTION_KEY. Он шифрует сохранённые в базе токены интеграций (API-ключи Sonarr, Radarr и так далее), поэтому хранить его нужно так же аккуратно, как пароль от базы данных, а не как случайную строку для галочки.

# /opt/homarr/docker-compose.yml
services:
  homarr:
    image: ghcr.io/homarr-labs/homarr:latest
    container_name: homarr
    restart: unless-stopped
    ports:
      - "7575:7575"
    environment:
      - SECRET_ENCRYPTION_KEY=${HOMARR_SECRET_KEY}
      - TZ=Europe/Moscow
    volumes:
      - ./data:/appdata
      - ./configs:/app/data/configs
      - ./icons:/app/public/icons
      # опционально: статус и управление контейнерами прямо с борда
      - /var/run/docker.sock:/var/run/docker.sock:ro
    healthcheck:
      test: ["CMD", "wget", "-qO-", "http://localhost:7575/api/health"]
      interval: 30s
      timeout: 5s
      retries: 3

Рядом положите .env:

# /opt/homarr/.env
HOMARR_SECRET_KEY=вставьте_сюда_вывод_openssl

Точный список переменных и путь до healthcheck-эндпоинта могут немного отличаться между релизами — проект активно развивается, поэтому перед деплоем в продакшен стоит свериться с текущим README на GitHub Homarr, особенно если вы обновляетесь с более старой версии (там менялась и схема БД, и набор переменных при переходе на новую архитектуру).

Поднимаем:

docker compose up -d
docker compose logs -f homarr

Дашборд откроется на http://IP-сервера:7575.

Первый запуск и создание борда

При первом заходе Homarr предложит создать администратора — логин, пароль, при желании email. Это отдельная встроенная система пользователей, никак не связанная с системными аккаунтами сервера, так что пароль стоит генерировать так же, как для любого админ-панели с доступом в интернет:

openssl rand -base64 18

После логина вы попадаете на пустой борд. Структура простая: борд (board) — это страница целиком, на ней можно разместить несколько секций (section) — сворачиваемых блоков-заголовков вроде «Медиа», «Инфраструктура», «Мониторинг», — а внутри секций уже лежат плитки (tile) — либо ссылка на приложение, либо виджет.

Добавление приложения — через кнопку редактирования борда (иконка карандаша в углу) → «Add item» → «App». Указываете название, URL и иконку: у Homarr встроен поиск по огромной библиотеке готовых иконок сервисов (проект dashboard-icons) — начинаете печатать «grafana» или «portainer», и находится подходящий SVG без загрузки файлов вручную. Плитку можно растянуть по сетке, задать поведение при клике (открыть в новой вкладке, во всплывающем окне iframe, или сразу показать статус пинга).

Все борды хранятся в базе, поэтому изменения переживают перезапуск контейнера — важно только не потерять волюм ./data, о бэкапе которого ниже.

Виджеты и Docker-интеграция

Ради этого Homarr обычно и ставят вместо простой страницы со ссылками. Из полезных для сервера виджетов:

• Docker — список запущенных контейнеров с их статусом (running/stopped/unhealthy), потреблением CPU и памяти, кнопками start/stop/restart прямо с дашборда. Требует смонтированный docker.sock.
• Ping / Health Monitor — проверка доступности сервисов по URL с историей аптайма.
• Weather, Calendar (iCal), RSS Feed, Notebook — общеинформационные, не привязаны к серверу.
• Интеграции с медиастеком (Sonarr, Radarr, Overseerr, qBittorrent, Jellyfin/Plex) и с мониторингом — если вы держите такой стек, виджеты подтягивают очередь загрузок, активные сессии и т.д. через API этих приложений.

Docker-виджет — самая частая причина держать /var/run/docker.sock смонтированным в контейнер Homarr. Стоит честно понимать риск: контейнер с доступом к сокету Docker фактически имеет root-доступ к хосту — через сокет можно поднять новый контейнер с примонтированным /, что эквивалентно полному доступу к файловой системе сервера. Для личного сервера с закрытым доступом извне это обычно приемлемый компромисс, но если Homarr смотрит в интернет напрямую — лучше не открывать порт 7575 наружу вообще, а заходить только через VPN или reverse proxy с авторизацией. Общие принципы разбирали в статье про безопасность Docker — сокет-прокси с ограниченным набором прав (вместо прямого монтирования сокета) снижает риск, если хочется перестраховаться.

HTTPS через reverse proxy

Открывать Homarr наружу по http://IP:7575 не стоит — админка со своими логинами и токенами интеграций должна ходить по HTTPS. Если на сервере уже есть Traefik, добавьте лейблы прямо в сервис homarr, без публикации порта наружу:

services:
  homarr:
    image: ghcr.io/homarr-labs/homarr:latest
    # ports больше не публикуем наружу, только внутри docker-сети
    networks:
      - traefik-network
    environment:
      - SECRET_ENCRYPTION_KEY=${HOMARR_SECRET_KEY}
    volumes:
      - ./data:/appdata
      - ./configs:/app/data/configs
      - ./icons:/app/public/icons
      - /var/run/docker.sock:/var/run/docker.sock:ro
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.homarr.rule=Host(`dash.example.com`)"
      - "traefik.http.routers.homarr.entrypoints=websecure"
      - "traefik.http.routers.homarr.tls.certresolver=letsencrypt"
      - "traefik.http.services.homarr.loadbalancer.server.port=7575"

networks:
  traefik-network:
    external: true

Как поднять сам Traefik с автоматическим Let's Encrypt — подробно в статье «Traefik как reverse proxy для Docker». Если Traefik пока нет и заводить его ради одного дашборда не хочется — Nginx Proxy Manager с готовым UI для сертификатов тоже подойдёт. Дополнительно на уровне reverse proxy имеет смысл повесить Basic Auth или ограничить доступ по IP/VPN — встроенная авторизация Homarr не заменяет defense-in-depth, если дашборд открыт всему интернету.

Бэкап и обновление

Всё состояние Homarr — борды, пользователи, токены интеграций, загруженные иконки — лежит в смонтированных волюмах ./data и ./configs. Бэкапить нужно именно их, а не сам контейнер:

# простой бэкап tar
docker compose stop homarr
tar czf homarr-backup-$(date +%F).tar.gz data configs icons
docker compose start homarr

Для регулярного автоматического бэкапа volume-директорий на другой сервер или в объектное хранилище удобнее взять restic или Duplicati. Если работаете с несколькими независимыми стеками на одном сервере, общие грабли с бэкапом именно Docker-volume'ов (а не бинда) собраны в статье про бэкап Docker volume.

Обновление — стандартное для одноконтейнерных стеков:

docker compose pull homarr
docker compose up -d homarr

Перед обновлением на мажорную версию (например, при явном скачке номера версии в теге образа) обязательно сделайте бэкап data — при смене архитектуры БД (это уже случалось у проекта при переходе на текущую линейку) миграция автоматическая, но откатиться назад без бэкапа будет нельзя. Если предпочитаете автообновления без ручного контроля — Watchtower умеет подтягивать новые теги по расписанию, но для сервиса с базой данных стоит трижды подумать: накатывать мажорные апдейты в БД без присмотра рискованно.

Ресурсы и производительность

Сам Homarr — Node.js-приложение, в простое ест немного: на 1 vCPU / 1 GB RAM он спокойно работает вместе с парой других лёгких контейнеров, узким местом обычно становится не CPU, а диск под SQLite-базу при активном использовании Docker-виджета (он периодически опрашивает сокет). Если планируете десятки приложений на борде и несколько пользователей одновременно — разумно взять минимум 2 GB RAM на сервер целиком, чтобы Homarr не конкурировал за память с сервисами, которые он же и отображает. Для сравнения: чисто статический Homepage без базы данных на старте требует заметно меньше — Homarr платит памятью и диском за удобство редактирования из браузера.

Точные цифры сильно зависят от количества виджетов с внешними интеграциями (каждый — это периодический запрос к чужому API) и от объёма истории в базе, поэтому ориентируйтесь на приведённые числа как на стартовую точку, а не как на гарантированный лимит.

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