本番配置の準備を追加（NAS の DB 定義、配置手順書、保存先の決定）

2026-10-04 12:01:19 +09:00
parent 80d9606750
commit 37d42851ff
5 changed files with 263 additions and 10 deletions
@@ -0,0 +1,204 @@
+---
+title: tver 本番配置手順
+tags:
+  - homelab
+  - tver
+  - deployment
+---
+
+# tver 本番配置手順
+
+> [!info] 対象
+> Synology NAS `ds923p`（`192.168.10.201`）に PostgreSQL 17 と動画共有を用意し、dockage（`192.168.10.155`）の `/opt/stacks/tver` で web・worker を起動する。
+
+> [!danger] 秘匿値を記録しない
+> PostgreSQL のパスワードや完成した `DATABASE_URL` は、この文書や Git 管理下のファイルに書かない。NAS と dockage の `.env` にだけ保存し、権限を `600` にする。
+
+## 事前に確認する値
+
+| 項目 | 値 |
+|---|---|
+| NAS | `ds923p` / `192.168.10.201` |
+| dockage | `192.168.10.155` |
+| NAS のNFS共有 | `/volume1/video` |
+| dockage のNFSマウント | `/mnt/nas-tver` |
+| tverの動画保存先 | NAS: `/volume1/video/tver`、dockage: `/mnt/nas-tver/tver` |
+| PostgreSQL 公開ポート | `15434` |
+| PostgreSQL ユーザー / DB | `tver` / `tver` |
+| アプリ配置先 | `/opt/stacks/tver` |
+
+> [!warning] 起動前の未確認事項
+> - [要確認] Container Manager と DSM で、TCP `15434` が他のコンテナやサービスに使われていないこと。
+
+## 1. NASを準備する
+
+### 1.1 NFSサービスを有効にする
+
+1. DSMの「コントロール パネル」→「ファイル サービス」→「NFS」でNFSサービスを有効にする。
+2. 共有フォルダ `video` が `/volume1/video` にあることを確認する。
+3. `video` の「編集」→「NFS 権限」で次を追加する。
+
+| 設定 | 値 |
+|---|---|
+| ホスト名またはIP | `192.168.10.155` |
+| 権限 | 読み書き |
+| Squash | すべてのユーザーをadminに割り当てる |
+| セキュリティ | `sys` |
+| 非同期を有効にする | オン |
+
+> [!success] adminへの割り当てを確認済み
+> DSMの`admin`アカウントが無効な状態でも、上記設定でUID `65532`からフォルダ作成・書き込み・読み込み・rename・削除に成功した。NAS上の所有者はUID `1024`・GID `100`だった。[実機] 2026-10-04 確認
+
+### 1.2 PostgreSQLのファイルを用意する
+
+1. NAS上に次のディレクトリを事前作成する。
+
+   ```text
+   /volume1/docker/tver-db/
+   /volume1/docker/tver-db/pgdata/
+   ```
+
+2. [[../deploy/nas/tver-db/compose.yaml|NAS用compose.yaml]] と `.env.example` を `/volume1/docker/tver-db/` に配置する。
+3. `.env.example`を`.env`へコピーし、`POSTGRES_PASSWORD`に十分長いランダムな値を設定する。値には、URLへの埋め込みで追加のエスケープが不要な16進文字列を使える。
+
+   ```bash
+   cd /volume1/docker/tver-db
+   umask 077
+   cp .env.example .env
+   # openssl rand -hex 64 で値を生成し、.env の POSTGRES_PASSWORD に設定する。
+   chmod 600 .env
+   ```
+
+> [!important] DBとアプリで同じパスワードを使う
+> ここで設定した値を、後述するdockage側の`DATABASE_URL`にも使う。値そのものは文書やGitへ残さない。
+
+### 1.3 Container ManagerでPostgreSQLを起動する
+
+1. Container Managerの「プロジェクト」で、`/volume1/docker/tver-db/compose.yaml`を使う`tver-db`プロジェクトを作成する。
+2. 起動前に、他のプロジェクトとポート一覧を確認し、`15434`が空いていることを確認する。[要確認]
+3. プロジェクトをビルド・起動する。
+4. `tver-postgres`が`healthy`になることを確認する。
+5. コンテナログに`database system is ready to accept connections`があることを確認する。
+
+初期化に失敗した場合は、先に`pgdata`の所有権・権限とログを確認する。空のDBを作り直す場合を除き、既存の`pgdata`を削除しない。
+
+### 1.4 DSMファイアウォールを設定する
+
+TCP `15434`について、送信元`192.168.10.155`だけを許可するルールを追加する。他の送信元を許可する広いルールより前に配置し、LAN内の別ホストからDBへ接続できない構成にする。
+
+## 2. dockageを準備する
+
+### 2.1 NFSクライアントとマウント先を用意する
+
+```bash
+sudo apt update
+sudo apt install -y nfs-common
+sudo mkdir -p /mnt/nas-tver
+```
+
+`/etc/fstab`へ次の1行を追加する。`_netdev`でネットワーク後に扱い、`nofail`でNAS停止時もdockageの起動を妨げない。
+
+```fstab
+192.168.10.201:/volume1/video /mnt/nas-tver nfs defaults,_netdev,nofail 0 0
+```
+
+設定を反映し、想定したNFS共有がマウントされたことを確認する。
+
+```bash
+sudo mount -a
+findmnt --target /mnt/nas-tver
+```
+
+実機ではNFSv3でマウントできた。NFS権限を追加した直後の1回目は`access denied`となり、直後の2回目で成功した。NFS権限の反映待ちと考えられるため、設定内容が正しい場合は少し待って`sudo mount -a`を再実行する。[実機] 2026-10-04 確認
+
+### 2.2 workerのUIDで書き込みを確認する
+
+既存の`anime`・`drama`・`misc`・`personal`・`variety`とアプリのファイルを分け、admin相当の書き込み範囲を限定するため、tver専用サブフォルダを使う。Dockerグループの`kazu634`で、workerコンテナと同じUID・GID `65532:65532`の確認用コンテナを実行し、フォルダ作成、書き込み、読み取り、rename、削除を確認する。`sudo`は不要である。
+
+```bash
+docker run --rm --user 65532:65532 -v /mnt/nas-tver/tver:/videos busybox:stable sh -c 'mkdir /videos/.tver-write-test && echo ok > /videos/.tver-write-test/f && cat /videos/.tver-write-test/f && mv /videos/.tver-write-test/f /videos/.tver-write-test/g && ls -ln /videos/.tver-write-test && rm -r /videos/.tver-write-test && echo cleanup-ok'
+```
+
+期待する結果は、内容の`ok`、`ls -ln`で表示される`g`の所有者`1024 100`、最後の`cleanup-ok`である。確認後は確認用イメージを削除する。
+
+```bash
+docker rmi busybox:stable
+```
+
+`/mnt/nas-tver/tver`は作成済みで、上記のDockerコンテナによる操作は実機確認済みである。[実機] 2026-10-04 確認。別環境へ作り直す場合も、書き込み確認が成功するまでworkerを起動しない。
+
+### 2.3 リポジトリと環境変数を用意する
+
+公開リポジトリを標準のスタックディレクトリへcloneする。
+
+```bash
+cd /opt/stacks
+git clone https://gitea.kazu634.com/kazu634/tver.git tver
+cd /opt/stacks/tver
+```
+
+`.env.example`をGit管理外の`.env`へコピーし、実環境の値を設定する。
+
+```bash
+umask 077
+cp .env.example .env
+chmod 600 .env
+```
+
+`.env`には次の形式で設定する。`<PostgreSQLのパスワード>`はNAS側の`.env`と同じ実値へ置き換える。
+
+```dotenv
+DATABASE_URL=postgres://tver:<PostgreSQLのパスワード>@192.168.10.201:15434/tver?sslmode=disable
+VIDEO_HOST_DIR=/mnt/nas-tver/tver
+VIDEO_DIR=/videos
+WORKER_CONCURRENCY=1
+```
+
+> [!warning] パスワードの文字種
+> 上のURLへ埋め込む値に予約文字がある場合はURLエンコードが必要になる。NAS準備時に16進文字列で生成すれば、この追加処理を避けられる。
+
+### 2.4 Dockgeで起動する
+
+1. Dockgeでスタックディレクトリ `/opt/stacks/tver` の`compose.yaml`を`tver`スタックとして開く。
+2. webとworkerの両方が`build`対象であり、`.env`が読み込まれることを確認する。
+3. 「Deploy」でビルドと起動を行う。
+4. Dockge上でweb・workerがともにrunningになり、再起動を繰り返していないことを確認する。
+
+コマンドでも状態とログを確認できる。
+
+```bash
+cd /opt/stacks/tver
+docker compose ps
+docker compose logs --tail=100 web worker
+```
+
+## 3. 動作を確認する
+
+1. ヘルスチェックが`200`と`ok`を返すことを確認する。
+
+   ```bash
+   curl --fail --show-error http://192.168.10.155:8080/healthz
+   ```
+
+2. ブラウザで`http://192.168.10.155:8080/`を開き、新着一覧が表示されることを確認する。
+3. 番組またはエピソードを1件登録し、`/queue`で待ち行列、進捗、完了を確認する。
+4. `/library`から動画を再生し、シークできることを確認する。
+5. NASの`/volume1/video/tver`に規則どおりのMP4が作成されたことを確認する。
+6. `tver-postgres`のログとweb・workerのログに、接続失敗やマイグレーション失敗がないことを確認する。
+
+## 4. 更新する
+
+```bash
+cd /opt/stacks/tver
+git status --short
+git pull --ff-only
+```
+
+`git status --short`に追跡対象ファイルの変更がある場合は、内容を確認してから更新する。pull後、Dockgeで`tver`スタックを再ビルドして再配置し、[[#3. 動作を確認する]]を繰り返す。
+
+yt-dlpを更新するときは`Dockerfile.worker`の`YT_DLP_VERSION`の既定値を変更してリポジトリへ反映し、workerイメージをキャッシュなしで再ビルドする。更新後はworkerログと少数の実動画で抽出・保存を確認する。
+
+## 5. 稼働後に残る作業
+
+> [!todo] PostgreSQLバックアップ
+> tver専用PostgreSQL 17コンテナ内の`pg_dump`で取得し、gzip圧縮してNASの`/volume1/backups/tver/`へ保存する日次処理を用意する。保持日数は既定14日とし、稼働確認後に別作業として実装する。