Diegimas

Paleisk HolyArrs per Docker ir atidaryk jį naršyklėje. Tai užtrunka kelias minutes.

Prieš pradedant

• Kompiuteris su Docker ir Docker Compose.
• Tavo medijos aplankai arba vieta, kur juos susikurti. Jei nori, kad failai būtų perkeliami iš karto, o ne kopijuojami, pirma perskaityk puslapį Aplankai.
• NAS, Unraid ar Synology atveju žr. NAS, Synology ir Unraid. Be Docker žr. Portable versija.

Žingsniai

1. Vietiniame diske susikurk konfigūracijos aplanką, pavyzdžiui /srv/holyarrs/config. Ne tinklo aplanką. Docker Desktop atveju vietoj to naudok pavadintą volume. Žr. Docker Desktop.

2. Išsiaiškink naudotoją ir grupę, kuriems priklauso tavo medijos aplankai:

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

   uid naudok kaip PUID, o gid kaip PGID.

3. Išsaugok tai kaip docker-compose.yml ir pakeisk kelius:

   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. Paleisk:

   docker compose up -d
   docker compose ps

   Kai HolyArrs atsiliepia, konteineris rodomas kaip healthy.

5. Atidaryk http://your-server:6262 ir iškart susikurk savininko paskyrą. Numatytojo slaptažodžio nėra. Kol jos nesukursi, savininku taps tas, kuris HolyArrs atidarys pirmas.

6. Atlik sąranką, kuri atsidaro toliau. Žr. Pirmas paleidimas.

Dėmesio

Numatytojo slaptažodžio nėra. Naujo HolyArrs savininku tampa tas, kas jį atidaro pirmas. Susikurk paskyrą dabar.

Jei nori naudoti 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 tag

Tag	Ką gauni
latest	Naujausią versiją
1.0.0 (bet kuri versija)	Būtent tą versiją, ji niekada nesikeičia

Nustatymai paaiškinti

Portai ir aplankai

Nustatymas	Ką daro
-p 6262:6262	Žiniatinklio programa.
-v /config	Duomenų bazės, nustatymai, pagrindinis raktas, backup ir log. Tik vietinis diskas.
-v /movies	Neprivaloma. Filmų Bibliotekos aplankas.
-v /tv	Neprivaloma. Serialų Bibliotekos aplankas.
-v /music	Neprivaloma. Muzikos Bibliotekos aplankas.
-v /downloads	Neprivaloma. Atsisiuntimo programos aplankas atsisiuntimams. Žr. Medijos aplankai.
--read-only=true	Neprivaloma. Žr. Tik skaitymui skirta šakninė failų sistema.
--user=1000:1000	Neprivaloma. Žr. Paleidimas kaip fiksuotas naudotojas.

Aplinkos kintamieji

Kintamasis	Ką daro
PUID, PGID	Naudotojas ir grupė, kuriais veikia HolyArrs. Jei nenurodyta, 1000 ir 1000.
TZ	Laiko juosta, pavyzdžiui Europe/Amsterdam.
UMASK	Neprivaloma. Kokių teisių bitų naujiems failams nesuteikti, pavyzdžiui 022 ar 002.
HOLYARRS_SAVE_PATH	Neprivaloma. Atsisiuntimo programos išsaugojimo aplankas taip, kaip jį mato atsisiuntimo programa.
HOLYARRS_ALLOWED_HOSTS	Neprivaloma. Papildomi pagrindinio kompiuterio vardai, kuriais žmonės pasiekia HolyArrs, atskirti kableliais.
HOLYARRS_TRUSTED_PROXIES	Neprivaloma. Tavo reverse proxy adresas arba tinklas.
HOLYARRS_URL_BASE	Neprivaloma. Aptarnauti HolyArrs po keliu. Žr. URL base ir reverse proxy.
HOLYARRS_MASTER_KEY_FILE	Neprivaloma. Nuskaityti pagrindinį raktą iš atskiro failo.

Bet kuris kintamasis gali būti paimtas iš failo. Prieš pavadinimą įrašyk FILE__, o reikšme nurodyk failo kelią:

environment:
  - FILE__HOLYARRS_ALLOWED_HOSTS=/run/secrets/holyarrs_hosts

Vienas naujos eilutės simbolis failo gale atmetamas. Tai veikia ir su PUID, PGID, UMASK bei TZ. Jei failo nėra, HolyArrs sustoja ir log įraše nurodo kintamąjį. Reikšmės jis niekada neišspausdina.

Image

Image turi HolyArrs ir beveik nieko daugiau. Jame nėra shell, todėl apsidairyti su docker exec negalėsi. Vietoj to skaityk log su docker logs holyarrs arba atidaryk logs/holyarrs.log konfigūracijos aplanke.

HolyArrs komandos per docker exec vis tiek veikia:

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

Image kuriami amd64, 64 bitų ARM ir 32 bitų ARM architektūroms. Kompiuteryje, kuriame yra apie 2.5 GiB atminties ar mažiau, HolyArrs pats įjungia mažos atminties režimą. Tai parašoma pirmoje log eilutėje.

Naudotojas ir grupė

Konteineris kaip root paleidžiamas tik tam, kad pasiruoštų. Prireikus jis atiduoda konfigūracijos aplanką PUID:PGID, o paskui visam laikui perjungia į tą naudotoją. Pirmoje log eilutėje matysi naudotoją, grupę ir umask.

HolyArrs niekada nekeičia tavo medijos ar atsisiuntimų aplankų savininko. Suteik PUID naudotojui rašymo teisę į juos pats. Vien skaitymo teisės nepakanka, nes HolyArrs kuria aplankus ir perkelia failus.

Kai kuriose saugyklose savininkų keisti negalima, pavyzdžiui NFS su root squash, SMB ar tik skaitymui prijungtame aplanke. Tada HolyArrs įrašo įspėjimą ir tęsia darbą. Konfigūracijos aplanką rankiniu būdu padaryk įrašomą PUID:PGID.

Norint perjungti naudotoją, reikia CHOWN, DAC_OVERRIDE, SETUID ir SETGID galimybių (capabilities). Docker jas suteikia pagal numatymą. Jei jų atsisakai, HolyArrs sustoja ir parodo pranešimą. Jis negrįžta prie root. Jei tikrai nori veikti kaip root, nustatyk PUID=0 ir PGID=0.

Papildomos grupės iš group_add: išlaikomos, kai HolyArrs perjungia naudotoją.

UMASK veikia tik naujus failus. Jei jo nenurodysi, liks 022: tu rašai, kiti skaito. Naudok 002, kai rašyti turi ir grupė.

Medijos aplankai

Prijunk tik tuos aplankus, kuriuos naudoji: /movies, /tv ir /music kaip Bibliotekos aplankus, o /downloads kaip atsisiuntimų aplanką.

Patarimas dėl hardlink (kietoji nuoroda): kiekvienas atskirai prijungtas aplankas yra atskiras prijungimas konteinerio viduje, o failo negalima sujungti hardlink tarp skirtingų prijungimų, todėl importas virsta pilnomis kopijomis. Jei nori hardlink, vietoj keturių neprivalomų prijungimų gali prijungti vieną bendrą aukštesnį aplanką (su atsisiuntimais ir Bibliotekos aplankais viduje), o atsisiuntimo programai duoti tą patį prijungimą tuo pačiu keliu. Aukštesnis aplankas taip pat turi būti vienoje failų sistemoje. Atskiri NAS aplankai ar duomenų rinkiniai (dataset) jame vis tiek kopijuojami. Settings > Library folders (nustatymai > Bibliotekos aplankai) įspėja tave, kai HolyArrs priversta kopijuoti.

HOLYARRS_SAVE_PATH siunčiamas atsisiuntimo programai su kiekvienu atsisiuntimu, todėl jis taip pat keičia, kur atsisiuntimo programa išsaugo. Jei jo nenurodysi, liks atsisiuntimo programos nustatymas. Jei jo nenurodai, pridėk atsisiuntimų aplanką per Settings > Library folders > Extra import folders (papildomi importo aplankai), kad galėtum importuoti rankiniu būdu iš jo.

Išsaugok pagrindinį raktą

HolyArrs užšifruoja saugomus slaptažodžius, raktus ir token pagrindiniu raktu. Pirmas paleidimas sukuria /config/holyarrs.key.

Backup šio rakto niekada neturi. Laikyk jo kopiją kitur. Lengviausias būdas: kaip savininkas atidaryk Settings > Backups (nustatymai > backup) ir pasirink Download key kit (atsisiųsti rakto rinkinį). Kad jį grąžintum, pavadink failą holyarrs.key ir padėk jį į konfigūracijos aplanką, kol HolyArrs sustabdytas. Atkūrimas su kitu raktu atmetamas. Su pavadintu volume nėra aplanko, kurį galėtum atidaryti: nukopijuok jį su docker cp holyarrs.key hx:/config/, kaip aprašyta Docker Desktop. Keliesi į naują kompiuterį? Pirma grąžink raktą, tada atkurk backup. Žr. Backup.

Raktą taip pat gali laikyti atskirame tik skaitymui skirtame faile:

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

Failas turi egzistuoti ir turėti 32 neapdorotus baitus, 64 šešioliktainius skaitmenis arba base64 iš 32 baitų. PUID naudotojas turi galėti jį skaityti.

Paleidimas iš naujo ir atkūrimas

Palik paleidimo iš naujo politiką. Atkūrimas patikrinamas ir paruošiamas, tada HolyArrs išeina su būsena 75, kad Docker jį paleistų iš naujo ir pritaikytų atkūrimą. Tam užtenka unless-stopped.

Kad atnaujintum vietinį build, perkompiliuok ir sukurk konteinerį iš naujo; prijungimų nekeisk:

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

Atnaujinant niekada nešalink /config. Žr. Atnaujinimai ir Backup.

Pagrindinio kompiuterio vardai ir reverse proxy

IP adresai ir localhost veikia iš karto. Namų vardas, pavyzdžiui tower.local, kurį naudoji per pirmą sąranką, išsaugomas tau. Kitus vardus pridėk per Allowed host names (leidžiami pagrindinio kompiuterio vardai) skiltyje Settings > Sign-in and security (nustatymai > prisijungimas ir sauga) arba per HOLYARRS_ALLOWED_HOSTS.

Kai reverse proxy prideda X-Forwarded-For, į HOLYARRS_TRUSTED_PROXIES įrašyk tik proxy adresą ar tinklą. Be jo neveikia single sign-on, tikri klientų adresai ir Secure slapukas, o visi už proxy dalijasi vienu prisijungimų limitu. Log nurodo proxy adresą, kurį reikia pridėti. Jei priekyje stovi dar vienas proxy, pavyzdžiui Cloudflare, pridėk ir jo diapazonus.

Su nginx siųsk abi antraštes:

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

Jei jos nesutampa, HolyArrs lankytoją laiko esančiu už tavo tinklo ribų.

Saugumo pagrindai

• Nepersiųsk porto 6262 savo maršrutizatoriuje. Naudok VPN, pavyzdžiui Tailscale, arba reverse proxy su HTTPS.
• Savininko paskyrą susikurk iškart po pirmo paleidimo.
• Pagrindinio rakto kopiją laikyk atskirai nuo konfigūracijos aplanko.
• Laikyk image atnaujintą.

Specialios sąrankos

Docker Desktop (Windows ir Mac)

Docker Desktop dalijasi pagrindinio kompiuterio aplankais per sluoksnį, kuriame duomenų bazės failų užraktai nėra saugūs. HolyArrs atsisako /config ten ir parodo sprendimą per portą 6262. /config naudok pavadintą volume. Medijos aplankai gali likti pagrindinio kompiuterio aplankais.

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:

Kad perkeltum seną konfigūracijos aplanką į volume, sustabdyk HolyArrs ir vykdyk:

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

Kad nukopijuotum backup į išorę: docker cp holyarrs:/config/backups .

Mac kompiuteryje, jei patikrinai, kad tavo aplanke failų užraktai veikia, nustatyk HOLYARRS_ALLOW_DESKTOP_FOLDER=1, kad vis tiek paleistum. HolyArrs įspėja kiekvieno paleidimo metu. Tai niekada neatšaukia atsisakymo tinklo aplankams.

Tik skaitymui skirta šakninė failų sistema

Rašyti turi būti galima tik į /config ir /tmp:

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

PUID, PGID ir UMASK vis tiek veikia.

Paleidimas kaip fiksuotas naudotojas

services:
  holyarrs:
    user: "1000:1000"

Tada HolyArrs nekeičia jokių savininkų, todėl konfigūracijos aplankas jau turi būti įrašomas tam naudotojui. PUID ir PGID ignoruojami, ir log tai pasako. Tai tinka ir Kubernetes runAsUser.

Rootless Docker ir Podman

Rootless režimu root konteinerio viduje yra tavo paties naudotojas, o kiti id pagrindiniame kompiuteryje atvaizduojami dideliais skaičiais. Su PUID=1000 konfigūracijos aplankas pagrindiniame kompiuteryje atitenka svetimam naudotojui.

Ką naudoji	docker info ar podman info rodo	Naudok
Įprastą Docker	nėra rootless	PUID ir PGID kaip įprasta
Rootless Docker	rootless skiltyje Security Options	1 variantą
Rootless Podman	rootless: true	1 arba 2 variantą

1 variantas. Nustatyk PUID=0 ir PGID=0. Tai saugu tik rootless režimu. Niekada taip nedaryk su įprastu Docker ar NAS.

2 variantas. Podman su keep-id, kaip Quadlet faile ~/.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

Arba viena komanda:

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 skirtas SELinux sistemoms. :z naudok aplankams, kuriuos naudoja ir atsisiuntimo programa. Neuždėk nė vieno tinklo aplankui (NFS ar SMB): jo negalima perženklinti, ir konteineris nepasileistų.
• Būklės patikrą nurodyk kaip sąrašą. Image neturi shell.
• Palik paleidimo iš naujo politiką always. Podman paslauga, paleidžianti po perkrovimo, paleidžia tik always konteinerius.
• Kad po perkrovimo viskas pasileistų be prisijungimo, vieną kartą vykdyk loginctl enable-linger $USER. Tada naudok Quadlet failą, o su podman run vykdyk systemctl --user enable podman-restart.service.

Jei aplankas jau priklauso dideliam id, pirma sustabdyk konteinerį, tada:

• Rootless Podman: podman unshare chown -R 0:0 ~/holyarrs/config (1 variantas) arba podman unshare chown -R 1000:1000 ~/holyarrs/config.
• Rootless Docker: rootlesskit chown -R 0:0 ~/holyarrs/config, vykdoma per nsenter į rootless daemon (nsenter -U --preserve-credentials -n -m -t $(cat $XDG_RUNTIME_DIR/docker.pid)).

Susikurk savo image

Iš HolyArrs checkout:

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

Tada kaip image naudok holyarrs:local.

Triktys ir sprendimai

Pirma paleisk doctor. Jis patikrina konfigūraciją, aplankus, tinklą ir laikrodį ir pasako, kaip ištaisyti kiekvieną problemą.

• Konteineris veikia: docker exec holyarrs /holyarrs doctor
• Konteineris nuolat paleidžiamas iš naujo: docker compose run --rm holyarrs doctor

Apie log ir palaikymo paketą žr. Triktys ir sprendimai.

Ką matai	Ką daryti
Konfigūracijos aplankas yra bendrame ar tinklo aplanke	Naudok vietinį diską arba pavadintą volume Docker Desktop atveju. Unraid naudok /mnt/<pool>/appdata/holyarrs.
Konfigūracijos aplankas yra atmintyje	Padėk /config į diską. Unraid patikrink, ar pool kelias egzistuoja. Bandomajam kompiuteriui tai leidžia HOLYARRS_CONFIG_IN_MEMORY=yes.
Į konfigūracijos aplanką negalima rašyti	Pašalink :ro ir patikrink, ar aplankas priklauso PUID:PGID.
Diskas pilnas	Atlaisvink vietos diske, kuriame yra /config, tada paleisk iš naujo.
/config nėra susietas	Žr. žemiau.
Negalima perjungti naudotojo	Grąžink keturias galimybes (capabilities) arba naudok user: "<uid>:<gid>".
PUID/PGID neegzistuoja šiame konteineryje	Id yra už susieto diapazono ribų. Žr. Rootless Docker ir Podman.
FILE__ kintamojo nepavyksta nuskaityti	Patikrink kelią ir ar failas prijungtas.
Permission denied	Patikrink PUID, PGID ir rašymo teisę visuose aplankuose.
Unknown host name	Atidaryk HolyArrs per IP ir pridėk vardą skiltyje Allowed host names.
Importai kopijuojami	Prijunk vieną bendrą aplanką. Žr. Medijos aplankai.
Master key does not match	Grąžink raktą, kuris priklauso toms duomenų bazėms.
Restore staged but the app stays down	Pridėk paleidimo iš naujo politiką ir paleisk konteinerį.

Pamiršai susieti /config?

HolyArrs vis tiek pasileidžia, bet visur įspėja. Pašalinus konteinerį viskas prarandama. Pirma viską išsaugok:

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

Tada susiek ./holyarrs-config:/config (arba pavadintą volume) ir sukurk konteinerį iš naujo. Docker Desktop (Windows ir Mac) atveju naudok pavadintą volume, ne pagrindinio kompiuterio aplanką, ir nukopijuok duomenis, kaip parodyta Docker Desktop. Senesnė sąranka dar gali būti neįvardytame volume. Išvardink juos su docker volume ls.

Susiję puslapiai

• Aplankai
• Pirmas paleidimas
• NAS, Synology ir Unraid
• Atnaujinimai