Docker（1/2）

compose・起動・日常コマンド。

ローカル開発環境 (Docker前提)

主旨

全開発者で環境を揃える: 「自分のPCでは動く」を排除
ホストOSを汚さない: 言語ランタイム・DBをホストにインストールしない
オンボーディング高速化: git clone → make up → 動く、を目標に
AIエージェントへの指示統一: 実行コマンドは常に docker compose exec 経由で提示させる

ファイル構成と役割

ファイル	役割	コミット
`docker/app/Dockerfile`	本番用イメージ (マルチステージ、最小化)	する
`docker/app/Dockerfile.dev`	開発用イメージ (hot-reload、デバッガ、ツール込み)	する
`docker-compose.yml`	開発環境のサービス構成 (app + db + redis 等)	する
`docker-compose.override.yml.example`	個人カスタマイズの雛形	する
`docker-compose.override.yml`	個人カスタマイズ実体 (ポート変更等)	しない
`Makefile`	コマンド集約 (up/down/test/lint/migrate)	する
`.env.example`	環境変数テンプレート	する
`.env`	環境変数実体	しない

`docker-compose.yml` 雛形 (Python/FastAPI例)

services:
  app:
    build:
      context: .
      dockerfile: docker/app/Dockerfile.dev
    volumes:
      - .:/workspace:cached
      - python-cache:/root/.cache
    working_dir: /workspace
    env_file: .env
    ports:
      - "8000:8000"
    depends_on:
      db:
        condition: service_healthy
    command: uvicorn src.interface.main:app --reload --host 0.0.0.0

  db:
    image: postgres:16-alpine
    environment:
      POSTGRES_DB: app_dev
      POSTGRES_USER: app
      POSTGRES_PASSWORD: app
    volumes:
      - postgres-data:/var/lib/postgresql/data
      - ./docker/db/init.sql:/docker-entrypoint-initdb.d/init.sql:ro
    ports:
      - "5432:5432"
    healthcheck:
      test: ["CMD", "pg_isready", "-U", "app"]
      interval: 5s
      timeout: 5s
      retries: 5

  redis:
    image: redis:7-alpine
    ports:
      - "6379:6379"
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 5s

volumes:
  postgres-data:
  python-cache:

`Makefile` 雛形

.PHONY: help up down restart logs sh test lint fmt migrate migrate-rollback shell-db clean

help:
    @grep -E '^[a-zA-Z_-]+:.*?## ' $(MAKEFILE_LIST) | awk 'BEGIN {FS=":.*?## "}; {printf "  %-20s %s
", $$1, $$2}'

up:           ## 開発環境起動
    docker compose up -d

down:         ## 開発環境停止
    docker compose down

restart:      ## 再起動
    docker compose restart app

logs:         ## アプリログ追尾
    docker compose logs -f app

sh:           ## アプリコンテナに入る
    docker compose exec app bash

test:         ## テスト実行
    docker compose exec app pytest -v --cov=src

lint:         ## Lint
    docker compose exec app ruff check . && docker compose exec app mypy src

fmt:          ## Format
    docker compose exec app ruff format .

migrate:      ## DBマイグレーション (forward)
    docker compose exec app alembic upgrade head

migrate-rollback: ## DBマイグレーション (rollback 1段)
    docker compose exec app alembic downgrade -1

shell-db:     ## DBに接続
    docker compose exec db psql -U app -d app_dev

clean:        ## ボリュームごと削除 (注意)
    docker compose down -v

言語が Go なら make test を docker compose exec app go test ./... に、Next.js なら docker compose exec app pnpm test に置換する。

ホストOSに言語ランタイム・DB・キャッシュを直接インストールせず、全コマンドをコンテナ内で実行する原則を定める。AIエージェントへの指示（コマンド提示は必ず docker compose exec 経由）、新規依存追加時のフロー、環境変数（.env.example の同時更新）、IDE統合（Dev Containers 推奨、テスト/ビルド/マイグレーションはコンテナ内必須）をカバーする。

コピー用全文: 70-local-env.mdc サンプル

README.md に書くべき起動手順 (3行ルール)

## 起動方法

```bash
cp .env.example .env       # 必要なら値を編集
make up                     # アプリ + DB + Redis を起動
make migrate                # 初回のみ
```

API: http://localhost:8000 (健康確認: /healthz)

詳細は make help を参照。

NOTE: 「3行で動く」を維持するため、初期化処理 (シードデータ等) は make up 後に1コマンドで完結させる。複雑になるなら make seed を別途用意する。

ホスト CLI — エージェントと自分の時短定番

エージェントはシェル経由で PR 作成・デプロイ・ログ確認を試みる。CLI 未インストール / 未ログインだと認証プロンプトで止まり、人間の手戻りが増える。利用中のクラウドサービス CLI はホストに入れ、認証済みの状態を Day1 目標にする。

ホスト vs コンテナ: ホストで gh・vercel・aws・docker compose・supabase。アプリ実行・テストは 11.3 Docker どおり docker compose exec 経由（例: MinIO の mc はコンテナ内）。

" aria-label="前後の章">← 運用ルール / Skills →" aria-label="前後の章">← 提出運用 →

AI利用開発フロー