ローカル開発環境 — Tilt + Colima によるマイクロサービス構築¶

対象フェーズ: 開発（PoC / Closed Beta / Open Beta / GA 準備）すべて 作成日: 2026-04-20 最終更新: 2026-04-20 ステータス: 承認待ち 前提ドキュメント: デプロイメント戦略 / 環境抽象化 & Feature Flag / マイクロサービス一覧

1. エグゼクティブサマリー¶

Recerdo は 9 個のマイクロサービス（auth / audit / album / events / timeline / storage / notifications / feature-flag / admin-console）と複数のミドルウェア（MySQL / Redis / Garage / Postfix / Flipt / Loki 等）で構成される。これらを開発者のマシン上で 本番と同等のトポロジ で起動し、かつ 保存即反映（live reload） できる環境を提供する。

原則: ローカル環境用に 新しい実装を作らない。環境抽象化 の Adapter と環境変数だけで Beta 相当を再現し、本番切替時の乖離をゼロにする。

2. 背景と目的¶

2.1 なぜ Docker Compose 単体では不足か¶

既存設計書（例: server-capacity-planning.md、firewall-data-protection.md）で Beta は Docker Compose で運用する方針を示しているが、開発者マシンでは以下の追加要件がある：

• 編集 → 実行 のフィードバックループを数秒に収めたい（docker compose up --build は毎回イメージを再生成する）
• 9 サービスの 起動順序 と ヘルスチェック を宣言的に扱いたい（depends_on だけでは不足）
• サービスごとのログ・ビルド状況・ポートを 一元ダッシュボード で確認したい
• ローカル k3s へ同じ定義で昇格できるようにし、将来の OKE 移行に備えたい

Tilt はこれらを同一 Tiltfile で表現でき、docker-compose.yml を "ソース" として読み込む互換モードも備えるため、既存資産を壊さずに導入できる。

2.2 なぜ Colima を採用候補に入れるか¶

Colima は Docker CLI / Docker Compose / Docker Engine API を互換提供するため、DOCKER_HOST を向けるだけで既存ワークフローを維持できる。Recerdo の AWS 利用は Cognito のみ・ストレージは Garage・キューは Redis と、いずれもロックインのない OSS に統一されているため、コンテナランタイムも OSS に統一 することでポリシー全体と整合する。

2.3 将来性の担保（ランタイム可搬性）¶

ポリシー §4.1（policy.md）の「単一コードベース」と同じ考え方を開発環境にも適用する。特定のコンテナランタイム（Docker Desktop）に依存した手順書を書かず、DOCKER_HOST と CONTAINER_RUNTIME の 環境変数 2 つ で差し替え可能な構成にする。

flowchart LR
  Dev["開発者マシン (macOS / Linux / WSL2)"]
  subgraph Runtimes["コンテナランタイム (差し替え可能)"]
    Colima["Colima (第一推奨・OSS)"]
    Docker["Docker Desktop (個人利用)"]
    Orb["OrbStack (補助)"]
    Rancher["Rancher Desktop (k8s 実験)"]
  end
  Tilt["Tilt (宣言的オーケストレーション)"]
  Stack["Beta 相当スタック<br/>MySQL / Redis / Garage / Flipt / Postfix / 9 マイクロサービス"]

  Dev -->|DOCKER_HOST 設定| Runtimes
  Runtimes -->|Docker Engine API| Tilt
  Tilt -->|live_update / k8s_yaml| Stack

3. ローカル開発スタック構成¶

3.1 起動対象サービス¶

3.2 全体トポロジ¶

flowchart TB
  subgraph Dev["開発者マシン"]
    IDE["VS Code / JetBrains"]
    CLI["tilt CLI"]
  end

  subgraph Runtime["Colima (Lima VM) / Docker Desktop"]
    subgraph Net["Docker Network: recerdo-dev"]
      GW["Traefik (Gateway)"]
      subgraph SVC["マイクロサービス群"]
        Auth["auth-svc :8001"]
        Album["album-svc :8003"]
        Events["events-svc :8004"]
        Timeline["timeline-svc :8005"]
        Storage["storage-svc :8006"]
        Notif["notifications-svc :8007"]
        Audit["audit-svc :8002"]
        FF["feature-flag-svc :8008"]
        Admin["admin-console-svc :8009"]
      end
      subgraph Infra["Beta 相当ミドルウェア"]
        MySQL["MySQL 8.0 :3306"]
        MariaDB["MariaDB 10.11 :3307"]
        Redis["Redis :6379"]
        Garage["Garage (S3 互換) :3900"]
        Flipt["Flipt :8090"]
        Postfix["Postfix+Dovecot+Rspamd :25/587"]
        MailHog["MailHog :8025"]
        CognitoLocal["cognito-local :9229"]
        FCMEmu["fcm-emulator :5005"]
        Loki["Loki :3100"]
        Grafana["Grafana :3001"]
      end
    end
  end

  IDE -->|保存| CLI
  CLI -->|live_update| SVC
  CLI -->|compose/ k8s_yaml| Infra
  GW --> Auth & Album & Events & Timeline & Storage & Notif & Admin
  SVC -->|MariaDB 互換 SQL| MySQL & MariaDB
  SVC -->|enqueue| Redis
  Storage -- S3 API --> Garage
  Album -- S3 API --> Garage
  Notif -- SMTP 587 STARTTLS --> Postfix
  Postfix --> MailHog
  Notif --> FCMEmu
  Auth -.JWKS.-> CognitoLocal
  SVC -->|EvaluateFlag| FF
  FF --> Flipt
  SVC -.logs.-> Loki
  Loki --> Grafana

4. Tilt 採用根拠と使いどころ¶

4.1 Tilt が解く問題¶

4.2 Tiltfile 構成方針¶

リポジトリルートに単一の Tiltfile を置き、以下のモードを切替可能にする：

• TILT_TARGET=compose（既定）: Docker Compose ベース起動（Beta と同じ）
• TILT_TARGET=k3s: Colima 同梱 k3s にデプロイ（将来の OKE 移行リハーサル）

# Tiltfile (抜粋) — アプリケーション本体リポジトリ (recerdo-infra など) に配置される想定
load('ext://restart_process', 'docker_build_with_restart')

target = os.environ.get('TILT_TARGET', 'compose')
# §4.3 で定義する 5 プロファイル (full / core / media / notify / admin)
profile = os.environ.get('TILT_PROFILE', 'full')

# 1) 共通ミドルウェアは compose から読み込み
docker_compose('./deploy/dev/docker-compose.infra.yml')

# 2) アプリは Go サービスごとに個別ビルド + live_update
# 4 要素目: そのサービスの依存先 (resource_deps に渡す他サービス名)
services = [
    ('feature-flag-svc',  8008, './services/feature-flag-svc',  []),
    ('auth-svc',          8001, './services/auth-svc',          ['feature-flag-svc']),
    ('audit-svc',         8002, './services/audit-svc',         ['feature-flag-svc']),
    ('album-svc',         8003, './services/album-svc',         ['auth-svc', 'feature-flag-svc']),
    ('events-svc',        8004, './services/events-svc',        ['auth-svc', 'feature-flag-svc']),
    ('timeline-svc',      8005, './services/timeline-svc',      ['auth-svc', 'feature-flag-svc']),
    ('storage-svc',       8006, './services/storage-svc',       ['auth-svc', 'feature-flag-svc']),
    ('notifications-svc', 8007, './services/notifications-svc', ['auth-svc', 'feature-flag-svc']),
    ('admin-console-svc', 8009, './services/admin-console-svc', ['auth-svc', 'feature-flag-svc']),
]

# プロファイルごとに含めるサービスを選択
profile_members = {
    'full':   {s[0] for s in services},
    'core':   {'auth-svc', 'audit-svc', 'feature-flag-svc'},
    'media':  {'storage-svc', 'album-svc', 'feature-flag-svc', 'auth-svc'},
    'notify': {'notifications-svc', 'feature-flag-svc', 'auth-svc'},
    'admin':  {'admin-console-svc', 'feature-flag-svc', 'auth-svc'},
}
enabled = profile_members[profile]

for name, port, path, deps in services:
    if name not in enabled:
        continue
    docker_build_with_restart(
        ref='recerdo/' + name + ':dev',
        context=path,
        dockerfile=path + '/Dockerfile.dev',
        entrypoint=['/app/bin/' + name],
        live_update=[
            sync(path + '/cmd',       '/app/cmd'),
            sync(path + '/internal',  '/app/internal'),
            sync(path + '/go.sum',    '/app/go.sum'),
            run('cd /app && go build -o /app/bin/' + name + ' ./cmd/' + name,
                trigger=[path + '/cmd', path + '/internal']),
        ],
    )
    # 起動順序 (Feature Flag → auth/audit → 他) は resource_deps で明示
    active_deps = [d for d in deps if d in enabled]
    if target == 'compose':
        dc_resource(name, resource_deps=active_deps, labels=['recerdo'])
    else:
        k8s_yaml('./deploy/k3s/' + name + '.yaml')
        k8s_resource(name, port_forwards=[port],
                     resource_deps=active_deps, labels=['recerdo'])

4.3 起動プロファイル¶

「全サービス起動」は重いため、用途別プロファイルを用意する。TILT_PROFILE で切替え：

5. Colima 採用根拠と運用¶

5.1 インストールと起動¶

# macOS (Homebrew)
brew install \
  colima docker docker-compose docker-buildx \
  tilt-dev/tap/tilt sops age

# Linux は distro のパッケージマネージャで colima を導入

# Recerdo 推奨プロファイル（Apple Silicon ネイティブ + Rosetta x86_64）
colima start recerdo \
  --cpu 6 \
  --memory 10 \
  --disk 80 \
  --arch aarch64 \
  --vm-type vz \
  --vz-rosetta \
  --mount-type virtiofs \
  --kubernetes=false

# DOCKER_HOST の自動設定（Colima が docker context を作成）
docker context use colima-recerdo

5.2 k3s 併設モード（将来性）¶

本番の Beta → GA 移行で OCI Container Instances → OKE（Kubernetes） への昇格を想定している（policy.md §1.2）。Colima の k3s を有効化し、同一 Tiltfile で Kubernetes モードに切り替えれば、移行リハーサルを開発者マシン上で行える。

colima start recerdo-k3s \
  --cpu 6 --memory 10 --disk 80 \
  --kubernetes \
  --kubernetes-version v1.30.3+k3s1

kubectl config use-context colima-recerdo-k3s
TILT_TARGET=k3s tilt up

5.3 複数ランタイムの切替¶

DOCKER_HOST と docker context を使うことで、Tiltfile を変更せず にランタイムを差し替える：

# Colima
docker context use colima-recerdo

# Docker Desktop（個人利用の開発者）
docker context use desktop-linux

# OrbStack
docker context use orbstack

6. 環境変数と Feature Flag¶

環境抽象化 の .env.local パターンをそのまま使う。ローカル固有値は（アプリ本体リポジトリ側の）deploy/dev/.env.local.example にテンプレート化する。

6.1 ローカル規定値¶

6.2 シークレット（整備予定）¶

• sops + age で .env.local.enc をアプリ側リポに Git 管理し、開発者は age 公開鍵を交換する。
• tilt up 前に make dev.decrypt で復号して .env.local に展開する Makefile を提供する 予定。成果物（Makefile / .env.local.enc / deploy/dev/.env.local.example）が揃うまでは、§7.1 の「現時点で動く代替手順」で sops --decrypt を直接叩くか、.env.local を手動作成する。
• .env.local は .gitignore 対象。

6.3 Flipt のシード¶

ローカル用に以下の Flag を起動時 Seed する（deploy/dev/flipt-seed.json）：

{
  "flags": [
    { "key": "infra.queue.provider",   "variant": "redis-bullmq" },
    { "key": "infra.storage.provider", "variant": "garage" },
    { "key": "infra.mail.provider",    "variant": "postfix-smtp" },
    { "key": "infra.media.transcoder", "variant": "ffmpeg-hls" },
    { "key": "infra.dualWrite.enabled","boolean": false },
    { "key": "infra.readFrom",         "variant": "beta" }
  ]
}

7. 動作確認手順¶

7.1 初回セットアップ（設計上の最短経路）¶

アプリケーションリポジトリが揃った後の理想形を示す。Brewfile / Makefile / .env.local.enc は 現時点ではまだ存在せず、アプリケーション本体リポジトリ側で順次整備する予定のため、現行で動かす場合は下の「現時点で動く代替手順」を使う。

# 将来の想定（Brewfile / Makefile が整備された後）
git clone git@github.com:Willen-Federation/recerdo-infra.git && cd recerdo-infra
brew bundle                              # Brewfile を追加後に有効化
colima start recerdo --cpu 6 --memory 10 --vz-rosetta
docker context use colima-recerdo
make dev.decrypt                         # .env.local を復号（sops + age のラッパ）
tilt up                                  # http://localhost:10350 でダッシュボード

現時点で動く代替手順（Brewfile / Makefile が無い前提）:

# 依存ツールを明示インストール（§5.1 と同じ）
brew install colima docker docker-compose docker-buildx tilt-dev/tap/tilt sops age

# VM 起動とコンテキスト切替
colima start recerdo --cpu 6 --memory 10 --vz-rosetta
docker context use colima-recerdo

# シークレット復号（Makefile 無しのフォールバック）
sops --decrypt deploy/dev/.env.local.enc > deploy/dev/.env.local   # ファイルが整備された後
# あるいは、初回は手元に `.env.local` を手動で作成（§6.1 のカタログを参照）

tilt up

初回は Garage / MySQL / MariaDB のボリューム初期化に 2〜3 分かかる。Tilt UI で各リソースが Ready になるのを確認する。

7.2 スモークチェック¶

# Cognito モックでトークン取得
curl -X POST http://localhost:9229/token -d 'username=dev&password=dev'

# Auth Svc のヘルスチェック（JWT 検証まで）
curl -H "Authorization: Bearer $TOKEN" http://localhost:8001/health

# Album 作成（MySQL + Redis + Garage + Flipt を経由）
curl -X POST http://localhost:8003/api/albums \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"name":"local-test"}'

# メール到達確認
open http://localhost:8025

# キュー状況
open http://localhost:3000    # Bull Board
open http://localhost:8085    # asynqmon

# メトリクス
open http://localhost:3001    # Grafana

7.3 MariaDB 互換テスト¶

DATABASE_COMPAT_URL を指すテストは make test.compat で MariaDB 10.11 側に対して同一 SQL を実行する（policy.md §3.1、environment-abstraction.md §6.1 参照）。CI でも同等ジョブを実行する。

8. Docker Compose との共存（段階的移行）¶

既存の Beta 運用スクリプト（recerdo-infra/deploy/beta/docker-compose.yml 想定）を残しつつ、開発は Tilt 経由に移行する。Tilt 側の docker_compose() でミドルウェアを読み込み、アプリのみ Tilt 管理にすることで Compose ファイル 1 セット を両環境で維持する。

9. Kubernetes（k3s / OKE）への昇格パス¶

本番は OCI Container Instances を起点に、スケール要件に応じて OKE（Kubernetes）へ移行する方針（policy.md §1.2）。Tiltfile は最初から k8s_yaml 経路を実装 しておき、開発者が任意でローカル k3s に切り替えられるようにする。

9.1 マニフェスト配置（アプリ本体リポジトリ例）¶

deploy/
├── dev/
│   ├── docker-compose.infra.yml   # ミドルウェア
│   └── docker-compose.full.yml    # 全サービス（Tilt 不使用時の保険）
├── beta/
│   └── docker-compose.yml         # XServer VPS 用
└── k3s/
    ├── namespace.yaml
    ├── auth-svc.yaml
    ├── album-svc.yaml
    ├── ...
    └── kustomization.yaml          # 本番 OKE 用 overlay の土台

9.2 Tilt からの切替¶

# Compose モード（既定）
tilt up

# k3s モード（Colima で k3s を起動した状態）
TILT_TARGET=k3s tilt up

k3s で動くことを CI で週次チェックすれば、OKE 移行時に Manifest を書き起こす必要がない。

10. リスクと緩和策¶

11. 運用 / リリースサイクルへの組み込み（目標）¶

• 現状（この docs リポジトリ）: GitHub Actions は mkdocs build --strict のみを実行。Tilt / Colima を回すワークフローは存在しない。
• 将来案（アプリ本体リポジトリ）: PR ごとに tilt ci を実行し、TILT_PROFILE=core のスモークを 5 分以内に完了させる（要: アプリリポ側でワークフロー追加）。
• 将来案（nightly）: Colima 上の k3s で TILT_TARGET=k3s を起動し、environment-abstraction.md §6.1 の統合テストマトリクスを回す。
• リリース直前: deployment-strategy.md §5 の Beta → 本番マッピングどおりに環境変数を OCI 向けに差し替え、同じ Tiltfile で本番 staging（OKE）の手前まで同一定義で動くことを確認する。

12. 参考文献¶

• Tilt 公式ドキュメント
• Tilt — live_update リファレンス
• Tilt — Docker Compose サポート
• Colima — GitHub
• Lima — Linux VMs on macOS
• k3s — Lightweight Kubernetes
• cognito-local — AWS Cognito ローカルエミュレータ
• Garage Documentation
• Flipt Documentation
• MailHog — SMTP testing tool
• The Twelve-Factor App — Dev/prod parity

13. 関連ドキュメント¶

• ローカル開発 (Tilt 起動手順) — 操作ガイド。本ドキュメントと対の関係で、実際の tilt up / colima start 手順・兄弟リポ clone スクリプト・トラブルシューティングをカバー
• デプロイメント戦略 — Beta（Docker Compose）／本番（OCI Container Instances / OKE）への接続点
• 環境抽象化 & Feature Flag — 本ドキュメントが前提とする .env.local / Adapter の切替
• サーバーキャパシティ計画 — Colima 推奨 CPU/メモリの根拠
• ファイアウォール & データプロテクション — Docker ネットワーク分離とローカル再現
• キュー抽象化設計 — Redis + BullMQ / asynq / OCI Queue の Port と Adapter
• マイクロサービス一覧 — 9 サービスの責務と依存関係

最終更新: 2026-04-20 初版（Tilt + Colima によるローカル開発環境の整備）