التثبيت

جديد هنا

شغّل HolyArrs في Docker وافتحه في المتصفح. يستغرق ذلك بضع دقائق.

قبل أن تبدأ

جهاز عليه Docker و Docker Compose.
مجلدات الوسائط لديك، أو مكان تنشئها فيه. اقرأ المجلدات أولًا إذا أردت نقلًا فوريًا بدل النسخ.
على NAS أو Unraid أو Synology، انظر NAS و Synology و Unraid. ومن دون Docker، انظر الحزم المحمولة.

الخطوات

أنشئ مجلدًا للإعدادات على قرص محلي، مثل /srv/holyarrs/config. لا تضعه على مشاركة شبكية. على Docker Desktop، استعمل وحدة تخزين مسمّاة (volume) بدلًا منه. انظر 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
```
تظهر الحاوية سليمة (healthy) حالما يستجيب HolyArrs.
افتح 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.2` (أي إصدار)	ذلك الإصدار بعينه، ولا يتغير أبدًا

شرح الإعدادات

المنافذ والمجلدات

الإعداد	وظيفته
`-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`	اختياري. عنوان الوكيل العكسي (reverse proxy) لديك أو شبكته.
`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 ويذكر اسم المتغير في سجل التشغيل. ولا يطبع القيمة أبدًا.

الصورة

صورة Docker تحوي HolyArrs وقليلًا غيره. ليس فيها shell، فلا يمكنك أن تدخلها عبر 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 أو أقل، يفعّل HolyArrs وضع الذاكرة المنخفضة من تلقاء نفسه. ويذكر ذلك أول سطر في سجل التشغيل.

المستخدم والمجموعة

تبدأ الحاوية بالمستخدم root لتهيّئ نفسها لا غير. تعطي مجلد الإعدادات للمستخدم PUID:PGID عند الحاجة، ثم تنتقل إلى ذلك المستخدم نهائيًا. ويعرض أول سطر في سجل التشغيل المستخدم والمجموعة وقيمة umask.

لا يغيّر HolyArrs مالك مجلدات الوسائط أو التنزيل أبدًا. امنح مستخدم PUID إذن الكتابة فيها بنفسك. إذن القراءة لا يكفي، لأن HolyArrs ينشئ مجلدات وينقل ملفات.

بعض وسائط التخزين لا تسمح بتغيير المالك، مثل NFS مع root squash، أو SMB، أو مجلد مركّب للقراءة فقط. يكتب HolyArrs حينها تحذيرًا في سجل التشغيل ويواصل. اجعل مجلد الإعدادات قابلًا للكتابة للمستخدم PUID:PGID يدويًا.

يحتاج تبديل المستخدم إلى القدرات (capabilities) CHOWN و DAC_OVERRIDE و SETUID و SETGID. يمنحها Docker افتراضيًا. إذا أسقطتها، يتوقف HolyArrs برسالة. ولا يرجع إلى العمل بالمستخدم root. لتشغيله بالمستخدم root فعلًا، اضبط PUID=0 و PGID=0.

المجموعات الإضافية من group_add: تبقى حين يبدّل HolyArrs المستخدم.

يؤثر UMASK في الملفات الجديدة لا غير. اتركه لتبقى القيمة 022، وفيها تكتب أنت ويقرأ الآخرون. استعمل 002 حين يجب أن تكتب المجموعة أيضًا.

مجلدات الوسائط

ركّب المجلدات التي تستعملها لا غير: /movies و /tv و /music مجلدات للمكتبة، و /downloads مجلدًا للتنزيل.

نصيحة للروابط الثابتة (hardlinks): كل مجلد تركّبه وحده هو نقطة تركيب مستقلة داخل الحاوية، ولا يمكن إنشاء رابط ثابت لملف بين نقطتي تركيب، فيصبح الاستيراد نسخًا كاملًا. إذا أردت روابط ثابتة، يمكنك أن تركّب مجلدًا أبًا مشتركًا واحدًا (بداخله مجلد التنزيلات ومجلدات المكتبة) بدل نقاط التركيب الأربع الاختيارية، وأن تعطي برنامج التنزيل نقطة التركيب نفسها بالمسار نفسه. ويجب أن يكون المجلد الأب نظام ملفات واحدًا كذلك. المشاركات أو مجموعات البيانات (datasets) المنفصلة على 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 رقمًا ست عشريًا، أو 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. من دونه لا يعمل تسجيل الدخول الموحّد ولا عناوين العملاء الحقيقية ولا ملف تعريف الارتباط 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 (Windows و Mac)

يشارك 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 .

على Mac، إذا تأكدت أن أقفال الملفات تعمل في مجلدك، اضبط 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 ويذكر سجل التشغيل ذلك. ويشمل هذا runAsUser في Kubernetes أيضًا.

Docker و Podman في وضع rootless

في وضع rootless، المستخدم root داخل الحاوية هو مستخدمك أنت، وبقية المعرّفات تقابلها أرقام عالية على الجهاز المضيف. مع PUID=1000، ينتهي مجلد الإعدادات مملوكًا لمستخدم غريب على الجهاز المضيف.

ما تشغّله	ما يعرضه `docker info` أو `podman info`	استعمل
Docker العادي	لا يظهر `rootless`	`PUID` و `PGID` كالمعتاد
Docker بوضع rootless	`rootless` تحت Security Options	الخيار 1
Podman بوضع rootless	`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): لا يمكن تغيير وسمها الأمني، ولن تبدأ الحاوية.
اكتب فحص السلامة في صورة قائمة. ليس في الصورة shell.
أبقِ سياسة إعادة التشغيل always. خدمة Podman للتشغيل بعد إعادة الإقلاع لا تشغّل إلا الحاويات التي سياستها always.
ليبدأ بعد إعادة الإقلاع من دون أن تسجّل الدخول، نفّذ loginctl enable-linger $USER مرة واحدة. ثم استعمل ملف Quadlet، أو مع podman run نفّذ systemctl --user enable podman-restart.service.

إذا كان المجلد مملوكًا من قبل لمعرّف عالٍ، أوقف الحاوية أولًا، ثم:

Podman بوضع rootless: podman unshare chown -R 0:0 ~/holyarrs/config (الخيار 1) أو podman unshare chown -R 1000:1000 ~/holyarrs/config.
Docker بوضع rootless: rootlesskit chown -R 0:0 ~/holyarrs/config، وينفَّذ عبر nsenter داخل خدمة Docker التي تعمل بوضع 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

انظر حل المشكلات لمعرفة سجل التشغيل وحزمة الدعم.

ما تراه	ما تفعله
مجلد الإعدادات على مجلد مشترك أو شبكي	استعمل قرصًا محليًا، أو وحدة تخزين مسمّاة على Docker Desktop. على Unraid استعمل `/mnt/<pool>/appdata/holyarrs`.
مجلد الإعدادات في الذاكرة	ضع `/config` على قرص. على Unraid، تأكد أن مسار الـ pool موجود. على جهاز للتجربة، يسمح `HOLYARRS_CONFIG_IN_MEMORY=yes` بذلك.
تتعذر الكتابة في مجلد الإعدادات	أزل `:ro` وتأكد أن `PUID:PGID` يملكان المجلد.
القرص ممتلئ	أفرغ مساحة على القرص الذي عليه `/config`، ثم أعد التشغيل.
`/config` بلا تعيين	انظر أدناه.
يتعذر تبديل المستخدم	أعد القدرات الأربع، أو استعمل `user: "<uid>:<gid>"`.
PUID/PGID غير موجود داخل هذه الحاوية	المعرّفات خارج النطاق المعيَّن. انظر Docker و Podman في وضع rootless.
تتعذر قراءة متغير `FILE__`	تحقق من المسار ومن أن الملف مركّب.
الإذن مرفوض	تحقق من `PUID` و `PGID` ومن إذن الكتابة في كل المجلدات.
اسم مضيف غير معروف	افتح HolyArrs بعنوان IP وأضف الاسم تحت Allowed host names.
الاستيراد يجري نسخًا	ركّب مجلدًا مشتركًا واحدًا. انظر مجلدات الوسائط.
المفتاح الرئيسي لا يطابق	أعد المفتاح الذي يخص قواعد البيانات تلك.
الاستعادة جاهزة لكن التطبيق لا يعود إلى العمل	أضف سياسة إعادة تشغيل وشغّل الحاوية.

نسيت تعيين /config؟

يبدأ HolyArrs مع ذلك، لكنه يحذّر في كل مكان. يضيع كل شيء حين تُزال الحاوية. احفظ البيانات أولًا:

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

ثم عيّن ./holyarrs-config:/config (أو وحدة تخزين مسمّاة) وأعد إنشاء الحاوية. على Docker Desktop (Windows و Mac)، استعمل وحدة تخزين مسمّاة لا مجلدًا على الجهاز المضيف، وانسخ البيانات إليها كما هو مبيَّن في Docker Desktop. قد يكون إعداد أقدم ما زال في وحدة تخزين بلا اسم. اعرضها بالأمر docker volume ls.

صفحات ذات صلة

HolyArrs مجاني. إذا وفّر عليك وقتًا، امنحه نجمة على GitHub أو ادعمه ماليًا أو ادعُني إلى فنجان قهوة.