نصب

تازه‌وارد

HolyArrs را در Docker اجرا کنید و در مرورگر باز کنید. چند دقیقه بیشتر طول نمی‌کشد.

پیش از شروع

رایانه‌ای که Docker و Docker Compose دارد.
پوشه‌های رسانهٔ شما، یا جایی برای ساختن آن‌ها. اگر می‌خواهید فایل‌ها به‌جای کپی شدن فوری جابه‌جا شوند، اول پوشه‌ها را بخوانید.
روی NAS، Unraid یا Synology NAS، Synology و Unraid را ببینید. بدون Docker، آرشیوهای قابل‌حمل را ببینید.

مراحل

روی یک دیسک محلی پوشه‌ای برای پیکربندی بسازید، برای مثال /srv/holyarrs/config. نه روی اشتراک شبکه. در Docker Desktop به‌جای آن از یک ولوم نام‌دار استفاده کنید. Docker Desktop را ببینید.
کاربر و گروهی را پیدا کنید که صاحب پوشه‌های رسانهٔ شما هستند:
Terminal window
```
id youruser
# uid=1000(youruser) gid=1000(youruser)
```
uid را برای PUID و gid را برای PGID به کار ببرید.

این را با نام docker-compose.yml ذخیره کنید و مسیرها را تغییر دهید:

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

آن را شروع کنید:
Terminal window
```
docker compose up -d
docker compose ps
```
وقتی HolyArrs پاسخ بدهد، کانتینر با وضعیت healthy نمایش داده می‌شود.
http://your-server:6262 را باز کنید و همان لحظه حساب مالک را بسازید. گذرواژهٔ پیش‌فرض وجود ندارد. تا وقتی حساب را نساخته‌اید، هر کسی که اول HolyArrs را باز کند مالک می‌شود.
راه‌اندازی‌ای را که بعد از آن باز می‌شود دنبال کنید. اولین اجرا را ببینید.

اگر 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

تگ ایمیج

تگ	چه چیزی می‌گیرید
`latest`	جدیدترین نسخه
`1.0.0` (هر نسخه‌ای)	همان نسخهٔ مشخص، هرگز تغییر نمی‌کند

توضیح تنظیمات

پورت‌ها و پوشه‌ها

تنظیم	چه کار می‌کند
`-p 6262:6262`	برنامهٔ وب.
`-v /config`	پایگاه‌های داده، تنظیمات، کلید اصلی، بکاپ‌ها و لاگ‌ها. فقط دیسک محلی.
`-v /movies`	اختیاری. یک پوشهٔ کتابخانه برای فیلم‌ها.
`-v /tv`	اختیاری. یک پوشهٔ کتابخانه برای سریال‌ها.
`-v /music`	اختیاری. یک پوشهٔ کتابخانه برای موسیقی.
`-v /downloads`	اختیاری. پوشهٔ دانلود دانلودر. پوشه‌های رسانه را ببینید.
`--read-only=true`	اختیاری. سیستم فایل ریشهٔ فقط‌خواندنی را ببینید.
`--user=1000:1000`	اختیاری. شروع با کاربر ثابت را ببینید.

متغیرهای محیطی

متغیر	چه کار می‌کند
`PUID`, `PGID`	کاربر و گروهی که HolyArrs با آن اجرا می‌شود. اگر ننویسید 1000 و 1000 است.
`TZ`	منطقهٔ زمانی، برای مثال `Europe/Amsterdam`.
`UMASK`	اختیاری. اینکه فایل‌های تازه کدام بیت‌های دسترسی را نداشته باشند، برای مثال `022` یا `002`.
`HOLYARRS_SAVE_PATH`	اختیاری. پوشهٔ ذخیرهٔ دانلودر، همان‌طور که دانلودر آن را می‌بیند.
`HOLYARRS_ALLOWED_HOSTS`	اختیاری. نام میزبان‌های اضافه‌ای که کاربران برای رسیدن به HolyArrs به کار می‌برند، جداشده با کاما.
`HOLYARRS_TRUSTED_PROXIES`	اختیاری. نشانی یا شبکهٔ ریورس پراکسی شما.
`HOLYARRS_URL_BASE`	اختیاری. HolyArrs را زیر یک مسیر ارائه می‌دهد. URL base و ریورس پراکسی‌ها را ببینید.
`HOLYARRS_MASTER_KEY_FILE`	اختیاری. کلید اصلی را از فایل جداگانهٔ خودش می‌خواند.

هر متغیر می‌تواند از یک فایل بیاید. FILE__ را جلوی نام بگذارید و مسیر فایل را به‌عنوان مقدار بدهید:

environment:
  - FILE__HOLYARRS_ALLOWED_HOSTS=/run/secrets/holyarrs_hosts

یک خط جدید در انتهای فایل حذف می‌شود. این برای PUID، PGID، UMASK و TZ هم کار می‌کند. اگر فایل نباشد، HolyArrs متوقف می‌شود و نام متغیر را در لاگ می‌نویسد. مقدار را هرگز چاپ نمی‌کند.

ایمیج

ایمیج HolyArrs را دارد و تقریباً چیز دیگری ندارد. شل ندارد، پس نمی‌توانید با docker exec واردش شوید و اطرافش را ببینید. به‌جای آن لاگ را با docker logs holyarrs بخوانید، یا logs/holyarrs.log را در پوشهٔ پیکربندی باز کنید.

دستورهای خود HolyArrs هنوز با docker exec کار می‌کنند:

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

ایمیج‌ها برای amd64، ARM ‏64 بیتی و ARM ‏32 بیتی ساخته می‌شوند. روی رایانه‌ای با حدود 2.5 GiB حافظهٔ RAM یا کمتر، HolyArrs حالت کم‌حافظه را خودش روشن می‌کند. اولین خط لاگ این را می‌گوید.

کاربر و گروه

کانتینر فقط برای راه‌اندازی خودش با root شروع می‌شود. در صورت نیاز پوشهٔ پیکربندی را به PUID:PGID می‌دهد و بعد برای همیشه به آن کاربر تغییر می‌کند. اولین خط لاگ کاربر، گروه و umask را نشان می‌دهد.

HolyArrs هرگز صاحب پوشه‌های رسانه یا دانلود شما را تغییر نمی‌دهد. دسترسی نوشتن را خودتان به کاربر PUID بدهید. دسترسی خواندن کافی نیست، چون HolyArrs پوشه می‌سازد و فایل جابه‌جا می‌کند.

بعضی فضاهای ذخیره‌سازی نمی‌توانند صاحب را عوض کنند، مثل NFS با root squash، SMB یا یک مونت فقط‌خواندنی. HolyArrs در این حالت هشدار را در لاگ می‌نویسد و ادامه می‌دهد. پوشهٔ پیکربندی را خودتان برای PUID:PGID قابل‌نوشتن کنید.

تغییر کاربر به قابلیت‌های CHOWN، DAC_OVERRIDE، SETUID و SETGID نیاز دارد. Docker آن‌ها را به‌طور پیش‌فرض می‌دهد. اگر آن‌ها را بردارید، HolyArrs با یک پیام متوقف می‌شود. به root برنمی‌گردد. برای اجرا با root، PUID=0 و PGID=0 را تنظیم کنید.

گروه‌های اضافه از group_add: هنگام تغییر کاربر نگه داشته می‌شوند.

UMASK فقط روی فایل‌های تازه اثر دارد. اگر ننویسید 022 می‌ماند، یعنی شما می‌نویسید و بقیه می‌خوانند. وقتی یک گروه هم باید بنویسد، 002 را به کار ببرید.

پوشه‌های رسانه

فقط پوشه‌هایی را مونت کنید که به کار می‌برید: /movies، /tv و /music به‌عنوان پوشه‌های کتابخانه و /downloads به‌عنوان پوشهٔ دانلود.

نکته دربارهٔ hardlink (پیوند سخت): هر پوشه‌ای که جداگانه مونت می‌کنید داخل کانتینر یک مونت جدا است و فایل را نمی‌شود بین مونت‌ها hardlink کرد، پس واردکردن‌ها به کپی کامل تبدیل می‌شوند. اگر hardlink می‌خواهید، می‌توانید به‌جای چهار مونت اختیاری، یک پوشهٔ والد مشترک (با پوشه‌های دانلود و کتابخانه داخل آن) مونت کنید و همان مونت را با همان مسیر به دانلودر بدهید. پوشهٔ والد باید یک سیستم فایل هم باشد. اشتراک‌ها یا دیتاست‌های جداگانهٔ NAS زیر آن باز هم کپی می‌شوند. Settings > Library folders وقتی HolyArrs باید کپی کند به شما هشدار می‌دهد.

HOLYARRS_SAVE_PATH با هر دانلود به دانلودر فرستاده می‌شود، پس جای ذخیرهٔ دانلودر را هم تغییر می‌دهد. اگر ننویسید تنظیم خود دانلودر می‌ماند. اگر ننویسید، پوشهٔ دانلود را زیر Settings > Library folders > Extra import folders اضافه کنید تا بتوانید از آن دستی وارد کنید.

کلید اصلی را نگه دارید

HolyArrs گذرواژه‌ها، کلیدها و توکن‌های ذخیره‌شده را با یک کلید اصلی رمزگذاری می‌کند. اولین شروع /config/holyarrs.key را می‌سازد.

بکاپ‌ها هرگز این کلید را ندارند. یک کپی از آن را جای دیگری نگه دارید. راه آسان: به‌عنوان مالک، Settings > Backups را باز کنید و Download key kit (دانلود بستهٔ کلید) را انتخاب کنید. برای برگرداندن آن، نام فایل را holyarrs.key بگذارید و هنگامی که HolyArrs متوقف است در پوشهٔ پیکربندی بگذارید. بازیابی با کلید دیگر رد می‌شود. با یک ولوم نام‌دار پوشه‌ای برای باز کردن نیست: آن را با docker cp holyarrs.key hx:/config/ وارد کنید، مثل Docker Desktop. به رایانهٔ تازه می‌روید؟ اول کلید را برگردانید، بعد بکاپ را بازیابی کنید. بکاپ‌ها را ببینید.

می‌توانید کلید را در فایل فقط‌خواندنی جداگانه هم نگه دارید:

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

فایل باید وجود داشته باشد و 32 بایت خام، 64 رقم hex یا base64 برای 32 بایت داشته باشد. کاربر PUID باید بتواند آن را بخواند.

راه‌اندازی مجدد و بازیابی

سیاست راه‌اندازی مجدد را نگه دارید. بازیابی بررسی و آماده می‌شود، بعد HolyArrs با وضعیت 75 خارج می‌شود تا Docker دوباره آن را شروع کند و بازیابی را اعمال کند. unless-stopped همین کار را می‌کند.

برای به‌روزرسانی یک ساخت محلی، بدون دست زدن به مونت‌ها دوباره بسازید و کانتینر را دوباره بسازید:

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

در هنگام به‌روزرسانی هرگز /config را پاک نکنید. به‌روزرسانی‌ها و بکاپ‌ها را ببینید.

نام میزبان‌ها و ریورس پراکسی‌ها

نشانی‌های IP و localhost بدون کار اضافه جواب می‌دهند. نام خانگی مثل tower.local که هنگام اولین راه‌اندازی به کار می‌برید خودکار ذخیره می‌شود. نام‌های دیگر را زیر Allowed host names (نام میزبان‌های مجاز) در Settings > Sign-in and security اضافه کنید، یا در HOLYARRS_ALLOWED_HOSTS.

وقتی ریورس پراکسی X-Forwarded-For اضافه می‌کند، فقط نشانی یا شبکهٔ پراکسی را در HOLYARRS_TRUSTED_PROXIES بگذارید. بدون آن، single sign-on، نشانی واقعی کلاینت‌ها و کوکی Secure کار نمی‌کنند و همهٔ کسانی که پشت پراکسی هستند یک سقف ورود مشترک دارند. لاگ نشانی پراکسی را که باید اضافه شود می‌گوید. اگر پراکسی دیگری جلوی آن باشد، مثل Cloudflare، بازه‌های آن را هم اضافه کنید.

با nginx هر دو هدر را بفرستید:

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

اگر این دو با هم نخوانند، HolyArrs بازدیدکننده را بیرون از شبکهٔ شما حساب می‌کند.

اصول امنیت

پورت 6262 را روی روتر فوروارد نکنید. از VPN مثل Tailscale استفاده کنید، یا از ریورس پراکسی با HTTPS.
حساب مالک را بلافاصله بعد از اولین شروع بسازید.
یک کپی از کلید اصلی را دور از پوشهٔ پیکربندی نگه دارید.
ایمیج را به‌روز نگه دارید.

راه‌اندازی‌های ویژه

Docker Desktop (ویندوز و مک)

Docker Desktop پوشه‌های میزبان را از لایه‌ای به اشتراک می‌گذارد که قفل فایل پایگاه داده در آن امن نیست. HolyArrs یک /config آنجا را قبول نمی‌کند و راه‌حل را روی پورت 6262 نشان می‌دهد. برای /config از ولوم نام‌دار استفاده کنید. پوشه‌های رسانه می‌توانند پوشهٔ میزبان بمانند.

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:

برای بردن پوشهٔ پیکربندی قدیمی به داخل ولوم، HolyArrs را متوقف کنید و این را اجرا کنید:

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

برای بیرون کپی کردن بکاپ‌ها: docker cp holyarrs:/config/backups .

روی مک، اگر بررسی کرده‌اید که قفل فایل در پوشهٔ شما کار می‌کند، HOLYARRS_ALLOW_DESKTOP_FOLDER=1 را بگذارید تا به هر حال شروع شود. HolyArrs در هر شروع هشدار می‌دهد. این هرگز رد شدن اشتراک‌های شبکه را برنمی‌دارد.

سیستم فایل ریشهٔ فقط‌خواندنی

فقط /config و /tmp باید قابل‌نوشتن باشند:

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

PUID، PGID و UMASK همچنان کار می‌کنند.

شروع با کاربر ثابت

services:
  holyarrs:
    user: "1000:1000"

HolyArrs در این حالت هیچ صاحبی را تغییر نمی‌دهد، پس پوشهٔ پیکربندی باید از قبل برای آن کاربر قابل‌نوشتن باشد. PUID و PGID نادیده گرفته می‌شوند و لاگ این را می‌گوید. این Kubernetes runAsUser را هم پوشش می‌دهد.

Docker و Podman بدون root (rootless)

در حالت rootless، root داخل کانتینر همان کاربر خود شما است و شناسه‌های دیگر روی میزبان به عددهای بزرگ نگاشت می‌شوند. با PUID=1000 پوشهٔ پیکربندی در میزبان مال یک کاربر ناشناس می‌شود.

شما اجرا می‌کنید	`docker info` یا `podman info` نشان می‌دهد	به کار ببرید
Docker معمولی	بدون `rootless`	`PUID` و `PGID` مثل همیشه
Docker بدون root	`rootless` زیر Security Options	گزینهٔ 1
Podman بدون root	`rootless: true`	گزینهٔ 1 یا 2

گزینهٔ 1. PUID=0 و PGID=0 را بگذارید. این فقط در حالت rootless امن است. هرگز با Docker معمولی یا روی NAS این کار را نکنید.

گزینهٔ 2. Podman با keep-id، به‌صورت Quadlet در ~/.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

یا به‌صورت یک دستور:

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 است. روی پوشه‌هایی که دانلودر به اشتراک می‌گذارد از :z استفاده کنید. روی اشتراک شبکه (NFS یا SMB) از هیچ‌کدام استفاده نکنید: برچسب آن عوض نمی‌شود و کانتینر شروع نمی‌شود.
بررسی سلامت را به‌صورت فهرست بدهید. ایمیج شل ندارد.
سیاست راه‌اندازی مجدد را always نگه دارید. سرویس شروع‌پس‌از‌ریبوت Podman فقط کانتینرهای always را شروع می‌کند.
برای شروع پس از ریبوت بدون وارد شدن، یک بار loginctl enable-linger $USER را اجرا کنید. بعد فایل Quadlet را به کار ببرید، یا برای podman run دستور systemctl --user enable podman-restart.service را اجرا کنید.

اگر پوشه از قبل مال یک شناسهٔ بزرگ است، اول کانتینر را متوقف کنید، بعد:

Podman بدون root: podman unshare chown -R 0:0 ~/holyarrs/config (گزینهٔ 1) یا podman unshare chown -R 1000:1000 ~/holyarrs/config.
Docker بدون root: rootlesskit chown -R 0:0 ~/holyarrs/config، که از طریق nsenter به داخل دیمن rootless اجرا می‌شود (nsenter -U --preserve-credentials -n -m -t $(cat $XDG_RUNTIME_DIR/docker.pid)).

ایمیج خودتان را بسازید

از چک‌اوت HolyArrs:

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

بعد holyarrs:local را به‌عنوان ایمیج به کار ببرید.

عیب‌یابی

اول doctor را اجرا کنید. پیکربندی، پوشه‌ها، شبکه و ساعت را بررسی می‌کند و می‌گوید هر مشکل را چطور درست کنید.

کانتینر در حال اجرا است: docker exec holyarrs /holyarrs doctor
کانتینر مدام دوباره شروع می‌شود: docker compose run --rm holyarrs doctor

برای لاگ و بستهٔ پشتیبانی عیب‌یابی را ببینید.

می‌بینید	این کار را بکنید
Config folder is on a shared or network folder	از دیسک محلی استفاده کنید، یا در Docker Desktop از ولوم نام‌دار. در Unraid از `/mnt/<pool>/appdata/holyarrs` استفاده کنید.
Config folder is in memory	`/config` را روی دیسک بگذارید. در Unraid بررسی کنید مسیر pool وجود دارد. برای یک دستگاه آزمایشی، `HOLYARRS_CONFIG_IN_MEMORY=yes` آن را مجاز می‌کند.
Config folder cannot be written	`:ro` را بردارید و بررسی کنید که `PUID:PGID` صاحب پوشه باشند.
Disk is full	روی دیسکی که `/config` را دارد فضا خالی کنید، بعد راه‌اندازی مجدد کنید.
`/config` is not mapped	پایین را ببینید.
Cannot switch user	آن چهار قابلیت را دوباره اضافه کنید، یا از `user: "<uid>:<gid>"` استفاده کنید.
PUID/PGID does not exist inside this container	شناسه‌ها بیرون از بازهٔ نگاشت‌شده‌اند. Docker و Podman بدون root (rootless) را ببینید.
A `FILE__` variable cannot be read	مسیر را بررسی کنید و اینکه فایل مونت شده باشد.
Permission denied	`PUID`، `PGID` و دسترسی نوشتن روی همهٔ پوشه‌ها را بررسی کنید.
Unknown host name	HolyArrs را با IP باز کنید و نام را زیر Allowed host names اضافه کنید.
Imports are copied	یک پوشهٔ مشترک مونت کنید. پوشه‌های رسانه را ببینید.
Master key does not match	کلیدی را که مال آن پایگاه‌های داده است برگردانید.
Restore staged but the app stays down	یک سیاست راه‌اندازی مجدد اضافه کنید و کانتینر را شروع کنید.

فراموش کردید /config را نگاشت کنید؟

HolyArrs باز هم شروع می‌شود، ولی همه‌جا هشدار می‌دهد. با پاک شدن کانتینر همه‌چیز از بین می‌رود. اول ذخیره‌اش کنید:

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

بعد ./holyarrs-config:/config (یا یک ولوم نام‌دار) را نگاشت کنید و کانتینر را دوباره بسازید. در Docker Desktop (ویندوز و مک) از ولوم نام‌دار استفاده کنید، نه پوشهٔ میزبان، و داده را همان‌طور که در Docker Desktop نشان داده شده وارد کنید. ممکن است یک راه‌اندازی قدیمی‌تر هنوز در یک ولوم بی‌نام باشد. آن‌ها را با docker volume ls فهرست کنید.

صفحه‌های مرتبط

HolyArrs رایگان است. اگر در وقتتان صرفه‌جویی کرد، در GitHub به آن ستاره بدهید، حمایت مالی کنید یا برای من یک قهوه بخرید.