Skip to content

Environment Variables

Jump to bottom
Jinmu Go edited this page Aug 19, 2026 · 6 revisions

Environment Variables

환경 변수는 앱(@nestjs/config + zod) 이 직접 로드·검증하고, mise 는 환경별 .env 파일을 로드합니다.

역할 분리

담당 역할
앱 (@nestjs/config) .env 파일 + process.env 로드 후 zod 검증. 실행 방법(Docker, 프로덕션 등)과 무관하게 동작
mise 셸 활성화 시 .env.development 자동 로드, 툴체인(Node, pnpm, kubectl 등) 설치와 개발 task 제공

포트

  • .env 파일의 PORT 값을 사용하며, 없으면 기본값 3000
  • 실제 값 파일은 gitignore 대상이므로 포트를 바꾸고 싶으면 환경별 .env 파일에서 변경

파일 구조

.env.development  # development 실제 값 (gitignore 대상)
.env.production   # production 실제 값 (gitignore 대상)
.env.example      # 변수 목록 (커밋, 신규 팀원은 복사해서 사용)
mise.toml         # development 환경 설정 (_.file = ".env.development")
src/config/env.ts # zod 스키마 + validateEnv 함수

동작 방식

  1. 부팅 시 ConfigModule.forRoot({ validate: validateEnv })가 .env + process.env를 zod 스키마로 검증
  2. 검증 실패 시 명확한 에러와 함께 부팅 중단 (fail-fast)
Error: Invalid environment variables:
- PORT: Invalid input: expected number, received NaN
  1. 코드에서는 ConfigService로 타입 안전하게 접근
const config = app.get(ConfigService) as ConfigService<Env, true>
config.get('PORT', { infer: true }) // number

로컬 개발 실행

mise 셸 활성화(mise activate) 상태에서 디렉토리에 진입하면 .env.development가 자동으로 로드되고, 앱은 process.env와 .env를 읽어 zod로 검증합니다.

개발 서버는 dev 클러스터의 PostgreSQL에 port-forward로 붙여서 실행합니다.

# 클러스터 접속 확인 (kubectl·kubeconfig·권한)
mise run cluster-check

# 개발 서버 (watch 모드, dev 클러스터 DB 연결)
mise run dev-api

# DB 터널만 필요할 때 (127.0.0.1:15432)
mise run db-forward-dev

mise run dev-api는 DB 자격증명을 클러스터 Secret(momo-postgres-auth)에서 읽어 환경 변수로 주입하므로 .env.development에 DB_* 값을 채울 필요가 없습니다. kubeconfig는 인프라 관리자에게 받아 ~/.kube/config로 저장하고, 팀 Tailscale 네트워크에 연결되어 있어야 합니다. OCI_REGION이 비어 있어도 S3Client 초기화 에러로 부팅에 실패하므로, .env.example을 복사한 뒤 최소한 리전 값은 채워야 합니다.

새 환경 변수 추가하기

  1. src/config/env.ts의 envSchema에 필드 추가
  2. .env.example에 변수 추가
  3. 필요하면 mise.toml에도 참조 추가
  4. 팀에 .env.development / .env.production 갱신 공유
// src/config/env.ts
const envSchema = z.object({
  // ...
  // biome-ignore lint/style/useNamingConvention: 환경 변수 이름과 동일하게 유지
  DB_HOST: z.string().default('localhost'),
})

스키마 키는 환경 변수 이름(CONSTANT_CASE)을 그대로 쓰므로 biome 네이밍 규칙 예외 주석(biome-ignore)을 붙입니다.

현재 변수 목록

앱

변수 기본값 설명
NODE_ENV development development / test / production
PORT 3000 서버 포트
CORS_ORIGINS — (필수) 허용 오리진 목록 (쉼표 구분)

Database

변수 기본값 설명
DB_HOST localhost PostgreSQL 호스트
DB_PORT 5432 PostgreSQL 포트
DB_USERNAME postgres PostgreSQL 사용자. 클러스터 연결 모드(mise run dev-api)에서는 클러스터 Secret에서 자동 주입
DB_PASSWORD '' PostgreSQL 비밀번호. 클러스터 연결 모드에서는 클러스터 Secret에서 자동 주입
DB_DATABASE postgres PostgreSQL 데이터베이스 이름. 클러스터 연결 모드에서는 클러스터 Secret에서 자동 주입
DB_SSL false SSL 연결 사용 여부
DB_SSL_CA — SSL CA 인증서 (PEM 형식, DB_SSL=true일 때 사용)
DB_SYNCHRONIZE false TypeORM synchronize 활성화 여부. 클러스터/공유 DB에서는 절대 true 금지

OCI Object Storage (S3 compatible)

변수 기본값 설명
OCI_REGION ap-hyderabad-1 OCI Object Storage 리전. 빈 문자열이면 S3Client 초기화 에러로 부팅 실패
OCI_NAMESPACE — OCI Object Storage namespace (production 필수)
OCI_S3_ACCESS_KEY — S3 compatible access key (production 필수)
OCI_S3_SECRET_KEY — S3 compatible secret key (production 필수)
OCI_BUCKET_NAME_DEV momo-bucket-dev development 버킷 이름
OCI_BUCKET_NAME_PROD momo-bucket-prod production 버킷 이름

Production 필수 변수

NODE_ENV=production일 때 다음 변수는 비어 있으면 zod 검증에서 실패합니다.

  • OCI_NAMESPACE
  • OCI_S3_ACCESS_KEY
  • OCI_S3_SECRET_KEY

Clone this wiki locally