Contents
Docker 環境の準備と基本設定
Docker Desktop をローカルに導入すれば、CLI だけでコンテナ操作が可能になります。本セクションではインストール手順とバージョン確認方法、そしてマルチステージビルドと Compose による複数サービスの連携を行うための基本的なファイル構成を解説します。Docker の公式ツールは自動更新がデフォルトで有効なので、常に最新のエンジンで開発できる点が大きな利点です。
Docker Desktop のインストールとバージョン確認
- 公式ダウンロードページ(Docker Desktop ダウンロード – docker.com)から OS に合わせたインストーラを取得し、画面の指示に従ってインストールします。
- インストール完了後、ターミナルで以下コマンドを実行し、クライアントとサーバー(Docker Engine)のバージョンが表示されることを確認してください。
|
1 2 3 |
docker version # Client と Server のバージョン情報 docker compose version # Docker Compose が同梱されているか確認 |
ポイント
Docker Desktop は自動更新機能が標準で有効です。Settings → General → Automatically check for updatesをオンにしておくと、手動操作なしで新バージョンが適用されます。
マルチステージ Dockerfile と Compose の基本構成
マルチステージビルドは開発時の依存関係を分離し、最終イメージを軽量化します。Compose はサービス間のネットワークやボリュームをコードで管理できるため、本番・ローカルどちらでも同一設定が再利用可能です。
Dockerfile(Node.js アプリの例)
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 |
# ---------- ビルドステージ ---------- FROM node:20-alpine AS builder WORKDIR /app COPY package*.json ./ RUN npm ci COPY . . RUN npm run build # dist ディレクトリに成果物を出力 # ---------- ランタイムステージ ---------- FROM node:20-alpine AS runtime WORKDIR /app ENV NODE_ENV=production COPY --from=builder /app/dist ./dist COPY package*.json ./ RUN npm ci --only=production CMD ["node", "dist/index.js"] |
- ビルドに必要なツールは
builderステージだけに限定し、最終イメージには実行に最低限必要なファイルのみをコピーします。
docker‑compose.yml(Web + PostgreSQL)
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 |
version: "3.9" services: web: build: . ports: - "8080:8080" environment: DATABASE_URL: postgres://user:password@db:5432/appdb depends_on: - db db: image: postgres:15-alpine restart: unless-stopped volumes: - pg_data:/var/lib/postgresql/data environment: POSTGRES_USER: user POSTGRES_PASSWORD: password POSTGRES_DB: appdb volumes: pg_data: |
depends_onによりwebコンテナはデータベースが起動してから開始します。環境変数で接続情報を注入することで、コード側に設定を書き込む必要がなくなります。
ローカルでのビルド・テストとイメージ管理
ローカルで作成したイメージはマルチプラットフォーム対応かつテスト済みであることを確認してからレジストリへプッシュします。このセクションでは buildx を用いた ARM64/x86 両方へのビルド、コンテナ内部での単体テスト実行方法、そして Docker Hub と Amazon ECR への安全なプッシュ手順を示します。
マルチプラットフォームイメージの作成とタグ付け
docker buildx は追加インストール不要で利用できます。初回はビルダーを作成し、その後にプラットフォーム指定でビルド・プッシュを行います。
|
1 2 3 4 5 6 7 8 9 |
# 初回のみ実行:マルチアーキテクチャ用ビルダー作成 docker buildx create --use --name multiarch # ビルド&レジストリへの同時プッシュ例 docker buildx build \ --platform linux/amd64,linux/arm64 \ -t yourrepo/app:${GIT_TAG:-latest} \ --push . |
コンテナ内部でのユニットテスト実行
ビルドしたイメージを一時コンテナとして起動し、pytest(または任意のテストフレームワーク)を走らせます。テストが成功した場合のみ次工程へ進めるようスクリプトで判定すると CI の信頼性が向上します。
|
1 2 |
docker run --rm yourrepo/app:${GIT_TAG:-latest} pytest tests/ |
Docker Hub と Amazon ECR へのプッシュ手順
| 手順 | Docker Hub | Amazon ECR |
|---|---|---|
| 認証 | docker login(ユーザー名・パスワード) |
aws ecr get-login-password --region <region> \| docker login --username AWS --password-stdin <account>.dkr.ecr.<region>.amazonaws.com |
| リポジトリ作成 | Web UI で手動作成 | aws ecr create-repository --repository-name app --image-scanning-configuration scanOnPush=true |
| プッシュ | docker push yourrepo/app:${TAG} |
docker push <account>.dkr.ecr.<region>.amazonaws.com/app:${TAG} |
ベストプラクティス
- タグは Semantic Versioning(例:v1.2.3)と Git SHA の二重付与を推奨。latestは自動デプロイ専用に限定します。
- ECR では画像スキャンが標準で有効になるため、脆弱性検出も同時に実施できます。
GitHub Actions による CI パイプライン構築
GitHub Actions を利用すればコードのプッシュごとに自動ビルド・テスト・セキュリティスキャン・レジストリ登録までを一貫して実行できます。本節では主要なジョブ設計と、シークレット管理のポイントを具体的に示します。
ワークフロー全体像
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 |
name: CI / CD on: push: branches: [ main ] pull_request: jobs: build-test-deploy: runs-on: ubuntu-latest permissions: contents: read packages: write # Docker Hub/ECR のプッシュに必要 steps: - name: Checkout repository uses: actions/checkout@v4 - name: Set up Docker Buildx uses: docker/setup-buildx-action@v3 - name: Log in to Docker Hub uses: docker/login-action@v3 with: username: ${{ secrets.DOCKERHUB_USER }} password: ${{ secrets.DOCKERHUB_TOKEN }} - name: Build and push image uses: docker/build-push-action@v5 with: context: . platforms: linux/amd64,linux/arm64 tags: | yourrepo/app:${{ github.sha }} yourrepo/app:${{ env.SEMVER }} push: true - name: Run container tests run: | docker run --rm yourrepo/app:${{ github.sha }} pytest tests/ - name: Security scan with Trivy uses: aquasecurity/trivy-action@v0.12 with: image-ref: yourrepo/app:${{ github.sha }} format: table exit-code: '1' # 脆弱性が検出されたらジョブ失敗 - name: Deploy to production (conditional) if: success() && github.ref == 'refs/heads/main' run: | ./scripts/deploy.sh ${{ github.sha }} |
docker/build-push-action@v5は公式が推奨する最新版で、マルチプラットフォームとキャッシュ最適化を自動的に行います。- 詳細は Docker の公式ドキュメント[^docker-buildx] と GitHub Actions のリファレンス[^github-actions] を参照してください。
シークレット管理のベストプラクティス
| 種類 | 保存先 | 用途 |
|---|---|---|
| Docker Hub 認証情報 | GitHub Secrets(DOCKERHUB_USER, DOCKERHUB_TOKEN) |
イメージプッシュ |
| AWS クレデンシャル | GitHub Secrets と AWS Parameter Store(暗号化保存) | ECR へのログイン、ECS デプロイ |
- GitHub のリポジトリ設定画面で
Settings → Secretsに上記項目を登録します。 - 長期的に使用する AWS 認証情報は Parameter Store に
SecureStringとして保存し、aws-actions/amazon-ssm-getparameters@v2で取得します。
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 |
- name: Retrieve ECR credentials from Parameter Store id: ssm uses: aws-actions/amazon-ssm-getparameters@v2 with: names: | /myapp/ecr/username /myapp/ecr/password region: us-east-1 - name: Login to Amazon ECR uses: docker/login-action@v3 with: registry: ${{ steps.ssm.outputs['/myapp/ecr/username'] }}.dkr.ecr.us-east-1.amazonaws.com username: ${{ steps.ssm.outputs['/myapp/ecr/username'] }} password: ${{ steps.ssm.outputs['/myapp/ecr/password'] }} |
本番環境への自動デプロイ比較
オンプレミス向けの Docker Swarm と、マネージドサービスである Amazon ECS/Fargate の両方に対応したデプロイ手順を示します。どちらも GitHub Actions から同一イメージをプッシュできる点が共通していますが、運用コストやスケーラビリティの観点で特徴が異なります。
Docker Swarm への SSH デプロイ
Swarm は Docker Engine に統合されたオーケストレーション機能です。SSH エージェント転送と docker stack deploy コマンドだけでサービス更新が可能です。
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 |
- name: Deploy to Docker Swarm if: github.ref == 'refs/heads/main' env: SSH_PRIVATE_KEY: ${{ secrets.SWARM_SSH_KEY }} DOCKERHUB_TOKEN: ${{ secrets.DOCKERHUB_TOKEN }} run: | mkdir -p ~/.ssh echo "$SSH_PRIVATE_KEY" > ~/.ssh/id_rsa chmod 600 ~/.ssh/id_rsa ssh-agent bash -c 'ssh-add ~/.ssh/id_rsa; \ ssh -o StrictHostKeyChecking=no user@swarm-manager "\ docker login -u ${{ secrets.DOCKERHUB_USER }} -p $DOCKERHUB_TOKEN && \ docker stack deploy -c ./deploy/stack.yml myapp"' |
stack.ymlはローカルのdocker-compose.ymlと同等の構成で、イメージタグは${{ github.sha }}を使用します。- 公式ドキュメント[^docker-swarm] に詳細な手順が掲載されています。
Amazon ECS/Fargate へのデプロイ
Fargate はサーバーレス型コンテナ実行基盤です。タスク定義の登録とサービス更新だけで新バージョンへ切り替えられます。
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 |
- name: Register ECS task definition id: register-task run: | IMAGE_URI="${{ secrets.AWS_ECR_ACCOUNT }}.dkr.ecr.${{ env.AWS_REGION }}.amazonaws.com/app:${{ github.sha }}" jq --arg img "$IMAGE_URI" '.containerDefinitions[0].image = $img' ecs-task-template.json > task-def.json aws ecs register-task-definition --cli-input-json file://task-def.json - name: Update ECS service run: | TASK_ARN=$(aws ecs describe-task-definition --family myapp | jq -r .taskDefinition.taskDefinitionArn) aws ecs update-service \ --cluster my-cluster \ --service my-service \ --task-definition $TASK_ARN \ --force-new-deployment |
ecs-task-template.jsonには Fargate 必要項目(cpu,memory,networkMode: awsvpc等)を記述しておきます。- AWS の公式リファレンス[^aws-ecs] が手順の根拠となります。
ロールバック戦略
| 手法 | Swarm での実装例 | ECS/Fargate での実装例 |
|---|---|---|
| タグベースロールバック | docker stack deploy -c stack.yml myapp --with-registry-auth(image: yourrepo/app:v1.2.3 に差し替え) |
aws ecs update-service … --task-definition taskdef-v1.2.3 |
| CI での自動復旧 | ビルド失敗時に前回成功 SHA を取得し再デプロイ | 同様に if: failure() 条件で直近タグを使用 |
推奨:すべてのイメージに Semantic Version と Git SHA の二重タグ付与を行い、ロールバック時は人が読めるバージョン(例 v1.2.3)で指定すると管理が楽になります。
運用・トラブルシューティング
デプロイ後の安定運用にはコンテナのヘルスチェックとログの可視化が不可欠です。ここでは Dockerfile への HEALTHCHECK 追加例、各プラットフォーム向けのログドライバ設定、そしてビルド失敗や起動エラー時のデバッグ手順をまとめます。
ヘルスチェックとログ収集
|
1 2 3 4 |
# Dockerfile の末尾に追記 HEALTHCHECK --interval=30s --timeout=5s \ CMD curl -f http://localhost:8080/health || exit 1 |
- アプリが
/healthエンドポイントで 200 を返さないとコンテナはunhealthyとマークされます。
Swarm のログドライバ(例:CloudWatch)
|
1 2 3 4 5 6 7 8 9 10 |
services: web: image: yourrepo/app:${TAG} logging: driver: "awslogs" options: aws-region: us-east-1 aws-log-group: /ecs/myapp/web aws-create-group: "true" |
ECS/Fargate の CloudWatch 設定(タスク定義)
|
1 2 3 4 5 6 7 8 9 |
"logConfiguration": { "logDriver": "awslogs", "options": { "awslogs-group": "/ecs/myapp", "awslogs-region": "us-east-1", "awslogs-stream-prefix": "web" } } |
- 収集したログは Grafana + Loki、あるいは CloudWatch ダッシュボードで可視化し、
ERRORキーワードやunhealthy状態をアラートに紐付けます。
ビルド失敗時のデバッグ手順
- 詳細ログ取得
GitHub Actions のdocker/build-push-action@v5にdebug: trueを設定し、ビルドコマンド全体を記録します。 - アーティファクト化
失敗したステップの標準エラー出力をactions/upload-artifactで保存すると、ローカルでも同様に再現可能です。
|
1 2 3 4 5 6 7 8 9 |
- name: Build and push (debug) uses: docker/build-push-action@v5 with: context: . platforms: linux/amd64,linux/arm64 tags: yourrepo/app:${{ github.sha }} push: false debug: true |
- ローカルでの再現
docker buildx bake --printを実行し、GitHub Actions が内部的に呼び出すコマンドを確認します。
コンテナ起動エラー時の対処法
|
1 2 3 4 5 6 7 8 9 |
# 失敗したコンテナ一覧取得 docker ps -a --filter "status=exited" # 詳細ログ表示 docker logs <container_id> # 必要に応じて環境変数やポート設定を上書き docker compose -f docker-compose.yml -f docker-compose.override.yml up --build |
- よくある落とし穴
- 環境変数未定義 →
docker compose configで最終的な設定を確認。 - ポート競合 →
docker psで既存コンテナのポート使用状況をチェック。
まとめ
- Docker 環境:公式サイトから Docker Desktop をインストールし、マルチステージ Dockerfile と Compose によるマルチコンテナ構成を作成すれば、ローカル開発がすぐに始められます。
- ローカルビルド・テスト:
buildxで ARM64/x86 両方のイメージを生成し、コンテナ内部テストと Semantic Version タグ付与を行った上で Docker Hub または Amazon ECR に安全にプッシュします。 - CI パイプライン:GitHub Actions の公式アクションだけでコードチェックアウト、Docker 設定、マルチプラットフォームビルド・プッシュ、テスト、Trivy スキャン、条件付きデプロイを自動化できます。シークレットは GitHub Secrets と Parameter Store で一元管理します。
- 本番デプロイ比較:オンプレミス向けは SSH +
docker stack deploy(Swarm)、サーバーレス環境はタスク定義登録とaws ecs update-service(ECS/Fargate)を用います。どちらもタグベースのロールバックが可能です。 - 運用・トラブルシューティング:Dockerfile に
HEALTHCHECKを組み込み、CloudWatch または Loki へログ転送し Grafana で可視化します。ビルド失敗は詳細デバッグ情報のアーティファクト化、起動エラーはdocker logsと Compose 設定見直しで迅速に解決できます。
上記手順をそのままリポジトリに組み込めば、Docker を利用した開発・テスト・本番デプロイの全工程が自動化され、信頼性と生産性が大幅に向上します。ぜひ実践してみてください。
参考文献
[^docker-desktop]: Docker Desktop ダウンロードページ – https://www.docker.com/products/docker-desktop
[^docker-buildx]: Docker Buildx ドキュメント – https://docs.docker.com/build/buildx/
[^github-actions]: GitHub Actions リファレンス – https://docs.github.com/actions
[^docker-swarm]: Docker Swarm 公式ガイド – https://docs.docker.com/engine/swarm/
[^aws-ecs]: Amazon ECS / Fargate ドキュメント – https://docs.aws.amazon.com/ecs/latest/developerguide/what-is-amazon-ecs.html