env

name	env
description	환경 설정 관리를 위한 가이드를 실행합니다.
user-invocable	true

Environment Configuration Skill

환경 설정 관리를 위한 가이드를 실행합니다.

핵심 원칙

1. 코드와 설정 분리 (12-Factor App)
2. 환경별 설정 관리
3. 민감 정보 보호
4. 기본값 제공
5. 유효성 검증

환경 변수 관리

.env 파일 구조

# .env.example (버전 관리에 포함)
NODE_ENV=development
PORT=3000

# Database
DATABASE_URL=postgresql://user:pass@localhost:5432/db
DATABASE_POOL_SIZE=10

# Redis
REDIS_URL=redis://localhost:6379

# API Keys (실제 값 대신 플레이스홀더)
API_KEY=your_api_key_here
JWT_SECRET=your_jwt_secret_here

# Feature Flags
FEATURE_NEW_UI=false

환경별 파일

.env                 # 기본 (공통)
.env.local           # 로컬 오버라이드 (gitignore)
.env.development     # 개발 환경
.env.staging         # 스테이징 환경
.env.production      # 프로덕션 환경
.env.test            # 테스트 환경

로딩 우선순위

1. 시스템 환경 변수
2. .env.{NODE_ENV}.local
3. .env.{NODE_ENV}
4. .env.local
5. .env

유효성 검증

Node.js (Zod)

import { z } from 'zod';

const envSchema = z.object({
  NODE_ENV: z.enum(['development', 'staging', 'production', 'test']),
  PORT: z.string().transform(Number).default('3000'),
  DATABASE_URL: z.string().url(),
  REDIS_URL: z.string().url().optional(),
  JWT_SECRET: z.string().min(32),
  API_KEY: z.string().min(1),
  LOG_LEVEL: z.enum(['debug', 'info', 'warn', 'error']).default('info'),
});

export const env = envSchema.parse(process.env);

Node.js (envalid)

import { cleanEnv, str, port, url, bool } from 'envalid';

export const env = cleanEnv(process.env, {
  NODE_ENV: str({ choices: ['development', 'staging', 'production', 'test'] }),
  PORT: port({ default: 3000 }),
  DATABASE_URL: url(),
  JWT_SECRET: str({ desc: 'Secret for JWT signing' }),
  ENABLE_CACHE: bool({ default: true }),
});

Python (pydantic)

from pydantic_settings import BaseSettings

class Settings(BaseSettings):
    node_env: str = "development"
    port: int = 3000
    database_url: str
    jwt_secret: str
    enable_cache: bool = True

    class Config:
        env_file = ".env"

settings = Settings()

설정 구조화

Config 객체

// config/index.ts
export const config = {
  app: {
    name: env.APP_NAME,
    port: env.PORT,
    env: env.NODE_ENV,
  },
  database: {
    url: env.DATABASE_URL,
    poolSize: env.DATABASE_POOL_SIZE,
  },
  redis: {
    url: env.REDIS_URL,
    ttl: env.REDIS_TTL,
  },
  auth: {
    jwtSecret: env.JWT_SECRET,
    jwtExpiresIn: env.JWT_EXPIRES_IN,
  },
  features: {
    newUi: env.FEATURE_NEW_UI,
  },
} as const;

환경별 설정

// config/database.ts
const configs = {
  development: {
    poolSize: 5,
    logging: true,
  },
  production: {
    poolSize: 20,
    logging: false,
  },
  test: {
    poolSize: 1,
    logging: false,
  },
};

export const dbConfig = configs[env.NODE_ENV];

시크릿 관리

절대 금지

# ❌ 절대 하지 말 것
git add .env
git add credentials.json
git add *.pem

.gitignore

# Environment
.env
.env.local
.env.*.local
!.env.example

# Secrets
*.pem
*.key
credentials.json
secrets/

프로덕션 시크릿 관리

옵션:
├── 환경 변수 (CI/CD에서 주입)
├── AWS Secrets Manager
├── HashiCorp Vault
├── Google Secret Manager
└── Azure Key Vault

Docker Secrets

# docker-compose.yml
services:
  app:
    secrets:
      - db_password
    environment:
      DATABASE_PASSWORD_FILE: /run/secrets/db_password

secrets:
  db_password:
    file: ./secrets/db_password.txt

Feature Flags

간단한 구현

// config/features.ts
export const features = {
  newDashboard: env.FEATURE_NEW_DASHBOARD === 'true',
  betaApi: env.FEATURE_BETA_API === 'true',
  darkMode: env.FEATURE_DARK_MODE === 'true',
};

// 사용
if (features.newDashboard) {
  renderNewDashboard();
}

환경별 기본값

const featureDefaults = {
  development: {
    newDashboard: true,
    betaApi: true,
  },
  production: {
    newDashboard: false,
    betaApi: false,
  },
};

체크리스트

설정 파일

• .env.example 작성
• .gitignore에 .env 추가
• 환경별 설정 분리
• 유효성 검증 구현

보안

• 민감 정보 하드코딩 없음
• 프로덕션 시크릿 안전하게 관리
• 로그에 민감 정보 출력 안됨
• 에러 메시지에 시크릿 노출 안됨

문서화

• 필수 환경 변수 문서화
• 기본값 명시
• 형식/제약조건 설명

출력 형식

## Environment Configuration

### .env.example
```bash
# 환경 변수 템플릿

Validation Schema

// 유효성 검증 코드

Config Structure

// 설정 구조

Environment Matrix

변수	개발	스테이징	프로덕션
LOG_LEVEL	debug	info	warn

Secrets Management

[시크릿 관리 방안]

---

요청에 맞는 환경 설정을 구성하세요.