Kurulum

HolyArrs’ı Docker’da çalıştır ve tarayıcında aç. Birkaç dakika sürer.

Başlamadan önce

• Docker ve Docker Compose kurulu bir bilgisayar.
• Medya klasörlerin ya da onları oluşturacağın bir yer. Kopyalamak yerine anında taşıma istiyorsan önce Klasörler sayfasını oku.
• NAS, Unraid veya Synology kullanıyorsan NAS, Synology ve Unraid sayfasına bak. Docker kullanmıyorsan Taşınabilir arşivler sayfasına bak.

Adımlar

1. Yapılandırma klasörü için yerel bir diskte bir klasör oluştur, örneğin /srv/holyarrs/config. Ağ paylaşımı olmasın. Docker Desktop’ta bunun yerine adlandırılmış birim kullan. Bkz. Docker Desktop.

2. Medya klasörlerinin sahibi olan kullanıcıyı ve grubu bul:

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

   uid değerini PUID olarak, gid değerini PGID olarak kullan.

3. Bunu docker-compose.yml olarak kaydet ve yolları değiştir:

   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. Başlat:

   docker compose up -d
   docker compose ps

   HolyArrs yanıt vermeye başlayınca konteyner sağlıklı görünür.

5. http://your-server:6262 adresini aç ve sahip hesabını hemen oluştur. Varsayılan parola yok. Sen hesabı oluşturana kadar HolyArrs’ı ilk açan kişi sahip olur.

6. Ardından açılan kurulumu izle. Bkz. İlk açılış.

Dikkat

Varsayılan parola yok. Yeni bir HolyArrs’ı ilk açan kişi sahip olur. Hesabı şimdi oluştur.

docker run kullanmayı tercih edersen:

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

İmaj etiketi

Etiket	Ne alırsın
latest	En yeni sürüm
1.0.2 (herhangi bir sürüm)	Tam o sürüm, hiç değişmez

Ayarların açıklaması

Portlar ve klasörler

Ayar	Ne işe yarar
-p 6262:6262	Web uygulaması.
-v /config	Veritabanları, ayarlar, ana anahtar, yedekler ve günlükler. Yalnızca yerel disk.
-v /movies	İsteğe bağlı. Film Kütüphane klasörü.
-v /tv	İsteğe bağlı. Dizi Kütüphane klasörü.
-v /music	İsteğe bağlı. Müzik Kütüphane klasörü.
-v /downloads	İsteğe bağlı. İndiricinin indirme klasörü. Bkz. Medya klasörleri.
--read-only=true	İsteğe bağlı. Bkz. Salt okunur kök dosya sistemi.
--user=1000:1000	İsteğe bağlı. Bkz. Sabit bir kullanıcıyla başlat.

Ortam değişkenleri

Değişken	Ne işe yarar
PUID, PGID	HolyArrs’ın hangi kullanıcı ve grupla çalışacağı. Yazmazsan 1000 ve 1000.
TZ	Saat dilimi, örneğin Europe/Amsterdam.
UMASK	İsteğe bağlı. Yeni dosyalarda hangi izin bitlerinin verilmeyeceği, örneğin 022 veya 002.
HOLYARRS_SAVE_PATH	İsteğe bağlı. İndiricinin kayıt klasörü, indiricinin gördüğü haliyle.
HOLYARRS_ALLOWED_HOSTS	İsteğe bağlı. İnsanların HolyArrs’a ulaşmak için kullandığı ek host adları, virgülle ayrılmış.
HOLYARRS_TRUSTED_PROXIES	İsteğe bağlı. Ters proxy’nin adresi veya ağı.
HOLYARRS_URL_BASE	İsteğe bağlı. HolyArrs’ı bir yolun altında sun. Bkz. URL base ve ters proxy.
HOLYARRS_MASTER_KEY_FILE	İsteğe bağlı. Ana anahtarı kendi dosyasından oku.

Her değişken bir dosyadan gelebilir. Adın başına FILE__ koy ve değer olarak dosyanın yolunu ver:

environment:
  - FILE__HOLYARRS_ALLOWED_HOSTS=/run/secrets/holyarrs_hosts

Dosyanın sonundaki tek satır sonu atılır. Bu PUID, PGID, UMASK ve TZ için de geçerli. Dosya yoksa HolyArrs durur ve değişkenin adını günlükte yazar. Değeri asla yazmaz.

İmaj

İmajda HolyArrs’tan başka neredeyse hiçbir şey yok. Shell yok, bu yüzden içine bakmak için docker exec ile giremezsin. Bunun yerine günlüğü docker logs holyarrs ile oku ya da yapılandırma klasöründeki logs/holyarrs.log dosyasını aç.

HolyArrs’ın kendi komutları docker exec ile yine çalışır:

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

İmajlar amd64, 64 bit ARM ve 32 bit ARM için üretilir. Yaklaşık 2.5 GiB veya daha az belleği olan bir bilgisayarda HolyArrs düşük bellek modunu kendiliğinden açar. Günlüğün ilk satırı bunu söyler.

Kullanıcı ve grup

Konteyner root olarak yalnızca kendini hazırlamak için başlar. Gerekirse yapılandırma klasörünü PUID:PGID kullanıcısına verir, sonra kalıcı olarak o kullanıcıya geçer. Günlüğün ilk satırı kullanıcıyı, grubu ve umask değerini gösterir.

HolyArrs medya ya da indirme klasörlerinin sahibini asla değiştirmez. PUID kullanıcısına bu klasörlerde yazma iznini kendin ver. Okuma izni yetmez, çünkü HolyArrs klasör oluşturur ve dosya taşır.

Bazı depolamalarda sahip değiştirilemez; root squash’li NFS, SMB veya salt okunur bağlama gibi. HolyArrs o zaman bir uyarı yazar ve devam eder. Yapılandırma klasörünü PUID:PGID için elle yazılabilir yap.

Kullanıcı değiştirmek için CHOWN, DAC_OVERRIDE, SETUID ve SETGID yetkileri gerekir. Docker bunları varsayılan olarak verir. Bunları kaldırırsan HolyArrs bir mesajla durur. Root’a geri dönmez. Gerçekten root olarak çalıştırmak için PUID=0 ve PGID=0 yaz.

group_add: ile eklenen ek gruplar, HolyArrs kullanıcı değiştirirken korunur.

UMASK yalnızca yeni dosyaları etkiler. 022 kalsın istiyorsan hiç yazma; bu durumda sen yazarsın, diğerleri okur. Bir grubun da yazması gerekiyorsa 002 kullan.

Medya klasörleri

Yalnızca kullandığın klasörleri bağla: Kütüphane klasörleri olarak /movies, /tv ve /music, indirme klasörü olarak /downloads.

Hardlink (sabit bağlantı) için ipucu: ayrı ayrı bağladığın her klasör konteynerin içinde ayrı bir bağlama noktasıdır ve bir dosya bağlama noktaları arasında hardlink yapılamaz, bu yüzden içe aktarmalar tam kopya olur. Hardlink istiyorsan dört isteğe bağlı bağlama yerine, içinde indirmelerin ve Kütüphane klasörlerinin olduğu tek bir ortak üst klasörü bağlayabilir ve indiriciye aynı bağlamayı aynı yolda verebilirsin. Üst klasör ayrıca tek bir dosya sistemi olmalı. Altındaki ayrı NAS paylaşımları veya dataset’ler yine kopyalar. HolyArrs kopyalamak zorunda kaldığında Settings > Library folders seni uyarır.

HOLYARRS_SAVE_PATH her indirmede indiriciye gönderilir, yani indiricinin nereye kaydettiğini de değiştirir. İndiricinin kendi ayarı kalsın istiyorsan yazma. Yazmazsan, elle içe aktarabilmek için indirme klasörünü Settings > Library folders > Extra import folders altına ekle.

Ana anahtarı sakla

HolyArrs kayıtlı parolaları, anahtarları ve token’ları bir ana anahtarla şifreler. İlk açılışta /config/holyarrs.key oluşur.

Yedekler bu anahtarı içermez. Bir kopyasını başka bir yerde sakla. Kolay yol: sahip olarak Settings > Backups sayfasını aç ve Download key kit (anahtar paketini indir) düğmesini seç. Geri koymak için dosyanın adını holyarrs.key yap ve HolyArrs durmuşken yapılandırma klasörüne koy. Farklı bir anahtarla geri yükleme reddedilir. Adlandırılmış birimde açabileceğin bir klasör yok; Docker Desktop bölümündeki gibi docker cp holyarrs.key hx:/config/ ile içeri kopyala. Yeni bir bilgisayara mı taşınıyorsun? Önce anahtarı geri koy, sonra yedeği geri yükle. Bkz. Yedekler.

Anahtarı kendi salt okunur dosyasında da tutabilirsin:

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

Dosya var olmalı ve 32 ham bayt, 64 onaltılık hane ya da 32 bayt için base64 içermeli. PUID kullanıcısı onu okuyabilmeli.

Yeniden başlatma ve geri yükleme

Bir yeniden başlatma ilkesi tut. Geri yükleme kontrol edilir ve hazırlanır, sonra HolyArrs 75 koduyla çıkar; Docker onu yeniden başlatır ve geri yükleme uygulanır. unless-stopped bunu halleder.

Yerel bir derlemeyi güncellemek için bağlamalara dokunmadan yeniden derle ve yeniden oluştur:

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

Güncelleme sırasında /config klasörünü asla silme. Bkz. Güncellemeler ve Yedekler.

Host adları ve ters proxy’ler

IP adresleri ve localhost ek bir ayar olmadan çalışır. İlk kurulumda kullandığın tower.local gibi bir ev adı senin için kaydedilir. Diğer adları Settings > Sign-in and security altındaki Allowed host names (izin verilen host adları) bölümüne ya da HOLYARRS_ALLOWED_HOSTS değişkenine ekle.

Bir ters proxy X-Forwarded-For eklediğinde, HOLYARRS_TRUSTED_PROXIES değişkenine yalnızca proxy’nin adresini veya ağını yaz. Bu olmadan tek oturum açma, gerçek istemci adresleri ve Secure çerezi çalışmaz, proxy’nin arkasındaki herkes de tek bir giriş limitini paylaşır. Günlük, eklenecek proxy adresini söyler. Önünde Cloudflare gibi başka bir proxy varsa onun aralıklarını da ekle.

nginx ile iki başlığı da gönder:

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

İkisi birbirini tutmazsa HolyArrs ziyaretçiyi ağının dışında sayar.

Güvenlik temelleri

• 6262 portunu router’ında dışarı açma. Tailscale gibi bir VPN ya da HTTPS’li bir ters proxy kullan.
• Sahip hesabını ilk açılıştan hemen sonra oluştur.
• Ana anahtarın bir kopyasını yapılandırma klasöründen uzakta sakla.
• İmajı güncel tut.

Özel kurulumlar

Docker Desktop (Windows ve Mac)

Docker Desktop host klasörlerini, veritabanı dosya kilitlerinin güvenli olmadığı bir katmandan paylaşır. HolyArrs oradaki bir /config klasörünü reddeder ve çözümü 6262 portunda gösterir. /config için adlandırılmış birim kullan. Medya klasörleri host klasörü olarak kalabilir.

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:

Eski bir yapılandırma klasörünü birime taşımak için HolyArrs’ı durdur ve şunu çalıştır:

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

Yedekleri dışarı kopyalamak için: docker cp holyarrs:/config/backups .

Mac’te klasöründe dosya kilitlerinin çalıştığını kontrol ettiysen yine de başlatmak için HOLYARRS_ALLOW_DESKTOP_FOLDER=1 yaz. HolyArrs her başlangıçta uyarır. Bu, ağ paylaşımlarındaki reddi asla kaldırmaz.

Salt okunur kök dosya sistemi

Yalnızca /config ve /tmp yazılabilir olmalı:

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

PUID, PGID ve UMASK yine çalışır.

Sabit bir kullanıcıyla başlat

services:
  holyarrs:
    user: "1000:1000"

HolyArrs o zaman hiçbir sahibi değiştirmez, yani yapılandırma klasörü o kullanıcı tarafından zaten yazılabilir olmalı. PUID ve PGID yok sayılır ve günlük bunu söyler. Kubernetes runAsUser için de bu geçerli.

Rootless Docker ve Podman

Rootless modda konteynerin içindeki root senin kendi kullanıcındır, diğer id’ler de host’ta yüksek numaralara eşlenir. PUID=1000 ile yapılandırma klasörü host’ta yabancı birinin olur.

Ne çalıştırıyorsun	docker info veya podman info ne gösterir	Ne kullan
Normal Docker	rootless yok	PUID ve PGID her zamanki gibi
Rootless Docker	Security Options altında rootless	Seçenek 1
Rootless Podman	rootless: true	Seçenek 1 veya 2

Seçenek 1. PUID=0 ve PGID=0 yaz. Bu yalnızca rootless modda güvenli. Normal Docker’da ya da bir NAS’ta asla yapma.

Seçenek 2. Podman’i keep-id ile, ~/.config/containers/systemd/holyarrs.container içinde bir Quadlet olarak kullan:

[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

Ya da tek komut olarak:

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 SELinux sistemleri içindir. İndiricinin paylaştığı klasörlerde :z kullan. Ağ paylaşımında (NFS veya SMB) ikisini de kullanma: yeniden etiketlenemez ve konteyner başlamaz.
• Sağlık denetimini liste olarak ver. İmajda shell yok.
• Yeniden başlatma ilkesi always kalsın. Podman’in yeniden başlatmadan sonra konteyner başlatan servisi yalnızca always konteynerlerini başlatır.
• Yeniden başlatmadan sonra, giriş yapmasan bile başlaması için bir kez loginctl enable-linger $USER çalıştır. Sonra Quadlet dosyasını kullan, podman run için ise systemctl --user enable podman-restart.service çalıştır.

Klasör zaten yüksek bir id’ye aitse önce konteyneri durdur, sonra:

• Rootless Podman: podman unshare chown -R 0:0 ~/holyarrs/config (Seçenek 1) veya podman unshare chown -R 1000:1000 ~/holyarrs/config.
• Rootless Docker: rootlesskit chown -R 0:0 ~/holyarrs/config, rootless daemon’a nsenter ile girerek çalıştır (nsenter -U --preserve-credentials -n -m -t $(cat $XDG_RUNTIME_DIR/docker.pid)).

Kendi imajını derle

HolyArrs checkout’unun içinden:

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

Sonra imaj olarak holyarrs:local kullan.

Sorun giderme

Önce doctor’ı çalıştır. Yapılandırmayı, klasörleri, ağı ve saati denetler ve her sorunun nasıl çözüleceğini söyler.

• Konteyner çalışıyorsa: docker exec holyarrs /holyarrs doctor
• Konteyner sürekli yeniden başlıyorsa: docker compose run --rm holyarrs doctor

Günlük ve destek paketi için Sorun giderme sayfasına bak.

Gördüğün	Yapman gereken
Config folder is on a shared or network folder	Yerel disk kullan ya da Docker Desktop’ta adlandırılmış birim. Unraid’de /mnt/<pool>/appdata/holyarrs kullan.
Config folder is in memory	/config klasörünü bir diske koy. Unraid’de havuz yolunun var olduğunu kontrol et. Bir test kutusu için HOLYARRS_CONFIG_IN_MEMORY=yes buna izin verir.
Config folder cannot be written	:ro ifadesini kaldır ve klasörün sahibinin PUID:PGID olduğunu kontrol et.
Disk is full	/config klasörünü tutan diskte yer aç, sonra yeniden başlat.
/config is not mapped	Aşağıya bak.
Cannot switch user	Dört yetkiyi geri ekle ya da user: "<uid>:<gid>" kullan.
PUID/PGID does not exist inside this container	İd’ler eşlenen aralığın dışında. Bkz. Rootless Docker ve Podman.
A FILE__ variable cannot be read	Yolu ve dosyanın bağlı olduğunu kontrol et.
Permission denied	PUID, PGID değerlerini ve tüm klasörlerdeki yazma iznini kontrol et.
Unknown host name	HolyArrs’ı IP ile aç ve adı Allowed host names altına ekle.
Imports are copied	Tek bir ortak klasör bağla. Bkz. Medya klasörleri.
Master key does not match	O veritabanlarına ait anahtarı geri koy.
Restore staged but the app stays down	Bir yeniden başlatma ilkesi ekle ve konteyneri başlat.

/config eşlemeyi unuttun mu?

HolyArrs yine başlar ama her yerde uyarır. Konteyner silinince her şey kaybolur. Önce kaydet:

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

Sonra ./holyarrs-config:/config yolunu (ya da adlandırılmış bir birimi) eşle ve konteyneri yeniden oluştur. Docker Desktop’ta (Windows ve Mac) host klasörü değil adlandırılmış birim kullan ve verileri Docker Desktop bölümünde gösterildiği gibi içeri kopyala. Eski bir kurulum hâlâ adsız bir birimde duruyor olabilir. Birimleri docker volume ls ile listele.

İlgili

• Klasörler
• İlk açılış
• NAS, Synology ve Unraid
• Güncellemeler