Homarr на сервере: частые ошибки и решения

MAATRIX

Homarr — удобный дашборд-агрегатор: одна страница с плитками всех ваших сервисов, drag-and-drop раскладка, виджеты погоды, RSS, статуса Docker-контейнеров. На бумаге всё просто — поднял контейнер, зашёл на порт, расставил виджеты. На практике почти каждый, кто ставит Homarr на свежий VPS, натыкается на одну и ту же пачку граблей: контейнер не видит Docker-сокет, конфиг теряется после перезапуска, интеграции падают с 401, а за reverse-proxy дашборд превращается в белый экран. Разберём эти ошибки по порядку — с командами и конкретными правками конфигов.

Быстрая установка: минимальный рабочий docker-compose

Прежде чем разбирать ошибки, зафиксируем базовый вариант, от которого будем отталкиваться. Homarr начиная с версии 1.x хранит настройки в SQLite и на файловой системе, поэтому volume для данных обязателен — без него любая переустановка контейнера обнуляет весь дашборд.

services:
  homarr:
    container_name: homarr
    image: ghcr.io/homarr-labs/homarr:latest
    restart: unless-stopped
    ports:
      - "7575:7575"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
      - ./homarr-data/configs:/appdata/configs
      - ./homarr-data/icons:/appdata/icons
      - ./homarr-data/data:/appdata/data
    environment:
      - SECRET_ENCRYPTION_KEY=замените_на_свой_ключ_64_символа

Ключевые моменты, которые обычно упускают:

• SECRET_ENCRYPTION_KEY нужен для шифрования сохранённых паролей интеграций (Sonarr, Portainer API и т.д.). Сгенерировать: openssl rand -hex 32.
• Сокет Docker монтируется :ro (только чтение) — Homarr читает список контейнеров, но не должен получать право их менять с хоста без вашего ведома.
• Каталог ./homarr-data должен существовать и принадлежать тому же пользователю, что запускает docker compose — иначе первая же ошибка будет про права на запись.

Если вы ещё не разворачивали прод-окружение с нуля, полезно сначала пройти пошаговую установку Docker Compose для продакшена — Homarr без правильно настроенного Docker-стека сам по себе бесполезен.

Ошибка 1: контейнер запускается, но список сервисов Docker пуст

Самая частая жалоба: Homarr открывается, но виджет "Docker containers" показывает пустой список или ошибку permission denied в логах.

Причина почти всегда одна — сокет не примонтирован или примонтирован с неверными правами. Проверьте:

docker exec -it homarr ls -la /var/run/docker.sock
docker logs homarr --tail 50 | grep -i docker

Если в логах видно EACCES или permission denied while trying to connect to the Docker daemon socket — значит внутри контейнера пользователь Homarr не входит в группу, владеющую сокетом на хосте. Варианты решения:

1. Добавить в compose переменную, которая заставит образ поднять GID группы docker динамически (некоторые сборки Homarr это поддерживают через PGID/docker-socket-proxy).
2. Использовать docker-socket-proxy — прокси-контейнер, который отдаёт Homarr только read-only API Docker, не открывая сокет напрямую. Это заметно безопаснее, особенно если сервер смотрит в интернет:

  socket-proxy:
    image: tecnativa/docker-socket-proxy
    container_name: socket-proxy
    restart: unless-stopped
    environment:
      - CONTAINERS=1
      - POST=0
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
    networks:
      - homarr-internal

  homarr:
    # ...
    environment:
      - DOCKER_HOST=tcp://socket-proxy:2375
    networks:
      - homarr-internal

networks:
  homarr-internal:
    internal: true

Такой прокси не даёт Homarr создавать или останавливать контейнеры — только читать статус. Если дашборд стоит на сервере, куда заходят несколько человек, это стоит настроить сразу.

Ошибка 2: после `docker compose down` пропали все настроенные плитки

Это классическая ошибка "забыли volume". Если вы монтировали не отдельные подпапки, а весь /appdata целиком, или вообще запускали контейнер без -v, при пересоздании (docker compose up -d --force-recreate или после обновления образа) все настройки исчезают — Homarr стартует с чистого листа.

Проверить, реально ли данные лежат вне контейнера:

ls -la ./homarr-data/data
docker inspect homarr --format '{{ json .Mounts }}' | python3 -m json.tool

Если каталог homarr-data пуст или в выводе inspect нет нужных путей — значит volume действительно не примонтирован, и это надо чинить до того, как вы заново расставите все виджеты. После правки compose-файла обязательно docker compose up -d (не restart — правки volumes применяются только при пересоздании контейнера).

Совет на будущее: даже с правильными volume делайте регулярный бэкап каталога homarr-data — это займёт секунды, а спасёт часы работы по раскладке дашборда. Общий подход к автоматизации бэкапов на сервере разобран в статье про резервное копирование баз данных — логика с cron и ротацией архивов подходит и для конфигов Homarr.

Ошибка 3: интеграции (Portainer, Sonarr, *arr-стек) падают с 401 или таймаутом

Homarr умеет подтягивать живые данные из других сервисов — статус загрузок в *arr-приложениях, список стеков в Portainer, статистику из Uptime Kuma. Типичная ошибка при настройке интеграции — 401 Unauthorized или бесконечный спиннер загрузки виджета.

Разбор по шагам:

• 401 Unauthorized почти всегда означает, что API-ключ вставлен с лишним пробелом или скопирован не полностью (частая история при копировании из терминала — теряется последний символ). Пересоздайте ключ в целевом сервисе и вставьте заново, проверив длину строки.
• Таймаут/недоступен обычно означает проблему с сетевой видимостью между контейнерами. Если Homarr и, скажем, Portainer в разных Docker-сетях (разные docker-compose.yml, не объединённые общей network), обращение по имени контейнера не сработает. Либо подключите оба сервиса к общей внешней сети:

networks:
  shared-net:
    external: true

docker network create shared-net

и добавьте shared-net в оба compose-файла, либо в настройках интеграции Homarr указывайте не имя контейнера, а IP хоста и опубликованный наружу порт сервиса.

• Если сервис за reverse-proxy с базовой аутентификацией (Authelia/Authentik) — Homarr должен обращаться к нему в обход прокси, иначе получит HTML-страницу логина вместо JSON-ответа API и выдаст непонятную ошибку парсинга.

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

Ошибка 4: белый экран или 502 за reverse-proxy

Homarr работает по прямому IP:порту, но стоит повесить его за Traefik или nginx-proxy-manager с доменом — получаете 502 Bad Gateway или белую страницу без ошибок в консоли браузера.

Частые причины именно для Homarr:

• WebSocket не проксируется. Некоторые виджеты и live-обновления статуса контейнеров используют WebSocket-соединение. Для nginx-proxy-manager в дополнительных полях конфига нужно явно включить websockets support (чекбокс в UI), для чистого nginx — добавить заголовки:

location / {
    proxy_pass http://127.0.0.1:7575;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_set_header Host $host;
}

• Неверный BASE_URL. Если Homarr открывается по поддомену вроде dash.example.com, а не по корню, некоторые версии образа требуют явно задать переменную окружения с базовым путём — иначе статические файлы (JS/CSS) запрашиваются по неверным относительным путям, и вы видите пустую белую страницу при 200-м статусе загрузки самой страницы.
• Таймаут прокси при первом запуске. Homarr при холодном старте может дольше обычного инициализировать SQLite-базу — если у вас в конфиге прокси стоит жёсткий proxy_read_timeout в 5-10 секунд, первый запрос может упасть по таймауту. Увеличьте до 60 секунд для этого location.

Если выбираете между Traefik и nginx-proxy-manager для организации доступа к нескольким сервисам разом (не только Homarr), у нас есть сравнение Traefik или nginx-proxy-manager — что выбрать для сервера.

Ошибка 5: высокая нагрузка на CPU от постоянного опроса контейнеров

На слабых VPS (1 vCPU, особенно с burstable-тарифами) владельцы иногда замечают, что Homarr держит процессор занятым больше, чем ожидали от простого дашборда. Причина — частый опрос Docker API для обновления статусов контейнеров и виджетов с внешними API (погода, RSS), особенно если на дашборде десятки плиток.

Что проверить и поправить:

docker stats homarr --no-stream

Если видите стабильно повышенный CPU — в настройках дашборда (Settings → Board) увеличьте интервал обновления виджетов там, где это доступно, и уберите с главного экрана виджеты, которые опрашивают внешние сервисы (RSS с медленных источников, weather API без кеша) — их можно вынести на отдельную вкладку, которую вы открываете редко.

Если ресурсов системно не хватает — это уже вопрос не настройки Homarr, а тарифа. Дашборд сам по себе лёгкий, но на связке с десятком других контейнеров (Portainer, Uptime Kuma, reverse-proxy, сами сервисы) 1 vCPU часто становится узким местом ещё до того, как вы это осознаёте по симптомам вроде подвисающего SSH.

Ошибка 6: не работает автообновление образа

Многие рассчитывают, что image: ghcr.io/homarr-labs/homarr:latest сам подтянет новую версию — но docker compose up -d без явного pull использует уже скачанный локально образ, даже если тег latest в реестре обновился.

Правильный порядок ручного обновления:

docker compose pull homarr
docker compose up -d homarr
docker image prune -f

Для автоматизации разумно использовать Watchtower — но с оговоркой: следите за примечаниями к релизам Homarr перед авто-обновлением на проде, потому что breaking changes в схеме конфигурации между мажорными версиями случаются, и слепое автообновление среди ночи может однажды сломать дашборд, который вы настраивали часами. Как настроить и на что обратить внимание при автообновлении контейнеров, подробно разобрано в статье про частые ошибки автообновления Watchtower на сервере.

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