docker - SKILL.md Agent Skill

name: Docker本番環境デプロイ description: Docker Composeでの本番デプロイ、PostgreSQL設定、LDAP認証設定。本番環境構築、デプロイ作業時に使用。

Docker本番環境デプロイガイド

前提条件

Docker / Docker Compose がインストール済み
Node.js 20+ がインストール済み
ソースコードがクローン済み

開発環境

コンテナ構成

services:
  postgres:        # PostgreSQL 16 (port: 5433)
  openldap:        # OpenLDAP 1.5 (port: 390)
  airag-backend:   # RAG Backend  (port: 8000)

セットアップ

# 全コンテナ起動
docker compose up -d

# PostgreSQLのみ起動
docker compose up -d postgres

# 環境変数を設定
cp apps/web/.env.example apps/web/.env
# AUTH_SECRETを生成して .env に記入
openssl rand -base64 48

# 依存関係インストール
pnpm install

# データベースを初期化
pnpm --filter @lionframe/web exec prisma db push
pnpm --filter @lionframe/web run db:seed

# 開発サーバ起動
pnpm dev

環境変数（.env）

# 必須
AUTH_SECRET=<openssl rand -base64 48 で生成>
AUTH_URL=http://localhost:3000
DATABASE_URL="postgresql://lionframe:lionframe@localhost:5433/lionframe?schema=public"
NEXT_PUBLIC_APP_NAME="LionFrame"

# WebAuthn / Passkey（本番は必ず設定）
NEXT_PUBLIC_WEBAUTHN_RP_ID=<本番ドメイン（例: example.com）。未指定時は AUTH_URL のホスト名>
NEXT_PUBLIC_WEBAUTHN_RP_NAME="LionFrame"
WEBAUTHN_ORIGIN=<AUTH_URL と一致させる。複数ならカンマ区切り>

# Web Push（プッシュ通知用 VAPID 鍵）
# 生成: npx web-push generate-vapid-keys
NEXT_PUBLIC_VAPID_PUBLIC_KEY=<公開鍵>
VAPID_PRIVATE_KEY=<秘密鍵>

本番環境デプロイ

1. 環境変数の設定

# .env（本番用）
AUTH_SECRET=<openssl rand -base64 48 で生成>
# 単一ホスト名で公開する場合は AUTH_URL を明示
AUTH_URL=https://<本番ドメイン>
# LAN IP / 複数ホスト名で公開する場合は AUTH_URL を未設定にし、
# AUTH_TRUST_HOST=true で Host ヘッダから動的解決する（Issue #46）
# AUTH_TRUST_HOST=true
DATABASE_URL="postgresql://<user>:<password>@<host>:5432/<dbname>?schema=public"
NEXT_PUBLIC_APP_NAME="LionFrame"

HTTPS 終端 / HSTS の運用

LionFrame の Next.js アプリ自体は HSTS ヘッダを送信しない設計です（Issue #46）。 HTTP のみで待ち受けるサーバ（dev / LAN 内本番）に HSTS を返すと RFC 6797 §7.2 違反となり、Chrome の Network State により ERR_ADDRESS_UNREACHABLE で到達不能になるためです。

本番では HTTPS 終端を行うリバースプロキシ層（Caddy / nginx 等）から HSTS を付与する 運用を推奨します。

Caddy の例:

example.com {
  reverse_proxy localhost:3000
  header Strict-Transport-Security "max-age=31536000; includeSubDomains"
}

nginx の例:

server {
  listen 443 ssl http2;
  server_name example.com;
  add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;
  location / {
    proxy_pass http://localhost:3000;
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header X-Forwarded-Host $host;
  }
}

アプリ側でも NODE_ENV=production のときは HSTS を送信するため、リバプロから二重に付与されても問題ありません。LAN IP 経由の本番（リバプロなしで HTTP 配信）では NODE_ENV=production にしないか、リバプロ経由のアクセスのみを想定して運用してください。

2. 本番イメージのビルドと起動

# ビルド
docker compose -f docker-compose.prod.yml build

# 起動
docker compose -f docker-compose.prod.yml up -d

# 状態確認
docker compose -f docker-compose.prod.yml ps

3. OpenLDAP設定

OpenLDAPの設定は管理画面から行います：

管理画面へアクセス: https://<本番ドメイン>/admin?tab=modules
OpenLDAPモジュールを選択
設定項目:
- サーバURL（例: ldap://ldap.example.com:389）
- ベースDN（例: ou=Users,dc=example,dc=com）
- バインドDN・パスワード（オプション）
- 有効/無効トグル

設定はデータベースに保存され、環境変数を使わずに本番環境で変更可能です。

4. ヘルスチェック

# HTTP応答確認
curl -I https://<本番ドメイン>/

# ログ確認
docker compose -f docker-compose.prod.yml logs nextjs | tail -60

確認メッセージ：

"All migrations have been successfully applied."
"Database seeded successfully!"
"Ready in XXms"

運用コマンド

# ログ確認（リアルタイム）
docker compose -f docker-compose.prod.yml logs -f nextjs

# 再起動
docker compose -f docker-compose.prod.yml restart

# 停止
docker compose -f docker-compose.prod.yml down

# Prisma Studio（本番DB確認）
docker exec -it <container-name> npx prisma studio

データベース

環境	ポート	接続先
開発	5433 (ホスト→5432)	localhost:5433 (Docker)
本番	5432 (内部)	postgres:5432 (Docker内部)

開発環境セットアップ

docker compose up -d postgres
npx prisma db push
npm run db:seed

マイグレーション

# スキーマ変更をDBに反映（開発）
npx prisma db push

# マイグレーションファイル作成（本番推奨）
npx prisma migrate dev --name <migration_name>

# 本番適用
npx prisma migrate deploy

トラブルシューティング

OpenLDAP認証が動かない

管理画面で設定確認: /admin?tab=modules → OpenLDAP
- サーバURLが正しいか確認
- 「接続テスト」ボタンで接続確認
- 有効/無効トグルがONになっているか確認
ログ確認:

docker compose logs nextjs | grep -i ldap

PostgreSQL接続できない

# ログ確認
docker compose logs postgres

# コンテナ再起動
docker compose restart postgres

# ヘルスチェック
docker exec lionframe-postgres pg_isready -U lionframe

ポート競合

# 使用中のポートを確認
lsof -i :5433  # PostgreSQL
lsof -i :390   # OpenLDAP
lsof -i :8000  # RAG Backend
lsof -i :3000  # Next.js開発サーバ

初期ログイン

項目	値
URL	http://localhost:3000
ユーザ名	admin
パスワード	admin

重要: 本番環境では初回ログイン後にパスワードを変更してください。

チェックリスト

本番デプロイ時:

.env に本番用の AUTH_SECRET を生成・設定
AUTH_URL を本番ドメインに変更（HTTPS 必須、WebAuthn 要件）。LAN IP / 複数ホスト名なら未設定 + AUTH_TRUST_HOST=true
DATABASE_URL を本番DBに変更
NEXT_PUBLIC_WEBAUTHN_RP_ID を本番ドメインで設定、WEBAUTHN_ORIGIN も揃える
VAPID 鍵（NEXT_PUBLIC_VAPID_PUBLIC_KEY / VAPID_PRIVATE_KEY）を生成・設定
docker compose -f docker-compose.prod.yml up -d で起動
ヘルスチェックで正常動作を確認
管理画面でOpenLDAP設定を確認（必要な場合）
初期パスワードを変更
HTTPS/TLSが有効になっているか確認
リバースプロキシ層から HSTS ヘッダを付与する設定になっているか確認（Issue #46）