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로 검증합니다.

개발 모드 시작은 한 줄입니다.

# 개발 모드 (로컬 DB 기동 + pending migration + API watch 모드)
mise run dev   # 또는 pnpm dev

mise run dev는 Docker 확인 → .env.development 자동 생성 → 로컬 PostGIS 기동 → migration → API 부팅을 처리하며, 여러 번 실행해도 안전합니다(각 단계가 멱등). Docker Desktop 또는 OrbStack이 실행 중이어야 합니다.

개별 단계가 필요할 때는 분리해서 실행할 수 있습니다.

# 로컬 데이터베이스 시작/중지 (PostGIS, 127.0.0.1:15432)
pnpm db:start
pnpm db:stop

# 스키마 생성 (최초 1회)
pnpm migration:run

# 개발 서버 (watch 모드)
pnpm start:dev

실데이터 디버깅이 필요할 때는 로컬 API를 dev 클러스터 DB에 붙여서 실행할 수 있습니다.

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

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

클러스터 연결 모드에서는 DB 자격증명을 클러스터 Secret(momo-postgres-auth)에서 읽어 환경 변수로 주입합니다. kubeconfig는 인프라 관리자에게 받아 ~/.kube/config로 저장하고, 팀 Tailscale 네트워크에 연결되어 있어야 합니다.

새 환경 변수 추가하기

  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 호스트. .env.example은 로컬 개발 기본값 127.0.0.1 사용
DB_PORT 5432 PostgreSQL 포트. .env.example은 로컬 개발 기본값 15432 사용
DB_USERNAME postgres PostgreSQL 사용자. 로컬 개발 DB(compose) 기본 사용자
DB_PASSWORD '' PostgreSQL 비밀번호. 로컬 개발 기본값 momo (compose 기본값과 일치)
DB_DATABASE postgres PostgreSQL 데이터베이스 이름. 로컬 개발 기본값 momo (compose 기본값과 일치)
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