Asennus

Suorita HolyArrs Dockerissa ja avaa se selaimessa. Siihen menee muutama minuutti.

Ennen kuin aloitat

• Kone, jossa on Docker ja Docker Compose.
• Mediakansiosi tai paikka, johon voit luoda ne. Lue ensin Kansiot, jos haluat siirrot kopioinnin sijaan heti.
• NAS-laitteella, Unraidissa tai Synologyssa katso NAS, Synology ja Unraid. Ilman Dockeria katso Portable-arkistot.

Vaiheet

1. Luo asetuskansio paikalliselle levylle, esimerkiksi /srv/holyarrs/config. Ei verkkojakoa. Docker Desktopissa käytä sen sijaan nimettyä volumea. Katso Docker Desktop.

2. Selvitä käyttäjä ja ryhmä, jotka omistavat mediakansiosi:

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

   Käytä uid-arvoa muuttujan PUID arvona ja gid-arvoa muuttujan PGID arvona.

3. Tallenna tämä tiedostoksi docker-compose.yml ja muuta polut:

   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. Käynnistä se:

   docker compose up -d
   docker compose ps

   Container näkyy tilassa healthy, kun HolyArrs vastaa.

5. Avaa http://your-server:6262 ja luo omistajan tili heti. Oletussalasanaa ei ole. Kunnes luot tilin, HolyArrsin ensimmäisenä avaava henkilö tulee omistajaksi.

6. Seuraa käyttöönottoa, joka aukeaa seuraavaksi. Katso Ensimmäinen käynnistys.

Varoitus

Oletussalasanaa ei ole. Uuden HolyArrsin ensimmäisenä avaava henkilö tulee omistajaksi. Luo tili nyt.

Jos käytät mieluummin komentoa 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-tagi

Tagi	Mitä saat
latest	Uusin versio
1.0.0 (mikä tahansa versio)	Juuri se versio, ei muutu koskaan

Asetukset selitettyinä

Portit ja kansiot

Asetus	Mitä se tekee
-p 6262:6262	Verkkosovellus.
-v /config	Tietokannat, asetukset, pääavain, varmuuskopiot ja lokit. Vain paikallinen levy.
-v /movies	Valinnainen. Elokuvien kirjastokansio.
-v /tv	Valinnainen. Sarjojen kirjastokansio.
-v /music	Valinnainen. Musiikin kirjastokansio.
-v /downloads	Valinnainen. Latausohjelman latauskansio. Katso Mediakansiot.
--read-only=true	Valinnainen. Katso Vain luku -juuritiedostojärjestelmä.
--user=1000:1000	Valinnainen. Katso Käynnistä kiinteänä käyttäjänä.

Ympäristömuuttujat

Muuttuja	Mitä se tekee
PUID, PGID	Käyttäjä ja ryhmä, joina HolyArrs toimii. Jos jätät pois, 1000 ja 1000.
TZ	Aikavyöhyke, esimerkiksi Europe/Amsterdam.
UMASK	Valinnainen. Mitkä oikeusbitit uusista tiedostoista jätetään pois, esimerkiksi 022 tai 002.
HOLYARRS_SAVE_PATH	Valinnainen. Latausohjelman tallennuskansio sellaisena kuin latausohjelma sen näkee.
HOLYARRS_ALLOWED_HOSTS	Valinnainen. Lisää isäntänimiä, joilla HolyArrsiin otetaan yhteys, pilkuilla erotettuina.
HOLYARRS_TRUSTED_PROXIES	Valinnainen. Reverse proxyn osoite tai verkko.
HOLYARRS_URL_BASE	Valinnainen. Tarjoile HolyArrs polun alla. Katso URL base ja reverse proxyt.
HOLYARRS_MASTER_KEY_FILE	Valinnainen. Lue pääavain omasta tiedostostaan.

Minkä tahansa muuttujan arvon voi lukea tiedostosta. Lisää nimen eteen FILE__ ja anna arvoksi tiedoston polku:

environment:
  - FILE__HOLYARRS_ALLOWED_HOSTS=/run/secrets/holyarrs_hosts

Tiedoston lopussa oleva yksi rivinvaihto jätetään pois. Tämä toimii myös muuttujille PUID, PGID, UMASK ja TZ. Jos tiedostoa ei ole, HolyArrs pysähtyy ja kertoo muuttujan nimen lokissa. Se ei koskaan tulosta arvoa.

Image

Image sisältää HolyArrsin ja vähän muuta. Siinä ei ole shelliä, joten et voi käydä siinä katsomassa komennolla docker exec. Lue sen sijaan loki komennolla docker logs holyarrs tai avaa asetuskansiosta logs/holyarrs.log.

HolyArrsin omat komennot toimivat silti komennon docker exec kautta:

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

Imaget tehdään amd64-, 64-bittiselle ARM- ja 32-bittiselle ARM-laitteille. Jos koneessa on noin 2,5 GiB muistia tai vähemmän, HolyArrs ottaa vähämuistitilan käyttöön itse. Lokin ensimmäinen rivi kertoo siitä.

Käyttäjä ja ryhmä

Container käynnistyy rootina vain valmistellakseen itsensä. Se antaa asetuskansion käyttäjälle PUID:PGID tarvittaessa ja vaihtaa sitten pysyvästi siihen käyttäjään. Lokin ensimmäinen rivi näyttää käyttäjän, ryhmän ja umaskin.

HolyArrs ei koskaan muuta mediakansioidesi tai latauskansioidesi omistajaa. Anna käyttäjälle PUID kirjoitusoikeus niihin itse. Lukuoikeus ei riitä, koska HolyArrs luo kansioita ja siirtää tiedostoja.

Joillakin tallennusratkaisuilla omistajaa ei voi vaihtaa, esimerkiksi NFS:llä root squashin kanssa, SMB:llä tai vain luku -liitoksella. HolyArrs kirjoittaa silloin lokiin varoituksen ja jatkaa. Tee asetuskansiosta kirjoitettavissa oleva käyttäjälle PUID:PGID käsin.

Käyttäjän vaihto vaatii oikeudet CHOWN, DAC_OVERRIDE, SETUID ja SETGID. Docker antaa ne oletuksena. Jos poistat ne, HolyArrs pysähtyy ja kertoo syyn. Se ei palaa rootiksi. Jos haluat todella ajaa rootina, aseta PUID=0 ja PGID=0.

Lisäryhmät, jotka annetaan asetuksella group_add:, säilyvät, kun HolyArrs vaihtaa käyttäjää.

UMASK vaikuttaa vain uusiin tiedostoihin. Jos jätät sen pois, arvo pysyy 022: sinä kirjoitat, muut lukevat. Käytä arvoa 002, kun ryhmänkin pitää voida kirjoittaa.

Mediakansiot

Liitä vain ne kansiot, joita käytät: /movies, /tv ja /music kirjastokansioiksi ja /downloads latauskansioksi.

Vinkki hardlinkeille (kova linkki): jokainen erikseen liitetty kansio on containerin sisällä oma liitoksensa, eikä tiedostoa voi linkittää liitosten yli, joten tuonneista tulee täysiä kopioita. Jos haluat hardlinkit, voit liittää neljän valinnaisen liitoksen sijaan yhden yhteisen ylätason kansion (jonka sisällä ovat lataukset ja kirjastokansiot) ja antaa latausohjelmalle saman liitoksen samalla polulla. Ylätason kansion pitää olla myös yksi tiedostojärjestelmä. Sen alla olevat erilliset NAS-jaot tai datasetit kopioivat silti. Kohta Settings > Library folders (asetukset > kirjastokansiot) varoittaa, kun HolyArrsin täytyy kopioida.

HOLYARRS_SAVE_PATH lähetetään latausohjelmalle jokaisen latauksen mukana, joten se muuttaa myös sitä, mihin latausohjelma tallentaa. Jos jätät sen pois, latausohjelman oma asetus pysyy voimassa. Jos jätät sen pois, lisää latauskansio kohtaan Settings > Library folders > Extra import folders (lisätuontikansiot), jotta voit tuoda siitä käsin.

Säilytä pääavain

HolyArrs salaa tallennetut salasanat, avaimet ja tokenit pääavaimella. Ensimmäinen käynnistys luo tiedoston /config/holyarrs.key.

Varmuuskopiot eivät koskaan sisällä tätä avainta. Säilytä kopio jossain muualla. Helpoin tapa: avaa omistajana Settings > Backups (varmuuskopiot) ja valitse Download key kit (lataa avainpaketti). Kun haluat laittaa sen takaisin, nimeä tiedosto holyarrs.key ja aseta se asetuskansioon, kun HolyArrs on pysäytetty. Palautus eri avaimella hylätään. Nimetyssä volumessa ei ole kansiota avattavaksi: kopioi se sisään komennolla docker cp holyarrs.key hx:/config/ kuten kohdassa Docker Desktop. Siirrytkö uudelle koneelle? Laita avain takaisin ensin ja palauta varmuuskopio vasta sitten. Katso Varmuuskopiot.

Voit säilyttää avaimen myös omassa vain luku -tiedostossaan:

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

Tiedoston pitää olla olemassa, ja siinä pitää olla 32 raakatavua, 64 heksadesimaalinumeroa tai base64-muotoiset 32 tavua. Käyttäjän PUID pitää pystyä lukemaan se.

Uudelleenkäynnistys ja palautus

Pidä uudelleenkäynnistyskäytäntö käytössä. Palautus tarkistetaan ja valmistellaan, minkä jälkeen HolyArrs poistuu tilakoodilla 75, jotta Docker käynnistää sen uudelleen ja ottaa palautuksen käyttöön. unless-stopped hoitaa sen.

Paikallisen buildin päivitys: rakenna ja luo container uudelleen koskematta liitoksiin:

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

Älä koskaan poista kansiota /config päivityksen aikana. Katso Päivitykset ja Varmuuskopiot.

Isäntänimet ja reverse proxyt

IP-osoitteet ja localhost toimivat heti. Kotinimi, kuten tower.local, jota käytät ensimmäisessä käyttöönotossa, tallennetaan puolestasi. Lisää muita nimiä kohtaan Allowed host names (sallitut isäntänimet) sivulla Settings > Sign-in and security (kirjautuminen ja turvallisuus) tai muuttujaan HOLYARRS_ALLOWED_HOSTS.

Kun reverse proxy lisää otsakkeen X-Forwarded-For, laita muuttujaan HOLYARRS_TRUSTED_PROXIES vain proxyn osoite tai verkko. Ilman sitä single sign-on, oikeat asiakasosoitteet ja Secure-eväste eivät toimi, ja kaikilla proxyn takana olevilla on yhteinen kirjautumisraja. Loki kertoo, minkä proxyn osoitteen lisäät. Jos edessä on toinen proxy, kuten Cloudflare, lisää myös sen osoitealueet.

Nginxissä lähetä molemmat otsakkeet:

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

Jos nämä kaksi ovat ristiriidassa, HolyArrs pitää kävijää verkkosi ulkopuolisena.

Turvallisuuden perusteet

• Älä ohjaa porttia 6262 reitittimessäsi. Käytä VPN:ää, kuten Tailscalea, tai reverse proxya HTTPS:llä.
• Luo omistajan tili heti ensimmäisen käynnistyksen jälkeen.
• Säilytä pääavaimen kopio kaukana asetuskansiosta.
• Pidä image ajan tasalla.

Erikoiset käyttöönotot

Docker Desktop (Windows ja Mac)

Docker Desktop jakaa isäntäkoneen kansiot kerroksen kautta, jossa tietokannan tiedostolukot eivät ole turvallisia. HolyArrs kieltäytyy kansiosta /config siellä ja näyttää korjauksen portissa 6262. Käytä kansiolle /config nimettyä volumea. Mediakansiot voivat pysyä isäntäkoneen kansioina.

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:

Jos haluat siirtää vanhan asetuskansion volumeen, pysäytä HolyArrs ja suorita:

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

Varmuuskopiot saat ulos näin: docker cp holyarrs:/config/backups .

Macilla, jos olet tarkistanut, että tiedostolukot toimivat kansiossasi, aseta HOLYARRS_ALLOW_DESKTOP_FOLDER=1, niin HolyArrs käynnistyy silti. HolyArrs varoittaa jokaisella käynnistyksellä. Tämä ei koskaan kumoa kieltoa verkkojaoilta.

Vain luku -juuritiedostojärjestelmä

Vain kansioiden /config ja /tmp tarvitsee olla kirjoitettavissa:

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

PUID, PGID ja UMASK toimivat edelleen.

Käynnistä kiinteänä käyttäjänä

services:
  holyarrs:
    user: "1000:1000"

HolyArrs ei silloin muuta omistajia, joten asetuskansion pitää olla jo sen käyttäjän kirjoitettavissa. PUID ja PGID ohitetaan, ja loki kertoo siitä. Tämä kattaa myös Kubernetesin runAsUser-asetuksen.

Rootless Docker ja Podman

Rootless-tilassa root containerin sisällä on oma käyttäjäsi, ja muut id:t vastaavat isäntäkoneella korkeita numeroita. Arvolla PUID=1000 asetuskansion omistajaksi isäntäkoneella päätyy vieras.

Käytät	docker info tai podman info näyttää	Käytä
Tavallinen Docker	ei rootless	PUID ja PGID kuten tavallisesti
Rootless Docker	rootless kohdassa Security Options	Vaihtoehto 1
Rootless Podman	rootless: true	Vaihtoehto 1 tai 2

Vaihtoehto 1. Aseta PUID=0 ja PGID=0. Tämä on turvallista vain rootless-tilassa. Älä koskaan tee näin tavallisella Dockerilla tai NAS-laitteella.

Vaihtoehto 2. Podman keep-id-asetuksella, Quadletina tiedostossa ~/.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

Tai yhtenä komentona:

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 on SELinux-järjestelmille. Käytä :z kansioissa, joita latausohjelma jakaa. Älä käytä kumpaakaan verkkojaolla (NFS tai SMB): sille ei voi asettaa SELinux-nimiöitä uudelleen, eikä container käynnistyisi.
• Anna kuntotarkistus listana. Imagessa ei ole shelliä.
• Pidä uudelleenkäynnistyskäytäntönä always. Podmanin palvelu, joka käynnistää containerit uudelleenkäynnistyksen jälkeen, käynnistää vain always-containerit.
• Jos haluat, että container käynnistyy koneen uudelleenkäynnistyksen jälkeen ilman kirjautumista, suorita kerran loginctl enable-linger $USER. Käytä sitten Quadlet-tiedostoa tai komennon podman run kanssa suorita systemctl --user enable podman-restart.service.

Jos kansio kuuluu jo korkealle id:lle, pysäytä container ensin ja sitten:

• Rootless Podman: podman unshare chown -R 0:0 ~/holyarrs/config (vaihtoehto 1) tai podman unshare chown -R 1000:1000 ~/holyarrs/config.
• Rootless Docker: rootlesskit chown -R 0:0 ~/holyarrs/config, suoritettuna komennolla nsenter rootless-daemoniin (nsenter -U --preserve-credentials -n -m -t $(cat $XDG_RUNTIME_DIR/docker.pid)).

Tee oma image

HolyArrsin checkoutista:

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

Käytä sitten imagena holyarrs:local.

Vianmääritys

Suorita ensin doctor. Se tarkistaa asetukset, kansiot, verkon ja kellon, ja kertoo, miten kunkin ongelman korjaat.

• Container on käynnissä: docker exec holyarrs /holyarrs doctor
• Container käynnistyy jatkuvasti uudelleen: docker compose run --rm holyarrs doctor

Katso Vianmääritys lokista ja tukipaketista.

Näet	Tee näin
Config folder is on a shared or network folder (asetuskansio on jaetulla tai verkkokansiolla)	Käytä paikallista levyä tai Docker Desktopissa nimettyä volumea. Unraidissa käytä /mnt/<pool>/appdata/holyarrs.
Config folder is in memory (asetuskansio on muistissa)	Laita /config levylle. Unraidissa tarkista, että poolin polku on olemassa. Testikoneella HOLYARRS_CONFIG_IN_MEMORY=yes sallii sen.
Config folder cannot be written (asetuskansioon ei voi kirjoittaa)	Poista :ro ja tarkista, että PUID:PGID omistavat kansion.
Disk is full (levy on täynnä)	Vapauta tilaa levyltä, jolla /config on, ja käynnistä uudelleen.
/config is not mapped (ei ole yhdistetty)	Katso alla.
Cannot switch user (käyttäjää ei voi vaihtaa)	Lisää neljä oikeutta takaisin tai käytä user: "<uid>:<gid>".
PUID/PGID does not exist inside this container (PUID/PGID:tä ei ole tässä containerissa)	Id:t ovat yhdistetyn alueen ulkopuolella. Katso Rootless Docker ja Podman.
A FILE__ variable cannot be read (muuttujaa ei voi lukea)	Tarkista polku ja että tiedosto on liitetty.
Permission denied (lupa evätty)	Tarkista PUID, PGID ja kirjoitusoikeus kaikkiin kansioihin.
Unknown host name (tuntematon isäntänimi)	Avaa HolyArrs IP-osoitteella ja lisää nimi kohtaan Allowed host names.
Imports are copied (tuonnit kopioidaan)	Liitä yksi yhteinen kansio. Katso Mediakansiot.
Master key does not match (pääavain ei täsmää)	Laita takaisin avain, joka kuuluu niille tietokannoille.
Restore staged but the app stays down (palautus valmisteltu mutta sovellus pysyy alhaalla)	Lisää uudelleenkäynnistyskäytäntö ja käynnistä container.

Unohtuiko yhdistää /config?

HolyArrs käynnistyy silti, mutta varoittaa kaikkialla. Kaikki katoaa, kun container poistetaan. Tallenna ensin:

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

Yhdistä sitten ./holyarrs-config:/config (tai nimetty volume) ja luo container uudelleen. Docker Desktopissa (Windows ja Mac) käytä nimettyä volumea, älä isäntäkoneen kansiota, ja kopioi tiedot sisään kuten kohdassa Docker Desktop. Vanhempi käyttöönotto voi yhä olla nimettömässä volumessa. Listaa ne komennolla docker volume ls.

Aiheesta lisää

• Kansiot
• Ensimmäinen käynnistys
• NAS, Synology ja Unraid
• Päivitykset