予約システムデプロイガイド

このドキュメントは、予約システムの完全なデプロイ手順を、開発環境と本番環境の両方を対象に説明するものです。

ディレクトリ構成

booking-deploy/
├── compose/                    # Docker Compose 設定ファイル
│   ├── docker-compose.dev.yml     # 開発環境オーケストレーション
│   ├── docker-compose.prod.yml    # 本番環境オーケストレーション
│   ├── dev.compose.env.example    # 開発環境変数のテンプレート
│   └── prod.compose.env.example   # 本番環境変数のテンプレート
├── env/                       # アプリケーション環境変数
│   ├── dev/                   # 開発環境
│   │   ├── backend.env.example
│   │   └── frontend.env.example
│   └── prod/                  # 本番環境
│       ├── backend.env.example
│       └── frontend.env.example
└── scripts/                   # デプロイスクリプト
    └── verify-images.sh       # イメージ検証スクリプト

環境準備

1. Docker と Docker Compose

Docker Engine 20.10+ または Docker Desktop
Docker Compose v2+ (推奨) または docker-compose v1.29+

2. 環境変数の準備

開発環境

# テンプレートファイルをコピー
cd booking-deploy

# Compose 用環境変数
cp compose/dev.compose.env.example compose/dev.compose.env
# 必要に応じて dev.compose.env を編集し、Docker Hub のイメージアドレスを更新

# アプリケーション用環境変数
cp env/dev/backend.env.example env/dev/backend.env
cp env/dev/frontend.env.example env/dev/frontend.env
# .env ファイルを編集し、実際の値(JWT_SECRET など)を設定

本番環境

cd booking-deploy
cp compose/prod.compose.env.example compose/prod.compose.env
cp env/prod/backend.env.example env/prod/backend.env
cp env/prod/frontend.env.example env/prod/frontend.env

# 重要: 本番環境では強いパスワードと本物のシークレットが必要

イメージタグ戦略

予約システムの CI/CD パイプラインは、複数種類の Docker イメージタグを自動生成します。それぞれ目的と信頼性の特性が異なります。

タグの種類

タグ種別	形式例	変更可否	推奨用途	信頼性
ブランチタグ	`dev`, `main`	可変 — プッシュのたびに更新	迅速な開発、統合テスト	低 — 本番には不適
コミットタグ	`dev-abc123`, `main-def456`	不変 — 特定コミットに紐付け	信頼性のあるデプロイ、ロールバック、監査	高 — 本番推奨
セマンティックバージョン	`v1.0.0`, `v1.2.3`	不変 — バージョン付けされたリリース	公式リリース、バージョン管理	最高 — 本番のベストプラクティス
PR タグ	`pr-123`	可変 — PR のビルド	PR 検証、コードレビュー	低 — 一時用途のみ
latest	`latest`	可変 — main の最新	開発便宜	低 — 本番禁止

選定ガイド

開発環境:
- 迅速なイテレーション: dev ブランチタグを使用
- 信頼性のあるテスト: dev-<commit-hash> コミットタグを使用
本番環境:
- 不変タグを必ず使用: コミットタグまたはセマンティックバージョンタグ
- 緊急修正: main-<commit-hash> を使用
- 公式リリース: v1.0.0 のようなセマンティックバージョンを使用
- 禁止: main または latest タグ

イメージ検証

すべてのイメージは実際のデプロイトポロジーで検証されます:

✅ PostgreSQL と Redis の依存関係を含む
✅ データベースマイグレーションを実行
✅ ヘルスエンドポイント(/v1/health)を検証
✅ データベースと Redis の接続状態を確認
✅ フロントエンドのアクセシビリティを検証

利用可能なタグの確認

イメージタグは GitHub Actions のワークフローにより自動生成されます:

バックエンドイメージ: booking-backend/.github/workflows/backend-image.yml
フロントエンドイメージ: booking-frontend/.github/workflows/frontend-image.yml
マイグレーションイメージ: 専用の booking-backend-migration イメージ

ロールバック操作

以前のバージョンへロールバックするには:

以前のコミットタグ(例: main-abc123def)を確認
prod.compose.env ファイル内のイメージタグを更新
更新した設定でサービスを再起動: docker compose -f compose/docker-compose.prod.yml --env-file compose/prod.compose.env up -d

# 特定のコミットへロールバック
BACKEND_IMAGE=docker.io/cho-geer/booking-backend:main-previous-commit
BACKEND_MIGRATION_IMAGE=docker.io/cho-geer/booking-backend-migration:main-previous-commit
FRONTEND_IMAGE=docker.io/cho-geer/booking-frontend:main-previous-commit

デプロイ手順

開発環境のデプロイ

# booking-deploy ディレクトリへ移動
cd booking-deploy

# 開発環境を起動
docker compose -f compose/docker-compose.dev.yml --env-file compose/dev.compose.env up -d

up -d の動作:

データベースマイグレーションを実行(独立したマイグレーションサービスが up 時に自動実行)
すべてのサービスを開始(PostgreSQL、Redis、バックエンド、フロントエンド)し、バックグラウンドで起動し続けます
ヘルスチェックで依存サービスの起動完了を待機してから、後続のサービスを起動します

既存イメージを最新に更新してから起動する場合は、事前に pull を実行します:

docker compose -f compose/docker-compose.dev.yml --env-file compose/dev.compose.env pull

起動後の確認先:

バックエンドヘルスエンドポイント: http://localhost:3001/v1/health
バックエンド Swagger: http://localhost:3001/api/docs
フロントエンドページ: http://localhost:3000

イメージ取得から起動・ヘルス検証までを一時的な起動でまとめて確認する場合は、検証スクリプトを使用します(検証完了後に自動で down します):

./scripts/verify-images.sh dev

本番環境のデプロイ

本番環境(prod)は現行スコープ外です(手順書 §6 で保留中)。prod を復活させる際に、本番デプロイ手順を改めて定義します。

サービス構成

開発環境サービス

サービス	イメージ	ポート	説明
PostgreSQL	`postgres:16`	5432	メインデータベース
Redis	`redis:7-alpine`	6379	キャッシュとセッションストア
Backend	`${BACKEND_IMAGE}`	3001	NestJS API サービス
Frontend	`${FRONTEND_IMAGE}`	3000	Next.js フロントエンドアプリケーション
Migration	`${BACKEND_MIGRATION_IMAGE}`	-	データベースマイグレーションサービス

本番環境との違い

コンテナ化された PostgreSQL の代わりに外部データベース(例: RDS)を使用する場合あり
外部 Redis クラスターを使用する場合あり
ロードバランサーや監視サービスを追加する場合あり
リソース制限や再起動ポリシーが異なる

データベースマイグレーション

独立したマイグレーションサービス

デプロイプロセスには、独立した migration サービスが含まれており、以下を保証します:

マイグレーションはアプリ起動前に実行される
失敗時にはデプロイを停止し、アプリが整合性のない DB に接続するのを防ぐ
冪等性: prisma migrate deploy は安全に繰り返し実行可能

手動でのマイグレーション実行

# 開発環境
docker compose -f compose/docker-compose.dev.yml --env-file compose/dev.compose.env run --rm migration

# 本番環境
docker compose -f compose/docker-compose.prod.yml --env-file compose/prod.compose.env run --rm migration

ヘルスチェックと監視

内蔵ヘルスチェック

Backend: GET /v1/health — アプリ、DB、Redis の状態を返す
PostgreSQL: Docker ヘルスチェックは pg_isready を使用
Redis: Docker ヘルスチェックは redis-cli ping を使用

デプロイ後の検証

検証スクリプト ./scripts/verify-images.sh dev は以下を自動検証します:

バックエンドのヘルスエンドポイントが 200 OK を返すこと
Swagger UI にアクセス可能であること
フロントエンドのホームページにアクセス可能であること

手動検証

# バックエンドのヘルスチェック
curl http://localhost:3001/v1/health | jq .

# サービスステータスの確認
docker compose -f compose/docker-compose.dev.yml --env-file compose/dev.compose.env ps

トラブルシューティング

よくある問題

1. 環境変数ファイルの欠落

Missing booking-deploy/compose/dev.compose.env
Create it from booking-deploy/compose/dev.compose.env.example

解決策: テンプレートファイルをコピーし、実際の値を入力してください。

2. マイグレーション失敗

Error: P3009: migrate found failed migrations in the target database

解決策:

データベース接続文字列を確認
手動でマイグレーションを修正: docker compose exec postgres psql -U postgres -d booking_system
マイグレーションログを確認

3. ヘルスチェック失敗

ヘルスチェックは依存サービスの起動完了を待機します。 解決策:

サービスログを確認: docker compose logs backend
データベース接続を確認: docker compose exec backend npm run prisma:deploy
ポート競合を確認

4. イメージ取得失敗

Error response from daemon: pull access denied for cho-geer/booking-backend

解決策:

Docker Hub リポジトリが存在し、公開されていることを確認
もしくはローカルビルドイメージを使うように compose/dev.compose.env を更新

ログの確認

# 全サービスのログを表示
docker compose -f compose/docker-compose.dev.yml --env-file compose/dev.compose.env logs

# 特定サービスのログを表示
docker compose -f compose/docker-compose.dev.yml --env-file compose/dev.compose.env logs backend

# リアルタイムでログを追跡
docker compose -f compose/docker-compose.dev.yml --env-file compose/dev.compose.env logs -f

アップグレードとロールバック

バージョンアップグレード

compose/dev.compose.env または compose/prod.compose.env のイメージタグを更新
サービスを再起動: docker compose -f compose/docker-compose.dev.yml --env-file compose/dev.compose.env up -d
新バージョンの機能を検証

ロールバック操作

環境変数ファイルの古いイメージタグを復元
サービスを再起動: docker compose -f compose/docker-compose.dev.yml --env-file compose/dev.compose.env up -d
データベース前方互換性: 古いバージョンのアプリが現在の DB スキーマで動作することを確認

ゼロダウンタイムデプロイ(将来の拡張)

現在のデプロイ戦略はローリング再起動を使用しており、将来的には次のような拡張が可能です:

ブルーグリーンデプロイ
カナリーリリース
Docker Swarm または Kubernetes の利用

セキュリティ考慮事項

1. 機密情報の管理

.env ファイルをバージョン管理に絶対にコミットしない
本番シークレットにはシークレット管理サービス(例: AWS Secrets Manager)を使用
JWT シークレットや DB パスワードを定期的にローテーション

2. ネットワークセキュリティ

本番環境には専用ネットワークを使用
データベースと Redis への外部アクセスを制限
ファイアウォールルールを有効化

3. イメージセキュリティ

イメージの脆弱性を定期的にスキャン
最小限のベースイメージを使用
依存関係を迅速に更新

自動化された CI/CD(将来)

現在のデプロイは手動起動ですが、将来的に CI/CD パイプラインと統合する予定です:

GitHub Actions ワークフロー

name: Deploy to Production
on:
  push:
    tags:
      - 'v*'
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Deploy to Server
        uses: appleboy/ssh-action@v0.1.5
        with:
          host: ${{ secrets.PROD_HOST }}
          username: ${{ secrets.PROD_USER }}
          key: ${{ secrets.PROD_SSH_KEY }}
          script: |
            cd /opt/booking-system/booking-deploy
            docker compose -f compose/docker-compose.prod.yml --env-file compose/prod.compose.env up -d

承認プロセス

本番デプロイには以下を含める必要があります:

コードレビュー
自動テスト合格
手動承認
デプロイ後の検証

付録

A. 手動デプロイコマンドリファレンス

# イメージを取得
docker compose -f compose/docker-compose.dev.yml --env-file compose/dev.compose.env pull

# マイグレーションを実行
docker compose -f compose/docker-compose.dev.yml --env-file compose/dev.compose.env run --rm migration

# サービスを起動
docker compose -f compose/docker-compose.dev.yml --env-file compose/dev.compose.env up -d

# サービスを停止
docker compose -f compose/docker-compose.dev.yml --env-file compose/dev.compose.env down

# ステータスを表示
docker compose -f compose/docker-compose.dev.yml --env-file compose/dev.compose.env ps

B. 環境変数の説明

各 .env.example ファイルのコメントを参照してください。

C. 関連ドキュメント

最終更新: 2026-04-08 メンテナー: DevOps チーム

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
.vscode		.vscode
compose		compose
docs		docs
env		env
scripts		scripts
.gitattributes		.gitattributes
.gitignore		.gitignore
LICENSE		LICENSE
README.en.md		README.en.md
README.md		README.md
README.zh.md		README.zh.md
test.log		test.log

Latest commit

History

Folders and files

Repository files navigation

予約システム デプロイガイド

ディレクトリ構成

環境準備

1. Docker と Docker Compose

2. 環境変数の準備

開発環境

本番環境

イメージタグ戦略

タグの種類

選定ガイド

イメージ検証

利用可能なタグの確認

ロールバック操作

デプロイ手順

開発環境のデプロイ

本番環境のデプロイ

サービス構成

開発環境サービス

本番環境との違い

データベースマイグレーション

独立したマイグレーションサービス

手動でのマイグレーション実行

ヘルスチェックと監視

内蔵ヘルスチェック

デプロイ後の検証

手動検証

トラブルシューティング

よくある問題

1. 環境変数ファイルの欠落

2. マイグレーション失敗

3. ヘルスチェック失敗

4. イメージ取得失敗

ログの確認

アップグレードとロールバック

バージョンアップグレード

ロールバック操作

ゼロダウンタイムデプロイ(将来の拡張)

セキュリティ考慮事項

1. 機密情報の管理

2. ネットワークセキュリティ

3. イメージセキュリティ

自動化された CI/CD(将来)

GitHub Actions ワークフロー

承認プロセス

付録

A. 手動デプロイコマンドリファレンス

B. 環境変数の説明

C. 関連ドキュメント

🇬🇧 English | 🇨🇳 中文

About

Topics

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

予約システムデプロイガイド