Install

Patakbuhin ang HolyArrs sa Docker at buksan ito sa browser mo. Aabutin ito ng ilang minuto.

Bago ka magsimula

• Isang computer na may Docker at Docker Compose.
• Ang mga media folder mo, o isang lugar na puwede mong pagawaan ng mga ito. Basahin muna ang Mga folder kung gusto mong agad na mailipat ang mga file sa halip na kopyahin.
• Sa NAS, Unraid o Synology, tingnan ang NAS, Synology at Unraid. Kung walang Docker, tingnan ang Mga portable na archive.

Mga hakbang

1. Gumawa ng folder para sa config sa isang lokal na disk, halimbawa /srv/holyarrs/config. Hindi sa network share. Sa Docker Desktop, gumamit na lang ng named volume. Tingnan ang Docker Desktop.

2. Hanapin ang user at group na may-ari ng mga media folder mo:

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

   Gamitin ang uid bilang PUID at ang gid bilang PGID.

3. I-save ito bilang docker-compose.yml at palitan ang mga path:

   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. Simulan ito:

   docker compose up -d
   docker compose ps

   Lalabas na healthy ang container kapag sumasagot na ang HolyArrs.

5. Buksan ang http://your-server:6262 at gawin agad ang account ng may-ari. Walang default na password. Hangga’t hindi mo ito nagagawa, ang unang magbukas ng HolyArrs ang magiging may-ari.

6. Sundan ang setup na bubukas pagkatapos. Tingnan ang Unang takbo.

Babala

Walang default na password. Ang unang magbukas ng bagong HolyArrs ang magiging may-ari. Gawin na ang account ngayon.

Kung mas gusto mo ang 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

Tag ng image

Tag	Ano ang makukuha mo
latest	Ang pinakabagong bersyon
1.0.0 (kahit anong bersyon)	Ang eksaktong bersyong iyon, hindi nagbabago

Ipinaliwanag ang mga setting

Mga port at folder

Setting	Ano ang ginagawa nito
-p 6262:6262	Ang web app.
-v /config	Mga database, setting, ang master key, mga backup at mga log. Lokal na disk lang.
-v /movies	Opsyonal. Isang folder ng Aklatan para sa pelikula.
-v /tv	Opsyonal. Isang folder ng Aklatan para sa mga palabas.
-v /music	Opsyonal. Isang folder ng Aklatan para sa musika.
-v /downloads	Opsyonal. Ang download folder ng Downloader. Tingnan ang Mga media folder.
--read-only=true	Opsyonal. Tingnan ang Read-only na root filesystem.
--user=1000:1000	Opsyonal. Tingnan ang Magsimula bilang nakapirming user.

Mga environment variable

Variable	Ano ang ginagawa nito
PUID, PGID	Ang user at group na pinagtatakbuhan ng HolyArrs. 1000 at 1000 kapag hindi nilagay.
TZ	Time zone, halimbawa Europe/Amsterdam.
UMASK	Opsyonal. Aling mga permission bit ang hindi isasama sa mga bagong file, halimbawa 022 o 002.
HOLYARRS_SAVE_PATH	Opsyonal. Ang save folder ng Downloader, ayon sa nakikita ng Downloader.
HOLYARRS_ALLOWED_HOSTS	Opsyonal. Mga dagdag na host name na ginagamit ng mga tao para maabot ang HolyArrs, pinaghihiwalay ng kuwit.
HOLYARRS_TRUSTED_PROXIES	Opsyonal. Ang address o network ng reverse proxy mo.
HOLYARRS_URL_BASE	Opsyonal. I-serve ang HolyArrs sa ilalim ng isang path. Tingnan ang URL base at mga reverse proxy.
HOLYARRS_MASTER_KEY_FILE	Opsyonal. Basahin ang master key mula sa sarili nitong file.

Kahit anong variable ay puwedeng galing sa file. Ilagay ang FILE__ sa unahan ng pangalan at ibigay ang path ng file bilang value:

environment:
  - FILE__HOLYARRS_ALLOWED_HOSTS=/run/secrets/holyarrs_hosts

Tinatanggal ang isang newline sa dulo ng file. Gumagana rin ito para sa PUID, PGID, UMASK at TZ. Kung wala ang file, hihinto ang HolyArrs at babanggitin ang pangalan ng variable sa log. Hindi nito kailanman ipinapakita ang value.

Ang image

Ang image ay may laman na HolyArrs at halos wala nang iba. Walang shell dito, kaya hindi ka makakapag-docker exec papasok para tumingin-tingin. Basahin na lang ang log gamit ang docker logs holyarrs, o buksan ang logs/holyarrs.log sa config folder.

Gumagana pa rin sa pamamagitan ng docker exec ang sariling mga command ng HolyArrs:

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

Ang mga image ay ginawa para sa amd64, 64-bit ARM at 32-bit ARM. Sa computer na may humigit-kumulang 2.5 GiB na memory o mas mababa, kusang ino-on ng HolyArrs ang mode na mababa ang memory. Sinasabi iyon ng unang linya ng log.

User at group

Nagsisimula ang container bilang root para lang i-set up ang sarili nito. Ibinibigay nito ang config folder kay PUID:PGID kung kailangan, tapos lilipat na sa user na iyon nang tuluyan. Ipinapakita ng unang linya ng log ang user, group at umask.

Hindi kailanman binabago ng HolyArrs ang owner ng mga media o download folder mo. Ikaw mismo ang magbigay sa user ng PUID ng permiso sa pagsulat. Hindi sapat ang permiso sa pagbasa, dahil gumagawa ng mga folder at naglilipat ng mga file ang HolyArrs.

May ilang storage na hindi kayang magpalit ng owner, tulad ng NFS na may root squash, SMB o read-only na mount. Sa ganitong kaso, magla-log ang HolyArrs ng babala at magpapatuloy. Gawin mong writable para kay PUID:PGID ang config folder nang mano-mano.

Para makalipat ng user, kailangan ang mga capability na CHOWN, DAC_OVERRIDE, SETUID at SETGID. Ibinibigay ng Docker ang mga ito bilang default. Kung tatanggalin mo ang mga ito, hihinto ang HolyArrs na may mensahe. Hindi ito babalik sa root. Para talagang tumakbo bilang root, i-set ang PUID=0 at PGID=0.

Pinapanatili ang mga dagdag na group mula sa group_add: kapag lumipat ng user ang HolyArrs.

Ang UMASK ay nakakaapekto lang sa mga bagong file. Huwag itong ilagay para manatili ang 022, kung saan ikaw ang nagsusulat at nagbabasa ang iba. Gamitin ang 002 kapag kailangang makasulat din ang isang group.

Mga media folder

I-mount lang ang mga folder na ginagamit mo: /movies, /tv at /music bilang mga folder ng Aklatan at /downloads bilang download folder.

Tip para sa hardlink (isang pangalan para sa parehong file): bawat folder na ini-mount mo nang hiwalay ay hiwalay na mount sa loob ng container, at hindi puwedeng i-hardlink ang file sa pagitan ng mga mount, kaya nagiging buong kopya ang mga import. Kung gusto mo ng mga hardlink, puwede kang mag-mount na lang ng isang shared na parent folder (na may downloads at mga folder ng Aklatan sa loob) kapalit ng apat na opsyonal na mount, at ibigay sa Downloader ang parehong mount sa parehong path. Dapat ding isang filesystem lang ang parent folder. Ang magkakahiwalay na NAS share o dataset sa ilalim nito ay magkokopya pa rin. Nagbababala ang Settings > Library folders (mga folder ng Aklatan) kapag kailangang kopyahin ng HolyArrs ang mga file.

Ipinapadala ang HOLYARRS_SAVE_PATH sa Downloader kasama ng bawat download, kaya binabago rin nito kung saan nagse-save ang Downloader. Huwag itong ilagay para manatili ang sariling setting ng Downloader. Kung hindi mo ito nilagay, idagdag ang download folder sa Settings > Library folders > Extra import folders (mga dagdag na folder para sa import) para makapag-import ka nang mano-mano mula roon.

Itago ang master key

Ine-encrypt ng HolyArrs ang mga naka-store na password, key at token gamit ang isang master key. Ang unang start ang gumagawa ng /config/holyarrs.key.

Hindi kailanman kasama ang key na ito sa mga backup. Magtabi ng kopya sa ibang lugar. Ang madaling paraan: bilang may-ari, buksan ang Settings > Backups at piliin ang Download key kit (i-download ang key kit). Para ibalik ito, pangalanan ang file na holyarrs.key at ilagay sa config folder habang nakahinto ang HolyArrs. Tinatanggihan ang restore na iba ang key. Kung named volume ang gamit, walang folder na mabubuksan: kopyahin ito papasok gamit ang docker cp holyarrs.key hx:/config/ tulad ng sa Docker Desktop. Lilipat sa bagong computer? Ibalik muna ang key, saka i-restore ang backup. Tingnan ang Mga backup.

Puwede mo ring itago ang key sa sarili nitong read-only na file:

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

Dapat umiiral ang file at may laman na 32 raw byte, 64 hex digit o base64 para sa 32 byte. Dapat mabasa ito ng user ng PUID.

I-restart at i-restore

Maglagay ng restart policy. Sinusuri at inihahanda muna ang restore, tapos lalabas ang HolyArrs na may status 75 para simulan ito ulit ng Docker at ilapat ito. Ang unless-stopped ang bahala roon.

Para i-update ang local build, i-rebuild at gawing muli ang container nang hindi ginagalaw ang mga mount:

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

Huwag kailanman tanggalin ang /config habang nag-a-update. Tingnan ang Mga update at Mga backup.

Mga host name at reverse proxy

Gumagana agad ang mga IP address at localhost. Ang pangalan sa bahay tulad ng tower.local na ginamit mo sa unang setup ay awtomatikong nase-save. Magdagdag ng ibang pangalan sa ilalim ng Allowed host names (mga pinapayagang host name) sa Settings > Sign-in and security, o sa HOLYARRS_ALLOWED_HOSTS.

Kapag nagdadagdag ng X-Forwarded-For ang isang reverse proxy, ang address o network lang ng proxy ang ilagay sa HOLYARRS_TRUSTED_PROXIES. Kung wala ito, hindi gagana ang single sign-on, ang totoong address ng client at ang Secure cookie, at iisa ang limitasyon sa sign-in ng lahat ng nasa likod ng proxy. Binabanggit ng log ang address ng proxy na dapat idagdag. Kung may isa pang proxy sa harap, tulad ng Cloudflare, idagdag din ang mga range nito.

Sa nginx, ipadala ang dalawang header:

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

Kung hindi magkatugma ang dalawa, ituturing ng HolyArrs na nasa labas ng network mo ang bisita.

Mga pangunahing kaalaman sa seguridad

• Huwag i-forward ang port 6262 sa router mo. Gumamit ng VPN tulad ng Tailscale, o isang reverse proxy na may HTTPS.
• Gawin agad ang account ng may-ari pagkatapos ng unang start.
• Magtabi ng kopya ng master key na malayo sa config folder.
• Panatilihing updated ang image.

Mga espesyal na setup

Docker Desktop (Windows at Mac)

Ibinabahagi ng Docker Desktop ang mga folder ng host sa pamamagitan ng isang layer kung saan hindi ligtas ang mga file lock ng database. Tinatanggihan ng HolyArrs ang /config doon at ipinapakita ang solusyon sa port 6262. Gumamit ng named volume para sa /config. Puwedeng manatiling mga folder ng host ang mga media folder.

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:

Para ilipat ang lumang config folder sa volume, ihinto ang HolyArrs at patakbuhin ito:

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

Para kopyahin palabas ang mga backup: docker cp holyarrs:/config/backups .

Sa Mac, kung nasuri mo na na gumagana ang mga file lock sa folder mo, i-set ang HOLYARRS_ALLOW_DESKTOP_FOLDER=1 para magsimula pa rin. Nagbababala ang HolyArrs sa bawat start. Hindi nito kailanman inaalis ang pagtanggi para sa mga network share.

Read-only na root filesystem

/config at /tmp lang ang kailangang writable:

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

Gumagana pa rin ang PUID, PGID at UMASK.

Magsimula bilang nakapirming user

services:
  holyarrs:
    user: "1000:1000"

Wala nang babaguhing owner ang HolyArrs sa ganitong setup, kaya dapat writable na ng user na iyon ang config folder. Hindi pinapansin ang PUID at PGID at sinasabi iyon ng log. Sakop nito pati ang runAsUser ng Kubernetes.

Rootless Docker at Podman

Sa rootless mode, ang root sa loob ng container ay ang sarili mong user, at ang ibang id ay nagma-map sa matataas na numero sa host. Kapag PUID=1000, magiging owner ng config folder ang isang estranghero sa host.

Ang pinapatakbo mo	Ang ipinapakita ng docker info o podman info	Gamitin
Normal na Docker	walang rootless	PUID at PGID gaya ng dati
Rootless Docker	rootless sa ilalim ng Security Options	Opsyon 1
Rootless Podman	rootless: true	Opsyon 1 o 2

Opsyon 1. I-set ang PUID=0 at PGID=0. Ligtas lang ito sa rootless mode. Huwag itong gawin sa normal na Docker o sa NAS.

Opsyon 2. Podman na may keep-id, bilang Quadlet sa ~/.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

O bilang isang command:

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

• Ang :Z ay para sa mga sistemang may SELinux. Gamitin ang :z sa mga folder na ibinabahagi ng Downloader. Huwag gamitin ng alinman sa network share (NFS o SMB): hindi ito mare-relabel at hindi magsisimula ang container.
• Ibigay ang health check bilang listahan. Walang shell ang image.
• Panatilihing always ang restart policy. Ang serbisyo ng Podman na nagsisimula pagkatapos ng reboot ay nagsisimula lang ng mga container na always.
• Para magsimula pagkatapos ng reboot nang hindi nagsa-sign in, patakbuhin nang isang beses ang loginctl enable-linger $USER. Pagkatapos, gamitin ang Quadlet file, o para sa podman run patakbuhin ang systemctl --user enable podman-restart.service.

Kung pag-aari na ng mataas na id ang folder, ihinto muna ang container, tapos:

• Rootless Podman: podman unshare chown -R 0:0 ~/holyarrs/config (Opsyon 1) o podman unshare chown -R 1000:1000 ~/holyarrs/config.
• Rootless Docker: rootlesskit chown -R 0:0 ~/holyarrs/config, patakbuhin sa pamamagitan ng nsenter papasok sa rootless daemon (nsenter -U --preserve-credentials -n -m -t $(cat $XDG_RUNTIME_DIR/docker.pid)).

Gumawa ng sarili mong image

Mula sa checkout ng HolyArrs:

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

Pagkatapos, gamitin ang holyarrs:local bilang image.

Pag-troubleshoot

Patakbuhin muna ang doctor. Sinusuri nito ang config, mga folder, network at orasan, at sinasabi kung paano ayusin ang bawat problema.

• Tumatakbo ang container: docker exec holyarrs /holyarrs doctor
• Paulit-ulit na nagre-restart ang container: docker compose run --rm holyarrs doctor

Tingnan ang Pag-troubleshoot para sa log at sa support bundle.

Nakikita mo	Gawin ito
Nasa shared o network na folder ang config folder	Gumamit ng lokal na disk, o named volume sa Docker Desktop. Sa Unraid gamitin ang /mnt/<pool>/appdata/holyarrs.
Nasa memory ang config folder	Ilagay ang /config sa isang disk. Sa Unraid, tingnan kung umiiral ang path ng pool. Para sa test box, pinapayagan ito ng HOLYARRS_CONFIG_IN_MEMORY=yes.
Hindi masulatan ang config folder	Alisin ang :ro at tingnan kung pag-aari ng PUID:PGID ang folder.
Puno na ang disk	Magbakante ng espasyo sa disk na may hawak ng /config, tapos i-restart.
Hindi naka-map ang /config	Tingnan sa ibaba.
Hindi makalipat ng user	Ibalik ang apat na capability, o gamitin ang user: "<uid>:<gid>".
Walang PUID/PGID sa loob ng container na ito	Nasa labas ng naka-map na range ang mga id. Tingnan ang Rootless Docker at Podman.
Hindi mabasa ang isang variable na FILE__	Tingnan ang path at kung naka-mount ang file.
Permission denied	Tingnan ang PUID, PGID at permiso sa pagsulat sa lahat ng folder.
Hindi kilalang host name	Buksan ang HolyArrs gamit ang IP at idagdag ang pangalan sa ilalim ng Allowed host names.
Kinokopya ang mga import	Mag-mount ng isang shared na folder. Tingnan ang Mga media folder.
Hindi tugma ang master key	Ibalik ang key na kabilang sa mga database na iyon.
Naihanda na ang restore pero nananatiling nakahinto ang app	Magdagdag ng restart policy at simulan ang container.

Nakalimutang i-map ang /config?

Magsisimula pa rin ang HolyArrs, pero magbababala ito sa lahat ng lugar. Mawawala ang lahat kapag inalis ang container. I-save muna ito:

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

Pagkatapos, i-map ang ./holyarrs-config:/config (o isang named volume) at gawing muli ang container. Sa Docker Desktop (Windows at Mac), gumamit ng named volume, hindi folder ng host, at kopyahin papasok ang data gaya ng ipinakita sa Docker Desktop. Maaaring nasa unnamed volume pa ang mas lumang setup. Ilista ang mga ito gamit ang docker volume ls.

Kaugnay

• Mga folder
• Unang takbo
• NAS, Synology at Unraid
• Mga update