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

MAATRIX

Когда на сервере крутится десяток сервисов — Portainer, Pi-hole, Nextcloud, пара *arr-приложений, панель мониторинга — держать все адреса в закладках браузера быстро надоедает. Heimdall решает эту задачу буквально одной страницей: плиточная стартовая страница, с которой одним кликом открывается любое приложение, а некоторые сервисы ещё и показывают на плитке живые данные через API. Ниже — установка на чистый VPS через Docker, настройка HTTPS и разбор нюансов, которые обычно всплывают уже после того, как «всё вроде заработало».

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

Heimdall Application Dashboard — open-source проект на Laravel/PHP, который существует с 2017 года и до сих пор активно поддерживается сообществом (в первую очередь через образ linuxserver.io). Идея простая: страница с плитками-иконками, каждая плитка ведёт на конкретное приложение в вашей инфраструктуре. В отличие от голого списка закладок, у Heimdall есть:

• группировка приложений по вкладкам (например «Инфраструктура», «Медиа», «Разработка»);
• поиск по плиткам и встроенный быстрый доступ к внешним поисковикам прямо со стартовой страницы;
• «enhanced applications» — готовые интеграции с популярными сервисами (Pi-hole, Sonarr, Radarr, Portainer, Plex, PaperlessNG и другими), которые подтягивают через API реальные цифры: сколько запросов заблокировал Pi-hole, сколько дискового пространства свободно и т.п.;
• светлая и тёмная темы, кастомные фоны и цвета плиток.

Это не панель управления сервером и не мониторинг в духе Grafana — Heimdall ничем не управляет, он просто витрина ссылок. Именно поэтому он лёгкий: контейнер занимает около 200-300 МБ памяти в простое и не требует отдельной базы данных — использует SQLite по умолчанию.

Стоит ли ставить Heimdall, если сервисов у вас три-четыре? Едва ли — хватит закладок. Но если счёт идёт на 10+ приложений и разные члены семьи или команды заходят на один и тот же сервер за разными вещами, единая точка входа экономит реальное время.

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

Разворачивать будем на Ubuntu 24.04 — если Docker ещё не стоит, сначала установите его с нуля. Дальше всё делается через compose-файл на базе официального образа linuxserver/heimdall.

Создайте директорию проекта и файл конфигурации:

mkdir -p ~/heimdall/config
cd ~/heimdall
nano docker-compose.yml

Содержимое docker-compose.yml:

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

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

id -u
id -g

Если у вас обычный пользователь ubuntu, скорее всего это будет 1000:1000 — тогда менять ничего не нужно. Порты 8080/8443 выбраны специально, чтобы не конфликтовать с портами 80/443, которые почти наверняка заняты обратным прокси или другими веб-сервисами на том же VPS.

Запуск:

docker compose up -d

Проверьте, что контейнер поднялся и не падает в рестарт-цикл:

docker compose ps
docker compose logs -f heimdall

Первый запуск инициализирует SQLite-базу и Laravel-приложение внутри ./config — это занимает 10-30 секунд, поэтому не пугайтесь, если страница по адресу http://ваш_ip:8080 откроется не сразу.

Первоначальная настройка и добавление приложений

Откройте http://ваш_ip:8080 в браузере — попадёте сразу на пустую панель без формы логина (в базовой конфигурации Heimdall не требует авторизации, об этом ниже отдельно). Добавление приложения делается через большую иконку + на главном экране:

1. Application Name — название, которое увидите на плитке.
2. Colour — цвет фона плитки (можно оставить авто).
3. URL — адрес, куда ведёт плитка (например https://portainer.example.com).
4. Icon — Heimdall умеет искать иконку автоматически по названию приложения из встроенной библиотеки (там сотни готовых логотипов популярных self-hosted проектов), либо загрузите свою.
5. Description, Tags — опционально, для поиска и группировки.

Если приложение есть в списке «enhanced» (при вводе названия в поле Application Name Heimdall подскажет совпадение), появится дополнительная вкладка Config — там указываются URL API-эндпоинта, API-ключ и иногда порт. Это включает на плитке живые метрики вместо статичной иконки.

Группы вкладок настраиваются в Settings → Tabs — можно создать отдельные вкладки для разных категорий и назначить каждой приложение через выпадающий список при добавлении/редактировании плитки. Полезно, когда на одном сервере живут и инфраструктурные, и пользовательские сервисы — не нужно листать общий список.

Ещё один момент, который стоит настроить сразу: Settings → Search Providers — по умолчанию включены Google, DuckDuckGo и несколько других, из главной строки поиска можно быстро переключаться между ними хоткеем без перехода на сам поисковик.

Настройка HTTPS-доступа через обратный прокси

Открывать панель по голому HTTP на порт 8080 нормально только для внутренней сети. Для доступа из интернета нужен обратный прокси с TLS — вариантов два: Nginx + Certbot вручную, либо Traefik/Nginx Proxy Manager с автоматическим выпуском сертификатов (сравнение подходов — в статье Traefik или Nginx Proxy Manager).

Пример конфига для классического Nginx (предполагается, что домен dash.example.com уже указывает A-записью на IP сервера):

server {
    listen 80;
    server_name dash.example.com;
    location / {
        proxy_pass http://127.0.0.1:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Дальше выпускаете сертификат через certbot — подробный разбор шагов есть в статье про установку Let's Encrypt SSL на VPS:

sudo apt install certbot python3-certbot-nginx -y
sudo certbot --nginx -d dash.example.com

Важный нюанс безопасности: Heimdall из коробки не требует пароль для входа — это осознанное решение авторов, панель считается инструментом для доверенной локальной сети. Если планируете доступ из открытого интернета, обязательно закройте его либо через VPN/Wireguard-туннель до сервера, либо через Basic Auth на уровне Nginx:

sudo apt install apache2-utils -y
sudo htpasswd -c /etc/nginx/.htpasswd admin

И добавьте в блок location конфига:

auth_basic "Restricted";
auth_basic_user_file /etc/nginx/.htpasswd;

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

API-ключи и автоматическое подтягивание данных из приложений

Живые метрики на плитках — самая полезная часть Heimdall, но настройка каждой интеграции своя. Разберём на паре частых примеров.

Portainer. В поле Application Name наберите «Portainer», выберите enhanced-вариант, укажите URL панели Portainer и добавьте логин/пароль в соответствующих полях конфига плитки — Heimdall будет получать токен через API Portainer и показывать число контейнеров и стеков.

Pi-hole. Понадобится API-ключ Pi-hole, который находится в Settings → API / Web interface → Show API token веб-интерфейса Pi-hole. Вставьте его в конфиг плитки вместе с URL — плитка начнёт показывать количество заблокированных запросов за сутки.

Sonarr/Radarr. API-ключ ищите в Settings → General → Security → API Key соответствующего приложения. После добавления плитка покажет число сериалов/фильмов в библиотеке.

Общая логика везде одна: Heimdall не хранит эти данные сам, а при каждой загрузке страницы делает запрос к API целевого приложения от имени контейнера. Отсюда следствие — если Heimdall и приложение сидят в разных Docker-сетях, обращение по внутреннему hostname (http://sonarr:8989) работать не будет, пока оба сервиса не окажутся в одной user-defined сети:

docker network create shared-net

И добавьте в оба compose-файла:

networks:
  default:
    external:
      name: shared-net

Иначе указывайте публичный или LAN-адрес приложения — трафик пойдёт через хост, что чуть медленнее, но проще и не требует пересборки сети.

Резервное копирование и обновление

Вся конфигурация Heimdall — включая список приложений, иконки, настройки вкладок — лежит в примонтированной директории ./config, конкретно в SQLite-базе config/www/heimdall.sqlite. Бэкап сводится к копированию этой папки:

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

Останавливать контейнер не обязательно, но безопаснее — база маленькая, простой незаметен. Для регулярных бэкапов заведите cron-задачу с ротацией архивов; если уже используется BorgBackup или Duplicati, добавьте ~/heimdall/config в общий список путей. Восстановление — обратная операция: остановить контейнер, распаковать архив на место ./config, запустить заново.

Обновление образа — стандартная процедура для linuxserver-контейнеров:

docker compose pull heimdall
docker compose up -d heimdall

Если хотите, чтобы обновления подтягивались сами, разверните рядом Watchtower — как это сделать, описано в статье про автообновление Watchtower на VPS. Для дашборда, который не хранит критичных данных (кроме списка ссылок), автообновление — низкий риск, но перед включением всё равно стоит сделать один ручной бэкап ./config, чтобы откат в случае проблем занял минуту, а не час.

Heimdall vs Homepage vs Dashy — когда что выбрать

Heimdall — не единственный вариант стартовой страницы, и прежде чем вкладывать время в настройку, стоит понимать, чем он отличается от главных конкурентов.

Если хочется всё настроить мышкой без единой строчки конфига — берите Heimdall. Если не против писать YAML и нужна максимальная гибкость с виджетами погоды, курсов валют, докер-контейнеров и прочего — присмотритесь к Homepage, у него сейчас заметно активнее сообщество и шире набор готовых интеграций. Dashy интересен, если важны встроенные статус-чеки доступности сервисов прямо на дашборде. Универсального ответа нет — Heimdall выигрывает там, где важна простота и минимум возни с текстовыми файлами.

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