AgentSkillsCN

local-environment

在构建与配置本地开发环境时，此技能将助您高效完成 Docker Compose 配置、子域名设置、数据库结构设计、SSL 证书签发，以及各类疑难问题的排查与解决。

SKILL.md
--- frontmatter
name: local-environment
description: ローカル開発環境の構築・設定を行う際に使用。Docker Compose、サブドメイン設定、データベース構成、SSL証明書、トラブルシューティングに役立つ。

ローカル開発環境ガイド

ドキュメント

  • •documentation/docs/content_02_quickstart/quickstart-01-getting-started.md - クイックスタート
    • •「ローカル環境のリソースチューニング」セクション - Docker/PostgreSQL/HikariCP/nginx設定
  • •documentation/docs/content_11_learning/26-performance-tuning/ - パフォーマンスチューニングガイド
  • •docker-compose.yaml - PostgreSQL構成
  • •docker-compose-mysql.yaml - MySQL構成

環境構成概要

code
┌─────────────────────────────────────────────────────────────┐
│                    *.local.dev サブドメイン                    │
├─────────────────────────────────────────────────────────────┤
│  api.local.dev    → nginx → idp-server-1/2 (8081/8082)     │
│  auth.local.dev   → app-view (認可UI)                       │
│  sample.local.dev → sample-web (サンプルRP)                 │
└─────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────┐
│                      データ層                                │
├─────────────────────────────────────────────────────────────┤
│  PostgreSQL Primary (:5432) ←→ Replica (:5433)             │
│  Redis (:6379) - セッション/キャッシュ                       │
│  Mockoon (:3010) - 外部サービスモック                        │
└─────────────────────────────────────────────────────────────┘

サブドメイン設定

方法1: dnsmasq（macOS推奨）

bash
# セットアップスクリプト実行
./scripts/setup-local-subdomain.sh

このスクリプトは以下を設定:

  • •dnsmasq による *.local.dev のローカルDNS解決
  • •mkcert によるローカルSSL証明書の生成

方法2: /etc/hosts（手動設定）

dnsmasqが使えない環境向け:

bash
# Linux / macOS
sudo sh -c 'echo "127.0.0.1 api.local.dev auth.local.dev sample.local.dev" >> /etc/hosts'

# Windows (管理者権限のPowerShell)
Add-Content -Path C:\Windows\System32\drivers\etc\hosts -Value "127.0.0.1 api.local.dev auth.local.dev sample.local.dev"

設定確認

bash
# DNS解決の確認
ping -c 1 api.local.dev
nslookup api.local.dev

# 127.0.0.1 が返されれば正常

SSL証明書

mkcert によるローカル証明書

bash
# mkcert インストール (macOS)
brew install mkcert

# ルートCA インストール
mkcert -install

# 証明書生成（setup-local-subdomain.sh が自動実行）
mkcert "*.local.dev"

証明書ファイルの場所:

  • •config/certs/_wildcard.local.dev.pem - 証明書
  • •config/certs/_wildcard.local.dev-key.pem - 秘密鍵

Docker Compose

PostgreSQL構成（推奨）

bash
# 環境変数設定
cp .env.example .env
# または
./init-generate-env.sh postgresql

# ビルド・起動
docker compose build
docker compose up -d

MySQL構成

bash
# 環境変数設定
./init-generate-env.sh mysql

# ビルド・起動
docker compose -f docker-compose-mysql.yaml build
docker compose -f docker-compose-mysql.yaml up -d

サービス一覧

サービスポート説明
nginx443リバースプロキシ（api.local.dev）
idp-server-18081idp-server インスタンス1
idp-server-28082idp-server インスタンス2
app-view3000認可UI（auth.local.dev）
sample-web3001サンプルRP（sample.local.dev）
postgres-primary5432PostgreSQL プライマリ
postgres-replica5433PostgreSQL レプリカ
redis6379Redis
mockoon3010外部サービスモック

データベース

PostgreSQL Primary/Replica構成

bash
# レプリケーション確認
./scripts/verify-replication.sh

# 個別起動（デバッグ用）
docker compose up -d postgres-primary postgres-replica redis

# マイグレーション実行
docker compose up flyway-migrator

接続情報

項目PrimaryReplica
ホストlocalhostlocalhost
ポート54325433
データベースidpidp
ユーザーidp_appidp_app

直接接続

bash
# Primary
docker compose exec postgres-primary psql -U idp_app -d idp

# Replica
docker compose exec postgres-replica psql -U idp_app -d idp

初期設定

admin-tenant 初期化

bash
# 設定ファイル生成
./init-admin-tenant-config.sh

# 初期化実行
./setup.sh

E2Eテスト用データ

bash
./config/scripts/e2e-test-data.sh

よく使うコマンド

bash
# ヘルスチェック
curl -v https://api.local.dev/actuator/health

# ログ確認
docker compose logs -f idp-server-1
docker compose logs -f nginx

# 再起動
docker compose restart idp-server-1 idp-server-2

# 全停止
docker compose down

# 全削除（ボリューム含む）
docker compose down -v

# E2Eテスト
cd e2e && npm test

トラブルシューティング

サブドメイン関連

問題原因解決策
ping api.local.dev 失敗dnsmasq停止brew services restart dnsmasq または /etc/hosts 手動設定
DNS解決が127.0.0.1以外他DNSリゾルバ優先/etc/resolver/local.dev ファイル確認
SSL証明書エラールートCA未インストールmkcert -install 実行

Docker関連

問題原因解決策
ポート競合他サービスがポート使用中lsof -i :5432 で確認、競合サービス停止
コンテナ起動失敗依存サービス未起動docker compose up -d postgres-primary redis を先に実行
ディスク容量不足Dockerボリューム肥大docker system prune -a で不要リソース削除

データベース関連

問題原因解決策
レプリケーション失敗WAL設定不正./scripts/verify-replication.sh でステータス確認
接続拒否認証設定不正.env のDB認証情報確認
マイグレーション失敗スキーマ不整合docker compose down -v で初期化後、再実行

アプリケーション関連

問題原因解決策
502 Bad Gatewayidp-server未起動docker compose logs idp-server-1 でログ確認
認証失敗admin-tenant未初期化./setup.sh 実行
E2Eテスト失敗テストデータ未設定./config/scripts/e2e-test-data.sh 実行

関連スキル

スキル用途
/onboardingプロジェクト全体像・学習ロードマップ
/architectureアーキテクチャ・レイヤー構造
/operations運用・監視