インストール

PosterPilot は単一の Docker コンテナとして動作します。同じマルチアーキテクチャイメージ （amd64 + arm64）が、Mac、Unraid サーバー、またはその他の Docker が動作する場所で 実行されます。

公式イメージ

公式のビルド済みイメージは GitHub Container Registry に公開されています：

docker pull ghcr.io/diegopeixoto/posterpilot:latest

タグはリリースに従います。:latest は最新のリリースを追跡します。再現性のある アップグレードを好む場合は、代わりに特定のバージョンタグに固定できます。

ボリュームとポート

2 つのボリュームが重要です：

• /data — SQLite、設定、暗号化キー、アートワークのスナップショット／履歴、 アプリバックアップ、キャッシュ、ローテーションログを含む永続状態です。
• /kometa — Kometa のアセット／設定ディレクトリをここにマウントすることで、 エクスポートされた YAML が Kometa が読み取る場所に配置されます。Kometa エクスポートを使う場合のみ必要です。

コンテナはデフォルトでポート 3000 をリッスンします（PORT 環境変数で設定可能）。UI に アクセスするには、ホストのポートに公開してください。

保存されるシークレットの暗号化キー

PosterPilot はシークレット設定（メディアサーバーのトークンとプロバイダーの API キー）を保存時に 暗号化します。デフォルトでは初回実行時に data/.app-key にインスタンスキーを自動生成します — セットアップは不要 です。そのキーは /data ボリューム内にあるため、/data を永続的で バックアップされたストレージに保持しておけば、コンテナの更新をまたいでシークレットを復号可能な 状態に保てます。

任意で APP_SECRET 環境変数を設定すると、代わりにあなたが管理する値からキーを導出します。 コンテナ（とその data/.app-key）が再作成されてもシークレットをポータブルに 保ちたい場合に設定します。 APP_SECRET を設定しない場合は、data/.app-key をバックアップの一部として扱ってください — それを失うと、保存したすべての認証情報を再入力することになります。完全な動作については 設定 → シークレットと暗号化を参照してください。

アップグレード前のバックアップ

変更ジョブの完了を待ち、/data ボリューム全体をコピーします。現在の版に 設定 → バックアップと復元があれば、手動バックアップも作成・検証します。同じ APP_SECRET または .app-key を保持してください。

アップグレードは追加型の DB 移行を実行します。1 サーバー環境は、項目／履歴を 捨てずに保護された名前付き Default server へ移行します。 複数サーバー移行チェックリストに従ってください。

Kometa 設定のマウント

Kometa マネージャーを使うには、config.yml のディレクトリを 読み書き可能でマウントし、例として KOMETA_CONFIG_PATH=/config/config.yml を設定します。 posterpilot-movies.yml と posterpilot-shows.yml は物理的に同じ場所へ書かれます。 KOMETA_METADATA_PATH_PREFIX（既定 config）は別に、Kometa の実行環境から見える相対参照を指定します。物理パスではありません。平文の Kometa シークレットを含むため、ボリュームの権限を保護してください。

Docker Compose（macOS）

docker-compose.yml を作成します：

services:
  posterpilot:
    image: ghcr.io/diegopeixoto/posterpilot:latest
    container_name: posterpilot
    ports:
      - '3000:3000'
    healthcheck:
      test:
        [
          'CMD',
          'bun',
          '-e',
          "fetch('http://localhost:3000/api/health').then(r=>process.exit(r.ok?0:1)).catch(()=>process.exit(1))"
        ]
      interval: 30s
      timeout: 5s
      retries: 3
      start_period: 20s
    environment:
      PORT: '3000'
      DATABASE_URL: file:/data/posterpilot.db
      KOMETA_ASSETS_DIR: /kometa
      # 任意 — 代わりにアプリ内の設定ページでこれらを設定することもできます:
      PLEX_URL: ${PLEX_URL:-}
      PLEX_TOKEN: ${PLEX_TOKEN:-}
      TMDB_KEY: ${TMDB_KEY:-}
      # 任意 — シークレット暗号化キーを導出します（未設定の場合は data/.app-key に自動生成）:
      # APP_SECRET: ${APP_SECRET:-}
    volumes:
      # 永続的なアプリの状態（SQLite db + 設定 + 履歴）。
      - ./data:/data
      # エクスポートされた YAML が取り込まれるよう、Kometa のアセット／設定ディレクトリをここにマウントします。
      - ./data/kometa:/kometa
    restart: unless-stopped

それから起動します：

docker compose up -d
# UI at http://localhost:3000

リポジトリに同梱されている docker-compose.yml は同じ構成で、イメージをプルする代わりに ローカルでビルドしたい場合の build: . オプションを含んでいます：

docker compose up -d --build

Unraid（Community Apps）

PosterPilot は Unraid Community Apps ストアに掲載されています。Apps タブを開き、 PosterPilot を検索して Install をクリックしてください。

手動で追加したい場合は、リポジトリにテンプレート unraid/posterpilot.xml も同梱しています。 Unraid の UI で Docker → Add Container に移動し、これを Template フィールドに貼り付けます：

https://raw.githubusercontent.com/diegopeixoto/posterpilot/main/unraid/posterpilot.xml

これは GHCR イメージ、WebUI ポート、/data と /kometa のボリューム、および任意の 認証情報フィールド（Plex / Jellyfin / Emby、TMDB、Fanart.tv、言語）を事前入力します — これらはすべて後から設定ページでも構成できます。

Docker Compose（Unraid）

Compose の方が好みですか？ボリュームを appdata 共有に向けてください — 特に、エクスポート された YAML が Kometa がすでに読み取っている場所に配置されるよう、Kometa ボリュームを 既存の Kometa 設定ディレクトリに向けてください：

services:
  posterpilot:
    image: ghcr.io/diegopeixoto/posterpilot:latest
    container_name: posterpilot
    ports:
      - '3000:3000'
    environment:
      PORT: '3000'
      DATABASE_URL: file:/data/posterpilot.db
      KOMETA_ASSETS_DIR: /kometa
      # 任意 — または設定ページでこれらを構成します:
      PLEX_URL: ${PLEX_URL:-}
      PLEX_TOKEN: ${PLEX_TOKEN:-}
      TMDB_KEY: ${TMDB_KEY:-}
      # 任意 — シークレット暗号化キーを導出します（未設定の場合は data/.app-key に自動生成）:
      # APP_SECRET: ${APP_SECRET:-}
    volumes:
      - /mnt/user/appdata/posterpilot:/data
      - /mnt/user/appdata/kometa/config:/kometa
    restart: unless-stopped

PLEX_URL / PLEX_TOKEN / TMDB_KEY をコンテナの環境に設定するか、空白のままにして 設定ページですべてを構成し、それからポート 3000 でコンテナにアクセスしてください。

初回実行

1. コンテナを起動し、http://<host>:3000（例： http://localhost:3000）を開きます。
2. 初回実行時はまだ何も同期されていません。バナーが /setup の 初回インストール ウィザード へ案内します。これは 6 つのステップを順を追って案内します：言語を選択する、 メディアサーバーを接続する、TMDB キーを追加する、アートワークプロバイダーを有効にする、 同期するライブラリを選択する、そして最初の同期を実行する。Plex の場合、ウィザードには PIN ログインと接続検出が含まれているため、トークンや URL を貼り付ける必要はありません。 ウィザードはスキップ可能です — 代わりに 設定 ですべてを構成することもできます。 各ステップはサーバー成功後だけ進み、最後は最初の同期を終了状態まで追跡して、 必要なら失敗詳細と再試行を表示します。
3. 環境変数経由で認証情報を設定した場合、それらはウィザードと設定の両方で設定済みかつ 編集ロック済みとして表示されます（ 設定 を参照）。
4. 同期が完了したら、カバーの検索と適用を始めます（ 使い方 を参照）。

アプリバックアップから復元

稼働中 SQLite を手動で置換せず、設定 → バックアップと復元を使います。プレビューは チェックサム、DB、スキーマ、容量、パス、キーを検証します。確認するとメンテナンスに入り、 変更ジョブを終了させ、安全バックアップとマーカーを作ります。コンテナを再起動し、libsql 起動前に置換した後、準備状況レポートを確認します。自動化と復旧も参照してください。

ヘルスチェック

アプリは認証不要の GET /api/health を公開しており、HTTP 200 とともに { "status": "ok", "version": "x.y.z" } を返します — コンテナのヘルスプローブとして 使用してください（同梱の docker-compose.yml はすでにそうしています）：

curl -s http://localhost:3000/api/health