ข้ามไปยังเนื้อหา

ติดตั้ง

มือใหม่

รัน HolyArrs ใน Docker แล้วเปิดในเบราว์เซอร์ ใช้เวลาไม่กี่นาที

  • เครื่องที่มี Docker และ Docker Compose
  • โฟลเดอร์สื่อของคุณ หรือที่ที่จะสร้างโฟลเดอร์เหล่านั้น ถ้าอยากให้ย้ายไฟล์ได้ทันทีแทนการคัดลอก อ่าน โฟลเดอร์ ก่อน
  • ถ้าใช้ NAS, Unraid หรือ Synology ดู NAS, Synology และ Unraid ถ้าไม่ใช้ Docker ดู ไฟล์บีบอัดแบบพกพา
  1. สร้างโฟลเดอร์สำหรับคอนฟิกบนดิสก์ในเครื่อง เช่น /srv/holyarrs/config ห้ามใช้เน็ตเวิร์กแชร์ ถ้าใช้ Docker Desktop ให้ใช้ named volume แทน ดู Docker Desktop

  2. หาผู้ใช้และกลุ่มที่เป็นเจ้าของโฟลเดอร์สื่อ:

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

    ใช้ uid เป็น PUID และ gid เป็น PGID

  3. บันทึกเป็นไฟล์ 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
  4. เริ่มทำงาน:

    Terminal window
    docker compose up -d
    docker compose ps

    เมื่อ HolyArrs ตอบสนองแล้ว Container จะขึ้นสถานะ healthy

  5. เปิด http://your-server:6262 แล้วสร้างบัญชีเจ้าของทันที ไม่มีรหัสผ่านเริ่มต้น จนกว่าคุณจะสร้างบัญชี คนแรกที่เปิด HolyArrs จะกลายเป็นเจ้าของ

  6. ทำตามการตั้งค่าเริ่มต้นที่เปิดขึ้นมา ดู การเปิดใช้ครั้งแรก

ถ้าชอบใช้ docker run:

Terminal window
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 สิ่งที่ได้
latest เวอร์ชันใหม่ล่าสุด
1.0.0 (เวอร์ชันไหนก็ได้) เวอร์ชันนั้นตรงตัว ไม่เปลี่ยนเลย
ค่าที่ตั้ง ใช้ทำอะไร
-p 6262:6262 เว็บแอป
-v /config ฐานข้อมูล การตั้งค่า คีย์หลัก Backup และ Log ใช้ดิสก์ในเครื่องเท่านั้น
-v /movies ไม่บังคับ โฟลเดอร์คลังภาพยนตร์
-v /tv ไม่บังคับ โฟลเดอร์คลังซีรีส์
-v /music ไม่บังคับ โฟลเดอร์คลังเพลง
-v /downloads ไม่บังคับ โฟลเดอร์ดาวน์โหลดของตัวดาวน์โหลด ดู โฟลเดอร์สื่อ
--read-only=true ไม่บังคับ ดู ระบบไฟล์ root แบบอ่านอย่างเดียว
--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 แต่ไม่พิมพ์ค่าออกมาเลย

Image มี HolyArrs และแทบไม่มีอย่างอื่น ไม่มี shell จึง docker exec เข้าไปดูไม่ได้ ให้อ่าน Log แทนด้วย docker logs holyarrs หรือเปิด logs/holyarrs.log ในโฟลเดอร์คอนฟิก

คำสั่งของ HolyArrs เองยังใช้ผ่าน docker exec ได้:

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

Image สร้างไว้สำหรับ amd64, ARM 64 บิต และ ARM 32 บิต ถ้าเครื่องมีหน่วยความจำ ประมาณ 2.5 GiB หรือน้อยกว่า HolyArrs จะเปิด โหมดประหยัดหน่วยความจำ ให้เอง และบอกไว้ใน Log บรรทัดแรก

Container เริ่มด้วย root เพื่อตั้งค่าตัวเองเท่านั้น จะโอนโฟลเดอร์คอนฟิก ให้ PUID:PGID เมื่อจำเป็น แล้วสลับไปใช้ผู้ใช้นั้นถาวร Log บรรทัดแรก จะแสดงผู้ใช้ กลุ่ม และ umask

HolyArrs ไม่เปลี่ยนเจ้าของโฟลเดอร์สื่อหรือโฟลเดอร์ดาวน์โหลดของคุณเด็ดขาด ให้สิทธิ์เขียนกับผู้ใช้ PUID ด้วยตัวเอง สิทธิ์อ่านอย่างเดียวไม่พอ เพราะ HolyArrs ต้องสร้างโฟลเดอร์และย้ายไฟล์

พื้นที่เก็บข้อมูลบางแบบเปลี่ยนเจ้าของไม่ได้ เช่น NFS ที่เปิด root squash, SMB หรือที่เมานต์แบบอ่านอย่างเดียว HolyArrs จะบันทึกคำเตือนแล้วทำงานต่อ ให้ตั้งสิทธิ์เขียนของโฟลเดอร์คอนฟิกสำหรับ PUID:PGID เอง

การสลับผู้ใช้ต้องมี capability CHOWN, DAC_OVERRIDE, SETUID และ SETGID Docker ให้มาโดยค่าเริ่มต้น ถ้าตัดออก HolyArrs จะหยุดพร้อมข้อความแจ้ง และไม่ถอยไปใช้ root ถ้าต้องการรันด้วย root จริง ๆ ให้ตั้ง PUID=0 และ PGID=0

กลุ่มเพิ่มเติมจาก group_add: จะยังอยู่หลัง HolyArrs สลับผู้ใช้

UMASK มีผลกับไฟล์ใหม่เท่านั้น ถ้าไม่ใส่จะคงเป็น 022 คือคุณเขียนได้ คนอื่นอ่านได้ ใช้ 002 เมื่อกลุ่มต้องเขียนได้ด้วย

เมานต์เฉพาะโฟลเดอร์ที่ใช้: /movies, /tv และ /music เป็นโฟลเดอร์คลัง และ /downloads เป็นโฟลเดอร์ดาวน์โหลด

เคล็ดลับเรื่อง hardlink: โฟลเดอร์ที่เมานต์แยกกันแต่ละตัวเป็นคนละเมานต์ใน Container และไฟล์ทำ hardlink ข้ามเมานต์ไม่ได้ การนำเข้าจึงกลายเป็นการคัดลอก เต็มไฟล์ ถ้าต้องการ hardlink ให้เมานต์โฟลเดอร์แม่ร่วมกันหนึ่งโฟลเดอร์ (มีโฟลเดอร์ดาวน์โหลดและโฟลเดอร์คลังอยู่ข้างใน) แทนเมานต์ไม่บังคับทั้งสี่ตัว แล้วให้ตัวดาวน์โหลดใช้เมานต์เดียวกันที่พาธเดียวกัน โฟลเดอร์แม่ต้องอยู่บน ระบบไฟล์เดียวกันด้วย เน็ตเวิร์กแชร์หรือ dataset ที่แยกกันข้างใต้ก็ยังคัดลอกอยู่ดี Settings > Library folders จะเตือนเมื่อ HolyArrs ต้องคัดลอก

HOLYARRS_SAVE_PATH ถูกส่งไปให้ตัวดาวน์โหลดทุกครั้งที่ดาวน์โหลด จึงเปลี่ยน ที่ที่ตัวดาวน์โหลดบันทึกไฟล์ด้วย ถ้าไม่ใส่ จะใช้ค่าที่ตั้งไว้ในตัวดาวน์โหลดเอง ถ้าไม่ใส่ ให้เพิ่มโฟลเดอร์ดาวน์โหลดใน Settings > Library folders > Extra import folders จะได้นำเข้าจากโฟลเดอร์นั้น ด้วยมือได้

HolyArrs เข้ารหัสรหัสผ่าน คีย์ และ token ที่เก็บไว้ด้วยคีย์หลัก การเริ่มครั้งแรกจะสร้าง /config/holyarrs.key

Backup ไม่มีคีย์นี้อยู่ข้างใน ให้เก็บสำเนาไว้ที่อื่น วิธีง่ายสุด: ในฐานะ เจ้าของ เปิด Settings > Backups แล้วเลือก Download key kit (ดาวน์โหลดชุดคีย์) ถ้าจะนำกลับมาวาง ตั้งชื่อไฟล์เป็น holyarrs.key แล้ววางในโฟลเดอร์คอนฟิกตอนที่ HolyArrs หยุดอยู่ การกู้คืนด้วยคีย์ที่ต่างกันจะถูกปฏิเสธ ถ้าใช้ named volume จะไม่มีโฟลเดอร์ให้เปิด: คัดลอกเข้าไปด้วย docker cp holyarrs.key hx:/config/ ตามที่แสดงใน Docker Desktop ย้ายไปเครื่องใหม่? นำ คีย์กลับมาวางก่อน แล้วค่อยกู้คืน Backup ดู Backup

จะเก็บคีย์ไว้ในไฟล์แบบอ่านอย่างเดียวของมันเองก็ได้:

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

ไฟล์ต้องมีอยู่จริงและเก็บข้อมูล 32 ไบต์ดิบ, เลขฐานสิบหก 64 หลัก หรือ base64 ของ 32 ไบต์ ผู้ใช้ PUID ต้องอ่านไฟล์นี้ได้

ต้องตั้งนโยบายรีสตาร์ตไว้ การกู้คืนจะถูกตรวจและเตรียมไว้ จากนั้น HolyArrs ออกด้วย สถานะ 75 เพื่อให้ Docker เริ่มมันใหม่แล้วนำการกู้คืนไปใช้ นโยบาย unless-stopped รองรับเรื่องนี้ได้

ถ้าจะอัปเดต build ในเครื่อง ให้ build ใหม่แล้วสร้าง Container ใหม่โดยไม่แตะเมานต์:

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

ห้ามลบ /config ระหว่างอัปเดต ดู การอัปเดต และ Backup

ที่อยู่ IP และ localhost ใช้ได้เลย ชื่อในบ้านอย่าง tower.local ที่ใช้ตอนตั้งค่าครั้งแรก ระบบบันทึกให้เอง เพิ่มชื่ออื่นได้ที่ Allowed host names (ชื่อโฮสต์ที่อนุญาต) ใน Settings > Sign-in and security หรือใน HOLYARRS_ALLOWED_HOSTS

เมื่อ reverse proxy เพิ่ม X-Forwarded-For ให้ใส่เฉพาะที่อยู่หรือเครือข่ายของ proxy ใน HOLYARRS_TRUSTED_PROXIES ถ้าไม่ใส่ single sign-on, ที่อยู่จริงของไคลเอนต์ และคุกกี้ Secure จะใช้ไม่ได้ และทุกคนที่อยู่หลัง proxy จะใช้ขีดจำกัดการล็อกอินร่วมกัน Log จะบอกที่อยู่ proxy ที่ต้องเพิ่ม ถ้ามี proxy อีกตัวอยู่ข้างหน้า เช่น Cloudflare ให้เพิ่มช่วงที่อยู่ของมันด้วย

ถ้าใช้ nginx ให้ส่งทั้งสอง header:

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

ถ้าสองค่านี้ไม่ตรงกัน HolyArrs จะมองว่าผู้เข้าชมอยู่นอกเครือข่ายของคุณ

พื้นฐานด้านความปลอดภัย

ลิงก์ไปยัง พื้นฐานด้านความปลอดภัย
  • อย่าทำ port forward 6262 บนเราเตอร์ ใช้ VPN เช่น Tailscale หรือ reverse proxy พร้อม HTTPS
  • สร้างบัญชีเจ้าของทันทีหลังเริ่มครั้งแรก
  • เก็บสำเนาคีย์หลักไว้ห่างจากโฟลเดอร์คอนฟิก
  • อัปเดต Image อยู่เสมอ

Docker Desktop แชร์โฟลเดอร์ของเครื่องผ่านชั้นที่ล็อกไฟล์ฐานข้อมูล ไม่ปลอดภัย HolyArrs จึงไม่รับ /config ที่อยู่ตรงนั้น และแสดงวิธีแก้ที่ port 6262 ให้ใช้ named volume สำหรับ /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:

ถ้าจะย้ายโฟลเดอร์คอนฟิกเก่าเข้า volume ให้หยุด HolyArrs แล้วรัน:

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

ถ้าจะคัดลอก Backup ออกมา: docker cp holyarrs:/config/backups .

บน Mac ถ้าคุณตรวจแล้วว่าการล็อกไฟล์ในโฟลเดอร์ของคุณใช้ได้ ให้ตั้ง HOLYARRS_ALLOW_DESKTOP_FOLDER=1 เพื่อเริ่มต่อไป HolyArrs จะเตือนทุกครั้ง ที่เริ่ม ค่านี้ไม่ปลดการปฏิเสธสำหรับเน็ตเวิร์กแชร์

ระบบไฟล์ root แบบอ่านอย่างเดียว

ลิงก์ไปยัง ระบบไฟล์ root แบบอ่านอย่างเดียว

เขียนได้เฉพาะ /config และ /tmp ก็พอ:

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

PUID, PGID และ UMASK ยังใช้ได้

เริ่มด้วยผู้ใช้ที่กำหนดตายตัว

ลิงก์ไปยัง เริ่มด้วยผู้ใช้ที่กำหนดตายตัว
services:
holyarrs:
user: "1000:1000"

ในกรณีนี้ HolyArrs จะไม่เปลี่ยนเจ้าของอะไรเลย โฟลเดอร์คอนฟิกจึงต้อง เขียนได้โดยผู้ใช้นั้นอยู่แล้ว PUID และ PGID จะถูกข้าม และ Log จะบอกไว้ กรณีนี้รวมถึง runAsUser ของ Kubernetes ด้วย

ในโหมด rootless root ภายใน Container คือผู้ใช้ของคุณเอง ส่วน id อื่น จะแมปเป็นเลขสูง ๆ บนเครื่อง ถ้าใช้ 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

หรือเป็นคำสั่งเดียว:

Terminal window
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) เพราะติดป้ายใหม่ไม่ได้ และ Container จะไม่เริ่มทำงาน
  • ใส่ health check เป็นลิสต์ เพราะ Image ไม่มี shell
  • ให้นโยบายรีสตาร์ตเป็น always เสมอ เพราะบริการเริ่มหลังรีบูตของ Podman จะเริ่มเฉพาะ Container ที่เป็น always
  • ถ้าจะให้เริ่มหลังรีบูตโดยไม่ต้องล็อกอิน ให้รัน loginctl enable-linger $USER หนึ่งครั้ง แล้วใช้ไฟล์ Quadlet หรือถ้าใช้ podman run ให้รัน systemctl --user enable podman-restart.service

ถ้าโฟลเดอร์เป็นของ id เลขสูงอยู่แล้ว ให้หยุด Container ก่อน แล้ว:

  • 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:

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

จากนั้นใช้ holyarrs:local เป็น Image

รัน doctor ก่อน มันตรวจคอนฟิก โฟลเดอร์ เครือข่ายและนาฬิกา แล้ว บอกวิธีแก้ของแต่ละปัญหา

  • Container กำลังทำงาน: docker exec holyarrs /holyarrs doctor
  • Container รีสตาร์ตซ้ำไปมา: docker compose run --rm holyarrs doctor

ดู การแก้ปัญหา สำหรับ Log และชุดข้อมูลสำหรับขอความช่วยเหลือ

อาการที่เห็น วิธีแก้
Config folder is on a shared or network folder ใช้ดิสก์ในเครื่อง หรือ named volume บน 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 เพิ่ม capability ทั้งสี่ตัวกลับ หรือใช้ user: "<uid>:<gid>"
PUID/PGID does not exist inside this container id อยู่นอกช่วงที่แมปไว้ ดู Docker แบบ rootless และ Podman
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 เพิ่มนโยบายรีสตาร์ตแล้วเริ่ม Container

HolyArrs ยังเริ่มได้ แต่จะเตือนทุกหน้า ข้อมูลทั้งหมดจะหายเมื่อ ลบ Container ให้เก็บไว้ก่อน:

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

จากนั้นแมป ./holyarrs-config:/config (หรือ named volume) แล้วสร้าง Container ใหม่ บน Docker Desktop (Windows และ Mac) ให้ใช้ named volume ไม่ใช่ โฟลเดอร์ของเครื่อง แล้วคัดลอกข้อมูลเข้าไปตามที่แสดงใน Docker Desktop การตั้งค่าแบบเก่าอาจยังอยู่ ใน volume ที่ไม่มีชื่อ ดูรายการด้วย docker volume ls

HolyArrs ใช้ได้ฟรี ถ้าช่วยประหยัดเวลาคุณได้ กดดาวบน GitHub, สนับสนุนโปรเจกต์ หรือ เลี้ยงกาแฟผู้พัฒนา