メインコンテンツまでスキップ

第30章：スターターキット化（テンプレ化）＆次の一歩🚀🎁

ここまでで「一発起動スタック」は完成してるので、この章は “次の新規PJでも秒速で同じ環境を作れる状態” に仕上げます 💪✨ つまり コピペ → 1コマンド → 開発開始 までを、迷いゼロにする章です 😺🧰

1) スターターキット化って、結局なにを“固定”するの？🧩​

スターターキット化の本体はこの3つです👇

  • 起動の手順を固定（READMEを見れば迷わない）📘
  • 設定の置き場所を固定（.envのルール、どこに何を書くか）🔑
  • ファイル構成を固定（次回のコピペが“事故らない”）📁

しかも Compose は今どき Compose Specification が前提で、compose.yaml中心・version:は実質不要（警告の原因にもなりがち）なので、テンプレもその形に揃えます 🐳✨ (Docker Documentation)

2) 最終テンプレのフォルダ構成（これを“型”にする）📦​

まずは完成形の「置き場所」を固定しちゃいましょう👇

my-starter/
├─ compose.yaml
├─ .env.example
├─ .gitignore
├─ .dockerignore
├─ README.md
├─ package.json
├─ apps/
│  ├─ api/        (Node/TS API)
│  └─ worker/     (Queue Worker)
└─ docker/
   ├─ api.Dockerfile
   └─ worker.Dockerfile

ポイントは「テンプレとして持ち運びやすい最小セット」にすることです ✨ （増やすのはいつでもできるけど、減らすのは面倒…！😇）

3) compose.yaml を“テンプレ向け”に整えるコツ 🛠️✨​

コツA：x-（Extensions）で“共通部分”を1か所にまとめる 🧷​

Compose は x- で始まる拡張ブロックを作れて、YAMLアンカーで使い回せます。テンプレ化と相性が最高です 😍 (Docker Documentation)

コツB：profilesで「普段はいらないサービス」を隠す 🎛️​

DB管理UIなどは毎回いらないので、必要なときだけ起動できるようにします 👍 (Docker Documentation)

コツC：Watchで「保存したら反映」をテンプレに埋め込む 👀⚡​

Compose Watch は Compose 2.22.0+ で使えて、develop: watch:で同期/再起動/リビルドまで制御できます 🔥 (Docker Documentation)

4) そのまま使える compose.yaml テンプレ（API + Worker + Postgres + Redis）🐘🟥🚚​

## compose.yaml（Compose Specification前提）
## 目標：コピペしてすぐ "docker compose up" できるスターターにする

x-common-env: &common-env
  TZ: Asia/Tokyo
  # アプリ側が参照する想定（例）
  DATABASE_URL: postgres://${POSTGRES_USER}:${POSTGRES_PASSWORD}@db:5432/${POSTGRES_DB}
  REDIS_URL: redis://redis:6379

x-common-depends: &common-depends
  db:
    condition: service_healthy
  redis:
    condition: service_started

services:
  db:
    image: postgres:16
    environment:
      POSTGRES_USER: ${POSTGRES_USER}
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
      POSTGRES_DB: ${POSTGRES_DB}
    ports:
      - "${POSTGRES_PORT}:5432"
    volumes:
      - pgdata:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER} -d ${POSTGRES_DB}"]
      interval: 5s
      timeout: 3s
      retries: 20

  redis:
    image: redis:7
    ports:
      - "${REDIS_PORT}:6379"

  api:
    build:
      context: .
      dockerfile: docker/api.Dockerfile
    environment:
      <<: *common-env
      NODE_ENV: development
      PORT: 3000
    ports:
      - "${API_PORT}:3000"
    depends_on:
      <<: *common-depends

    # ✅ Compose Watch：保存したら同期（node_modulesは同期しない）
    develop:
      watch:
        - action: sync
          path: ./apps/api/src
          target: /app/apps/api/src
          ignore:
            - node_modules/
        - action: rebuild
          path: ./apps/api/package.json

  worker:
    build:
      context: .
      dockerfile: docker/worker.Dockerfile
    environment:
      <<: *common-env
      NODE_ENV: development
    depends_on:
      <<: *common-depends

    develop:
      watch:
        - action: sync
          path: ./apps/worker/src
          target: /app/apps/worker/src
          ignore:
            - node_modules/
        - action: rebuild
          path: ./apps/worker/package.json

  # 🔧 便利だけど普段は不要：必要なときだけ起動（profiles）
  pgadmin:
    image: dpage/pgadmin4:latest
    profiles: ["tools"]
    environment:
      PGADMIN_DEFAULT_EMAIL: ${PGADMIN_EMAIL}
      PGADMIN_DEFAULT_PASSWORD: ${PGADMIN_PASSWORD}
    ports:
      - "${PGADMIN_PORT}:80"
    depends_on:
      db:
        condition: service_healthy

volumes:
  pgdata:
  • Watch は docker compose up --watch で動きます（または docker compose watch）👀✨ (Docker Documentation)
  • x-拡張とアンカーでテンプレがスッキリします 🧷 (Docker Documentation)
  • profiles で pgadmin を “普段は隠す” ができます 🎛️ (Docker Documentation)

5) .env.example（この形を固定すると事故が減る）🔑📦​

## .env.example（コピーして .env にする）
POSTGRES_USER=app
POSTGRES_PASSWORD=app
POSTGRES_DB=app
POSTGRES_PORT=5432

REDIS_PORT=6379
API_PORT=3000

## tools profile 用
PGADMIN_EMAIL=admin@example.com
PGADMIN_PASSWORD=admin
PGADMIN_PORT=5050

ちょい大事な話：環境変数は“上書き優先順位”がある ⚠️​

Compose は同じ変数が複数箇所にあると優先順位で決めます（CLI -e が一番強い、など）🔁 テンプレでは「.envは基本値、必要なら上書き」の運用がラクです 🙂 (Docker Documentation)

6) Dockerfile（テンプレは“薄くてOK”）🧱​

docker/api.Dockerfile​

FROM node:24-slim AS base
WORKDIR /app

## 依存だけ先に入れる（キャッシュ効かせる）
COPY apps/api/package*.json ./apps/api/
RUN cd apps/api && npm ci

## ソース
COPY apps/api ./apps/api

WORKDIR /app/apps/api
CMD ["npm", "run", "dev"]

docker/worker.Dockerfile​

FROM node:24-slim AS base
WORKDIR /app

COPY apps/worker/package*.json ./apps/worker/
RUN cd apps/worker && npm ci

COPY apps/worker ./apps/worker

WORKDIR /app/apps/worker
CMD ["npm", "run", "dev"]

Node は v24 が Active LTS（2026年2月時点）なので、テンプレは “LTS寄せ” にしておくと安心です 🛡️ (Node.js)

7) “1コマンド文化”を README と npm scripts に埋め込む 🧰✨​

テンプレの強さは「操作が短い」ことです。コマンドを固定しましょう 😺

package.json（ルート）​

{
  "name": "my-starter",
  "private": true,
  "scripts": {
    "up": "docker compose up -d --build",
    "watch": "docker compose up --watch",
    "down": "docker compose down",
    "logs": "docker compose logs -f --tail=200",
    "ps": "docker compose ps",
    "tools:up": "docker compose --profile tools up -d",
    "tools:down": "docker compose --profile tools down"
  }
}

README.md に書く“最低限の儀式”📘​

  • cp .env.example .env
  • npm run up（または npm run watch）
  • 困ったら npm run logs

これだけにすると、テンプレとして超つよいです 💪🔥

8) もっと“テンプレ向け”にしたい人へ：include: で分割する（任意）🧩✨​

Compose には include: があって、別ファイルを取り込めます。Docker Compose 2.20.0+ が必要です ✅ (Docker Documentation)

たとえば…

  • compose.yaml（本体）
  • docker/compose.tools.yaml（pgAdminなど）
  • docker/compose.dev.yaml（watchや開発専用）

みたいに分けると、「テンプレなのに巨大」問題が減ります 😍

9) 次の一歩：「本番は別物」の入口だけ触る 🚪🌍​

ここは深入りしないけど、方向性だけ押さえると強いです 👍

  • 本番は bind mount / watch を基本しない（成果物イメージで動かす）
  • 秘密情報はイメージに焼かない（.env運用から“秘密管理”へ）🔐
  • 入口（TLS/リバプロ）やログ/監視が主役になってくる 👀📈

「開発は“早さ”、本番は“安定と安全”」って感じで、設計の軸が変わります 😺✨

10) 最終チェックリスト（テンプレ合格ライン）✅🎉​

  • 新規フォルダにコピペして、.env作って npm run up で起動できる
  • npm run down で止められる（戻せる）
  • npm run logs で原因追跡できる
  • tools:up みたいに “普段いらない物”が分離されてる
  • 設定が散ってなくて、迷子にならない（.env中心）

おまけ：テンプレ作りを爆速に始める裏技 🧪⚡​

既存プロジェクトなら docker init で Dockerfile / compose.yaml / .dockerignore などの叩き台を自動生成できます 🪄 「ゼロから書くのダルい…」を最短で抜けられます 😆 (Docker Documentation)

ここまでできたら、もうあなたのComposeは “作品”じゃなくて“武器” です 🗡️😺✨ 次は「速度（キャッシュ）」「データ運用」「開発体験の強化」のどれに進んでも、全部つながりますよ 🚀