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

MAATRIX

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

Что такое Heimdall и когда он лучше альтернатив

Heimdall (linuxserver/heimdall) — дашборд приложений от команды LinuxServer.io, написанный на PHP/Laravel. Задача у него одна: собрать ссылки на все сервисы сервера в виде плиток на одном экране. По сравнению с Homepage, у Heimdall принципиально другой подход к настройке:

• управление через веб-интерфейс, а не через YAML-файлы — приложение добавляется формой в браузере, без SSH и редактирования конфигов;
• Enhanced Applications — примерно три десятка популярных сервисов (Pi-hole, Plex, Portainer, Sonarr/Radarr, qBittorrent, Transmission, pfSense, OpenWeatherMap и другие) поддерживают встроенную интеграцию: тайл сам подтягивает живые данные через API сервиса;
• поиск по нескольким провайдерам прямо со страницы дашборда, с горячими клавишами для переключения источника;
• лёгкость — контейнер стартует за секунды, интерфейс отзывчивый даже на слабом VPS.

Из ограничений: живых виджетов у Heimdall на порядок меньше, чем у Homepage (десятки против сотни с лишним коннекторов), автообнаружения контейнеров через Docker-лейблы нет вовсе — каждое приложение добавляется вручную через форму. Если инфраструктура растёт быстро и сервисов больше двадцати, ручное управление через UI станет утомительным — тогда стоит присмотреться к конфигурации как коду. Но для домашней лаборатории на 5-15 сервисов, где состав меняется редко, простота Heimdall — это плюс, а не недостаток: не нужно разбираться в синтаксисе YAML, чтобы добавить новую плитку.

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

LinuxServer.io публикует образ по своим стандартам: переменные PUID/PGID для соответствия прав файлов пользователю на хосте, отдельный том под конфигурацию:

services:
  heimdall:
    image: lscr.io/linuxserver/heimdall:latest
    container_name: heimdall
    restart: unless-stopped
    environment:
      - PUID=1000
      - PGID=1000
      - TZ=Europe/Moscow
    volumes:
      - ./heimdall-config:/config
    ports:
      - "8080:80"
      - "8443:443"
    networks:
      - heimdall-net

networks:
  heimdall-net:
    driver: bridge

Нюансы, на которые стоит обратить внимание:

• PUID/PGID должны совпадать с UID/GID пользователя-владельца каталога heimdall-config на хосте — иначе контейнер либо не сможет писать в конфиг, либо создаст файлы от root, и следующий docker compose down && up перезатрёт права. Узнать свои ID: id $USER.
• Порт 443 внутри контейнера поднимает HTTPS с самоподписанным сертификатом — для личного использования без reverse proxy этого достаточно, браузер просто предупредит о недоверенном сертификате при первом заходе.
• Тег :latest в продакшене — риск: LinuxServer.io обновляет образы часто, и хотя мажорные ломающие изменения в Heimdall редкость, лучше зафиксировать конкретный тег с страницы релизов на Docker Hub и обновлять осознанно, а не через автообновление по расписанию.

Поднимаем:

mkdir -p heimdall-config
docker compose up -d

Первый запуск занимает несколько секунд — Laravel-приложению нужно инициализировать SQLite-базу внутри /config. Открываем http://<ip-сервера>:8080 и попадаем на пустой дашборд с кнопкой добавления первого приложения.

Первые шаги: добавление приложений через веб-интерфейс

Вся настройка Heimdall — это форма «Add Application», без единого текстового конфига. Процесс:

1. На главной странице жмём плитку +.
2. Вводим название, URL сервиса (например, https://portainer.example.com или внутренний адрес по имени контейнера, если Heimdall и целевой сервис в одной Docker-сети — http://portainer:9000).
3. Выбираем иконку — Heimdall тянет их из встроенной библиотеки популярных сервисов (по названию приложения находится сама), либо загружаем свою PNG/SVG.
4. Указываем цвет фона плитки и, если приложение открывается не в текущей вкладке, — поведение ссылки (новая вкладка / iframe / текущая вкладка).

Приложения группируются простым порядком добавления — секций и категорий, как в Homepage, здесь нет: все плитки лежат на одной сетке, которую можно перетаскивать мышью, меняя порядок. Для десятка сервисов это удобно и наглядно; для полусотни — превращается в длинную простыню без структуры, и здесь уже проявляется разница в философии инструментов.

Обращаться к сервисам, поднятым на том же хосте в других docker-compose.yml, из Heimdall можно как по внешнему домену, так и по внутреннему адресу контейнера — если подключить оба стека к общей внешней сети:

networks:
  heimdall-net:
    driver: bridge
  shared-net:
    external: true

services:
  heimdall:
    # ...
    networks:
      - heimdall-net
      - shared-net

Enhanced Applications: живые данные без внешних конфигов

Часть плиток Heimdall умеет больше, чем просто открывать ссылку — это и есть Enhanced Applications. При добавлении такого сервиса форма показывает дополнительные поля: обычно API-ключ или логин/пароль, и на плитке появляется живой блок с данными вместо статичной иконки.

Пример для Pi-hole: в форме добавления выбираем тип «Pi-hole», указываем URL (http://pihole:80) и API-токен из настроек Pi-hole (Settings → API/Web interface → Show API token) — тайл начинает показывать количество заблокированных запросов за сутки прямо на дашборде, без перехода в интерфейс Pi-hole.

Аналогично для Portainer — тип «Portainer», URL инстанса и API-ключ, сгенерированный в Settings → API. Тайл покажет число запущенных контейнеров.

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

Поиск по нескольким источникам с клавиатуры

Отдельная особенность Heimdall — встроенная поисковая строка на главной странице, которая умеет обращаться сразу к нескольким внешним поисковикам и сервисам без перехода на их сайты вручную. Включается в настройках (Settings → Search), где можно выбрать провайдеры по умолчанию — обычно доступны как минимум общий веб-поиск и несколько специализированных источников (документация проектов, GitHub, YouTube и подобные).

Переключение между источниками — с клавиатуры, префиксом перед запросом (конкретные комбинации горячих клавиш заданы в настройках поиска и могут отличаться между версиями — проверьте актуальный список прямо на странице Settings → Search своей установки). Для домашней лаборатории, где Heimdall — это стартовая страница браузера, такой поиск экономит пару кликов на каждый запрос за день.

Публикация через reverse proxy и защита доступа

Heimdall не имеет встроенной системы пользователей и паролей — кто угодно, кто откроет порт, получит полный доступ к списку сервисов и (если добавлены Enhanced Applications) к их API-ключам, введённым через форму. Открывать 8080-й порт в интернет напрямую не стоит — как минимум, спрячьте дашборд за HTTPS и Basic Auth через reverse proxy.

Если Traefik уже настроен для остальных сервисов на сервере, добавляем лейблы прямо в сервис Heimdall и убираем публикацию портов наружу:

services:
  heimdall:
    image: lscr.io/linuxserver/heimdall:latest
    container_name: heimdall
    restart: unless-stopped
    environment:
      - PUID=1000
      - PGID=1000
      - TZ=Europe/Moscow
    volumes:
      - ./heimdall-config:/config
    networks:
      - heimdall-net
      - traefik-net
    labels:
      traefik.enable: "true"
      traefik.http.routers.heimdall.rule: Host(`dash.example.com`)
      traefik.http.routers.heimdall.entrypoints: websecure
      traefik.http.routers.heimdall.tls.certresolver: letsencrypt
      traefik.http.services.heimdall.loadbalancer.server.port: "80"
      traefik.http.routers.heimdall.middlewares: heimdall-auth
      traefik.http.middlewares.heimdall-auth.basicauth.users: "admin:$$apr1$$xyz...hash"

networks:
  heimdall-net:
  traefik-net:
    external: true

Хеш для Basic Auth генерируется командой htpasswd -nB admin — результат вида admin:$apr1$... вставляем в лейбл, удвоив каждый $ ($ → $$), иначе Docker Compose примет их за переменные окружения и подставит пустоту вместо хеша. Тем, кто ещё не разворачивал reverse proxy на сервере, разумнее сначала поднять и проверить Traefik на одном простом сервисе, а Heimdall подключить последним, когда маршрутизация и сертификаты уже стабильно работают.

Резервное копирование и перенос конфигурации

Вся настройка Heimdall — иконки, ссылки, API-ключи Enhanced Applications, порядок плиток — хранится в SQLite-базе внутри примонтированного каталога /config. Это одновременно и удобство, и единственная точка отказа: потеряли каталог — потеряли весь дашборд, восстанавливать плитки придётся вручную через форму заново.

Простой бэкап каталога конфигурации:

tar -czf heimdall-backup-$(date +%F).tar.gz heimdall-config/

Для переноса на другой сервер достаточно скопировать heimdall-config целиком и поднять тот же docker-compose.yml — контейнер подхватит существующую базу и все настроенные приложения появятся сразу, без повторного ввода. Права на скопированный каталог стоит проверить: если PUID/PGID на новом сервере отличаются, лучше выставить владельца заново через chown -R 1000:1000 heimdall-config под фактического пользователя контейнера.

Автоматизировать регулярный бэкап каталога конфигурации на внешнее хранилище проще всего обычным cron-заданием с tar и rclone или restic — для дашборда, который меняется редко, ежедневного снапшота более чем достаточно.

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