התקנה

חדש כאן

הרץ את 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
```
הקונטיינר מוצג כ-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.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`	אופציונלי. הכתובת או הרשת של ה-reverse proxy שלך.
`HOLYARRS_URL_BASE`	אופציונלי. להגיש את HolyArrs תחת נתיב. ראה URL base ו-reverse proxy.
`HOLYARRS_MASTER_KEY_FILE`	אופציונלי. לקרוא את המפתח הראשי מקובץ משלו.

כל משתנה יכול לבוא מקובץ. שים FILE__ לפני השם ותן את הנתיב של הקובץ בתור הערך:

environment:
  - FILE__HOLYARRS_ALLOWED_HOSTS=/run/secrets/holyarrs_hosts

שורה חדשה אחת בסוף הקובץ מוסרת. זה עובד גם עבור PUID, PGID, UMASK ו-TZ. אם הקובץ חסר, HolyArrs נעצר ומציין את שם המשתנה בלוג (log). הוא אף פעם לא מדפיס את הערך.

האימג’

האימג’ מכיל את 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 ידנית.

המעבר למשתמש אחר דורש את היכולות CHOWN, DAC_OVERRIDE, SETUID ו-SETGID. Docker נותן אותן כברירת מחדל. אם אתה מסיר אותן, HolyArrs נעצר עם הודעה. הוא לא חוזר לעבוד כ-root. כדי באמת לרוץ כ-root, הגדר PUID=0 ו-PGID=0.

קבוצות נוספות מ-group_add: נשמרות כש-HolyArrs עובר למשתמש אחר.

UMASK משפיע רק על קבצים חדשים. השמט אותו כדי להשאיר את 022, שבו אתה כותב ואחרים קוראים. השתמש ב-002 כשגם קבוצה צריכה לכתוב.

תיקיות מדיה

עגן רק את התיקיות שבהן אתה משתמש: /movies, /tv ו-/music בתור תיקיות ספרייה, ו-/downloads בתור תיקיית ההורדות.

טיפ ל-hardlink (קישור קשיח): כל תיקייה שאתה מעגן בנפרד היא נקודת עיגון נפרדת בתוך הקונטיינר, ואי אפשר ליצור hardlink לקובץ בין נקודות עיגון, ולכן ייבוא הופך להעתקה מלאה. אם אתה רוצה hardlink, אפשר במקום זה לעגן תיקיית אב משותפת אחת (עם ההורדות ותיקיות הספרייה בתוכה) במקום ארבע העיגונים האופציונליים, ולתת למוריד את אותו עיגון באותו נתיב. תיקיית האב חייבת להיות גם מערכת קבצים אחת. שיתופי NAS או datasets נפרדים מתחתיה עדיין מעתיקים. Settings > Library folders (הגדרות > תיקיות ספרייה) מזהיר אותך כש-HolyArrs צריך להעתיק.

HOLYARRS_SAVE_PATH נשלח למוריד עם כל הורדה, ולכן הוא גם משנה את המקום שבו המוריד שומר. השמט אותו כדי להשאיר את ההגדרה של המוריד עצמו. אם השמטת אותו, הוסף את תיקיית ההורדות תחת Settings > Library folders > Extra import folders כדי שתוכל לייבא ידנית ממנה.

שמור את המפתח הראשי

HolyArrs מצפין סיסמאות, מפתחות ו-tokens שנשמרו עם מפתח ראשי. ההפעלה הראשונה יוצרת את /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 בזמן עדכון. ראה עדכונים ו-גיבויים.

שמות מארח ו-reverse proxy

כתובות IP ו-localhost עובדות מיד. שם ביתי כמו tower.local שבו אתה משתמש בהגדרה הראשונית נשמר בשבילך. הוסף שמות אחרים תחת Allowed host names (שמות מארח מותרים) ב-Settings > Sign-in and security (הגדרות > התחברות ואבטחה), או ב- HOLYARRS_ALLOWED_HOSTS.

כש-reverse proxy מוסיף X-Forwarded-For, שים ב-HOLYARRS_TRUSTED_PROXIES רק את הכתובת או הרשת של ה-proxy. בלי זה, כניסה יחידה (SSO), כתובות לקוח אמיתיות והעוגייה Secure לא עובדים, וכולם מאחורי ה-proxy חולקים מגבלת התחברות אחת. הלוג מציין את כתובת ה-proxy להוספה. אם proxy אחר עומד לפניו, כמו 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, או ב- reverse proxy עם 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 אז לא משנה בעלים, ולכן תיקיית ההגדרות חייבת כבר להיות ניתנת לכתיבה על ידי המשתמש הזה. 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 לתוך ה-daemon של ה-rootless (nsenter -U --preserve-credentials -n -m -t $(cat $XDG_RUNTIME_DIR/docker.pid)).

בנה אימג’ משלך

מתוך ה-checkout של 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 במצב 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 (Windows ו-Mac), השתמש בווליום בעל שם, לא בתיקיית מארח, והעתק את הנתונים פנימה כפי שמוצג ב- Docker Desktop. ייתכן שהגדרה ישנה יותר עדיין יושבת בווליום ללא שם. רשום אותם עם docker volume ls.

קשור

HolyArrs חינמי. אם זה חסך לך זמן, תן לו כוכב ב-GitHub, תמוך בפרויקט או קנה לי קפה.