インストール

はじめての方

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`	Web アプリです。
`-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 ベースとリバースプロキシを参照してください。
`HOLYARRS_MASTER_KEY_FILE`	任意。マスターキーを専用のファイルから読み込みます。

どの変数もファイルから読み込めます。名前の前に FILE__ を付け、値としてファイルのパスを指定します。

environment:
  - FILE__HOLYARRS_ALLOWED_HOSTS=/run/secrets/holyarrs_hosts

ファイル末尾の改行 1 つは取り除かれます。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 のケーパビリティが必要です。Docker は既定でこれらを与えます。外した場合、HolyArrs はメッセージを出して停止します。root のまま動き続けることはありません。本当に root で動かしたい場合は、PUID=0 と PGID=0 を設定します。

group_add: で追加したグループは、HolyArrs がユーザーを切り替えたあとも残ります。

UMASK が影響するのは新しいファイルだけです。省略すると 022 のままで、自分が書き込み、ほかのユーザーは読み取りだけできます。グループにも書き込ませる場合は 002 を使います。

メディアフォルダー

使うフォルダーだけをマウントします。/movies、/tv、/music はライブラリフォルダー、/downloads はダウンロードフォルダーです。

ハードリンクのヒント: 個別にマウントしたフォルダーは、コンテナの中でそれぞれ別のマウントになります。ファイルはマウントをまたいでハードリンクできないので、インポートは完全なコピーになります。ハードリンクを使いたい場合は、4 つの任意のマウントの代わりに、共有の親フォルダー (ダウンロードフォルダーとライブラリフォルダーをその中に置きます) を 1 つマウントし、ダウンローダーにも同じマウントを同じパスで渡します。親フォルダーは 1 つのファイルシステムである必要もあります。その下に別々の NAS 共有やデータセットがあると、やはりコピーになります。HolyArrs がコピーするしかない場合は、Settings > Library folders(設定 > ライブラリフォルダー)に警告が出ます。

HOLYARRS_SAVE_PATH はダウンロードのたびにダウンローダーへ送られるので、ダウンローダーの保存先も変わります。ダウンローダー自身の設定を使う場合は省略します。省略した場合は、Settings > Library folders > Extra import folders(追加のインポートフォルダー)にダウンロードフォルダーを追加すると、そこから手動でインポートできます。

マスターキーを保管する

HolyArrs は、保存するパスワード、キー、トークンをマスターキーで暗号化します。初回の起動時に /config/holyarrs.key が作られます。

バックアップにこのキーは含まれません。別の場所にコピーを保管してください。簡単な方法: オーナーとして Settings > Backups(設定 > バックアップ)を開き、Download key kit(キーキットをダウンロード)を選びます。キーを戻すときは、HolyArrs を停止した状態で、ファイル名を holyarrs.key にして設定フォルダーに置きます。別のキーでの復元は拒否されます。名前付きボリュームでは開けるフォルダーがないので、Docker Desktop と同じように docker cp holyarrs.key hx:/config/ でコピーします。新しいマシンへ移す場合は、先にキーを戻してから、バックアップを復元します。バックアップを参照してください。

キーを専用の読み取り専用ファイルに置くこともできます。

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

ファイルは実際に存在し、中身が 32 バイトの生データ、64 桁の 16 進数、または 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 にそのプロキシのアドレスまたはネットワークだけを入れます。これがないと、シングルサインオン、実際のクライアントアドレス、Secure 属性付きの Cookie が機能せず、プロキシの後ろにいる全員が 1 つのサインイン回数の上限を共有します。追加するプロキシのアドレスはログに出ます。Cloudflare のように、さらに手前に別のプロキシがある場合は、その範囲も追加します。

nginx では、両方のヘッダーを送ります。

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

2 つの値が食い違う場合、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 もこれに当たります。

ルートレスの Docker と Podman

ルートレスモードでは、コンテナ内の root は自分自身のユーザーで、ほかの ID はホスト上の大きな番号に対応します。PUID=1000 にすると、設定フォルダーの所有者がホスト上では見知らぬユーザーになってしまいます。

使っているもの	`docker info` または `podman info` の表示	使う方法
通常の Docker	`rootless` の表示なし	いつもどおり `PUID` と `PGID`
ルートレスの Docker	Security Options の下に `rootless`	方法 1
ルートレスの Podman	`rootless: true`	方法 1 または 2

方法 1. PUID=0 と PGID=0 を設定します。安全なのはルートレスモードのときだけです。通常の Docker や NAS では絶対に使わないでください。

方法 2. keep-id を使った Podman。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

1 つのコマンドで実行する場合:

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 を 1 回実行します。そのうえで Quadlet ファイルを使うか、 podman run の場合は systemctl --user enable podman-restart.service を実行します。

フォルダーの所有者がすでに大きな ID になっている場合は、先にコンテナを停止してから、次を実行します。

ルートレスの Podman: podman unshare chown -R 0:0 ~/holyarrs/config (方法 1) または podman unshare chown -R 1000:1000 ~/holyarrs/config。
ルートレスの 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

ログとサポートバンドルについては、トラブルシューティングを参照してください。

表示される内容	対処
設定フォルダーが共有フォルダーまたはネットワークフォルダーにある	ローカルディスクを使います。Docker Desktop では名前付きボリュームを使います。Unraid では `/mnt/<pool>/appdata/holyarrs` を使います。
設定フォルダーがメモリ上にある	`/config` をディスクに置きます。Unraid では、プールのパスが存在するか確認します。テスト用のマシンなら、`HOLYARRS_CONFIG_IN_MEMORY=yes` で許可できます。
設定フォルダーに書き込めない	`:ro` を外し、フォルダーの所有者が `PUID:PGID` であることを確認します。
ディスクがいっぱい	`/config` があるディスクの空き容量を増やし、再起動します。
`/config` が割り当てられていない	下を参照してください。
ユーザーを切り替えられない	4 つのケーパビリティを戻すか、`user: "<uid>:<gid>"` を使います。
PUID/PGID がこのコンテナ内に存在しない	ID が割り当て範囲の外にあります。ルートレスの Docker と Podman を参照してください。
`FILE__` の変数を読み込めない	パスと、ファイルがマウントされていることを確認します。
権限がない (Permission denied)	`PUID`、`PGID` と、すべてのフォルダーの書き込み権限を確認します。
不明なホスト名	HolyArrs を IP で開き、Allowed host names にその名前を追加します。
インポートがコピーになる	共有のフォルダーを 1 つマウントします。メディアフォルダーを参照してください。
マスターキーが一致しない	そのデータベースに対応するキーを戻します。
復元の準備はできたのにアプリが停止したまま	再起動ポリシーを追加し、コンテナを起動します。

/config の割り当てを忘れた場合

HolyArrs は起動しますが、あらゆる場所に警告が出ます。コンテナを削除すると、すべて失われます。先に保存してください。

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

そのあと ./holyarrs-config:/config (または名前付きボリューム) を割り当て、コンテナを再作成します。Docker Desktop (Windows と Mac) では、ホストのフォルダーではなく名前付きボリュームを使い、Docker Desktop の手順でデータをコピーします。以前の構成が、名前のないボリュームにまだ残っていることもあります。docker volume ls で一覧を確認できます。