Installasjon

Kjør HolyArrs i Docker og åpne den i nettleseren. Det tar noen minutter.

Før du begynner

• En maskin med Docker og Docker Compose.
• Mediemappene dine, eller et sted å opprette dem. Les Mapper først hvis du vil ha umiddelbar flytting i stedet for kopiering.
• På en NAS, Unraid eller Synology, se NAS, Synology og Unraid. Uten Docker, se Portabel versjon.

Trinn

1. Lag en mappe til konfigurasjonen på en lokal disk, for eksempel /srv/holyarrs/config. Ikke en nettverksressurs. På Docker Desktop bruker du et navngitt volume i stedet. Se Docker Desktop.

2. Finn brukeren og gruppen som eier mediemappene dine:

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

   Bruk uid som PUID og gid som PGID.

3. Lagre dette som docker-compose.yml og endre stiene:

   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. Start den:

   docker compose up -d
   docker compose ps

   Containeren vises som healthy når HolyArrs svarer.

5. Åpne http://your-server:6262 og opprett eierkontoen med en gang. Det finnes ikke noe standardpassord. Helt til du oppretter den, blir den som åpner HolyArrs først eieren.

6. Følg oppsettet som åpnes deretter. Se Første oppstart.

Advarsel

Det finnes ikke noe standardpassord. Den som åpner en ny HolyArrs først, blir eieren. Opprett kontoen nå.

Hvis du heller vil bruke 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	Hva du får
latest	Den nyeste versjonen
1.0.0 (en hvilken som helst versjon)	Nøyaktig den versjonen, endres aldri

Innstillinger forklart

Porter og mapper

Innstilling	Hva den gjør
-p 6262:6262	Web-appen.
-v /config	Databaser, innstillinger, hovednøkkelen, backuper og logger. Bare lokal disk.
-v /movies	Valgfri. En bibliotekmappe for filmer.
-v /tv	Valgfri. En bibliotekmappe for serier.
-v /music	Valgfri. En bibliotekmappe for musikk.
-v /downloads	Valgfri. Nedlastingsmappen til nedlasteren. Se Mediemapper.
--read-only=true	Valgfri. Se Skrivebeskyttet rotfilsystem.
--user=1000:1000	Valgfri. Se Start som en fast bruker.

Miljøvariabler

Variabel	Hva den gjør
PUID, PGID	Brukeren og gruppen HolyArrs kjører som. 1000 og 1000 hvis de utelates.
TZ	Tidssone, for eksempel Europe/Amsterdam.
UMASK	Valgfri. Hvilke tillatelsesbiter nye filer ikke får, for eksempel 022 eller 002.
HOLYARRS_SAVE_PATH	Valgfri. Nedlasterens lagringsmappe, slik nedlasteren ser den.
HOLYARRS_ALLOWED_HOSTS	Valgfri. Ekstra vertsnavn folk bruker for å nå HolyArrs, adskilt med komma.
HOLYARRS_TRUSTED_PROXIES	Valgfri. Adressen eller nettverket til reverse proxyen din.
HOLYARRS_URL_BASE	Valgfri. Kjør HolyArrs under en sti. Se URL base og reverse proxyer.
HOLYARRS_MASTER_KEY_FILE	Valgfri. Les hovednøkkelen fra en egen fil.

Alle variabler kan komme fra en fil. Sett FILE__ foran navnet og oppgi stien til filen som verdi:

environment:
  - FILE__HOLYARRS_ALLOWED_HOSTS=/run/secrets/holyarrs_hosts

Ett linjeskift på slutten av filen fjernes. Dette fungerer også for PUID, PGID, UMASK og TZ. Hvis filen mangler, stopper HolyArrs og nevner variabelen i loggen. Verdien skrives aldri ut.

Imaget

Imaget inneholder HolyArrs og lite annet. Det har ingen shell, så du kan ikke bruke docker exec for å se deg rundt inni det. Les loggen i stedet med docker logs holyarrs, eller åpne logs/holyarrs.log i konfigurasjonsmappen.

HolyArrs sine egne kommandoer fungerer fortsatt gjennom docker exec:

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

Imager bygges for amd64, 64-bit ARM og 32-bit ARM. På en maskin med omtrent 2,5 GiB minne eller mindre slår HolyArrs på modus for lite minne av seg selv. Den første linjen i loggen sier fra om det.

Bruker og gruppe

Containeren starter som root bare for å sette seg opp. Den gir konfigurasjonsmappen til PUID:PGID når det trengs, og bytter deretter til den brukeren for godt. Den første linjen i loggen viser bruker, gruppe og umask.

HolyArrs endrer aldri eieren av medie- eller nedlastingsmappene dine. Gi PUID-brukeren skrivetilgang til dem selv. Lesetilgang er ikke nok, fordi HolyArrs oppretter mapper og flytter filer.

Noe lagring kan ikke endre eiere, for eksempel NFS med root squash, SMB eller en skrivebeskyttet mount. HolyArrs logger da en advarsel og fortsetter. Gjør konfigurasjonsmappen skrivbar for PUID:PGID for hånd.

Å bytte bruker krever egenskapene CHOWN, DAC_OVERRIDE, SETUID og SETGID (capabilities). Docker gir dem som standard. Hvis du fjerner dem, stopper HolyArrs med en melding. Den faller ikke tilbake til root. For å kjøre som root på ekte setter du PUID=0 og PGID=0.

Ekstra grupper fra group_add: beholdes når HolyArrs bytter bruker.

UMASK påvirker bare nye filer. Utelat den for å beholde 022, der du skriver og andre leser. Bruk 002 når en gruppe også må kunne skrive.

Mediemapper

Monter bare mappene du bruker: /movies, /tv og /music som bibliotekmapper og /downloads som nedlastingsmappe.

Tips for hardlinks: hver mappe du monterer for seg er en egen mount inni containeren, og en fil kan ikke hardlinkes på tvers av mounter, så importer blir til fulle kopier. Hvis du vil ha hardlinks, kan du i stedet montere én felles overordnet mappe (med nedlastinger og bibliotekmapper inni) i stedet for de fire valgfrie mountene, og gi nedlasteren den samme mounten på samme sti. Den overordnede mappen må også være ett filsystem. Separate NAS-ressurser eller datasett under den gir fortsatt kopiering. Settings > Library folders advarer deg når HolyArrs må kopiere.

HOLYARRS_SAVE_PATH sendes til nedlasteren med hver nedlasting, så den endrer også hvor nedlasteren lagrer. Utelat den for å beholde nedlasterens egen innstilling. Hvis du utelater den, legger du til nedlastingsmappen under Settings > Library folders > Extra import folders, så du kan importere for hånd fra den.

Ta vare på hovednøkkelen

HolyArrs krypterer lagrede passord, nøkler og tokens med en hovednøkkel. Den første oppstarten oppretter /config/holyarrs.key.

Backuper inneholder aldri denne nøkkelen. Ta vare på en kopi et annet sted. Den enkle måten: som eier åpner du Settings > Backups og velger Download key kit (last ned nøkkelpakke). For å legge den tilbake, gi filen navnet holyarrs.key og plasser den i konfigurasjonsmappen mens HolyArrs er stoppet. En gjenoppretting med en annen nøkkel avvises. Med et navngitt volume finnes det ingen mappe å åpne: kopier den inn med docker cp holyarrs.key hx:/config/ som i Docker Desktop. Skal du flytte til en ny maskin? Legg nøkkelen tilbake først, og gjenopprett deretter backupen. Se Backuper.

Du kan også ha nøkkelen i en egen skrivebeskyttet fil:

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

Filen må finnes og inneholde 32 rå bytes, 64 hex-sifre eller base64 for 32 bytes. PUID-brukeren må kunne lese den.

Omstart og gjenoppretting

Behold en omstartspolicy. En gjenoppretting kontrolleres og klargjøres, deretter avslutter HolyArrs med status 75, slik at Docker starter den igjen og tar gjenopprettingen i bruk. unless-stopped ordner det.

For å oppdatere en lokal build bygger du på nytt og oppretter containeren på nytt uten å røre mountene:

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

Fjern aldri /config under en oppdatering. Se Oppdateringer og Backuper.

Vertsnavn og reverse proxyer

IP-adresser og localhost fungerer uten videre. Et hjemmenavn som tower.local som du bruker under første oppsett, lagres for deg. Legg til andre navn under Allowed host names (tillatte vertsnavn) i Settings > Sign-in and security, eller i HOLYARRS_ALLOWED_HOSTS.

Når en reverse proxy legger til X-Forwarded-For, setter du bare proxyens adresse eller nettverk i HOLYARRS_TRUSTED_PROXIES. Uten den fungerer ikke single sign-on, ekte klientadresser og Secure-cookien, og alle bak proxyen deler én innloggingsgrense. Loggen nevner proxy-adressen du skal legge til. Hvis en annen proxy står foran, for eksempel Cloudflare, legger du til adresseområdene dens også.

Med nginx sender du begge headerne:

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

Hvis de to er uenige, behandler HolyArrs den besøkende som utenfor nettverket ditt.

Grunnleggende sikkerhet

• Ikke videresend port 6262 på ruteren din. Bruk et VPN som Tailscale, eller en reverse proxy med HTTPS.
• Opprett eierkontoen rett etter første oppstart.
• Ta vare på en kopi av hovednøkkelen utenfor konfigurasjonsmappen.
• Hold imaget oppdatert.

Spesielle oppsett

Docker Desktop (Windows og Mac)

Docker Desktop deler vertsmapper gjennom et lag der låser på databasefiler ikke er trygge. HolyArrs avviser en /config der og viser løsningen på port 6262. Bruk et navngitt volume til /config. Mediemapper kan fortsatt være vertsmapper.

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:

For å flytte en gammel konfigurasjonsmappe inn i volumet stopper du HolyArrs og kjører:

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

For å kopiere backuper ut: docker cp holyarrs:/config/backups .

På en Mac, hvis du har kontrollert at fillåser fungerer i mappen din, setter du HOLYARRS_ALLOW_DESKTOP_FOLDER=1 for å starte likevel. HolyArrs advarer ved hver oppstart. Dette opphever aldri avvisningen for nettverksressurser.

Skrivebeskyttet rotfilsystem

Bare /config og /tmp må være skrivbare:

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

PUID, PGID og UMASK fungerer fortsatt.

Start som en fast bruker

services:
  holyarrs:
    user: "1000:1000"

HolyArrs endrer da ingen eiere, så konfigurasjonsmappen må allerede være skrivbar for den brukeren. PUID og PGID ignoreres, og loggen sier fra om det. Dette gjelder også Kubernetes runAsUser.

Rootless Docker og Podman

I rootless-modus er root inni containeren din egen bruker, og andre ID-er tilordnes høye tall på verten. Med PUID=1000 ender konfigurasjonsmappen opp med å eies av en fremmed på verten.

Du kjører	docker info eller podman info viser	Bruk
Vanlig Docker	ingen rootless	PUID og PGID som vanlig
Rootless Docker	rootless under Security Options	Valg 1
Rootless Podman	rootless: true	Valg 1 eller 2

Valg 1. Sett PUID=0 og PGID=0. Dette er trygt bare i rootless-modus. Gjør det aldri med vanlig Docker eller på en NAS.

Valg 2. Podman med keep-id, som en Quadlet i ~/.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

Eller som én kommando:

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 er for systemer med SELinux. Bruk :z på mapper nedlasteren deler. Bruk ingen av dem på en nettverksressurs (NFS eller SMB): den kan ikke merkes på nytt, og containeren ville ikke startet.
• Oppgi helsesjekken som en liste. Imaget har ingen shell.
• Behold omstartspolicyen always. Podmans tjeneste for start etter omstart starter bare always-containere.
• For å starte etter en omstart uten å logge inn, kjør loginctl enable-linger $USER én gang. Bruk deretter Quadlet-filen, eller for podman run kjør systemctl --user enable podman-restart.service.

Hvis mappen allerede tilhører en høy ID, stopper du containeren først og kjører deretter:

• Rootless Podman: podman unshare chown -R 0:0 ~/holyarrs/config (valg 1) eller podman unshare chown -R 1000:1000 ~/holyarrs/config.
• Rootless Docker: rootlesskit chown -R 0:0 ~/holyarrs/config, kjørt gjennom nsenter inn i rootless-daemonen (nsenter -U --preserve-credentials -n -m -t $(cat $XDG_RUNTIME_DIR/docker.pid)).

Bygg ditt eget image

Fra HolyArrs-utsjekken din:

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

Bruk deretter holyarrs:local som image.

Feilsøking

Kjør doctor først. Den sjekker konfigurasjonen, mapper, nettverk og klokke, og forteller deg hvordan du løser hvert problem.

• Containeren kjører: docker exec holyarrs /holyarrs doctor
• Containeren starter stadig på nytt: docker compose run --rm holyarrs doctor

Se Feilsøking for loggen og supportpakken.

Du ser	Gjør dette
Config folder is on a shared or network folder	Bruk en lokal disk, eller et navngitt volume på Docker Desktop. På Unraid bruker du /mnt/<pool>/appdata/holyarrs.
Config folder is in memory	Legg /config på en disk. På Unraid, sjekk at pool-stien finnes. På en testmaskin tillater HOLYARRS_CONFIG_IN_MEMORY=yes det.
Config folder cannot be written	Fjern :ro og sjekk at PUID:PGID eier mappen.
Disk is full	Frigjør plass på disken som har /config, og start på nytt.
/config is not mapped	Se nedenfor.
Cannot switch user	Legg tilbake de fire egenskapene, eller bruk user: "<uid>:<gid>".
PUID/PGID does not exist inside this container	ID-ene er utenfor det tilordnede området. Se Rootless Docker og Podman.
A FILE__ variable cannot be read	Sjekk stien og at filen er montert.
Permission denied	Sjekk PUID, PGID og skrivetilgang på alle mapper.
Unknown host name	Åpne HolyArrs med IP og legg til navnet under Allowed host names.
Imports are copied	Monter én felles mappe. Se Mediemapper.
Master key does not match	Legg tilbake nøkkelen som hører til de databasene.
Restore staged but the app stays down	Legg til en omstartspolicy og start containeren.

Glemte du å koble til /config?

HolyArrs starter fortsatt, men advarer overalt. Alt går tapt når containeren fjernes. Lagre det først:

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

Koble deretter til ./holyarrs-config:/config (eller et navngitt volume) og opprett containeren på nytt. På Docker Desktop (Windows og Mac) bruker du et navngitt volume, ikke en vertsmappe, og kopierer dataene inn som vist i Docker Desktop. Et eldre oppsett kan fortsatt ligge i et navnløst volume. List dem med docker volume ls.

Relatert

• Mapper
• Første oppstart
• NAS, Synology og Unraid
• Oppdateringer