Встановлення

Новачкам

Запусти 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
```
Коли HolyArrs відповість, контейнер покаже стан healthy.
Відкрий 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

Тег image

Тег	Що ти отримуєш
`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 зупиняється і називає змінну в лозі. Значення він ніколи не виводить.

Image

В image є 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

Image збирають для 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 (жорстких посилань): кожна тека, яку ти монтуєш окремо, це окреме монтування всередині контейнера, а файл не можна зв’язати hardlink через різні монтування, тому імпорт стає повним копіюванням. Якщо хочеш hardlink, змонтуй натомість одну спільну батьківську теку (із завантаженнями й теками бібліотеки всередині) замість чотирьох необов’язкових монтувань і дай завантажувачу те саме монтування за тим самим шляхом. Батьківська тека також має бути однією файловою системою. Окремі мережеві ресурси або датасети у ній усе одно копіюють. 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 лише адресу або мережу проксі. Без цього single sign-on, справжні адреси клієнтів і 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.
Створи обліковий запис власника одразу після першого запуску.
Тримай копію головного ключа окремо від теки конфігурації.
Тримай image оновленим.

Особливі конфігурації

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 усередині контейнера це твій власний користувач, а інші id відображаються на великі числа на хості. З 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): його не можна перемаркувати, і контейнер не запуститься.
Задай перевірку справності списком. В image немає shell.
Залиш політику перезапуску always. Служба Podman для запуску після перезавантаження запускає лише контейнери з always.
Щоб запускати після перезавантаження без входу в систему, виконай один раз loginctl enable-linger $USER. Потім використай файл Quadlet, а для podman run виконай systemctl --user enable podman-restart.service.

Якщо тека вже належить великому id, спершу зупини контейнер, потім:

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)).

Збери власний image

З копії коду HolyArrs:

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

Потім використовуй holyarrs:local як image.

Усунення проблем

Спершу запусти doctor. Він перевіряє конфігурацію, теки, мережу й годинник і підказує, як виправити кожну проблему.

Контейнер працює: docker exec holyarrs /holyarrs doctor
Контейнер постійно перезапускається: docker compose run --rm holyarrs doctor

Про лог і пакет для підтримки див. Усунення проблем.

Ти бачиш	Зроби так
Config folder is on a shared or network folder (тека конфігурації на спільній або мережевій теці)	Використай локальний диск або іменований том у Docker Desktop. На Unraid використай `/mnt/<pool>/appdata/holyarrs`.
Config folder is in memory (тека конфігурації в оперативній пам’яті)	Постав `/config` на диск. На Unraid перевір, що шлях до пулу існує. Для тестового комп’ютера це дозволяє `HOLYARRS_CONFIG_IN_MEMORY=yes`.
Config folder cannot be written (у теку конфігурації не можна писати)	Прибери `:ro` і перевір, що `PUID:PGID` володіють текою.
Disk is full (диск заповнений)	Звільни місце на диску, де лежить `/config`, потім перезапусти.
`/config` is not mapped (теку конфігурації не зіставлено)	Див. нижче.
Cannot switch user (не вдається перемкнути користувача)	Поверни чотири capabilities або використай `user: "<uid>:<gid>"`.
PUID/PGID does not exist inside this container (PUID/PGID не існує всередині цього контейнера)	Ці id поза зіставленим діапазоном. Див. Rootless Docker і Podman.
A `FILE__` variable cannot be read (змінну з префіксом FILE__ не вдається прочитати)	Перевір шлях і те, що файл змонтовано.
Permission denied (доступ заборонено)	Перевір `PUID`, `PGID` і доступ на запис до всіх тек.
Unknown host name (невідоме ім’я хоста)	Відкрий HolyArrs за IP і додай ім’я в Allowed host names.
Imports are copied (імпорт копіюється)	Змонтуй одну спільну теку. Див. Теки з медіа.
Master key does not match (головний ключ не збігається)	Поверни ключ, що належить до цих баз даних.
Restore staged but the app stays down (відновлення підготовлено, але застосунок не працює)	Додай політику перезапуску і запусти контейнер.

Забув зіставити /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, підтримай проєкт або пригости мене кавою.