@k2works/claude-code-booster 4.15.0 → 5.0.0

package/lib/assets/.claude/skills/migrating-okf-workspace/iteration-1/eval-1-migrate-docs/with_skill/outputs/docs_after/reference//347/222/260/345/242/203/345/244/211/346/225/260/347/256/241/347/220/206/343/202/254/343/202/244/343/203/211.md

@@ -0,0 +1,681 @@
+---
+type: Reference
+title: 環境変数管理ガイド
+description: dotenv による環境変数管理の仕組み・セットアップ手順・プロジェクト環境変数（Docker・MkDocs）の一覧と、DOCKER_HOST やセキュリティに関する注意事項。
+tags: [reference, environment, dotenv, configuration]
+status: stable
+generated: { by: claude-code/claude-fable-5, at: 2026-08-25T02:18:46Z }
+stale_after: 2027-02-25T00:00:00Z
+sources:
+  - id: twelve-factor
+    resource: https://12factor.net/ja/config
+    title: The Twelve-Factor App — Config
+---
+
+# 環境変数管理ガイド
+
+このドキュメントでは、プロジェクトで使用する環境変数について説明します。
+
+## dotenv とは
+
+### 概要
+
+**dotenv** は、環境変数を `.env` ファイルから読み込むためのライブラリです。アプリケーションの設定値をソースコードから分離し、環境ごとに異なる設定を簡単に管理できます。
+
+### なぜ dotenv を使うのか
+
+1. **セキュリティ**: パスワードや API キーをソースコードにハードコーディングせず、Git 管理外のファイルで管理
+2. **環境の分離**: 開発・ステージング・本番環境で異なる設定を簡単に切り替え
+3. **チーム開発**: 各開発者が自分の環境に合わせた設定を使用可能
+4. **12-Factor App**: [The Twelve-Factor App](https://12factor.net/ja/config) の設定管理ベストプラクティスに準拠[^twelve-factor]
+
+### 仕組み
+
+```plantuml
+@startuml
+title dotenv による環境変数読み込みの流れ
+
+skinparam rectangle {
+  BackgroundColor #f5f5f5
+  BorderColor #333333
+}
+
+rectangle ".env ファイル" as env
+rectangle "process.env (Node.js)" as process
+rectangle "アプリケーションコード" as app
+
+env -down-> process : dotenv が読み込み
+process -down-> app : アプリケーションで使用
+
+note right of env
+  MKDOCS_PORT=8000
+  DOCKER_HOST=npipe:////./pipe/docker_engine
+end note
+
+note right of process
+  process.env.MKDOCS_PORT
+  process.env.DOCKER_HOST
+end note
+
+note right of app
+  const port = process.env.MKDOCS_PORT;
+end note
+
+@enduml
+```
+
+## セットアップ方法
+
+### 1. パッケージのインストール
+
+```bash
+npm install dotenv
+```
+
+### 2. .env ファイルの作成
+
+```bash
+# テンプレートからコピー
+cp .env.example .env
+
+# または新規作成
+touch .env
+```
+
+### 3. .env ファイルの編集
+
+```bash
+# プロジェクトルート/.env
+MKDOCS_PORT=8000
+```
+
+### 4. アプリケーションでの読み込み
+
+```javascript
+// 方法1: エントリーポイントの先頭でインポート（推奨）
+import 'dotenv/config';
+
+// 方法2: 明示的に config() を呼び出し
+import * as dotenv from 'dotenv';
+dotenv.config();
+
+// 環境変数を使用
+const port = process.env.MKDOCS_PORT || 8000;
+```
+
+### 5. .gitignore に追加
+
+```gitignore
+# .gitignore
+.env
+.env.local
+.env.*.local
+```
+
+## 環境変数ファイル一覧
+
+| ファイル | 用途 | Git 管理 |
+|---------|------|----------|
+| `.env` | ローカル開発用設定 | ✗ |
+| `.env.example` | 設定テンプレート | ✓ |
+
+## プロジェクト環境変数
+
+### Docker 設定
+
+| 変数名 | 説明 | デフォルト値 |
+|--------|------|-------------|
+| `DOCKER_HOST` | Docker デーモンへの接続先 | (システム依存) |
+
+### MkDocs 設定
+
+| 変数名 | 説明 | デフォルト値 |
+|--------|------|-------------|
+| `MKDOCS_PORT` | MkDocs サーバーのポート番号 | `8000` |
+
+## 重要な注意事項
+
+### DOCKER_HOST 環境変数について
+
+Docker Desktop 使用時に `DOCKER_HOST` 環境変数が不正に設定されていると接続エラーが発生します。
+
+```
+ERROR: error during connect: Head "http://.%2Fpipe%2Fdocker_engine/_ping":
+open ./pipe/docker_engine: The system cannot find the path specified.
+```
+
+**Windows 環境での正しい設定:**
+
+```bash
+# 正しい形式
+DOCKER_HOST=npipe:////./pipe/docker_engine
+
+# 誤った形式（エラーになる）
+DOCKER_HOST=npipe://./pipe/docker_engine
+```
+
+**解決方法:**
+
+```bash
+# 環境変数を削除（Docker Desktop が自動設定する）
+unset DOCKER_HOST
+```
+
+> **注意**: 本プロジェクトの gulp タスクは Windows 環境で自動的に `DOCKER_HOST` を正規化します。
+
+### セキュリティに関する注意
+
+- `.env` ファイルは Git にコミットしないでください
+- 機密情報（API キー、パスワード等）は `.env` ファイルで管理してください
+- 本番環境では環境変数を直接設定することを推奨します
+
+## .env ファイルの読み込み優先順位
+
+```plantuml
+@startuml
+title Node.js (dotenv) 読み込み優先順位
+
+skinparam defaultTextAlignment center
+
+rectangle "1. シェル環境変数\n(最優先)" as shell #ff9999
+rectangle "2. .env.local\n(Git 管理外)" as local #ffcc99
+rectangle "3. .env\n(ローカル設定)" as env #99ff99
+
+shell -[hidden]down-> local
+local -[hidden]down-> env
+
+note right of shell : 既存の環境変数は上書きされない
+note right of local : ローカル固有の設定
+note right of env : デフォルト値
+
+@enduml
+```
+
+## .env ファイルの書き方
+
+```bash
+# コメントは # で始める
+
+# 基本的な書き方
+KEY=value
+
+# 値にスペースを含む場合はクォートで囲む
+MESSAGE="Hello World"
+
+# 変数の展開（dotenv-expand が必要）
+BASE_URL=http://localhost
+API_URL=${BASE_URL}/api
+```
+
+## ベストプラクティス
+
+| Do | Don't |
+|----|-------|
+| `.env.example` をテンプレートとして Git 管理 | `.env` を Git にコミット |
+| 本番環境では環境変数を直接設定 | 本番環境で `.env` ファイルを使用 |
+| 変数名は `SCREAMING_SNAKE_CASE` を使用 | 小文字や camelCase を使用 |
+| デフォルト値をコードで設定 | `.env` ファイルのみに依存 |
+
+```javascript
+// デフォルト値の設定例
+const port = process.env.MKDOCS_PORT || 8000;
+const nodeEnv = process.env.NODE_ENV || 'development';
+```
+
+## Vault（暗号化・復号化）
+
+### 概要
+
+Vault は `.env` ファイルを安全に暗号化・復号化するためのツールです。暗号化されたファイル（`.env.vault`）は Git にコミットでき、チームメンバー間で安全に環境変数を共有できます。
+
+### なぜ Vault を使うのか
+
+1. **チーム間での秘密情報共有**: `.env` を直接共有せず、暗号化して Git 管理
+2. **環境の再現性**: 新しいメンバーがすぐに開発環境を構築可能
+3. **セキュリティ**: AES-256-GCM による強力な暗号化
+4. **シンプルさ**: 外部サービス不要、パスワードのみで運用
+
+### 暗号化仕様
+
+```plantuml
+@startuml
+title Vault 暗号化の仕組み
+
+skinparam rectangle {
+  BackgroundColor #f5f5f5
+  BorderColor #333333
+}
+
+rectangle "パスワード" as password
+rectangle "ソルト\n(32バイト乱数)" as salt
+rectangle "PBKDF2\n(SHA-512, 100,000回)" as pbkdf2
+rectangle "暗号化キー\n(256ビット)" as key
+rectangle "IV\n(16バイト乱数)" as iv
+rectangle "AES-256-GCM" as aes
+rectangle ".env\n(平文)" as plaintext
+rectangle ".env.vault\n(暗号文)" as ciphertext
+
+password -down-> pbkdf2
+salt -down-> pbkdf2
+pbkdf2 -down-> key
+key -down-> aes
+iv -down-> aes
+plaintext -right-> aes
+aes -down-> ciphertext
+
+note right of pbkdf2
+  100,000回のイテレーションで
+  ブルートフォース攻撃を困難に
+end note
+
+note right of aes
+  認証付き暗号（AEAD）
+  改ざん検知機能付き
+end note
+
+@enduml
+```
+
+| 項目 | 値 |
+|------|-----|
+| 暗号化アルゴリズム | AES-256-GCM（認証付き暗号） |
+| 鍵導出関数 | PBKDF2-SHA512 |
+| イテレーション回数 | 100,000 回 |
+| ソルト長 | 32 バイト（毎回ランダム生成） |
+| IV（初期化ベクトル）長 | 16 バイト（毎回ランダム生成） |
+| 認証タグ長 | 16 バイト |
+
+### .env.vault ファイル形式
+
+暗号化されたファイルはバイナリ形式で、以下の構造を持ちます：
+
+```
++------------------+
+| Salt (32 bytes)  |
++------------------+
+| IV (16 bytes)    |
++------------------+
+| AuthTag (16 bytes)|
++------------------+
+| Ciphertext       |
+| (可変長)          |
++------------------+
+```
+
+### コマンド詳細
+
+#### vault:encrypt
+
+`.env` ファイルを暗号化して `.env.vault` を作成します。
+
+```bash
+npm run vault:encrypt
+```
+
+**動作フロー:**
+
+```plantuml
+@startuml
+title vault:encrypt の動作フロー
+
+start
+:.env ファイルの存在確認;
+
+if (.env が存在する?) then (yes)
+  :パスワード入力を要求;
+  :パスワード確認入力を要求;
+
+  if (パスワードが一致?) then (yes)
+    if (8文字以上?) then (yes)
+      :ソルトを生成（32バイト乱数）;
+      :PBKDF2で暗号化キーを導出;
+      :IVを生成（16バイト乱数）;
+      :AES-256-GCMで暗号化;
+      :.env.vault を出力;
+      :成功メッセージを表示;
+    else (no)
+      :エラー: パスワードが短すぎる;
+      stop
+    endif
+  else (no)
+    :エラー: パスワードが一致しない;
+    stop
+  endif
+else (no)
+  :エラー: .env が見つからない;
+  stop
+endif
+
+stop
+@enduml
+```
+
+**オプション:**
+
+| 環境変数 | 説明 |
+|---------|------|
+| `VAULT_PASSWORD` | パスワードを事前に指定（対話入力をスキップ） |
+
+**例:**
+
+```bash
+# 対話的にパスワードを入力
+npm run vault:encrypt
+
+# 環境変数でパスワードを指定（CI/CD 用）
+VAULT_PASSWORD=my-secret-password npm run vault:encrypt
+```
+
+---
+
+#### vault:decrypt
+
+`.env.vault` ファイルを復号化して `.env` を復元します。
+
+```bash
+npm run vault:decrypt
+```
+
+**動作フロー:**
+
+```plantuml
+@startuml
+title vault:decrypt の動作フロー
+
+start
+:.env.vault ファイルの存在確認;
+
+if (.env.vault が存在する?) then (yes)
+  if (.env が既に存在する?) then (yes)
+    :上書き確認を表示;
+    if (上書きを許可?) then (yes)
+    else (no)
+      :処理を中止;
+      stop
+    endif
+  endif
+
+  :パスワード入力を要求;
+  :暗号化ファイルを読み込み;
+  :ソルト・IV・認証タグを抽出;
+  :PBKDF2で暗号化キーを導出;
+
+  if (復号化成功?) then (yes)
+    :.env を出力;
+    :成功メッセージを表示;
+  else (no)
+    :エラー: パスワードが正しくない;
+    stop
+  endif
+else (no)
+  :エラー: .env.vault が見つからない;
+  stop
+endif
+
+stop
+@enduml
+```
+
+**例:**
+
+```bash
+# 対話的にパスワードを入力
+npm run vault:decrypt
+
+# 環境変数でパスワードを指定
+VAULT_PASSWORD=my-secret-password npm run vault:decrypt
+```
+
+---
+
+#### vault:view
+
+`.env.vault` の内容を復号化して表示します。ファイルは作成されません。
+
+```bash
+npm run vault:view
+```
+
+**用途:**
+
+- 暗号化された内容を確認したいが、`.env` ファイルを作成したくない場合
+- CI/CD パイプラインでのデバッグ
+- 復号化前の内容確認
+
+**例:**
+
+```bash
+# 内容を確認
+npm run vault:view
+
+# 出力例:
+# --- .env.vault contents ---
+#
+# DATABASE_URL=mysql://user:pass@localhost:3306/mydb
+# API_KEY=sk-xxxxxxxxxxxx
+#
+# --- end ---
+```
+
+---
+
+#### vault:rekey
+
+現在のパスワードで復号化し、新しいパスワードで再暗号化します。
+
+```bash
+npm run vault:rekey
+```
+
+**動作フロー:**
+
+```plantuml
+@startuml
+title vault:rekey の動作フロー
+
+start
+:.env.vault ファイルの存在確認;
+
+if (.env.vault が存在する?) then (yes)
+  :現在のパスワード入力を要求;
+
+  if (復号化成功?) then (yes)
+    :新しいパスワード入力を要求;
+    :新しいパスワード確認入力を要求;
+
+    if (パスワードが一致 & 8文字以上?) then (yes)
+      :新しいソルト・IVを生成;
+      :新しいパスワードで再暗号化;
+      :.env.vault を上書き;
+      :成功メッセージを表示;
+    else (no)
+      :エラー: パスワード要件を満たさない;
+      stop
+    endif
+  else (no)
+    :エラー: 現在のパスワードが正しくない;
+    stop
+  endif
+else (no)
+  :エラー: .env.vault が見つからない;
+  stop
+endif
+
+stop
+@enduml
+```
+
+**用途:**
+
+- 定期的なパスワードローテーション
+- チームメンバーの退職時
+- パスワード漏洩の疑いがある場合
+
+### 使い方
+
+#### 初回セットアップ（暗号化）
+
+```bash
+# 1. .env ファイルを作成・編集
+cp .env.example .env
+vim .env
+
+# 2. 暗号化（パスワード入力を求められる）
+npm run vault:encrypt
+# New vault password: ********
+# Confirm vault password: ********
+# Encrypted .env -> .env.vault
+
+# 3. 暗号化ファイルをコミット
+git add .env.vault
+git commit -m "Add encrypted environment file"
+```
+
+#### 別の環境での復元（復号化）
+
+```bash
+# 1. リポジトリをクローン
+git clone <repository>
+cd <project>
+
+# 2. 依存関係をインストール
+npm install
+
+# 3. 暗号化ファイルを復号化（パスワード入力を求められる）
+npm run vault:decrypt
+# Vault password: ********
+# Decrypted .env.vault -> .env
+```
+
+#### CI/CD での使用
+
+```yaml
+# GitHub Actions の例
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+      - run: npm install
+      - run: npm run vault:decrypt
+        env:
+          VAULT_PASSWORD: ${{ secrets.VAULT_PASSWORD }}
+      - run: npm run deploy
+```
+
+#### パスワードの変更
+
+```bash
+# 現在のパスワードと新しいパスワードを入力
+npm run vault:rekey
+# Enter current password:
+# Current vault password: ********
+#
+# Enter new password:
+# New vault password: ********
+# Confirm vault password: ********
+# Re-encrypted .env.vault with new password.
+```
+
+### ワークフロー
+
+```plantuml
+@startuml
+title Vault ワークフロー
+
+actor 開発者A as devA
+actor 開発者B as devB
+database Git as git
+
+devA -> devA: .env を編集
+devA -> devA: npm run vault:encrypt
+devA -> git: .env.vault をコミット
+
+git -> devB: git pull
+devB -> devB: npm run vault:decrypt
+devB -> devB: .env が復元される
+
+note right of devA
+  パスワードは安全な方法で
+  チームに共有
+end note
+
+@enduml
+```
+
+### セキュリティのベストプラクティス
+
+| Do | Don't |
+|----|-------|
+| 8 文字以上の強力なパスワードを使用 | 短い・推測しやすいパスワードを使用 |
+| パスワードを安全な方法で共有（1Password など） | パスワードを Slack やメールで送信 |
+| `.env.vault` を Git にコミット | `.env` を Git にコミット |
+| 定期的にパスワードを変更（vault:rekey） | 同じパスワードを長期間使用 |
+| CI/CD では Secrets 機能を使用 | CI/CD ログにパスワードを出力 |
+
+### 注意事項
+
+- パスワードを忘れると復号化できなくなります（復旧不可）
+- `.env.vault` を Git に追加しても `.env` は `.gitignore` で除外されています
+- CI/CD 環境では `VAULT_PASSWORD` 環境変数を使用してください
+- 同じ内容でも暗号化するたびに異なる出力になります（ソルトとIVがランダム）
+
+### Vault トラブルシューティング
+
+#### 復号化に失敗する
+
+```
+Error: Invalid password
+```
+
+**原因:** パスワードが正しくない
+
+**解決策:**
+
+1. パスワードを再確認
+2. Caps Lock がオフになっているか確認
+3. パスワードマネージャーから正しいパスワードをコピー
+
+#### .env.vault が見つからない
+
+```
+Error: .env.vault not found
+```
+
+**原因:** 暗号化ファイルが存在しない
+
+**解決策:**
+
+1. `git pull` で最新を取得
+2. `.env.vault` がコミットされているか確認
+3. まだ暗号化されていない場合は `vault:encrypt` を実行
+
+#### パスワードが短すぎる
+
+```
+Error: Password must be at least 8 characters
+```
+
+**原因:** 8 文字未満のパスワードを入力
+
+**解決策:**
+8 文字以上のパスワードを使用してください。推奨は 12 文字以上。
+
+## トラブルシューティング
+
+### 環境変数が読み込まれない
+
+1. `.env` ファイルがプロジェクトルートにあるか確認
+2. `dotenv/config` がエントリーポイントの先頭でインポートされているか確認
+3. 変数名にタイポがないか確認
+
+### Docker 接続エラー
+
+1. Docker Desktop が起動しているか確認
+2. `DOCKER_HOST` 環境変数が正しく設定されているか確認
+3. 必要に応じて `unset DOCKER_HOST` を実行
+
+[^twelve-factor]: The Twelve-Factor App — Config