GitLab Stack Config Generator

GitLab スタック設定ジェネレーター

このスキルは、GitLab スタックプロジェクト向けにサービス固有の設定ファイルを生成・管理します。設定が適切なパターンに従い、すべての変数に .env を使用し、シークレットが含まれないようにします。

このスキルを使用する場面

ユーザーから次の依頼があった場合に、このスキルを有効にします。

• サービス（nginx、PostgreSQL、Redis など）の設定ファイルを生成する
• 新しいサービスの設定テンプレートを作成する
• ./config ディレクトリ構造を設定する
• 既存の設定ファイルを検証する
• 設定で .env 変数が正しく使われていることを確認する
• 設定にシークレットが含まれていないことを確認する
• プロジェクトのメタファイル（CLAUDE.md、.gitignore、.dockerignore）を設定する
• .env と .env.example を同期する

設定の基本原則

重要なルール：

1. ./env は設定のソースです：すべての設定変数は .env に記述します（設定ファイルには記述しません）
2. 設定にシークレットを含めない：設定ファイルには決してシークレットを記述しません（secrets-manager を使用します）
3. サービスディレクトリ：各サービスに ./config/service-name/ ディレクトリを用意します
4. サービス内はフラットにする：設定ファイルはサービスディレクトリ内にフラットに配置します
5. .env の同期：.env と .env.example は常に一致させる必要があります
6. パスの検証：参照されるすべてのパスが存在する必要があります
7. Docker の検証：Docker 設定には docker-validation スキルを使用します
8. プロジェクトのメタファイル：CLAUDE.md、.gitignore、.dockerignore が必要です

設定ワークフロー

フェーズ 1：要件の把握

ステップ 1：生成する内容を決定する

ユーザーに確認する（または推測する）項目：

• どのサービスの設定が必要ですか？
• 新しい設定を作成しますか、それとも既存の設定を更新しますか？
• 本番環境、開発環境、または両方の設定が必要ですか？
• 使用するテンプレートはありますか？

ステップ 2：現在の状態を確認する

1. ./config ディレクトリは存在しますか？
2. .env は存在しますか？
3. .env.example は存在しますか？
4. サービスディレクトリはすでに存在しますか？
5. メタファイル（CLAUDE.md、.gitignore、.dockerignore）はありますか？

フェーズ 2：ディレクトリ構造の設定

ステップ 1：./config ディレクトリを作成する

mkdir -p ./config
chmod 755 ./config

ステップ 2：サービスディレクトリを作成する

サービス（例：nginx、postgres、redis）ごとに作成します。

mkdir -p ./config/nginx
mkdir -p ./config/postgres
mkdir -p ./config/redis
chmod 755 ./config/*

ディレクトリ構造：

./config/
├── nginx/
│   ├── nginx.conf
│   ├── ssl/
│   │   └── (SSL configs, not certificates)
│   └── conf.d/
│       └── default.conf
├── postgres/
│   ├── postgresql.conf
│   └── init.sql
├── redis/
│   └── redis.conf
└── app/
    └── settings.yml

原則：

• サービスごとにディレクトリを 1 つ作成します
• 各サービスディレクトリ内はフラットな構造にします
• サブディレクトリは論理的に必要な場合にのみ作成します（例：nginx/ssl/、nginx/conf.d/）

フェーズ 3：メタファイルの生成

重要：これらのファイルが常に存在することを確認します

ステップ 1：CLAUDE.md を生成する

プロジェクトのルートに CLAUDE.md を作成します。

# CLAUDE.md

This file provides guidance when working with code in this repository.

## Repository Purpose

[Brief description of the stack project]

## Stack Architecture

This is a GitLab stack project following these principles:

- **Configuration**: All variables in .env, configs in ./config
- **Secrets**: All secrets in ./secrets via Docker secrets
- **Structure**: Standard directories (./config, ./secrets, ./_temporary)
- **Docker**: Modern Docker Compose (no version field)
- **Ownership**: No root-owned files

## Working with This Stack

### Configuration Files

All service configurations are in `./config/[service-name]/` directories.
Configuration values are loaded from `.env` file.

### Environment Variables

- `.env` contains all configuration (NOT secrets)
- `.env.example` must match `.env` exactly (critical requirement)
- Update both files when adding new variables

### Secrets Management

All secrets are managed via Docker secrets:
- Location: `./secrets/` directory
- Never in .env or docker-compose.yml
- Use secrets-manager skill for secret operations

### Docker Commands

```bash
# Start stack
docker compose up -d

# View logs
docker compose logs -f

# Stop stack
docker compose down

重要なルール

Git コミット

重要：コミットメッセージを作成する際は、「Claude」や「Claude Code」に言及しないでください。

適切なコミットメッセージ：

• 「SSL 終端用の nginx 設定を追加」
• 「本番環境向けに PostgreSQL の設定を更新」
• 「Redis の永続化設定を修正」

不適切なコミットメッセージ：

• 「Claude が nginx 設定を追加」 ❌
• 「Claude に設定の更新を依頼」 ❌

ファイルのアクセス権

すべてのファイルは現在のユーザーが所有する必要があります（root ではありません）。

# Check ownership
find . -user root -type f

# Fix if needed
sudo chown -R $(id -u):$(id -g) .

検証

デプロイ前に必ず次を実行します。

# Validate entire stack
[validation command]

# Check secrets
[secrets validation command]

ディレクトリ構造

./
├── docker-compose.yml      # Main compose file (NO version field)
├── .env                    # Configuration variables
├── .env.example            # Template (must match .env)
├── CLAUDE.md               # This file
├── .gitignore              # Git exclusions
├── .dockerignore           # Docker build exclusions
├── config/                 # Service configurations
│   ├── nginx/
│   ├── postgres/
│   └── redis/
├── secrets/                # Docker secrets (NOT in git)
│   └── .gitkeep
└── _temporary/             # Transient files (NOT in git)

利用可能なスキル

• stack-validator：デプロイ前にスタック全体を検証します
• secrets-manager：Docker シークレットを安全に管理します
• config-generator：サービス設定を生成・更新します
• docker-validation：Docker 設定を検証します

---

最終更新日：[date]

**Step 2: Generate/Update .gitignore**

```gitignore
# Secrets - NEVER commit
/secrets/
/secrets/*
!secrets/.gitkeep

# Environment
.env
.env.local
.env.*.local

# Temporary
/_temporary/
/_temporary/*

# Docker
.dockerignore

# IDE
.vscode/
.idea/
*.swp
*.swo
*~

# OS
.DS_Store
Thumbs.db

# Logs
*.log
logs/

# Build artifacts
dist/
build/
node_modules/
vendor/

# Backup files
*.backup
*.old
*.bak

ステップ 3：.dockerignore を生成する

# Git
.git/
.gitignore

# Environment
.env
.env.*

# Secrets
secrets/

# Temporary
_temporary/

# Documentation
*.md
CLAUDE.md

# IDE
.vscode/
.idea/

# OS
.DS_Store
Thumbs.db

# Dependencies (if not needed in build)
node_modules/
vendor/

# Logs
*.log
logs/

フェーズ 4：サービス設定の生成

一般的なサービス：nginx、PostgreSQL、Redis

各サービスについて、以下の手順に従います。

ステップ 1：設定要件の確認

ユーザーに確認します。

• テンプレートを使用するか、カスタム設定にするか？
• どの機能を有効にするか？
• 本番環境用と開発環境用のどちらの設定にするか？

ステップ 2：必要な .env 変数の特定

各サービスで必要となるすべての .env 変数を列挙します。

nginx の例：

• NGINX_PORT
• NGINX_HOST
• NGINX_SSL_ENABLED
• APP_HOST
• APP_PORT

ステップ 3：設定ファイルの生成

重要：環境変数のプレースホルダー（${VAR_NAME}）を使用します。

nginx.conf の例：

# Nginx Configuration
# Loads variables from .env

upstream app {
    server ${APP_HOST}:${APP_PORT};
}

server {
    listen ${NGINX_PORT};
    server_name ${NGINX_HOST};

    # SSL configuration
    # SSL certificates loaded from Docker secrets
    # ssl_certificate /run/secrets/ssl_cert;
    # ssl_certificate_key /run/secrets/ssl_key;

    location / {
        proxy_pass http://app;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

ステップ 4：.env の更新

必要な変数をすべて追加します。

# Nginx Configuration
NGINX_PORT=80
NGINX_HOST=localhost
NGINX_SSL_ENABLED=false
APP_HOST=app
APP_PORT=8080

ステップ 5：.env.example の更新

重要：.env と完全に一致させる必要があります。

# Nginx Configuration
NGINX_PORT=80
NGINX_HOST=localhost
NGINX_SSL_ENABLED=false
APP_HOST=app
APP_PORT=8080

ステップ 6：docker-compose.yml の更新

設定用のボリュームマウントを追加します。

services:
  nginx:
    image: nginx:alpine
    ports:
      - "${NGINX_PORT}:80"
    volumes:
      - ./config/nginx/nginx.conf:/etc/nginx/nginx.conf:ro
    environment:
      # Variables loaded from .env automatically
      NGINX_HOST: ${NGINX_HOST}
      APP_HOST: ${APP_HOST}
      APP_PORT: ${APP_PORT}

フェーズ 5：設定の検証

ステップ 1：構文の検証

各設定ファイルの種類について検証します。

Nginx：

# Test nginx config
docker run --rm -v $(pwd)/config/nginx:/etc/nginx:ro nginx:alpine nginx -t

PostgreSQL：

# Check SQL syntax
# Parse init.sql for syntax errors

Redis：

# Test redis config
docker run --rm -v $(pwd)/config/redis:/usr/local/etc/redis:ro redis:alpine redis-server --test-memory 1024

ステップ 2：シークレットの検出（重要）

すべての設定ファイルをスキャンして、シークレットを検出します。

# Check for common secret patterns
grep -r -iE "(password|secret|key|token|api_key)" ./config/

# If found, this is CRITICAL SECURITY ISSUE
# Must use secrets-manager to fix

ステップ 3：パスの検証

参照されているすべてのパスが存在することを確認します。

1. 設定ファイルから他のファイルを参照していますか？
2. docker-compose.yml 内のボリュームマウントを確認しましたか？
3. すべてのパスが存在しますか？

ステップ 4：.env の同期（重要）

# Extract variable names from .env
env_vars=$(grep -E "^[A-Z_]+" .env | cut -d'=' -f1 | sort)

# Extract from .env.example
example_vars=$(grep -E "^[A-Z_]+" .env.example | cut -d'=' -f1 | sort)

# Compare
diff <(echo "$env_vars") <(echo "$example_vars")

# If any difference, this is CRITICAL ERROR

ステップ 5：Docker の検証

重要：docker-validation スキルを使用します。

"Validate docker-compose.yml using docker-validation skill"

完了する前に、すべての指摘事項に対処してください。

フェーズ 6：テンプレートの選択

ステップ 1：テンプレートの提示

nginx、PostgreSQL、Redis について、次の選択肢を提示します。

Nginx テンプレート：

1. シンプルなリバースプロキシ（デフォルト）

   • バックエンドサービスへの基本的なプロキシ
   • SSL なし
   • 最小限の設定

2. SSL 終端

   • HTTPS を有効化
   • Docker secrets から SSL 証明書を取得
   • HTTP から HTTPS へのリダイレクト

3. 静的コンテンツ配信 + プロキシ

   • 静的ファイルを配信
   • API リクエストをプロキシ
   • キャッシュヘッダー

4. カスタム

   • ユーザーが要件を提示
   • カスタム設定を生成

PostgreSQL テンプレート：

1. 基本（デフォルト）

   • 標準設定
   • シンプルな init.sql
   • 開発向け

2. 本番環境用

   • 最適化された設定
   • コネクションプーリング
   • パフォーマンスの調整

3. 拡張機能付き

   • PostGIS、UUID など
   • 拡張機能固有の設定
   • 拡張機能用の初期化スクリプト

4. カスタム

   • ユーザー指定

Redis テンプレート：

1. キャッシュ（デフォルト）

   • 永続化なし
   • メモリのみ
   • 高速

2. 永続化

   • RDB スナップショット
   • AOF ロギング
   • データの永続性

3. Pub/Sub

   • メッセージング向けに最適化
   • 永続化なし
   • 高スループット

4. カスタム

   • ユーザーの要件

ステップ 2：テンプレートからの生成

ユーザーの選択に基づいて、以下を含む適切な設定を生成します。

• 必要な .env 変数
• 適切な docker-compose.yml との統合
• 設定を説明する README セクション

フェーズ 7：検証レポート

生成後、包括的なレポートを提示します。

📝 Configuration Generation Report
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

✅ Meta Files
✅ CLAUDE.md created
✅ .gitignore updated
✅ .dockerignore created

✅ Directory Structure
✅ ./config/nginx created
✅ ./config/postgres created
✅ ./config/redis created

📄 Generated Configurations

Nginx (Simple Reverse Proxy):
✅ ./config/nginx/nginx.conf
✅ Variables added to .env (3)
✅ .env.example synced
✅ docker-compose.yml updated
✅ Syntax validation: PASS

PostgreSQL (Basic):
✅ ./config/postgres/postgresql.conf
✅ ./config/postgres/init.sql
✅ Variables added to .env (5)
✅ .env.example synced
✅ docker-compose.yml updated

Redis (Cache):
✅ ./config/redis/redis.conf
✅ Variables added to .env (2)
✅ .env.example synced
✅ docker-compose.yml updated

🔐 Security Validation
✅ No secrets in config files
✅ All secrets in ./secrets (via secrets-manager)
✅ Configs use .env variables only

✅ Path Validation
✅ All referenced paths exist
✅ Volume mounts valid

✅ .env Synchronization
✅ .env and .env.example match (10 variables)

🐳 Docker Validation
✅ docker-compose.yml syntax valid
✅ All volume mounts exist
✅ No deprecated syntax

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
✅ Configuration generation complete!

Next Steps:
1. Review generated configurations
2. Customize as needed
3. Run: docker compose config (validate)
4. Run: docker compose up -d

サービス固有のパターン

Nginx の設定

必ず含めるもの：

• 環境変数のプレースホルダー
• アップストリームのバックエンド参照
• 基本的なセキュリティヘッダー
• ログ設定

含めてはいけないもの：

• ハードコードされた IP アドレスやホスト
• SSL 証明書の内容（Docker secrets を使用）
• パスワードやトークン

変数の例：

NGINX_PORT=80
NGINX_HOST=localhost
NGINX_WORKER_PROCESSES=auto
NGINX_WORKER_CONNECTIONS=1024
APP_BACKEND_HOST=app
APP_BACKEND_PORT=8080

PostgreSQL の設定

必ず含めるもの：

• データベース／ユーザー作成用の初期化スクリプト
• 基本的なパフォーマンス調整
• 接続数の上限
• ログ設定

含めてはいけないもの：

• パスワード（Docker secrets を使用）
• 開発環境での本番データベース名
• ハードコードされた接続文字列

変数の例：

POSTGRES_DB=myapp_db
POSTGRES_USER=myapp_user
# POSTGRES_PASSWORD in ./secrets/db_password
POSTGRES_MAX_CONNECTIONS=100
POSTGRES_SHARED_BUFFERS=256MB

Redis の設定

必ず含めるもの：

• 永続化の設定
• メモリ制限
• ネットワークバインディング

含めてはいけないもの：

• パスワード（必要に応じて Docker secrets を使用）
• ハードコードされたマスター／スレーブの IP アドレス

変数の例：

REDIS_PORT=6379
REDIS_MAXMEMORY=256mb
REDIS_MAXMEMORY_POLICY=allkeys-lru
REDIS_SAVE_ENABLED=false

関連スキルとの連携

secrets-manager

呼び出すタイミング：

• 設定ファイル内でシークレットが検出された場合 → 重要
• 設定でシークレットを参照する必要がある場合
• SSL 証明書または秘密鍵が必要な場合

docker-validation

呼び出すタイミング：

• docker-compose.yml を更新した後（必ず）
• 生成を完了する前
• ユーザーが検証を依頼したとき

stack-validator

呼び出すタイミング：

• 生成の完了後
• スタック全体を検証するとき
• すべてのパターンに従っていることを確認するとき

重要な注意事項

• シークレット禁止：設定ファイルにシークレットを絶対に記述しないでください
• .env をソースにする：すべての設定は .env から取得します
• .env の同期：.env と .env.example の内容を一致させてください
• Docker の検証：必ず docker-validation スキルを使用してください
• CLAUDE.md のルール：コミットメッセージに「Claude」を含めないことを明記してください
• テンプレートは任意：ユーザーがデフォルトまたはカスタムを選択します
• パスの検証：すべてのパスが存在している必要があります

ワークフローの例

User: "Generate nginx and PostgreSQL configs"

1. Check current state
   - ./config missing → create it
   - .env exists
   - .env.example exists
   - CLAUDE.md missing → create it

2. Generate meta files
   - Create CLAUDE.md
   - Update .gitignore
   - Create .dockerignore

3. Ask user for templates
   "Which templates would you like?
    - Nginx: [Simple Reverse Proxy], SSL Termination, Static + Proxy, Custom
    - PostgreSQL: [Basic], Production, With Extensions, Custom"

4. User selects: Simple Reverse Proxy, Basic

5. Generate nginx config
   - Create ./config/nginx/nginx.conf
   - Add variables to .env
   - Sync .env.example
   - Update docker-compose.yml
   - Validate syntax

6. Generate PostgreSQL config
   - Create ./config/postgres/postgresql.conf
   - Create ./config/postgres/init.sql
   - Add variables to .env
   - Sync .env.example
   - Update docker-compose.yml

7. Run validations
   - Secret detection: PASS
   - Path validation: PASS
   - .env sync check: PASS
   - Docker validation (via docker-validation skill): PASS

8. Generate report
   - Show all created files
   - List .env variables added
   - Confirmation that validations passed

9. Next steps
   - Suggest testing: docker compose config
   - Recommend: docker compose up -d

---

このスキルは、厳格な検証を行いながら GitLab スタックのパターンに従ってサービス設定を生成します。