Инсталација

Покрени 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	Опционо. Погледај Root фајл систем само за читање.
--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 база и реверс прокси.
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.

За промену корисника потребне су дозволе CHOWN, DAC_OVERRIDE, SETUID и SETGID. Docker их даје подразумевано. Ако их одбациш, HolyArrs се зауставља уз поруку. Не враћа се на root. Да би заиста радио као root, постави PUID=0 и PGID=0.

Додатне групе из group_add: остају кад HolyArrs промени корисника.

UMASK утиче само на нове фајлове. Изостави га да задржиш 022, где ти пишеш, а остали читају. Користи 002 када и група мора да пише.

Медија фолдери

Монтирај само фолдере које користиш: /movies, /tv и /music као фолдере библиотеке, а /downloads као фолдер за преузимања.

Савет за хардлинкове (тврда веза): сваки фолдер који монтираш појединачно је засебно монтирање унутар контејнера, а фајл не може да се хардлинкује преко монтирања, па увози постану пуне копије. Ако желиш хардлинкове, уместо четири опциона монтирања можеш да монтираш један заједнички надређени фолдер (са преузимањима и фолдерима библиотеке унутар њега), а преузимачу даш исто монтирање на истој путањи. Надређени фолдер мора такође да буде један фајл систем. Одвојени NAS дељени фолдери или dataset-ови испод њега и даље праве копије. 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), праве адресе клијената и 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 упозорава при сваком покретању. Ово никад не укида одбијање за мрежне дељене фолдере.

Root фајл систем само за читање

Само /config и /tmp морају бити уписиви:

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

PUID, PGID и UMASK и даље раде.

Покретање као фиксни корисник

services:
  holyarrs:
    user: "1000:1000"

HolyArrs тада не мења власнике, па конфигурациони фолдер мора већ бити уписив за тог корисника. PUID и PGID се игноришу и лог то каже. Ово покрива и Kubernetes runAsUser.

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): не може да се поново означи и контејнер се не би покренуо.
• Health check наведи као листу. Слика контејнера нема 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 checkout-а:

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	Id-јеви су ван мапираног опсега. Погледај Rootless Docker и Podman.
A FILE__ variable cannot be read	Провери путању и да је фајл монтиран.
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.

Повезане странице

• Фолдери
• Прво покретање
• NAS, Synology и Unraid
• Ажурирања