環境変数管理ガイド¶

このドキュメントでは、プロジェクトで使用する環境変数について説明します。

dotenv とは¶

概要¶

dotenv は、環境変数を .env ファイルから読み込むためのライブラリです。アプリケーションの設定値をソースコードから分離し、環境ごとに異なる設定を簡単に管理できます。

なぜ dotenv を使うのか¶

セキュリティ: パスワードや API キーをソースコードにハードコーディングせず、Git 管理外のファイルで管理
環境の分離: 開発・ステージング・本番環境で異なる設定を簡単に切り替え
チーム開発: 各開発者が自分の環境に合わせた設定を使用可能
12-Factor App: The Twelve-Factor App の設定管理ベストプラクティスに準拠

仕組み¶

uml diagram

セットアップ方法¶

1. パッケージのインストール¶

npm install dotenv

2. .env ファイルの作成¶

# テンプレートからコピー
cp .env.example .env

# または新規作成
touch .env

3. .env ファイルの編集¶

# プロジェクトルート/.env
MKDOCS_PORT=8000

4. アプリケーションでの読み込み¶

// 方法1: エントリーポイントの先頭でインポート（推奨）
import 'dotenv/config';

// 方法2: 明示的に config() を呼び出し
import * as dotenv from 'dotenv';
dotenv.config();

// 環境変数を使用
const port = process.env.MKDOCS_PORT || 8000;

5. .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 環境での正しい設定:

# 正しい形式
DOCKER_HOST=npipe:////./pipe/docker_engine

# 誤った形式（エラーになる）
DOCKER_HOST=npipe://./pipe/docker_engine

解決方法:

# 環境変数を削除（Docker Desktop が自動設定する）
unset DOCKER_HOST

注意: 本プロジェクトの gulp タスクは Windows 環境で自動的に DOCKER_HOST を正規化します。

セキュリティに関する注意¶

.env ファイルは Git にコミットしないでください
機密情報（API キー、パスワード等）は .env ファイルで管理してください
本番環境では環境変数を直接設定することを推奨します

.env ファイルの読み込み優先順位¶

uml diagram

.env ファイルの書き方¶

# コメントは # で始める

# 基本的な書き方
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` ファイルのみに依存

// デフォルト値の設定例
const port = process.env.MKDOCS_PORT || 8000;
const nodeEnv = process.env.NODE_ENV || 'development';

Vault（暗号化・復号化）¶

概要¶

Vault は .env ファイルを安全に暗号化・復号化するためのツールです。暗号化されたファイル（.env.vault）は Git にコミットでき、チームメンバー間で安全に環境変数を共有できます。

なぜ Vault を使うのか¶

チーム間での秘密情報共有: .env を直接共有せず、暗号化して Git 管理
環境の再現性: 新しいメンバーがすぐに開発環境を構築可能
セキュリティ: AES-256-GCM による強力な暗号化
シンプルさ: 外部サービス不要、パスワードのみで運用

暗号化仕様¶

uml diagram

項目	値
暗号化アルゴリズム	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 を作成します。

npm run vault:encrypt

動作フロー:

uml diagram

オプション:

環境変数	説明
`VAULT_PASSWORD`	パスワードを事前に指定（対話入力をスキップ）

例:

# 対話的にパスワードを入力
npm run vault:encrypt

# 環境変数でパスワードを指定（CI/CD 用）
VAULT_PASSWORD=my-secret-password npm run vault:encrypt

vault:decrypt¶

.env.vault ファイルを復号化して .env を復元します。

npm run vault:decrypt

動作フロー:

uml diagram

例:

# 対話的にパスワードを入力
npm run vault:decrypt

# 環境変数でパスワードを指定
VAULT_PASSWORD=my-secret-password npm run vault:decrypt

vault:view¶

.env.vault の内容を復号化して表示します。ファイルは作成されません。

npm run vault:view

用途:

暗号化された内容を確認したいが、.env ファイルを作成したくない場合
CI/CD パイプラインでのデバッグ
復号化前の内容確認

例:

# 内容を確認
npm run vault:view

# 出力例:
# --- .env.vault contents ---
#
# DATABASE_URL=mysql://user:pass@localhost:3306/mydb
# API_KEY=sk-xxxxxxxxxxxx
#
# --- end ---

vault:rekey¶

現在のパスワードで復号化し、新しいパスワードで再暗号化します。

npm run vault:rekey

動作フロー:

uml diagram

用途:

定期的なパスワードローテーション
チームメンバーの退職時
パスワード漏洩の疑いがある場合

使い方¶

初回セットアップ（暗号化）¶

# 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"

別の環境での復元（復号化）¶

# 1. リポジトリをクローン
git clone <repository>
cd <project>

# 2. 依存関係をインストール
npm install

# 3. 暗号化ファイルを復号化（パスワード入力を求められる）
npm run vault:decrypt
# Vault password: ********
# Decrypted .env.vault -> .env

CI/CD での使用¶

# 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

パスワードの変更¶

# 現在のパスワードと新しいパスワードを入力
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.

ワークフロー¶

uml diagram

セキュリティのベストプラクティス¶

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 文字以上。

トラブルシューティング¶

環境変数が読み込まれない¶

.env ファイルがプロジェクトルートにあるか確認
dotenv/config がエントリーポイントの先頭でインポートされているか確認
変数名にタイポがないか確認

Docker 接続エラー¶

Docker Desktop が起動しているか確認
DOCKER_HOST 環境変数が正しく設定されているか確認
必要に応じて unset DOCKER_HOST を実行