설치

처음이라면

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.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`	선택 사항. 리버스 프록시의 주소 또는 네트워크.
`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, 64비트 ARM, 32비트 ARM용으로 빌드됩니다. 메모리가 약 2.5 GiB 이하인 장비에서는 HolyArrs가 저메모리 모드를 스스로 켭니다. 로그 첫 줄에 그 사실이 나옵니다.

사용자와 그룹

컨테이너는 초기 준비를 위해서만 root로 시작합니다. 필요하면 설정 폴더를 PUID:PGID에게 넘긴 뒤, 그 사용자로 완전히 전환합니다. 로그 첫 줄에 사용자, 그룹, umask가 나옵니다.

HolyArrs는 미디어 폴더나 다운로드 폴더의 소유자를 절대 바꾸지 않습니다. PUID 사용자에게 쓰기 권한을 직접 주세요. HolyArrs는 폴더를 만들고 파일을 옮기므로 읽기 권한만으로는 부족합니다.

root squash가 걸린 NFS, SMB, 읽기 전용 마운트처럼 소유자를 바꿀 수 없는 저장소도 있습니다. 이 경우 HolyArrs는 로그에 경고를 남기고 계속 진행합니다. 설정 폴더를 PUID:PGID가 쓸 수 있도록 직접 바꿔 주세요.

사용자를 전환하려면 CHOWN, DAC_OVERRIDE, SETUID, SETGID capability가 필요합니다. Docker는 기본으로 줍니다. 이를 빼면 HolyArrs는 메시지를 남기고 멈춥니다. root로 대신 실행하지는 않습니다. 정말 root로 실행하려면 PUID=0과 PGID=0으로 설정하세요.

group_add:로 추가한 그룹은 HolyArrs가 사용자를 전환해도 유지됩니다.

UMASK는 새 파일에만 영향을 줍니다. 생략하면 022가 유지되어 본인은 쓰고 다른 사용자는 읽기만 합니다. 그룹도 써야 한다면 002를 쓰세요.

미디어 폴더

쓰는 폴더만 마운트하세요. /movies, /tv, /music은 라이브러리 폴더로, /downloads는 다운로드 폴더로 씁니다.

하드링크 팁: 따로 마운트한 폴더는 컨테이너 안에서 각각 별개의 마운트가 되고, 파일은 마운트를 넘어 하드링크할 수 없으므로 가져오기가 전체 복사가 됩니다. 하드링크를 원하면 선택 사항인 마운트 4개 대신 공통 상위 폴더 하나(다운로드 폴더와 라이브러리 폴더가 그 안에 있는)를 마운트하고, 다운로더에도 같은 마운트를 같은 경로로 주면 됩니다. 상위 폴더는 하나의 파일 시스템이어야 합니다. 그 아래에 NAS 공유 폴더나 데이터세트가 따로 나뉘어 있으면 여전히 복사됩니다. HolyArrs가 복사해야 하는 경우 Settings > Library folders(설정 > 라이브러리 폴더)에서 경고합니다.

HOLYARRS_SAVE_PATH는 다운로드할 때마다 다운로더로 전달되므로, 다운로더가 저장하는 위치도 바뀝니다. 생략하면 다운로더 자체 설정이 유지됩니다. 생략한 경우에는 Settings > Library folders > Extra import folders(추가 가져오기 폴더)에 다운로드 폴더를 추가해 두세요. 그래야 그 폴더에서 수동으로 가져올 수 있습니다.

마스터 키 보관

HolyArrs는 저장된 비밀번호, 키, 토큰을 마스터 키로 암호화합니다. 처음 시작할 때 /config/holyarrs.key가 만들어집니다.

백업에는 이 키가 절대 들어가지 않습니다. 사본을 다른 곳에 보관하세요. 쉬운 방법: 소유자로 Settings > Backups(설정 > 백업)를 열고 Download key kit(키 키트 다운로드)를 선택하세요. 되돌려 놓으려면 파일 이름을 holyarrs.key로 하고, HolyArrs가 중지된 상태에서 설정 폴더에 넣으세요. 다른 키로 하는 복원은 거부됩니다. 네임드 볼륨에는 열어 볼 폴더가 없으니 Docker Desktop에 나온 대로 docker cp holyarrs.key hx:/config/로 복사해 넣으세요. 새 장비로 옮기나요? 키를 먼저 되돌려 놓은 다음 백업을 복원하세요. 백업을 보세요.

키를 별도의 읽기 전용 파일로 둘 수도 있습니다:

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

파일은 반드시 있어야 하고, 원시 32바이트, 16진수 64자리, 또는 32바이트를 base64로 적은 값이 들어 있어야 합니다. 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 같은 집 안 이름은 자동으로 저장됩니다. 다른 이름은 Settings > Sign-in and security(설정 > 로그인 및 보안)의 Allowed host names(허용된 호스트 이름)나 HOLYARRS_ALLOWED_HOSTS에 추가하세요.

리버스 프록시가 X-Forwarded-For를 붙인다면 HOLYARRS_TRUSTED_PROXIES에 프록시의 주소나 네트워크만 넣으세요. 넣지 않으면 통합 로그인(SSO), 실제 클라이언트 주소, Secure 쿠키가 동작하지 않고, 프록시 뒤의 모든 사람이 로그인 한도 하나를 같이 씁니다. 추가할 프록시 주소는 로그에 나옵니다. Cloudflare처럼 그 앞에 프록시가 하나 더 있으면 그 주소 범위도 추가하세요.

nginx에서는 두 헤더를 모두 보내세요:

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

둘이 서로 다르면 HolyArrs는 방문자를 네트워크 밖에서 온 것으로 취급합니다.

보안 기본 사항

공유기에서 6262 포트를 포트 포워딩하지 마세요. Tailscale 같은 VPN이나 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는 무시되고 로그에 그 사실이 나옵니다. Kubernetes의 runAsUser도 여기에 해당합니다.

Rootless Docker와 Podman

루트리스 모드에서는 컨테이너 안의 root가 본인 사용자이고, 다른 ID는 호스트에서 큰 번호로 매핑됩니다. PUID=1000으로 두면 호스트에서 설정 폴더의 소유자가 모르는 사용자가 됩니다.

실행 환경	`docker info` 또는 `podman info`에 나오는 것	쓸 방법
일반 Docker	`rootless` 없음	평소처럼 `PUID`와 `PGID`
Rootless Docker	Security Options 아래에 `rootless`	방법 1
Rootless Podman	`rootless: true`	방법 1 또는 2

방법 1. PUID=0과 PGID=0으로 설정합니다. 루트리스 모드에서만 안전합니다. 일반 Docker나 NAS 장비에서는 절대 하지 마세요.

방법 2. keep-id를 쓰는 Podman. ~/.config/containers/systemd/holyarrs.container에 Quadlet으로 둡니다:

[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를 실행하세요.

폴더가 이미 큰 번호의 ID 소유라면 먼저 컨테이너를 중지한 다음:

Rootless Podman: podman unshare chown -R 0:0 ~/holyarrs/config (방법 1) 또는 podman unshare chown -R 1000:1000 ~/holyarrs/config.
Rootless Docker: rootlesskit chown -R 0:0 ~/holyarrs/config. nsenter로 루트리스 데몬 안에 들어가서 실행합니다 (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에서는 풀 경로가 있는지 확인하세요. 테스트용 장비라면 `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 4개를 다시 추가하거나 `user: "<uid>:<gid>"`를 쓰세요.
PUID/PGID does not exist inside this container (PUID/PGID가 이 컨테이너 안에 없음)	ID가 매핑된 범위 밖에 있습니다. Rootless Docker와 Podman을 보세요.
A `FILE__` variable cannot be read (변수를 읽을 수 없음)	경로와 파일이 마운트되어 있는지 확인하세요.
Permission denied (권한 거부됨)	`PUID`, `PGID`와 모든 폴더의 쓰기 권한을 확인하세요.
Unknown host name (알 수 없는 호스트 이름)	IP로 HolyArrs를 열고 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로 목록을 보세요.