Skip to content

Environment Variables

Jump to bottom
JinmuGo edited this page Aug 7, 2026 · 6 revisions

Environment Variables

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

역할 분리

담당 역할
앱 (@nestjs/config) .env 파일 + process.env 로드 후 zod 검증. 실행 방법(Docker, 프로덕션 등)과 무관하게 동작
mise 셸 활성화 시 .env.development 자동 로드, 로컬 개발 인프라(PostgreSQL, Redis) 실행 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로 검증합니다.

# 로컬 PostgreSQL 시작/중지
pnpm db:start
pnpm db:stop

# DB role과 앱 DB 생성 (최초 1회, .env.example 기준값)
createuser -h /tmp postgres
createdb -h /tmp -O postgres momo

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

mise run setup의 db-init은 OS 사용자명의 superuser만 생성합니다. 위 createuser / createdb 단계를 건너뛰면 role "postgres" does not exist / database "momo" does not exist 에러로 부팅에 실패합니다. 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 사용자. 로컬에서는 같은 이름의 role을 createuser로 생성해야 함
DB_PASSWORD '' PostgreSQL 비밀번호
DB_DATABASE postgres PostgreSQL 데이터베이스 이름. .env.example은 로컬 개발용으로 momo 사용하며, 같은 이름의 DB를 createdb로 생성해야 함
DB_SSL false SSL 연결 사용 여부
DB_SSL_CA — SSL CA 인증서 (PEM 형식, DB_SSL=true일 때 사용)
DB_SYNCHRONIZE false TypeORM synchronize 활성화 여부. .env.example은 로컬 개발용으로 true 설정. 클러스터/공유 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