Инсталиране

Стартирай HolyArrs в Docker и го отвори в браузъра. Отнема няколко минути.

Преди да започнеш

• Компютър с Docker и Docker Compose.
• Папките ти за медия или място, където да ги направиш. Ако искаш мигновено преместване вместо копиране, първо прочети Папки.
• На NAS, Unraid или Synology виж NAS, Synology и Unraid. Без Docker виж Преносими архиви.

Стъпки

1. Направи папка за конфигурацията на локален диск, например /srv/holyarrs/config. Не на мрежова папка. В Docker Desktop използвай вместо това именуван том. Виж Docker Desktop.

2. Намери потребителя и групата, които притежават папките ти за медия:

   id youruser
   # uid=1000(youruser) gid=1000(youruser)

   Използвай uid като PUID и gid като PGID.

3. Запази това като 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

4. Стартирай го:

   docker compose up -d
   docker compose ps

   Контейнерът се показва като healthy (здрав), щом HolyArrs отговори.

5. Отвори http://your-server:6262 и веднага направи акаунта на собственика. Няма парола по подразбиране. Докато не го направиш, който първи отвори HolyArrs, става собственик.

6. Следвай настройката, която се отваря след това. Виж Първо стартиране.

Внимание

Няма парола по подразбиране. Който първи отвори нов 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.0 (всяка версия)	Точно тази версия, никога не се променя

Обяснение на настройките

Портове и папки

Настройка	Какво прави
-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	По избор. Допълнителни имена на host, с които хората стигат до HolyArrs, разделени със запетая.
HOLYARRS_TRUSTED_PROXIES	По избор. Адресът или мрежата на твоя reverse proxy.
HOLYARRS_URL_BASE	По избор. Сервира HolyArrs под даден път. Виж URL base и reverse proxy.
HOLYARRS_MASTER_KEY_FILE	По избор. Чете главния ключ от отделен файл.

Всяка променлива може да идва от файл. Сложи FILE__ пред името и дай пътя до файла като стойност:

environment:
  - FILE__HOLYARRS_ALLOWED_HOSTS=/run/secrets/holyarrs_hosts

Един нов ред в края на файла се отрязва. Това важи и за PUID, PGID, UMASK и TZ. Ако файлът липсва, HolyArrs спира и посочва променливата в дневника (log). Стойността никога не се показва.

Образът

Образът съдържа 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 на ръка.

За смяната на потребител са нужни правата 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 се справя с това.

За да актуализираш локален build, прекомпилирай и създай контейнера наново, без да пипаш монтиранията:

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

Никога не трий /config при актуализация. Виж Актуализации и Резервни копия.

Имена на host и reverse proxy

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

Когато reverse proxy добавя X-Forwarded-For, сложи в HOLYARRS_TRUSTED_PROXIES само адреса или мрежата на proxy. Без това single sign-on, истинските адреси на клиентите и бисквитката Secure не работят, а всички зад proxy делят едно ограничение за вход. Дневникът посочва адреса на proxy, който да добавиш. Ако пред него стои друг proxy, например 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 или reverse proxy с HTTPS.
• Направи акаунта на собственика веднага след първото стартиране.
• Пази копие на главния ключ далеч от папката с конфигурация.
• Дръж образа актуален.

Специални настройки

Docker Desktop (Windows и Mac)

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

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 се превеждат във високи числа на host. При PUID=1000 папката с конфигурация завършва като притежавана от непознат на host.

Какво използваш	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): не може да се пренагласи етикетът ѝ и контейнерът няма да стартира.
• Дай проверката на здравето като списък. Образът няма 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)).

Направи свой образ

От копието на HolyArrs:

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

После използвай holyarrs:local като образ.

Отстраняване на проблеми

Първо пусни 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 (не може да се смени потребителят)	Върни четирите права или използвай 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 (непознато име на host)	Отвори 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) използвай именуван том, а не папка на host, и копирай данните вътре, както е показано в Docker Desktop. По-стара настройка може още да стои в неименуван том. Виж ги с docker volume ls.

Свързано

• Папки
• Първо стартиране
• NAS, Synology и Unraid
• Актуализации