docker-compose.yml

# =============================================================================
# 基本的なDocker Compose設定ファイル（マルチコンテナアプリケーション）
# =============================================================================
# Docker Composeは複数のDockerコンテナを一括管理するツール
# 単一のYAMLファイルでアプリケーションの全てのサービスを定義
# 開発環境での迅速なセットアップと一貫した動作環境を実現

# =============================================================================
# Compose ファイルバージョン指定
# =============================================================================
# version: Docker Composeファイルの書式バージョンを指定
# '3.8': Docker Engine 19.03.0+で対応、最新機能を活用可能
# 主な機能: external secrets、init、healthcheck、deploy等
# バージョンによって利用可能な機能が異なるため、環境に応じて選択
version: '3.8'

# =============================================================================
# サービス定義（アプリケーションを構成する各コンテナ）
# =============================================================================
# services: アプリケーションを構成する各サービス（コンテナ）を定義
# マイクロサービスアーキテクチャに対応し、各機能を独立したサービスとして管理
services:
  # ---------------------------------------------------------------------------
  # アプリケーションサービス（Goアプリケーション）
  # ---------------------------------------------------------------------------
  app:
    # =========================================================================
    # ビルド設定
    # =========================================================================
    # build: Dockerfileからイメージを構築
    # ".": カレントディレクトリ（docker-compose.ymlと同じディレクトリ）のDockerfileを使用
    # 実行時にDockerfileを元にしてイメージが自動ビルドされる
    build: .
    
    # =========================================================================
    # ポートマッピング設定
    # =========================================================================
    # ports: ホストとコンテナ間のポート接続を定義
    # 形式: "ホストポート:コンテナポート"
    ports:
      # HTTPサーバーポート: ブラウザ・クライアントからのアクセス用
      # 8080:8080 = ホストの8080番ポートをコンテナの8080番ポートに転送
      # アプリケーションへのHTTPリクエストアクセスポイント
      - "8080:8080"
      
      # Delveデバッガーポート: リモートデバッグ用通信ポート  
      # 2345:2345 = ホストの2345番ポートをコンテナの2345番ポートに転送
      # IDEからのデバッグ接続でブレークポイント設定・変数確認が可能
      - "2345:2345" # delveと通信するためのポート
    
    # =========================================================================
    # サービス依存関係設定
    # =========================================================================
    # depends_on: サービスの起動順序と依存関係を定義
    # アプリケーションはデータベースが完全に準備できてから起動する必要がある
    depends_on:
      mysql:
        # condition: 依存サービスの起動条件を指定
        # service_healthy: MySQLのヘルスチェックが成功してから app を起動
        # これによりデータベース接続エラーを防止
        condition: service_healthy
    
    # =========================================================================
    # 環境変数設定（アプリケーション設定）
    # =========================================================================
    # environment: コンテナ内で使用する環境変数を定義
    # アプリケーションの設定をコンテナ外部から制御可能
    # 設定変更時にコードの再ビルドが不要
    environment:
      # データベース接続設定
      - DB_HOST=mysql        # データベースサーバーのホスト名（サービス名を指定）
      - DB_PORT=3306         # MySQLのデフォルトポート番号
      - DB_USER=root         # データベースユーザー名
      - DB_PASSWORD=password # データベースパスワード（本番環境では秘匿化が必要）
      - DB_NAME=task_management # 使用するデータベース名
    
    # =========================================================================
    # ネットワーク設定
    # =========================================================================
    # networks: コンテナが参加するネットワークを指定
    # 同一ネットワーク内のコンテナ同士は通信可能
    # サービス名による名前解決が自動的に行われる
    networks:
      - app-network

  # ---------------------------------------------------------------------------
  # データベースサービス（MySQL）
  # ---------------------------------------------------------------------------
  mysql:
    # =========================================================================
    # イメージ指定
    # =========================================================================
    # image: Docker Hubから既存のイメージを使用
    # mysql:8.0 = MySQL 8.0の公式イメージ
    # 最新機能と安定性を両立した推奨バージョン
    image: mysql:8.0
    
    # =========================================================================
    # ポートマッピング設定
    # =========================================================================
    # データベース外部アクセス用ポート設定
    ports:
      # 3307:3306 = ホストの3307番ポートをコンテナの3306番ポート（MySQL標準）に転送
      # ホストの3306番ポートとの競合を避けるため3307番を使用
      # データベース管理ツール（phpMyAdmin、MySQL Workbench等）からの接続に使用
      - "3307:3306"
    
    # =========================================================================
    # MySQL環境変数設定
    # =========================================================================
    # MySQLコンテナの初期設定を環境変数で制御
    environment:
      # データベース管理者パスワード設定
      MYSQL_ROOT_PASSWORD: password        # rootユーザーのパスワード
      
      # アプリケーション用データベース設定
      MYSQL_DATABASE: task_management      # 自動作成されるデータベース名
      
      # 文字エンコーディング設定（日本語対応）
      MYSQL_CHARSET: utf8mb4              # UTF-8の4バイト拡張（絵文字対応）
      MYSQL_COLLATION: utf8mb4_unicode_ci # Unicode照合順序（多言語対応）
    
    # =========================================================================
    # ボリューム マウント設定（データ永続化）
    # =========================================================================
    # volumes: ホストとコンテナ間でファイル・ディレクトリを共有
    volumes:
      # データベースファイルの永続化
      # mysql_data:/var/lib/mysql = 名前付きボリュームでMySQLデータを永続保存
      # コンテナ削除後もデータが保持される
      - mysql_data:/var/lib/mysql
      
      # データベース初期化スクリプト
      # ./pkg/config/db:/docker-entrypoint-initdb.d = 初期化SQLファイルをマウント
      # コンテナ初回起動時に自動実行される（テーブル作成、初期データ投入等）
      - ./pkg/config/db:/docker-entrypoint-initdb.d
    
    # =========================================================================
    # ヘルスチェック設定（サービス可用性監視）
    # =========================================================================
    # healthcheck: コンテナの健全性を定期的に監視
    # depends_on の condition: service_healthy で使用される
    healthcheck:
      # test: 実行するヘルスチェックコマンド
      # mysqladmin ping: MySQLサーバーが応答可能かを確認
      test: ["CMD", "mysqladmin", "ping", "-h", "localhost"]
      
      # timeout: ヘルスチェックのタイムアウト時間
      # 20秒以内にレスポンスがない場合は失敗と判定
      timeout: 20s
      
      # retries: 失敗時のリトライ回数
      # 10回連続で失敗した場合にコンテナを異常と判定
      retries: 10
    
    # ネットワーク参加設定
    networks:
      - app-network

# =============================================================================
# ボリューム定義（データ永続化設定）
# =============================================================================
# volumes: 名前付きボリュームを定義
# Docker管理下でデータを永続的に保存するストレージ領域
volumes:
  # MySQLデータボリューム
  # mysql_data: MySQL のデータファイル（/var/lib/mysql）を永続保存
  # コンテナの停止・削除・再作成を行ってもデータが失われない
  # 開発中のデータベーススキーマ変更やテストデータが保持される
  mysql_data:

# =============================================================================
# ネットワーク定義（コンテナ間通信設定）
# =============================================================================
# networks: カスタムネットワークを定義
# サービス間の通信を制御し、外部からの不要なアクセスを防止
networks:
  # アプリケーション専用ネットワーク
  app-network:
    # driver: ネットワークドライバーの種類を指定
    # bridge: 同一Dockerホスト内でのコンテナ間通信を提供
    # 特徴:
    #   - サービス名による自動名前解決（app → mysql の通信が可能）
    #   - 外部ネットワークからの直接アクセスは不可（セキュリティ向上）
    #   - ポートマッピングにより必要な通信のみ外部公開
    driver: bridge