Cài đặt

Chạy HolyArrs trong Docker rồi mở nó trong trình duyệt. Chỉ mất vài phút.

Trước khi bắt đầu

• Một máy tính có Docker và Docker Compose.
• Các thư mục media của bạn, hoặc một nơi để tạo chúng. Nếu muốn di chuyển tệp tức thì thay vì sao chép, hãy đọc Thư mục trước.
• Trên NAS, Unraid hoặc Synology, xem NAS, Synology và Unraid. Nếu không dùng Docker, xem Bản portable.

Các bước

1. Tạo một thư mục cấu hình trên ổ đĩa cục bộ, ví dụ /srv/holyarrs/config. Không dùng thư mục chia sẻ mạng. Trên Docker Desktop, hãy dùng named volume. Xem Docker Desktop.

2. Tìm người dùng và nhóm đang sở hữu các thư mục media của bạn:

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

   Dùng uid làm PUID và gid làm PGID.

3. Lưu đoạn này thành docker-compose.yml và đổi các đường dẫn:

   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. Khởi động:

   docker compose up -d
   docker compose ps

   Container hiện trạng thái healthy khi HolyArrs đã phản hồi.

5. Mở http://your-server:6262 và tạo ngay tài khoản chủ sở hữu. Không có mật khẩu mặc định. Cho đến khi bạn tạo tài khoản, ai mở HolyArrs trước sẽ trở thành chủ sở hữu.

6. Làm theo phần thiết lập mở ra tiếp theo. Xem Lần chạy đầu tiên.

Chú ý

Không có mật khẩu mặc định. Ai mở một HolyArrs mới trước sẽ trở thành chủ sở hữu. Hãy tạo tài khoản ngay bây giờ.

Nếu bạn thích dùng 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

Tag của image

Tag	Bạn nhận được gì
latest	Phiên bản mới nhất
1.0.0 (bất kỳ phiên bản nào)	Đúng phiên bản đó, không bao giờ thay đổi

Giải thích các tùy chọn

Cổng và thư mục

Tùy chọn	Công dụng
-p 6262:6262	Ứng dụng web.
-v /config	Cơ sở dữ liệu, cài đặt, khóa chính, bản sao lưu và nhật ký. Chỉ dùng ổ đĩa cục bộ.
-v /movies	Tùy chọn. Một thư mục Thư viện cho phim lẻ.
-v /tv	Tùy chọn. Một thư mục Thư viện cho phim bộ.
-v /music	Tùy chọn. Một thư mục Thư viện cho nhạc.
-v /downloads	Tùy chọn. Thư mục tải xuống của trình tải xuống. Xem Thư mục media.
--read-only=true	Tùy chọn. Xem Hệ thống tệp gốc chỉ đọc.
--user=1000:1000	Tùy chọn. Xem Khởi động với người dùng cố định.

Biến môi trường

Biến	Công dụng
PUID, PGID	Người dùng và nhóm mà HolyArrs chạy dưới quyền. Mặc định là 1000 và 1000 nếu bỏ trống.
TZ	Múi giờ, ví dụ Europe/Amsterdam.
UMASK	Tùy chọn. Những bit quyền mà tệp mới sẽ không có, ví dụ 022 hoặc 002.
HOLYARRS_SAVE_PATH	Tùy chọn. Thư mục lưu của trình tải xuống, theo cách trình tải xuống nhìn thấy.
HOLYARRS_ALLOWED_HOSTS	Tùy chọn. Các hostname bổ sung mà mọi người dùng để truy cập HolyArrs, ngăn cách bằng dấu phẩy.
HOLYARRS_TRUSTED_PROXIES	Tùy chọn. Địa chỉ hoặc mạng của reverse proxy của bạn.
HOLYARRS_URL_BASE	Tùy chọn. Chạy HolyArrs dưới một đường dẫn con. Xem URL base và reverse proxy.
HOLYARRS_MASTER_KEY_FILE	Tùy chọn. Đọc khóa chính từ một tệp riêng.

Biến nào cũng có thể lấy từ một tệp. Đặt FILE__ trước tên biến và đưa đường dẫn của tệp làm giá trị:

environment:
  - FILE__HOLYARRS_ALLOWED_HOSTS=/run/secrets/holyarrs_hosts

Một ký tự xuống dòng ở cuối tệp sẽ bị bỏ đi. Cách này cũng dùng được cho PUID, PGID, UMASK và TZ. Nếu thiếu tệp, HolyArrs dừng lại và ghi tên biến vào nhật ký. Nó không bao giờ in giá trị ra.

Image

Image chỉ chứa HolyArrs và rất ít thứ khác. Image không có shell, nên bạn không thể docker exec vào để xem. Hãy đọc nhật ký bằng docker logs holyarrs, hoặc mở logs/holyarrs.log trong thư mục cấu hình.

Các lệnh riêng của HolyArrs vẫn chạy được qua docker exec:

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

Image được build cho amd64, ARM 64-bit và ARM 32-bit. Trên máy tính có khoảng 2.5 GiB bộ nhớ trở xuống, HolyArrs tự bật chế độ ít bộ nhớ. Dòng đầu tiên của nhật ký cho biết điều đó.

Người dùng và nhóm

Container chỉ khởi động với quyền root để tự thiết lập. Khi cần, nó giao thư mục cấu hình cho PUID:PGID, rồi chuyển hẳn sang người dùng đó. Dòng đầu tiên của nhật ký hiện người dùng, nhóm và umask.

HolyArrs không bao giờ đổi chủ sở hữu của các thư mục media hay thư mục tải xuống. Hãy tự cấp quyền ghi cho người dùng PUID. Chỉ có quyền đọc là chưa đủ, vì HolyArrs tạo thư mục và di chuyển tệp.

Một số nơi lưu trữ không đổi được chủ sở hữu, như NFS với root squash, SMB hoặc một mount chỉ đọc. Khi đó HolyArrs ghi một lưu ý vào nhật ký và chạy tiếp. Hãy tự cấp quyền ghi cho PUID:PGID trên thư mục cấu hình.

Việc chuyển người dùng cần các capability CHOWN, DAC_OVERRIDE, SETUID và SETGID. Docker cấp chúng theo mặc định. Nếu bạn bỏ chúng đi, HolyArrs dừng lại kèm một thông báo. Nó không quay về chạy với quyền root. Muốn thật sự chạy với quyền root, hãy đặt PUID=0 và PGID=0.

Các nhóm bổ sung từ group_add: được giữ nguyên khi HolyArrs chuyển người dùng.

UMASK chỉ ảnh hưởng đến tệp mới. Bỏ trống để giữ 022, nghĩa là bạn ghi được còn người khác chỉ đọc. Dùng 002 khi cả nhóm cũng cần quyền ghi.

Thư mục media

Chỉ mount những thư mục bạn dùng: /movies, /tv và /music làm thư mục Thư viện, còn /downloads làm thư mục tải xuống.

Mẹo về hardlink (liên kết cứng): mỗi thư mục bạn mount riêng là một mount riêng bên trong container, và một tệp không thể tạo hardlink giữa các mount, nên việc nhập sẽ thành sao chép toàn bộ. Nếu muốn dùng hardlink, bạn có thể mount một thư mục cha chung (chứa cả thư mục tải xuống lẫn các thư mục Thư viện) thay cho bốn mount tùy chọn, và cho trình tải xuống cùng mount đó ở cùng đường dẫn. Thư mục cha cũng phải nằm trên một hệ thống tệp duy nhất. Các thư mục chia sẻ hoặc dataset NAS riêng bên dưới vẫn bị sao chép. Settings > Library folders cảnh báo bạn khi HolyArrs phải sao chép.

HOLYARRS_SAVE_PATH được gửi cho trình tải xuống cùng mỗi lượt tải xuống, nên nó cũng đổi nơi trình tải xuống lưu tệp. Bỏ trống để giữ cài đặt riêng của trình tải xuống. Nếu bỏ trống, hãy thêm thư mục tải xuống vào Settings > Library folders > Extra import folders để bạn nhập thủ công từ đó.

Giữ khóa chính

HolyArrs mã hóa mật khẩu, khóa và token đã lưu bằng một khóa chính. Lần khởi động đầu tiên tạo /config/holyarrs.key.

Bản sao lưu không bao giờ chứa khóa này. Hãy giữ một bản ở nơi khác. Cách dễ: với tư cách chủ sở hữu, mở Settings > Backups và chọn Download key kit (tải bộ khóa). Để phục hồi, đặt tên tệp là holyarrs.key và để nó trong thư mục cấu hình khi HolyArrs đang dừng. Việc khôi phục với một khóa khác sẽ bị từ chối. Với named volume thì không có thư mục nào để mở: hãy chép vào bằng docker cp holyarrs.key hx:/config/ như trong Docker Desktop. Chuyển sang máy tính mới? Hãy phục hồi khóa trước, rồi khôi phục bản sao lưu. Xem Sao lưu.

Bạn cũng có thể giữ khóa trong một tệp chỉ đọc riêng:

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

Tệp phải tồn tại và chứa 32 byte thô, 64 chữ số hex hoặc base64 của 32 byte. Người dùng PUID phải đọc được nó.

Khởi động lại và khôi phục

Hãy giữ một chính sách khởi động lại. Một lần khôi phục được kiểm tra và chuẩn bị sẵn, rồi HolyArrs thoát với mã 75 để Docker khởi động nó lại và áp dụng. unless-stopped lo việc đó.

Để cập nhật một bản build cục bộ, hãy build lại và tạo lại container mà không đụng đến các mount:

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

Không bao giờ xóa /config trong lúc cập nhật. Xem Cập nhật và Sao lưu.

Hostname và reverse proxy

Địa chỉ IP và localhost chạy được ngay. Một tên trong mạng nhà như tower.local mà bạn dùng trong lần thiết lập đầu tiên sẽ được lưu giúp bạn. Thêm các tên khác ở Allowed host names (hostname được phép) trong Settings > Sign-in and security, hoặc trong HOLYARRS_ALLOWED_HOSTS.

Khi reverse proxy thêm X-Forwarded-For, chỉ đặt địa chỉ hoặc mạng của proxy vào HOLYARRS_TRUSTED_PROXIES. Nếu không, đăng nhập một lần, địa chỉ thật của máy khách và cookie Secure sẽ không hoạt động, và mọi người sau proxy dùng chung một giới hạn đăng nhập. Nhật ký cho biết địa chỉ proxy cần thêm. Nếu còn một proxy khác đứng trước, như Cloudflare, hãy thêm cả các dải địa chỉ của nó.

Với nginx, hãy gửi cả hai header:

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

Nếu hai header này không khớp nhau, HolyArrs coi người truy cập là ở ngoài mạng của bạn.

Bảo mật cơ bản

• Không chuyển tiếp cổng 6262 trên router. Hãy dùng VPN như Tailscale, hoặc một reverse proxy có HTTPS.
• Tạo tài khoản chủ sở hữu ngay sau lần khởi động đầu tiên.
• Giữ một bản sao của khóa chính tách khỏi thư mục cấu hình.
• Luôn cập nhật image.

Các thiết lập đặc biệt

Docker Desktop (Windows và Mac)

Docker Desktop chia sẻ thư mục của máy chủ qua một lớp mà ở đó việc khóa tệp cơ sở dữ liệu không an toàn. HolyArrs từ chối một /config ở đó và chỉ cách khắc phục ở cổng 6262. Hãy dùng named volume cho /config. Các thư mục media vẫn có thể là thư mục của máy chủ.

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:

Để chuyển một thư mục cấu hình cũ vào volume, hãy dừng HolyArrs và chạy:

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

Để chép bản sao lưu ra ngoài: docker cp holyarrs:/config/backups .

Trên Mac, nếu bạn đã kiểm tra và khóa tệp hoạt động tốt trong thư mục của mình, hãy đặt HOLYARRS_ALLOW_DESKTOP_FOLDER=1 để vẫn khởi động. HolyArrs sẽ cảnh báo ở mỗi lần khởi động. Tùy chọn này không bao giờ gỡ việc từ chối đối với thư mục chia sẻ mạng.

Hệ thống tệp gốc chỉ đọc

Chỉ /config và /tmp cần ghi được:

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

PUID, PGID và UMASK vẫn hoạt động.

Khởi động với người dùng cố định

services:
  holyarrs:
    user: "1000:1000"

Khi đó HolyArrs không đổi chủ sở hữu nào cả, nên người dùng đó phải có sẵn quyền ghi vào thư mục cấu hình. PUID và PGID bị bỏ qua và nhật ký có nói rõ. Cách này cũng áp dụng cho runAsUser của Kubernetes.

Docker rootless và Podman

Ở chế độ rootless, root bên trong container chính là người dùng của bạn, còn các id khác được ánh xạ sang số lớn trên máy chủ. Với PUID=1000, thư mục cấu hình cuối cùng thuộc về một người lạ trên máy chủ.

Bạn chạy	docker info hoặc podman info cho thấy	Dùng
Docker thông thường	không có rootless	PUID và PGID như bình thường
Docker rootless	rootless trong Security Options	Cách 1
Podman rootless	rootless: true	Cách 1 hoặc 2

Cách 1. Đặt PUID=0 và PGID=0. Chỉ an toàn ở chế độ rootless. Không bao giờ làm vậy với Docker thông thường hay trên NAS.

Cách 2. Podman với keep-id, dưới dạng Quadlet trong ~/.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

Hoặc dưới dạng một lệnh:

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 dành cho hệ thống có SELinux. Dùng :z trên các thư mục mà trình tải xuống chia sẻ. Không dùng cả hai trên thư mục chia sẻ mạng (NFS hoặc SMB): không thể gắn nhãn lại và container sẽ không khởi động.
• Khai báo health check dưới dạng danh sách. Image không có shell.
• Giữ chính sách khởi động lại là always. Dịch vụ khởi động sau khi reboot của Podman chỉ khởi động các container always.
• Để khởi động sau khi reboot mà không cần đăng nhập, hãy chạy loginctl enable-linger $USER một lần. Sau đó dùng tệp Quadlet, hoặc với podman run thì chạy systemctl --user enable podman-restart.service.

Nếu thư mục đã thuộc về một id số lớn, hãy dừng container trước, rồi:

• Podman rootless: podman unshare chown -R 0:0 ~/holyarrs/config (Cách 1) hoặc podman unshare chown -R 1000:1000 ~/holyarrs/config.
• Docker rootless: rootlesskit chown -R 0:0 ~/holyarrs/config, chạy qua nsenter vào daemon rootless (nsenter -U --preserve-credentials -n -m -t $(cat $XDG_RUNTIME_DIR/docker.pid)).

Tự build image của bạn

Từ bản checkout của HolyArrs:

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

Sau đó dùng holyarrs:local làm image.

Khắc phục sự cố

Hãy chạy doctor trước. Nó kiểm tra cấu hình, thư mục, mạng và đồng hồ, và chỉ cách khắc phục từng vấn đề.

• Container đang chạy: docker exec holyarrs /holyarrs doctor
• Container cứ khởi động lại liên tục: docker compose run --rm holyarrs doctor

Xem Khắc phục sự cố để biết về nhật ký và gói hỗ trợ.

Bạn thấy	Cách làm
Config folder is on a shared or network folder (thư mục cấu hình nằm trên thư mục chia sẻ hoặc thư mục mạng)	Dùng ổ đĩa cục bộ, hoặc named volume trên Docker Desktop. Trên Unraid dùng /mnt/<pool>/appdata/holyarrs.
Config folder is in memory (thư mục cấu hình nằm trong bộ nhớ)	Đặt /config lên ổ đĩa. Trên Unraid, kiểm tra đường dẫn pool có tồn tại. Với máy thử nghiệm, HOLYARRS_CONFIG_IN_MEMORY=yes cho phép việc này.
Config folder cannot be written (không ghi được thư mục cấu hình)	Bỏ :ro và kiểm tra PUID:PGID là chủ sở hữu thư mục.
Disk is full (ổ đĩa đầy)	Giải phóng dung lượng trên ổ đĩa chứa /config, rồi khởi động lại.
/config is not mapped (chưa được ánh xạ)	Xem bên dưới.
Cannot switch user (không chuyển được người dùng)	Thêm lại bốn capability, hoặc dùng user: "<uid>:<gid>".
PUID/PGID does not exist inside this container (PUID/PGID không tồn tại trong container này)	Các id nằm ngoài dải được ánh xạ. Xem Docker rootless và Podman.
A FILE__ variable cannot be read (không đọc được biến dạng FILE__)	Kiểm tra đường dẫn và xem tệp đã được mount chưa.
Permission denied (từ chối quyền truy cập)	Kiểm tra PUID, PGID và quyền ghi trên mọi thư mục.
Unknown host name (hostname không xác định)	Mở HolyArrs bằng IP và thêm tên đó vào Allowed host names.
Imports are copied (các mục nhập bị sao chép)	Mount một thư mục chung. Xem Thư mục media.
Master key does not match (khóa chính không khớp)	Phục hồi đúng khóa thuộc về các cơ sở dữ liệu đó.
Restore staged but the app stays down (đã chuẩn bị khôi phục nhưng ứng dụng vẫn tắt)	Thêm chính sách khởi động lại và khởi động container.

Quên ánh xạ /config?

HolyArrs vẫn khởi động, nhưng cảnh báo ở khắp nơi. Mọi thứ sẽ mất khi container bị xóa. Hãy lưu lại trước:

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

Sau đó ánh xạ ./holyarrs-config:/config (hoặc một named volume) và tạo lại container. Trên Docker Desktop (Windows và Mac), hãy dùng named volume, không dùng thư mục của máy chủ, và chép dữ liệu vào như trong Docker Desktop. Một thiết lập cũ hơn có thể vẫn nằm trong một volume không tên. Liệt kê chúng bằng docker volume ls.

Liên quan

• Thư mục
• Lần chạy đầu tiên
• NAS, Synology và Unraid
• Cập nhật