Pasang

Jalankan HolyArrs dalam Docker dan buka dalam pelayar anda. Ia mengambil masa beberapa minit.

Sebelum bermula

• Sebuah komputer dengan Docker dan Docker Compose.
• Folder media anda, atau tempat untuk membuatnya. Baca Folder dahulu jika anda mahu pemindahan segera, bukan salinan.
• Pada NAS, Unraid atau Synology, lihat NAS, Synology dan Unraid. Tanpa Docker, lihat Arkib mudah alih.

Langkah

1. Buat folder untuk konfigurasi pada cakera setempat, contohnya /srv/holyarrs/config. Bukan folder kongsi rangkaian. Pada Docker Desktop, gunakan volum bernama sebagai ganti. Lihat Docker Desktop.

2. Cari pengguna dan kumpulan yang memiliki folder media anda:

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

   Gunakan uid sebagai PUID dan gid sebagai PGID.

3. Simpan ini sebagai docker-compose.yml dan ubah laluannya:

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

   docker compose up -d
   docker compose ps

   Kontena dipaparkan sebagai sihat sebaik sahaja HolyArrs memberi respons.

5. Buka http://your-server:6262 dan buat akaun pemilik serta-merta. Tiada kata laluan lalai. Selagi anda belum membuatnya, sesiapa yang membuka HolyArrs dahulu menjadi pemilik.

6. Ikuti persediaan yang terbuka seterusnya. Lihat Larian pertama.

Awas

Tiada kata laluan lalai. Sesiapa yang membuka HolyArrs baharu dahulu menjadi pemilik. Buat akaun sekarang.

Jika anda lebih suka 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

Teg imej

Teg	Apa yang anda dapat
latest	Keluaran terbaharu
1.0.0 (mana-mana versi)	Versi tepat itu, tidak pernah berubah

Tetapan dijelaskan

Port dan folder

Tetapan	Fungsinya
-p 6262:6262	App web.
-v /config	Pangkalan data, tetapan, kunci induk, sandaran dan log. Cakera setempat sahaja.
-v /movies	Pilihan. Folder Pustaka untuk filem.
-v /tv	Pilihan. Folder Pustaka untuk siri.
-v /music	Pilihan. Folder Pustaka untuk muzik.
-v /downloads	Pilihan. Folder muat turun milik pemuat turun. Lihat Folder media.
--read-only=true	Pilihan. Lihat Sistem fail root baca sahaja.
--user=1000:1000	Pilihan. Lihat Mula sebagai pengguna tetap.

Pemboleh ubah persekitaran

Pemboleh ubah	Fungsinya
PUID, PGID	Pengguna dan kumpulan yang menjalankan HolyArrs. 1000 dan 1000 jika ditinggalkan.
TZ	Zon waktu, contohnya Europe/Amsterdam.
UMASK	Pilihan. Bit kebenaran yang tidak diberikan kepada fail baharu, contohnya 022 atau 002.
HOLYARRS_SAVE_PATH	Pilihan. Folder simpan pemuat turun, seperti yang dilihat oleh pemuat turun.
HOLYARRS_ALLOWED_HOSTS	Pilihan. Nama hos tambahan yang digunakan orang untuk mencapai HolyArrs, dipisahkan dengan koma.
HOLYARRS_TRUSTED_PROXIES	Pilihan. Alamat atau rangkaian proksi songsang (reverse proxy) anda.
HOLYARRS_URL_BASE	Pilihan. Sajikan HolyArrs di bawah satu laluan. Lihat URL base dan proksi songsang.
HOLYARRS_MASTER_KEY_FILE	Pilihan. Baca kunci induk daripada failnya sendiri.

Mana-mana pemboleh ubah boleh datang daripada fail. Letakkan FILE__ di hadapan nama dan berikan laluan fail sebagai nilai:

environment:
  - FILE__HOLYARRS_ALLOWED_HOSTS=/run/secrets/holyarrs_hosts

Satu baris baharu di hujung fail dibuang. Ini berfungsi untuk PUID, PGID, UMASK dan TZ juga. Jika fail tiada, HolyArrs berhenti dan menyebut nama pemboleh ubah dalam log (rekod). Ia tidak pernah mencetak nilainya.

Imej

Imej ini mengandungi HolyArrs dan hampir tiada yang lain. Ia tiada shell, jadi anda tidak boleh docker exec masuk ke dalamnya untuk melihat-lihat. Baca log dengan docker logs holyarrs, atau buka logs/holyarrs.log dalam folder konfigurasi.

Perintah HolyArrs sendiri masih berfungsi melalui docker exec:

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

Imej dibina untuk amd64, ARM 64-bit dan ARM 32-bit. Pada komputer dengan memori kira-kira 2.5 GiB atau kurang, HolyArrs menghidupkan mod memori rendah dengan sendirinya. Baris log pertama menyatakannya.

Pengguna dan kumpulan

Kontena bermula sebagai root hanya untuk menyediakan dirinya. Ia memberikan folder konfigurasi kepada PUID:PGID apabila perlu, kemudian bertukar kepada pengguna itu untuk selama-lamanya. Baris log pertama menunjukkan pengguna, kumpulan dan umask.

HolyArrs tidak pernah menukar pemilik folder media atau folder muat turun anda. Berikan pengguna PUID kebenaran menulis pada folder itu sendiri. Kebenaran membaca tidak mencukupi, kerana HolyArrs membuat folder dan memindahkan fail.

Sesetengah storan tidak boleh menukar pemilik, seperti NFS dengan root squash, SMB atau pelekapan baca sahaja. HolyArrs kemudian mencatat peringatan dalam log dan meneruskan kerja. Jadikan folder konfigurasi boleh ditulis oleh PUID:PGID secara manual.

Menukar pengguna memerlukan keupayaan CHOWN, DAC_OVERRIDE, SETUID dan SETGID. Docker memberikannya secara lalai. Jika anda membuangnya, HolyArrs berhenti dengan satu mesej. Ia tidak kembali kepada root. Untuk benar-benar berjalan sebagai root, tetapkan PUID=0 dan PGID=0.

Kumpulan tambahan daripada group_add: dikekalkan apabila HolyArrs bertukar pengguna.

UMASK hanya memberi kesan kepada fail baharu. Tinggalkan untuk mengekalkan 022, iaitu anda boleh menulis dan orang lain boleh membaca. Gunakan 002 apabila kumpulan juga mesti boleh menulis.

Folder media

Lekapkan hanya folder yang anda gunakan: /movies, /tv dan /music sebagai folder Pustaka dan /downloads sebagai folder muat turun.

Petua untuk hardlink (pautan keras): setiap folder yang anda lekapkan satu demi satu ialah pelekapan berasingan di dalam kontena, dan sesuatu fail tidak boleh di-hardlink merentasi pelekapan, jadi import menjadi salinan penuh. Jika anda mahu hardlink, anda boleh melekapkan satu folder induk kongsi (dengan muat turun dan folder Pustaka di dalamnya) sebagai ganti empat pelekapan pilihan itu, dan berikan pemuat turun pelekapan yang sama pada laluan yang sama. Folder induk itu juga mesti satu sistem fail. Folder kongsi NAS atau set data berasingan di bawahnya tetap menyalin. Settings > Library folders (Tetapan > folder Pustaka) memberi peringatan kepada anda apabila HolyArrs terpaksa menyalin.

HOLYARRS_SAVE_PATH dihantar kepada pemuat turun bersama setiap muat turun, jadi ia juga mengubah tempat pemuat turun menyimpan. Tinggalkan untuk mengekalkan tetapan pemuat turun sendiri. Jika anda meninggalkannya, tambahkan folder muat turun di bawah Settings > Library folders > Extra import folders (Tetapan > folder Pustaka > Folder import tambahan) supaya anda boleh mengimport secara manual daripadanya.

Simpan kunci induk

HolyArrs menyulitkan kata laluan, kunci dan token yang disimpan dengan kunci induk. Permulaan pertama membuat /config/holyarrs.key.

Sandaran tidak pernah mengandungi kunci ini. Simpan satu salinan di tempat lain. Cara mudah: sebagai pemilik, buka Settings > Backups (Tetapan > Sandaran) dan pilih Download key kit (muat turun kit kunci). Untuk meletakkannya semula, namakan fail itu holyarrs.key dan letakkan dalam folder konfigurasi semasa HolyArrs dihentikan. Pemulihan dengan kunci yang berbeza ditolak. Dengan volum bernama tiada folder untuk dibuka: salin masuk dengan docker cp holyarrs.key hx:/config/ seperti dalam Docker Desktop. Berpindah ke komputer baharu? Letakkan kunci semula dahulu, kemudian pulihkan sandaran. Lihat Sandaran.

Anda juga boleh menyimpan kunci dalam failnya sendiri yang baca sahaja:

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

Fail itu mesti wujud dan mengandungi 32 bait mentah, 64 digit hex atau base64 untuk 32 bait. Pengguna PUID mesti boleh membacanya.

Mula semula dan pemulihan

Kekalkan polisi mula semula. Pemulihan disemak dan disediakan, kemudian HolyArrs keluar dengan status 75 supaya Docker memulakannya semula dan menggunakannya. unless-stopped mengendalikannya.

Untuk mengemas kini binaan setempat, bina semula dan cipta semula tanpa menyentuh pelekapan:

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

Jangan sekali-kali buang /config semasa kemas kini. Lihat Kemas kini dan Sandaran.

Nama hos dan proksi songsang

Alamat IP dan localhost berfungsi terus. Nama rumah seperti tower.local yang anda gunakan semasa persediaan pertama disimpan untuk anda. Tambah nama lain di bawah Allowed host names (nama hos yang dibenarkan) dalam Settings > Sign-in and security (Tetapan > Log masuk dan keselamatan), atau dalam HOLYARRS_ALLOWED_HOSTS.

Apabila proksi songsang menambah X-Forwarded-For, letakkan hanya alamat atau rangkaian proksi itu dalam HOLYARRS_TRUSTED_PROXIES. Tanpanya, log masuk tunggal, alamat pelanggan sebenar dan kuki Secure tidak berfungsi, dan semua orang di belakang proksi berkongsi satu had log masuk. Log menyebut alamat proksi yang perlu ditambah. Jika proksi lain berada di hadapan, seperti Cloudflare, tambahkan julatnya juga.

Dengan nginx, hantar kedua-dua pengepala:

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

Jika kedua-duanya tidak sepadan, HolyArrs menganggap pelawat berada di luar rangkaian anda.

Asas keselamatan

• Jangan buat port forward untuk port 6262 pada penghala anda. Gunakan VPN seperti Tailscale, atau proksi songsang dengan HTTPS.
• Buat akaun pemilik sebaik sahaja permulaan pertama.
• Simpan satu salinan kunci induk jauh daripada folder konfigurasi.
• Pastikan imej sentiasa terkini.

Persediaan khas

Docker Desktop (Windows dan Mac)

Docker Desktop berkongsi folder hos melalui satu lapisan di mana kunci fail pangkalan data tidak selamat. HolyArrs menolak /config di situ dan menunjukkan penyelesaiannya pada port 6262. Gunakan volum bernama untuk /config. Folder media boleh kekal sebagai folder hos.

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:

Untuk memindahkan folder konfigurasi lama ke dalam volum, hentikan HolyArrs dan jalankan:

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

Untuk menyalin sandaran keluar: docker cp holyarrs:/config/backups .

Pada Mac, jika anda telah menyemak bahawa kunci fail berfungsi dalam folder anda, tetapkan HOLYARRS_ALLOW_DESKTOP_FOLDER=1 untuk memulakan juga. HolyArrs memberi peringatan pada setiap permulaan. Ini tidak pernah membatalkan penolakan untuk folder kongsi rangkaian.

Sistem fail root baca sahaja

Hanya /config dan /tmp yang perlu boleh ditulis:

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

PUID, PGID dan UMASK masih berfungsi.

Mula sebagai pengguna tetap

services:
  holyarrs:
    user: "1000:1000"

HolyArrs kemudian tidak menukar sebarang pemilik, jadi folder konfigurasi mesti sudah boleh ditulis oleh pengguna itu. PUID dan PGID diabaikan dan log menyatakannya. Ini juga meliputi runAsUser Kubernetes.

Docker rootless dan Podman

Dalam mod rootless, root di dalam kontena ialah pengguna anda sendiri, dan id lain dipetakan kepada nombor tinggi pada hos. Dengan PUID=1000, folder konfigurasi akhirnya dimiliki oleh orang asing pada hos.

Anda jalankan	docker info atau podman info menunjukkan	Gunakan
Docker biasa	tiada rootless	PUID dan PGID seperti biasa
Docker rootless	rootless di bawah Security Options	Pilihan 1
Podman rootless	rootless: true	Pilihan 1 atau 2

Pilihan 1. Tetapkan PUID=0 dan PGID=0. Ini selamat hanya dalam mod rootless. Jangan lakukannya dengan Docker biasa atau pada NAS.

Pilihan 2. Podman dengan keep-id, sebagai Quadlet dalam ~/.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

Atau sebagai satu perintah:

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 untuk sistem SELinux. Gunakan :z pada folder yang dikongsi pemuat turun. Jangan gunakan kedua-duanya pada folder kongsi rangkaian (NFS atau SMB): ia tidak boleh dilabel semula dan kontena tidak akan bermula.
• Berikan semakan kesihatan sebagai senarai. Imej tiada shell.
• Kekalkan polisi mula semula always. Perkhidmatan mula-selepas-reboot Podman hanya memulakan kontena always.
• Untuk bermula selepas reboot tanpa log masuk, jalankan loginctl enable-linger $USER sekali. Kemudian gunakan fail Quadlet, atau untuk podman run jalankan systemctl --user enable podman-restart.service.

Jika folder sudah dimiliki oleh id tinggi, hentikan kontena dahulu, kemudian:

• Podman rootless: podman unshare chown -R 0:0 ~/holyarrs/config (Pilihan 1) atau podman unshare chown -R 1000:1000 ~/holyarrs/config.
• Docker rootless: rootlesskit chown -R 0:0 ~/holyarrs/config, dijalankan melalui nsenter ke dalam daemon rootless (nsenter -U --preserve-credentials -n -m -t $(cat $XDG_RUNTIME_DIR/docker.pid)).

Bina imej anda sendiri

Daripada checkout HolyArrs:

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

Kemudian gunakan holyarrs:local sebagai imej.

Penyelesaian masalah

Jalankan doctor dahulu. Ia menyemak konfigurasi, folder, rangkaian dan jam, dan memberitahu anda cara membetulkan setiap masalah.

• Kontena berjalan: docker exec holyarrs /holyarrs doctor
• Kontena terus dimulakan semula: docker compose run --rm holyarrs doctor

Lihat Penyelesaian masalah untuk log dan pakej sokongan.

Anda nampak	Lakukan ini
Config folder is on a shared or network folder	Gunakan cakera setempat, atau volum bernama pada Docker Desktop. Pada Unraid gunakan /mnt/<pool>/appdata/holyarrs.
Config folder is in memory	Letakkan /config pada cakera. Pada Unraid, semak laluan pool wujud. Untuk komputer ujian, HOLYARRS_CONFIG_IN_MEMORY=yes membenarkannya.
Config folder cannot be written	Buang :ro dan semak bahawa PUID:PGID memiliki folder itu.
Disk is full	Kosongkan ruang pada cakera yang menyimpan /config, kemudian mula semula.
/config is not mapped	Lihat di bawah.
Cannot switch user	Letakkan semula empat keupayaan itu, atau gunakan user: "<uid>:<gid>".
PUID/PGID does not exist inside this container	Id berada di luar julat yang dipetakan. Lihat Docker rootless dan Podman.
A FILE__ variable cannot be read	Semak laluan dan bahawa fail telah dilekapkan.
Permission denied	Semak PUID, PGID dan kebenaran menulis pada semua folder.
Unknown host name	Buka HolyArrs melalui IP dan tambah nama di bawah Allowed host names.
Imports are copied	Lekapkan satu folder kongsi. Lihat Folder media.
Master key does not match	Letakkan semula kunci milik pangkalan data itu.
Restore staged but the app stays down	Tambah polisi mula semula dan mulakan kontena.

Terlupa petakan /config?

HolyArrs masih bermula, tetapi memberi peringatan di mana-mana. Semuanya hilang apabila kontena dibuang. Simpan dahulu:

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

Kemudian petakan ./holyarrs-config:/config (atau volum bernama) dan cipta semula kontena. Pada Docker Desktop (Windows dan Mac), gunakan volum bernama, bukan folder hos, dan salin data masuk seperti yang ditunjukkan dalam Docker Desktop. Persediaan lama mungkin masih berada dalam volum tanpa nama. Senaraikannya dengan docker volume ls.

Berkaitan

• Folder
• Larian pertama
• NAS, Synology dan Unraid
• Kemas kini