Установка

Новичкам

Запустите HolyArrs в Docker и откройте его в браузере. Это займёт несколько минут.

Перед началом

Компьютер с Docker и Docker Compose.
Ваши папки с медиа или место, где их создать. Сначала прочитайте Папки, если хотите мгновенные перемещения вместо копирования.
Для NAS, Unraid или Synology см. NAS, Synology и Unraid. Без Docker см. Переносимые архивы.

Шаги

Создайте папку конфигурации на локальном диске, например /srv/holyarrs/config. Не в сетевой папке. В Docker Desktop используйте вместо неё именованный том. См. Docker Desktop.
Узнайте пользователя и группу, которым принадлежат ваши папки с медиа:
Terminal window
```
id youruser
# uid=1000(youruser) gid=1000(youruser)
```
Значение uid укажите как PUID, а gid — как PGID.

Сохраните это как docker-compose.yml и поменяйте пути:

name: HolyArrs
services:
  holyarrs:
    image: holyarrs/holyarrs:latest
    container_name: holyarrs
    environment:
      - PUID=1000
      - PGID=1000
      - TZ=Etc/UTC
    volumes:
      - /srv/holyarrs/config:/config
      - /path/to/movies:/movies #optional
      - /path/to/tv:/tv #optional
      - /path/to/music:/music #optional
      - /path/to/downloads:/downloads #optional
    ports:
      - 6262:6262
    restart: unless-stopped

Запустите:
Terminal window
```
docker compose up -d
docker compose ps
```
Контейнер получит состояние healthy, как только HolyArrs начнёт отвечать.
Откройте http://your-server:6262 и сразу создайте учётную запись владельца. Пароля по умолчанию нет. Пока вы её не создали, владельцем станет тот, кто первым откроет HolyArrs.
Пройдите настройку, которая откроется дальше. См. Первый запуск.

Если вам удобнее docker run:

docker run -d \
  --name=holyarrs \
  -e PUID=1000 \
  -e PGID=1000 \
  -e TZ=Etc/UTC \
  -p 6262:6262 \
  -v /srv/holyarrs/config:/config \
  -v /path/to/movies:/movies `#optional`   -v /path/to/tv:/tv `#optional`   -v /path/to/music:/music `#optional`   -v /path/to/downloads:/downloads `#optional` \
  --restart unless-stopped \
  holyarrs/holyarrs:latest

Тег образа

Тег	Что вы получаете
`latest`	Самая новая версия
`1.0.2` (любая версия)	Ровно эта версия, никогда не меняется

Настройки подробно

Порты и папки

Настройка	Что она делает
`-p 6262:6262`	Веб-приложение.
`-v /config`	Базы данных, настройки, мастер-ключ, резервные копии и журналы. Только локальный диск.
`-v /movies`	Необязательно. Папка Медиатеки для фильмов.
`-v /tv`	Необязательно. Папка Медиатеки для сериалов.
`-v /music`	Необязательно. Папка Медиатеки для музыки.
`-v /downloads`	Необязательно. Папка загрузок Загрузчика. См. Папки с медиа.
`--read-only=true`	Необязательно. См. Корневая файловая система только для чтения.
`--user=1000:1000`	Необязательно. См. Запуск от фиксированного пользователя.

Переменные окружения

Переменная	Что она делает
`PUID`, `PGID`	Пользователь и группа, от имени которых работает HolyArrs. Если не указать, то 1000 и 1000.
`TZ`	Часовой пояс, например `Europe/Amsterdam`.
`UMASK`	Необязательно. Какие биты прав не получают новые файлы, например `022` или `002`.
`HOLYARRS_SAVE_PATH`	Необязательно. Папка сохранения Загрузчика — так, как её видит сам Загрузчик.
`HOLYARRS_ALLOWED_HOSTS`	Необязательно. Дополнительные имена хоста, по которым люди открывают HolyArrs, через запятую.
`HOLYARRS_TRUSTED_PROXIES`	Необязательно. Адрес или сеть вашего обратного прокси.
`HOLYARRS_URL_BASE`	Необязательно. Открывать HolyArrs по отдельному пути. См. URL base и обратные прокси.
`HOLYARRS_MASTER_KEY_FILE`	Необязательно. Читать мастер-ключ из отдельного файла.

Любую переменную можно взять из файла. Поставьте FILE__ перед именем и укажите путь к файлу как значение:

environment:
  - FILE__HOLYARRS_ALLOWED_HOSTS=/run/secrets/holyarrs_hosts

Один перевод строки в конце файла отбрасывается. Это работает и для PUID, PGID, UMASK и TZ. Если файла нет, HolyArrs останавливается и называет переменную в журнале (логе). Само значение он никогда не выводит.

Образ

В образе есть HolyArrs и почти ничего больше. В нём нет оболочки (shell), поэтому зайти внутрь через docker exec и осмотреться не получится. Вместо этого читайте журнал командой docker logs holyarrs или откройте logs/holyarrs.log в папке конфигурации.

Собственные команды HolyArrs по-прежнему работают через docker exec:

docker exec holyarrs /holyarrs doctor
docker exec -i holyarrs /holyarrs reset-owner
docker exec holyarrs /holyarrs restore --pre-update

Образы собираются для amd64, 64-битных ARM и 32-битных ARM. На компьютере, где памяти около 2.5 GiB или меньше, HolyArrs сам включает режим экономии памяти. Об этом сказано в первой строке журнала.

Пользователь и группа

Контейнер запускается от root только чтобы подготовить себя. При необходимости он отдаёт папку конфигурации пользователю PUID:PGID, а потом насовсем переключается на него. В первой строке журнала видны пользователь, группа и umask.

HolyArrs никогда не меняет владельца ваших папок с медиа и загрузками. Права на запись в них дайте пользователю PUID сами. Прав на чтение мало: HolyArrs создаёт папки и перемещает файлы.

Некоторые хранилища не дают менять владельца: NFS с root squash, SMB или точка монтирования только для чтения. Тогда HolyArrs пишет в журнал предупреждение и работает дальше. Сделайте папку конфигурации доступной для записи для PUID:PGID вручную.

Для переключения пользователя нужны привилегии (capabilities) CHOWN, DAC_OVERRIDE, SETUID и SETGID. Docker даёт их по умолчанию. Если их убрать, HolyArrs остановится с сообщением. К работе от root он не возвращается. Чтобы действительно работать от root, задайте PUID=0 и PGID=0.

Дополнительные группы из group_add: сохраняются, когда HolyArrs переключает пользователя.

UMASK влияет только на новые файлы. Не указывайте его, чтобы осталось 022: вы пишете, остальные читают. Задайте 002, если писать должна и группа.

Папки с медиа

Монтируйте только те папки, которыми пользуетесь: /movies, /tv и /music как папки Медиатеки и /downloads как папку загрузок.

Совет про жёсткие ссылки (hardlink): каждая папка, смонтированная отдельно, — это отдельная точка монтирования внутри контейнера, а жёсткую ссылку на файл нельзя создать между разными точками монтирования, поэтому импорт превращается в полное копирование. Если вам нужны жёсткие ссылки, вместо четырёх необязательных точек монтирования можно смонтировать одну общую родительскую папку (с загрузками и папками Медиатеки внутри) и дать Загрузчику ту же точку монтирования по тому же пути. Родительская папка к тому же должна быть одной файловой системой. Отдельные сетевые папки или датасеты NAS внутри неё всё равно копируются. Settings > Library folders (Настройки > Папки Медиатеки) предупреждает, когда HolyArrs приходится копировать.

HOLYARRS_SAVE_PATH отправляется Загрузчику с каждой загрузкой, поэтому она меняет и то, куда Загрузчик сохраняет файлы. Не указывайте её, чтобы осталась собственная настройка Загрузчика. Если вы её не указали, добавьте папку загрузок в Settings > Library folders > Extra import folders (дополнительные папки импорта), чтобы импортировать из неё вручную.

Сохраните мастер-ключ

HolyArrs шифрует сохранённые пароли, ключи и токены мастер-ключом. При первом запуске создаётся /config/holyarrs.key.

В резервные копии этот ключ никогда не попадает. Храните его копию в другом месте. Простой способ: как владелец откройте Settings > Backups (Настройки > Резервные копии) и выберите Download key kit (скачать набор с ключом). Чтобы вернуть ключ, назовите файл holyarrs.key и положите его в папку конфигурации, пока HolyArrs остановлен. Восстановление с другим ключом отклоняется. С именованным томом папки, которую можно открыть, нет: скопируйте ключ командой docker cp holyarrs.key hx:/config/, как в разделе Docker Desktop. Переезжаете на новый компьютер? Сначала верните ключ, потом восстановите резервную копию. См. Резервные копии.

Ключ можно также держать в отдельном файле только для чтения:

environment:
  - HOLYARRS_MASTER_KEY_FILE=/keys/holyarrs.key
volumes:
  - /srv/holyarrs/keys:/keys:ro

Файл должен существовать и содержать 32 сырых байта, 64 шестнадцатеричные цифры или base64 от 32 байт. У пользователя PUID должны быть права на его чтение.

Перезапуск и восстановление

Оставьте политику перезапуска. Восстановление проверяется и подготавливается, затем HolyArrs завершается с кодом 75, чтобы Docker запустил его снова и применил восстановление. unless-stopped с этим справляется.

Чтобы обновить локальную сборку, пересоберите образ и пересоздайте контейнер, не трогая точки монтирования:

docker build --file deploy/Dockerfile --tag holyarrs:local .
docker compose up -d --force-recreate

Никогда не удаляйте /config при обновлении. См. Обновления и Резервные копии.

Имена хоста и обратные прокси

IP-адреса и localhost работают сразу. Домашнее имя вроде tower.local, по которому вы зашли при первой настройке, сохраняется само. Другие имена добавьте в Allowed host names (разрешённые имена хоста) в Settings > Sign-in and security (Настройки > Вход и безопасность) или в HOLYARRS_ALLOWED_HOSTS.

Если обратный прокси добавляет X-Forwarded-For, укажите в HOLYARRS_TRUSTED_PROXIES только адрес или сеть прокси. Без этого единый вход (SSO), настоящие адреса клиентов и cookie с флагом Secure не работают, а у всех, кто за прокси, один общий лимит попыток входа. Журнал называет адрес прокси, который нужно добавить. Если впереди стоит ещё один прокси, например Cloudflare, добавьте и его диапазоны.

В nginx передавайте оба заголовка:

proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;

Если они расходятся, HolyArrs считает, что посетитель находится вне вашей сети.

Основы безопасности

Не пробрасывайте порт 6262 на роутере. Используйте VPN, например Tailscale, или обратный прокси с HTTPS.
Создайте учётную запись владельца сразу после первого запуска.
Храните копию мастер-ключа отдельно от папки конфигурации.
Держите образ обновлённым.

Особые случаи

Docker Desktop (Windows и Mac)

Docker Desktop отдаёт папки хоста через слой, в котором блокировки файлов базы данных ненадёжны. HolyArrs не принимает такой /config и показывает решение на порту 6262. Используйте для /config именованный том. Папки с медиа могут оставаться папками хоста.

name: HolyArrs
services:
  holyarrs:
    image: holyarrs/holyarrs:latest
    container_name: holyarrs
    environment:
      - TZ=Etc/UTC
    volumes:
      - holyarrs-config:/config
      - C:/Media/movies:/movies
    ports:
      - 6262:6262
    restart: unless-stopped

volumes:
  holyarrs-config:

Чтобы перенести старую папку конфигурации в том, остановите HolyArrs и выполните:

docker create --name hx -v holyarrs-config:/config holyarrs/holyarrs:latest
docker cp C:\old\config\. hx:/config/
docker rm hx

Чтобы достать резервные копии: docker cp holyarrs:/config/backups .

На Mac, если вы проверили, что блокировки файлов в вашей папке работают, задайте HOLYARRS_ALLOW_DESKTOP_FOLDER=1, чтобы всё равно запуститься. HolyArrs предупреждает при каждом запуске. Для сетевых папок отказ этим никогда не снимается.

Корневая файловая система только для чтения

Запись нужна только в /config и /tmp:

services:
  holyarrs:
    read_only: true
    tmpfs:
      - /tmp

PUID, PGID и UMASK по-прежнему работают.

Запуск от фиксированного пользователя

services:
  holyarrs:
    user: "1000:1000"

Тогда HolyArrs не меняет владельцев, поэтому папка конфигурации уже должна быть доступна этому пользователю для записи. PUID и PGID не учитываются, и в журнале об этом сказано. Это относится и к runAsUser в Kubernetes.

Rootless Docker и Podman

В режиме rootless root внутри контейнера — это ваш собственный пользователь, а остальные идентификаторы на хосте превращаются в большие номера. С PUID=1000 владельцем папки конфигурации на хосте оказывается посторонний пользователь.

Что вы запускаете	`docker info` или `podman info` показывает	Что использовать
Обычный Docker	нет `rootless`	`PUID` и `PGID` как обычно
Rootless Docker	`rootless` в Security Options	Способ 1
Rootless Podman	`rootless: true`	Способ 1 или 2

Способ 1. Задайте PUID=0 и PGID=0. Это безопасно только в режиме rootless. Никогда не делайте так с обычным Docker или на NAS.

Способ 2. Podman с keep-id, в виде Quadlet в ~/.config/containers/systemd/holyarrs.container:

[Container]
Image=holyarrs/holyarrs:latest
UserNS=keep-id
User=%U:%G
Volume=%h/holyarrs/config:/config:Z
PublishPort=6262:6262
HealthCmd=["/holyarrs","-healthcheck"]
HealthInterval=30s

[Service]
Restart=always

[Install]
WantedBy=default.target

Или одной командой:

podman run -d --name holyarrs --userns=keep-id --user "$(id -u):$(id -g)" -v ~/holyarrs/config:/config:Z -p 6262:6262 --health-cmd '["/holyarrs","-healthcheck"]' --health-interval 30s --restart always holyarrs/holyarrs:latest

:Z нужен в системах с SELinux. Для папок, которые делит с вами Загрузчик, используйте :z. В сетевой папке (NFS или SMB) не используйте ни то, ни другое: ей нельзя сменить метку SELinux, и контейнер не запустится.
Проверку исправности задавайте списком. В образе нет оболочки.
Оставьте политику перезапуска always. Служба Podman, которая запускает контейнеры после перезагрузки, запускает только контейнеры с always.
Чтобы контейнер запускался после перезагрузки без входа в систему, один раз выполните loginctl enable-linger $USER. Затем используйте файл Quadlet, а для podman run выполните systemctl --user enable podman-restart.service.

Если папка уже принадлежит идентификатору с большим номером, сначала остановите контейнер, а затем:

Rootless Podman: podman unshare chown -R 0:0 ~/holyarrs/config (способ 1) или podman unshare chown -R 1000:1000 ~/holyarrs/config.
Rootless Docker: rootlesskit chown -R 0:0 ~/holyarrs/config, выполненная через nsenter внутри rootless-демона (nsenter -U --preserve-credentials -n -m -t $(cat $XDG_RUNTIME_DIR/docker.pid)).

Соберите свой образ

Из рабочей копии репозитория HolyArrs:

docker build --file deploy/Dockerfile --tag holyarrs:local .

Затем укажите holyarrs:local как образ.

Устранение неполадок

Сначала запустите doctor. Он проверяет конфигурацию, папки, сеть и часы и подсказывает, как исправить каждую проблему.

Контейнер работает: docker exec holyarrs /holyarrs doctor
Контейнер всё время перезапускается: docker compose run --rm holyarrs doctor

Про журнал и пакет для поддержки см. Устранение неполадок.

Что вы видите	Что делать
Папка конфигурации находится в общей или сетевой папке	Используйте локальный диск или именованный том в Docker Desktop. В Unraid используйте `/mnt/<pool>/appdata/holyarrs`.
Папка конфигурации находится в памяти	Поместите `/config` на диск. В Unraid проверьте, что путь к пулу существует. Для тестового компьютера это разрешает `HOLYARRS_CONFIG_IN_MEMORY=yes`.
В папку конфигурации нельзя писать	Уберите `:ro` и проверьте, что папка принадлежит `PUID:PGID`.
Диск заполнен	Освободите место на диске, где лежит `/config`, затем перезапустите.
`/config` не проброшена	См. ниже.
Не удаётся переключить пользователя	Верните четыре привилегии или используйте `user: "<uid>:<gid>"`.
PUID/PGID не существует внутри этого контейнера	Идентификаторы вне сопоставленного диапазона. См. Rootless Docker и Podman.
Переменную `FILE__` не удаётся прочитать	Проверьте путь и то, что файл смонтирован.
Отказано в доступе	Проверьте `PUID`, `PGID` и права на запись во всех папках.
Неизвестное имя хоста	Откройте HolyArrs по IP и добавьте имя в Allowed host names.
Импорт копирует файлы	Смонтируйте одну общую папку. См. Папки с медиа.
Мастер-ключ не подходит	Верните ключ, который относится к этим базам данных.
Восстановление подготовлено, но приложение не поднимается	Добавьте политику перезапуска и запустите контейнер.

Забыли пробросить /config?

HolyArrs всё равно запускается, но предупреждает везде. Когда контейнер удалят, всё пропадёт. Сначала сохраните данные:

docker stop holyarrs
docker cp holyarrs:/config ./holyarrs-config

Затем пробросьте ./holyarrs-config:/config (или именованный том) и пересоздайте контейнер. В Docker Desktop (Windows и Mac) используйте именованный том, а не папку хоста, и скопируйте данные внутрь, как показано в разделе Docker Desktop. Старая установка может всё ещё лежать в безымянном томе. Список томов выводит docker volume ls.

См. также

HolyArrs бесплатен. Если он сэкономил вам время, поставьте звезду на GitHub, станьте спонсором или угостите меня кофе.