Pasang

Jalankan HolyArrs di Docker lalu buka di browser kamu. Hanya butuh beberapa menit.

Sebelum mulai

• Sebuah komputer dengan Docker dan Docker Compose.
• Folder media kamu, atau tempat untuk membuatnya. Baca Folder dulu kalau kamu ingin pemindahan instan, bukan salinan.
• Di NAS, Unraid atau Synology, lihat NAS, Synology dan Unraid. Tanpa Docker, lihat Arsip portabel.

Langkah

1. Buat folder untuk konfigurasi di disk lokal, misalnya /srv/holyarrs/config. Jangan di berbagi jaringan. Di Docker Desktop, pakai volume bernama. Lihat Docker Desktop.

2. Cari pengguna dan grup yang memiliki folder media kamu:

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

   Pakai uid sebagai PUID dan gid sebagai PGID.

3. Simpan ini sebagai docker-compose.yml lalu ubah path-nya:

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

   docker compose up -d
   docker compose ps

   Container akan tampil healthy begitu HolyArrs merespons.

5. Buka http://your-server:6262 dan langsung buat akun pemilik. Tidak ada kata sandi bawaan. Sampai akun itu dibuat, siapa pun yang membuka HolyArrs lebih dulu menjadi pemilik.

6. Ikuti penyiapan yang terbuka berikutnya. Lihat Pertama kali dijalankan.

Perhatian

Tidak ada kata sandi bawaan. Siapa pun yang pertama membuka HolyArrs baru akan menjadi pemilik. Buat akunnya sekarang.

Kalau kamu 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

Tag image

Tag	Yang kamu dapat
latest	Versi terbaru
1.0.0 (versi apa pun)	Versi persis itu, tidak pernah berubah

Penjelasan pengaturan

Port dan folder

Pengaturan	Fungsinya
-p 6262:6262	Aplikasi web.
-v /config	Database, pengaturan, kunci utama, backup dan log. Hanya disk lokal.
-v /movies	Opsional. Satu folder pustaka untuk film.
-v /tv	Opsional. Satu folder pustaka untuk serial.
-v /music	Opsional. Satu folder pustaka untuk musik.
-v /downloads	Opsional. Folder unduhan milik Downloader. Lihat Folder media.
--read-only=true	Opsional. Lihat Sistem file root hanya-baca.
--user=1000:1000	Opsional. Lihat Mulai sebagai pengguna tetap.

Variabel lingkungan

Variabel	Fungsinya
PUID, PGID	Pengguna dan grup yang menjalankan HolyArrs. 1000 dan 1000 kalau tidak diisi.
TZ	Zona waktu, misalnya Europe/Amsterdam.
UMASK	Opsional. Bit izin mana yang tidak diberikan ke file baru, misalnya 022 atau 002.
HOLYARRS_SAVE_PATH	Opsional. Folder simpan milik Downloader, seperti yang dilihat Downloader.
HOLYARRS_ALLOWED_HOSTS	Opsional. Nama host tambahan yang dipakai orang untuk membuka HolyArrs, dipisah koma.
HOLYARRS_TRUSTED_PROXIES	Opsional. Alamat atau jaringan reverse proxy kamu.
HOLYARRS_URL_BASE	Opsional. Sajikan HolyArrs di bawah sebuah path. Lihat URL base dan reverse proxy.
HOLYARRS_MASTER_KEY_FILE	Opsional. Baca kunci utama dari file tersendiri.

Variabel apa pun bisa berasal dari sebuah file. Taruh FILE__ di depan namanya dan isi nilainya dengan path file itu:

environment:
  - FILE__HOLYARRS_ALLOWED_HOSTS=/run/secrets/holyarrs_hosts

Satu baris baru di akhir file akan dibuang. Ini juga berlaku untuk PUID, PGID, UMASK dan TZ. Kalau file-nya tidak ada, HolyArrs berhenti dan menyebut nama variabelnya di log. HolyArrs tidak pernah mencetak nilainya.

Image

Image ini berisi HolyArrs dan hampir tidak ada yang lain. Image ini tidak punya shell, jadi kamu tidak bisa docker exec ke dalamnya untuk melihat-lihat. Baca log saja dengan docker logs holyarrs, atau buka logs/holyarrs.log di folder konfigurasi.

Perintah bawaan HolyArrs tetap bisa dijalankan lewat docker exec:

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

Image dibuat untuk amd64, ARM 64-bit dan ARM 32-bit. Di komputer dengan memori sekitar 2.5 GiB atau kurang, HolyArrs mengaktifkan mode memori rendah dengan sendirinya. Baris pertama di log menyebutkannya.

Pengguna dan grup

Container dimulai sebagai root hanya untuk menyiapkan dirinya. Container memberikan folder konfigurasi kepada PUID:PGID kalau perlu, lalu berpindah ke pengguna itu untuk seterusnya. Baris pertama di log menampilkan pengguna, grup dan umask.

HolyArrs tidak pernah mengubah pemilik folder media atau folder unduhan kamu. Beri pengguna PUID izin tulis ke folder-folder itu sendiri. Izin baca saja tidak cukup, karena HolyArrs membuat folder dan memindahkan file.

Sebagian penyimpanan tidak bisa mengubah pemilik, seperti NFS dengan root squash, SMB atau mount hanya-baca. HolyArrs lalu mencatat peringatan dan tetap jalan. Buat folder konfigurasi dapat ditulisi untuk PUID:PGID secara manual.

Untuk berpindah pengguna dibutuhkan capability CHOWN, DAC_OVERRIDE, SETUID dan SETGID. Docker memberikannya secara bawaan. Kalau kamu melepasnya, HolyArrs berhenti dengan sebuah pesan. HolyArrs tidak beralih ke root. Untuk benar-benar berjalan sebagai root, atur PUID=0 dan PGID=0.

Grup tambahan dari group_add: tetap dipertahankan saat HolyArrs berpindah pengguna.

UMASK hanya memengaruhi file baru. Kosongkan untuk tetap memakai 022, yaitu kamu menulis dan yang lain membaca. Pakai 002 kalau sebuah grup juga harus bisa menulis.

Folder media

Mount hanya folder yang kamu pakai: /movies, /tv dan /music sebagai folder pustaka, dan /downloads sebagai folder unduhan.

Tips untuk hardlink (tautan keras): setiap folder yang kamu mount sendiri-sendiri adalah mount terpisah di dalam container, dan sebuah file tidak bisa di-hardlink melintasi mount, sehingga impor menjadi salinan penuh. Kalau kamu ingin hardlink, kamu bisa mount satu folder induk bersama (berisi folder unduhan dan folder pustaka di dalamnya) sebagai ganti keempat mount opsional, lalu beri Downloader mount yang sama di path yang sama. Folder induk itu juga harus berada di satu sistem file. Share atau dataset NAS terpisah di bawahnya tetap membuat salinan. Settings > Library folders memperingatkan kamu saat HolyArrs harus menyalin.

HOLYARRS_SAVE_PATH dikirim ke Downloader bersama setiap unduhan, jadi nilainya juga mengubah tempat Downloader menyimpan. Kosongkan untuk tetap memakai pengaturan milik Downloader sendiri. Kalau dikosongkan, tambahkan folder unduhan di Settings > Library folders > Extra import folders supaya kamu bisa mengimpor manual dari sana.

Simpan kunci utama

HolyArrs mengenkripsi kata sandi, kunci dan token yang tersimpan dengan sebuah kunci utama. Saat pertama kali dimulai, HolyArrs membuat /config/holyarrs.key.

Backup tidak pernah berisi kunci ini. Simpan salinannya di tempat lain. Cara mudahnya: sebagai pemilik, buka Settings > Backups dan pilih Download key kit (unduh paket kunci). Untuk mengembalikannya, beri nama file holyarrs.key dan taruh di folder konfigurasi selagi HolyArrs berhenti. Pemulihan dengan kunci yang berbeda akan ditolak. Dengan volume bernama tidak ada folder yang bisa dibuka: salin ke dalam dengan docker cp holyarrs.key hx:/config/ seperti di Docker Desktop. Pindah ke komputer baru? Kembalikan kuncinya dulu, baru pulihkan backup. Lihat Backup.

Kamu juga bisa menyimpan kunci di file hanya-baca tersendiri:

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

File itu harus ada dan berisi 32 byte mentah, 64 digit hex atau base64 untuk 32 byte. Pengguna PUID harus bisa membacanya.

Restart dan pemulihan

Pertahankan kebijakan restart. Pemulihan diperiksa dan disiapkan, lalu HolyArrs keluar dengan status 75 agar Docker memulainya lagi dan menerapkannya. unless-stopped menangani itu.

Untuk memperbarui build lokal, build ulang dan buat ulang tanpa menyentuh mount:

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

Jangan pernah menghapus /config saat update. Lihat Update dan Backup.

Nama host dan reverse proxy

Alamat IP dan localhost langsung bisa dipakai. Nama rumahan seperti tower.local yang kamu pakai saat penyiapan pertama akan disimpan otomatis. Tambahkan nama lain di bawah Allowed host names (nama host yang diizinkan) di Settings > Sign-in and security, atau di HOLYARRS_ALLOWED_HOSTS.

Kalau reverse proxy menambahkan X-Forwarded-For, isi HOLYARRS_TRUSTED_PROXIES hanya dengan alamat atau jaringan proxy itu. Tanpa itu, single sign-on, alamat klien yang sebenarnya dan cookie Secure tidak berfungsi, dan semua orang di belakang proxy berbagi satu batas login. Log menyebutkan alamat proxy yang perlu ditambahkan. Kalau ada proxy lain di depannya, seperti Cloudflare, tambahkan juga rentang alamatnya.

Dengan nginx, kirim kedua header:

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

Kalau keduanya tidak cocok, HolyArrs menganggap pengunjung berada di luar jaringan kamu.

Dasar-dasar keamanan

• Jangan forward port 6262 di router kamu. Pakai VPN seperti Tailscale, atau reverse proxy dengan HTTPS.
• Buat akun pemilik tepat setelah pertama kali dimulai.
• Simpan salinan kunci utama jauh dari folder konfigurasi.
• Selalu perbarui image.

Penyiapan khusus

Docker Desktop (Windows dan Mac)

Docker Desktop membagikan folder host lewat lapisan yang kunci file database-nya tidak aman. HolyArrs menolak /config di sana dan menampilkan solusinya di port 6262. Pakai volume bernama untuk /config. Folder media boleh tetap berupa folder host.

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 volume, hentikan HolyArrs lalu jalankan:

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

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

Di Mac, kalau kamu sudah memastikan kunci file berfungsi di folder kamu, atur HOLYARRS_ALLOW_DESKTOP_FOLDER=1 agar tetap mulai. HolyArrs memberi peringatan di setiap start. Ini tidak pernah mencabut penolakan untuk berbagi jaringan.

Sistem file root hanya-baca

Hanya /config dan /tmp yang perlu dapat ditulisi:

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

PUID, PGID dan UMASK tetap berfungsi.

Mulai sebagai pengguna tetap

services:
  holyarrs:
    user: "1000:1000"

HolyArrs lalu tidak mengubah pemilik apa pun, jadi folder konfigurasi harus sudah dapat ditulisi oleh pengguna itu. PUID dan PGID diabaikan dan log menyebutkannya. Ini juga berlaku untuk runAsUser di Kubernetes.

Docker dan Podman rootless

Di mode rootless, root di dalam container adalah pengguna kamu sendiri, dan id lain dipetakan ke angka tinggi di host. Dengan PUID=1000, folder konfigurasi berakhir dimiliki oleh orang asing di host.

Yang kamu jalankan	docker info atau podman info menampilkan	Pakai
Docker biasa	tidak ada rootless	PUID dan PGID seperti biasa
Docker rootless	rootless di bawah Security Options	Opsi 1
Podman rootless	rootless: true	Opsi 1 atau 2

Opsi 1. Atur PUID=0 dan PGID=0. Ini aman hanya di mode rootless. Jangan pernah lakukan ini dengan Docker biasa atau di NAS.

Opsi 2. Podman dengan keep-id, sebagai Quadlet di ~/.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. Pakai :z di folder yang dibagikan dengan Downloader. Jangan pakai keduanya di berbagi jaringan (NFS atau SMB): label tidak bisa diubah dan container tidak akan mulai.
• Tulis health check sebagai list. Image ini tidak punya shell.
• Pertahankan kebijakan restart always. Layanan start-after-reboot milik Podman hanya memulai container always.
• Agar mulai setelah reboot tanpa login, jalankan loginctl enable-linger $USER sekali. Lalu pakai file Quadlet, atau untuk podman run jalankan systemctl --user enable podman-restart.service.

Kalau folder itu sudah dimiliki id yang tinggi, hentikan container dulu, lalu:

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

Build image sendiri

Dari checkout HolyArrs:

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

Lalu pakai holyarrs:local sebagai image.

Pemecahan masalah

Jalankan doctor dulu. Doctor memeriksa konfigurasi, folder, jaringan dan jam, lalu memberi tahu cara memperbaiki tiap masalah.

• Container berjalan: docker exec holyarrs /holyarrs doctor
• Container terus restart: docker compose run --rm holyarrs doctor

Lihat Pemecahan masalah untuk log dan paket dukungan.

Yang kamu lihat	Lakukan ini
Config folder is on a shared or network folder (folder konfigurasi ada di folder bersama atau jaringan)	Pakai disk lokal, atau volume bernama di Docker Desktop. Di Unraid pakai /mnt/<pool>/appdata/holyarrs.
Config folder is in memory (folder konfigurasi ada di memori)	Taruh /config di disk. Di Unraid, periksa path pool-nya ada. Untuk komputer uji, HOLYARRS_CONFIG_IN_MEMORY=yes mengizinkannya.
Config folder cannot be written (folder konfigurasi tidak bisa ditulisi)	Hapus :ro dan periksa bahwa PUID:PGID memiliki folder itu.
Disk is full (disk penuh)	Kosongkan ruang di disk yang menyimpan /config, lalu mulai ulang.
/config is not mapped (/config belum dipetakan)	Lihat di bawah.
Cannot switch user (tidak bisa berpindah pengguna)	Kembalikan keempat capability, atau pakai user: "<uid>:<gid>".
PUID/PGID does not exist inside this container (PUID/PGID tidak ada di dalam container ini)	Id-nya di luar rentang yang dipetakan. Lihat Docker dan Podman rootless.
Variabel FILE__ tidak bisa dibaca	Periksa path-nya dan pastikan file-nya di-mount.
Permission denied (izin ditolak)	Periksa PUID, PGID dan izin tulis di semua folder.
Unknown host name (nama host tidak dikenal)	Buka HolyArrs lewat IP dan tambahkan namanya di Allowed host names.
Imports are copied (impor disalin)	Mount satu folder bersama. Lihat Folder media.
Master key does not match (kunci utama tidak cocok)	Kembalikan kunci yang cocok dengan database itu.
Restore staged but the app stays down (pemulihan sudah disiapkan tetapi aplikasi tetap mati)	Tambahkan kebijakan restart lalu mulai container.

Lupa memetakan /config?

HolyArrs tetap mulai, tetapi memperingatkan di mana-mana. Semuanya hilang saat container dihapus. Simpan dulu:

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

Lalu petakan ./holyarrs-config:/config (atau volume bernama) dan buat ulang container. Di Docker Desktop (Windows dan Mac), pakai volume bernama, bukan folder host, dan salin datanya masuk seperti yang ditunjukkan di Docker Desktop. Penyiapan lama mungkin masih berada di volume tanpa nama. Lihat daftarnya dengan docker volume ls.

Terkait

• Folder
• Pertama kali dijalankan
• NAS, Synology dan Unraid
• Update