Telepítés

Futtasd a HolyArrsot Dockerben, és nyisd meg a böngésződben. Pár perc az egész.

Mielőtt elkezdenéd

• Egy gép Dockerrel és Docker Compose-zal.
• A médiamappáid, vagy egy hely, ahol létrehozhatod őket. Ha azonnali áthelyezést akarsz másolás helyett, előbb olvasd el a Mappák oldalt.
• NAS-on, Unraidon vagy Synologyn lásd: NAS, Synology és Unraid. Docker nélkül lásd: Hordozható archívumok.

Lépések

1. Hozz létre egy mappát a konfigurációnak egy helyi lemezen, például /srv/holyarrs/config. Ne hálózati megosztáson legyen. Docker Desktopon használj helyette névvel ellátott volume-ot. Lásd: Docker Desktop.

2. Nézd meg, melyik felhasználó és csoport a tulajdonosa a médiamappáidnak:

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

   A uid értéke legyen a PUID, a gid értéke a PGID.

3. Mentsd el ezt docker-compose.yml néven, és írd át az útvonalakat:

   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. Indítsd el:

   docker compose up -d
   docker compose ps

   Amint a HolyArrs válaszol, a container healthy állapotot mutat.

5. Nyisd meg a http://your-server:6262 címet, és azonnal hozd létre a tulajdonosi fiókot. Nincs alapértelmezett jelszó. Amíg te nem hozod létre, az lesz a tulajdonos, aki először megnyitja a HolyArrsot.

6. Kövesd a következőként megnyíló beállítást. Lásd: Első indítás.

Figyelem

Nincs alapértelmezett jelszó. Aki először megnyit egy új HolyArrsot, az lesz a tulajdonos. Hozd létre a fiókot most.

Ha inkább a docker run parancsot használod:

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	Mit kapsz
latest	A legújabb verzió
1.0.0 (bármelyik verzió)	Pontosan az a verzió, soha nem változik

A beállítások magyarázata

Portok és mappák

Beállítás	Mit csinál
-p 6262:6262	A webes app.
-v /config	Adatbázisok, beállítások, a főkulcs, backupok és logok. Csak helyi lemezen.
-v /movies	Opcionális. Egy filmes médiatár-mappa.
-v /tv	Opcionális. Egy sorozatos médiatár-mappa.
-v /music	Opcionális. Egy zenés médiatár-mappa.
-v /downloads	Opcionális. A letöltő letöltési mappája. Lásd: Médiamappák.
--read-only=true	Opcionális. Lásd: Csak olvasható gyökér-fájlrendszer.
--user=1000:1000	Opcionális. Lásd: Indítás rögzített felhasználóként.

Környezeti változók

Változó	Mit csinál
PUID, PGID	A felhasználó és a csoport, amelyként a HolyArrs fut. Ha kihagyod, 1000 és 1000.
TZ	Időzóna, például Europe/Amsterdam.
UMASK	Opcionális. Mely jogosultsági biteket hagyja ki az új fájloknál, például 022 vagy 002.
HOLYARRS_SAVE_PATH	Opcionális. A letöltő mentési mappája úgy, ahogy a letöltő látja.
HOLYARRS_ALLOWED_HOSTS	Opcionális. További gépnevek, amelyekkel az emberek elérik a HolyArrsot, vesszővel elválasztva.
HOLYARRS_TRUSTED_PROXIES	Opcionális. A reverse proxyd címe vagy hálózata.
HOLYARRS_URL_BASE	Opcionális. A HolyArrs kiszolgálása egy útvonal alatt. Lásd: URL base és reverse proxyk.
HOLYARRS_MASTER_KEY_FILE	Opcionális. A főkulcs beolvasása egy külön fájlból.

Bármelyik változó jöhet fájlból. Írd a név elé a FILE__ előtagot, és add meg a fájl útvonalát értékként:

environment:
  - FILE__HOLYARRS_ALLOWED_HOSTS=/run/secrets/holyarrs_hosts

A fájl végén lévő egyetlen újsort a HolyArrs eldobja. Ez a PUID, PGID, UMASK és TZ esetén is működik. Ha a fájl hiányzik, a HolyArrs leáll, és a logban megnevezi a változót. Az értéket soha nem írja ki.

Az image

Az image a HolyArrsot tartalmazza, és szinte semmi mást. Nincs benne shell, ezért a docker exec paranccsal nem tudsz belépni körülnézni. Olvasd inkább a logot a docker logs holyarrs paranccsal, vagy nyisd meg a logs/holyarrs.log fájlt a konfigurációs mappában.

A HolyArrs saját parancsai a docker exec segítségével továbbra is működnek:

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

Az image-ek amd64-re, 64 bites ARM-re és 32 bites ARM-re készülnek. Ha a gépben körülbelül 2,5 GiB memória vagy kevesebb van, a HolyArrs magától bekapcsolja a kevés memóriás módot. Ezt az első logsor jelzi.

Felhasználó és csoport

A container csak a saját beállításához indul rootként. Szükség esetén átadja a konfigurációs mappát a PUID:PGID felhasználónak, aztán végleg átvált erre a felhasználóra. Az első logsor kiírja a felhasználót, a csoportot és az umaskot.

A HolyArrs soha nem változtatja meg a média- vagy letöltési mappáid tulajdonosát. Az írási jogot a PUID felhasználónak neked kell megadnod. Az olvasási jog nem elég, mert a HolyArrs mappákat hoz létre és fájlokat mozgat.

Néhány tárolón nem lehet tulajdonost váltani, például NFS-en root squash mellett, SMB-n vagy csak olvasható csatolásnál. Ilyenkor a HolyArrs figyelmeztetést ír a logba, és megy tovább. Tedd írhatóvá a konfigurációs mappát a PUID:PGID számára kézzel.

A felhasználóváltáshoz a CHOWN, DAC_OVERRIDE, SETUID és SETGID capability kell. A Docker alapértelmezés szerint megadja őket. Ha elveszed őket, a HolyArrs leáll egy üzenettel. Nem esik vissza rootra. Ha tényleg rootként akarod futtatni, állítsd be a PUID=0 és PGID=0 értéket.

A group_add: extra csoportjai megmaradnak, amikor a HolyArrs felhasználót vált.

A UMASK csak az új fájlokat érinti. Ha kihagyod, marad a 022: te írsz, mások olvasnak. Használd a 002 értéket, ha a csoportnak is írnia kell.

Médiamappák

Csak azokat a mappákat csatold, amelyeket használsz: a /movies, /tv és /music médiatár-mappaként, a /downloads pedig letöltési mappaként.

Tipp hardlinkekhez (kemény hivatkozás): minden külön csatolt mappa önálló csatolás a containeren belül, és egy fájlt nem lehet csatolások között hardlinkelni, ezért az importálás teljes másolat lesz. Ha hardlinket szeretnél, a négy opcionális csatolás helyett csatolhatsz egyetlen közös szülőmappát (benne a letöltési és a médiatár-mappákkal), és a letöltőnek is ugyanazt a csatolást kell adnod ugyanazon az útvonalon. A szülőmappának ráadásul egyetlen fájlrendszeren kell lennie. Az alatta lévő külön NAS-megosztások vagy datasetek továbbra is másolnak. A Settings > Library folders (Beállítások > médiatár-mappák) figyelmeztet, ha a HolyArrsnak másolnia kell.

A HOLYARRS_SAVE_PATH minden letöltéssel együtt megy a letöltőnek, ezért azt is megváltoztatja, hová ment a letöltő. Ha kihagyod, a letöltő saját beállítása marad érvényben. Ha kihagyod, add hozzá a letöltési mappát a Settings > Library folders > Extra import folders alatt, hogy kézzel importálhass belőle.

Őrizd meg a főkulcsot

A HolyArrs a tárolt jelszavakat, kulcsokat és tokeneket egy főkulccsal titkosítja. Az első indításkor létrejön a /config/holyarrs.key.

A backupok soha nem tartalmazzák ezt a kulcsot. Tarts róla másolatot máshol. A könnyű mód: tulajdonosként nyisd meg a Settings > Backups részt (Beállítások > Backupok), és válaszd a Download key kit (kulcscsomag letöltése) gombot. A visszatételhez nevezd át a fájlt holyarrs.key névre, és tedd a konfigurációs mappába, miközben a HolyArrs le van állítva. Eltérő kulccsal a visszaállítást elutasítja. Névvel ellátott volume-nál nincs mappa, amit megnyithatnál: másold be a docker cp holyarrs.key hx:/config/ paranccsal, ahogy a Docker Desktop résznél áll. Új gépre költözöl? Előbb tedd vissza a kulcsot, utána állítsd vissza a backupot. Lásd: Backupok.

A kulcsot külön, csak olvasható fájlban is tarthatod:

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

A fájlnak léteznie kell, és 32 nyers bájtot, 64 hexadecimális számjegyet vagy 32 bájtnyi base64-et kell tartalmaznia. A PUID felhasználónak olvasnia kell tudnia.

Újraindítás és visszaállítás

Tarts újraindítási szabályt. A visszaállítást a HolyArrs ellenőrzi és előkészíti, aztán kilép a 75-ös státusszal, hogy a Docker újra elindítsa, és alkalmazza. Az unless-stopped ezt kezeli.

Helyi build frissítéséhez építsd újra és hozd létre újra a csatolások érintése nélkül:

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

Frissítés közben soha ne töröld a /config mappát. Lásd: Frissítések és Backupok.

Gépnevek és reverse proxyk

Az IP-címek és a localhost alapból működnek. Egy otthoni név, például tower.local, amelyet az első beállítás során használsz, azt a HolyArrs magától elmenti. Más neveket add hozzá az Allowed host names (engedélyezett gépnevek) alatt a Settings > Sign-in and security (Beállítások > Bejelentkezés és biztonság) részen, vagy a HOLYARRS_ALLOWED_HOSTS változóban.

Ha a reverse proxy hozzáadja az X-Forwarded-For fejlécet, a HOLYARRS_TRUSTED_PROXIES értékébe csak a proxy címét vagy hálózatát írd. Enélkül a single sign-on, a valódi klienscímek és a Secure cookie nem működik, és mindenki a proxy mögött egyetlen bejelentkezési korláton osztozik. A log megnevezi a hozzáadandó proxycímet. Ha előtte egy másik proxy áll, például a Cloudflare, add hozzá annak tartományait is.

Nginx esetén mindkét fejlécet küldd el:

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

Ha a kettő eltér, a HolyArrs a látogatót a hálózatodon kívülinek tekinti.

Biztonsági alapok

• Ne továbbítsd a 6262-es portot a routeren. Használj VPN-t, például Tailscale-t, vagy reverse proxyt HTTPS-sel.
• Hozd létre a tulajdonosi fiókot közvetlenül az első indítás után.
• Tarts másolatot a főkulcsról a konfigurációs mappán kívül.
• Tartsd naprakészen az image-et.

Különleges beállítások

Docker Desktop (Windows és Mac)

A Docker Desktop a gazdagép mappáit olyan rétegen keresztül osztja meg, ahol az adatbázis- fájlzárak nem biztonságosak. A HolyArrs ott elutasít egy /config mappát, és a 6262-es porton mutatja a megoldást. Használj névvel ellátott volume-ot a /config helyett. A médiamappák maradhatnak gazdagép-mappák.

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:

Egy régi konfigurációs mappa volume-ba költöztetéséhez állítsd le a HolyArrsot, és futtasd:

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

A backupok kimásolásához: docker cp holyarrs:/config/backups .

Macen, ha ellenőrizted, hogy a fájlzárak működnek a mappádban, állítsd be a HOLYARRS_ALLOW_DESKTOP_FOLDER=1 értéket, hogy mégis elinduljon. A HolyArrs minden indításkor figyelmeztet. Ez a hálózati megosztásoknál soha nem oldja fel az elutasítást.

Csak olvasható gyökér-fájlrendszer

Csak a /config és a /tmp kell, hogy írható legyen:

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

A PUID, PGID és UMASK ilyenkor is működik.

Indítás rögzített felhasználóként

services:
  holyarrs:
    user: "1000:1000"

Ilyenkor a HolyArrs nem változtat tulajdonost, ezért a konfigurációs mappának már írhatónak kell lennie annak a felhasználónak. A PUID és a PGID figyelmen kívül marad, és a log ezt jelzi. Ez a Kubernetes runAsUser esetére is vonatkozik.

Rootless Docker és Podman

Rootless módban a container belsejében a root a te saját felhasználód, a többi id pedig magas számokra képződik le a gazdagépen. PUID=1000 esetén a konfigurációs mappa a gazdagépen egy idegen tulajdonába kerül.

Ezt futtatod	A docker info vagy podman info ezt mutatja	Használd
Normál Docker	nincs rootless	PUID és PGID a megszokott módon
Rootless Docker	rootless a Security Options alatt	1. lehetőség
Rootless Podman	rootless: true	1. vagy 2. lehetőség

1. lehetőség. Állítsd be a PUID=0 és PGID=0 értéket. Ez csak rootless módban biztonságos. Normál Dockerrel vagy NAS-on soha ne tedd.

2. lehetőség. Podman keep-id móddal, Quadletként a ~/.config/containers/systemd/holyarrs.container fájlban:

[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

Vagy egyetlen parancsként:

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

• A :Z SELinuxos rendszerekhez való. Használd a :z jelölőt azokon a mappákon, amelyeket a letöltő megoszt. Hálózati megosztáson (NFS vagy SMB) egyiket se használd: nem lehet újracímkézni, és a container nem indulna el.
• Az állapotellenőrzést listaként add meg. Az image-ben nincs shell.
• Az újraindítási szabály maradjon always. A Podman újraindítás utáni indító szolgáltatása csak az always containereket indítja el.
• Ha bejelentkezés nélkül akarod elindítani újraindítás után, futtasd egyszer a loginctl enable-linger $USER parancsot. Utána használd a Quadlet fájlt, podman run esetén pedig futtasd a systemctl --user enable podman-restart.service parancsot.

Ha a mappa már egy magas id-hez tartozik, előbb állítsd le a containert, aztán:

• Rootless Podman: podman unshare chown -R 0:0 ~/holyarrs/config (1. lehetőség) vagy podman unshare chown -R 1000:1000 ~/holyarrs/config.
• Rootless Docker: rootlesskit chown -R 0:0 ~/holyarrs/config, az nsenter paranccsal a rootless démonba futtatva (nsenter -U --preserve-credentials -n -m -t $(cat $XDG_RUNTIME_DIR/docker.pid)).

Építsd meg a saját image-edet

A HolyArrs checkoutból:

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

Utána használd a holyarrs:local image-et.

Hibaelhárítás

Először futtasd a doctort. Ellenőrzi a konfigurációt, a mappákat, a hálózatot és az órát, és megmondja, hogyan javítsd ki az egyes hibákat.

• Fut a container: docker exec holyarrs /holyarrs doctor
• A container folyton újraindul: docker compose run --rm holyarrs doctor

A logról és a támogatási csomagról lásd: Hibaelhárítás.

Ezt látod	Ezt tedd
Config folder is on a shared or network folder (a konfigurációs mappa megosztott vagy hálózati mappán van)	Használj helyi lemezt, vagy névvel ellátott volume-ot Docker Desktopon. Unraidon használd a /mnt/<pool>/appdata/holyarrs útvonalat.
Config folder is in memory (a konfigurációs mappa a memóriában van)	Tedd a /config mappát lemezre. Unraidon ellenőrizd, hogy a pool útvonala létezik. Tesztgépen a HOLYARRS_CONFIG_IN_MEMORY=yes engedélyezi.
Config folder cannot be written (a konfigurációs mappába nem lehet írni)	Vedd le a :ro részt, és ellenőrizd, hogy a mappa tulajdonosa a PUID:PGID.
Disk is full (megtelt a lemez)	Szabadíts fel helyet azon a lemezen, amelyen a /config van, aztán indítsd újra.
/config is not mapped (a /config nincs leképezve)	Lásd lent.
Cannot switch user (nem lehet felhasználót váltani)	Add vissza a négy capabilityt, vagy használd a user: "<uid>:<gid>" beállítást.
PUID/PGID does not exist inside this container (a PUID/PGID nem létezik ebben a containerben)	Az id-k a leképezett tartományon kívül vannak. Lásd: Rootless Docker és Podman.
A FILE__ variable cannot be read (egy FILE__ változó nem olvasható)	Ellenőrizd az útvonalat, és hogy a fájl csatolva van.
Permission denied (hozzáférés megtagadva)	Ellenőrizd a PUID, PGID értékét és az írási jogot az összes mappán.
Unknown host name (ismeretlen gépnév)	Nyisd meg a HolyArrsot IP-címmel, és add hozzá a nevet az Allowed host names alatt.
Imports are copied (az importálás másol)	Csatolj egy közös mappát. Lásd: Médiamappák.
Master key does not match (a főkulcs nem egyezik)	Tedd vissza azt a kulcsot, amelyik ezekhez az adatbázisokhoz tartozik.
Restore staged but the app stays down (a visszaállítás előkészítve, de az app nem indul)	Add meg az újraindítási szabályt, és indítsd el a containert.

Elfelejtetted leképezni a /config mappát?

A HolyArrs ilyenkor is elindul, de mindenhol figyelmeztet. Minden elvész, ha a containert eltávolítod. Előbb mentsd el:

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

Aztán képezd le a ./holyarrs-config:/config mappát (vagy egy névvel ellátott volume-ot), és hozd újra létre a containert. Docker Desktopon (Windows és Mac) névvel ellátott volume-ot használj, ne gazdagép- mappát, és másold be az adatokat a Docker Desktop résznél látható módon. Egy régebbi beállítás még névtelen volume-ban lehet. Listázd őket a docker volume ls paranccsal.

Kapcsolódó oldalak

• Mappák
• Első indítás
• NAS, Synology és Unraid
• Frissítések