.env 설정

Sonamu는 환경별로 다른 설정을 적용하기 위해 .env 파일을 사용합니다. 데이터베이스 연결 정보, API 키, 세션 비밀키 등 민감한 정보는 .env 파일에 저장하고 sonamu.config.ts에서 참조합니다.

.env 파일은 절대 Git에 커밋하면 안 됩니다! .gitignore에 .env가 포함되어 있는지 확인하세요.

빠른 시작

.env.example 복사

프로젝트 루트에서 .env.example을 복사하여 .env 파일을 생성합니다.

cp .env.example .env

환경변수 설정

.env 파일을 열어 실제 값으로 수정합니다.

# 예시
DB_HOST=localhost
DB_PORT=5432
DB_USER=postgres
DB_PASSWORD=your-db-password

설정 파일에서 참조

sonamu.config.ts에서 process.env로 환경변수를 읽습니다.

database: {
  defaultOptions: {
    connection: {
      host: process.env.DB_HOST || "0.0.0.0",
      password: process.env.DB_PASSWORD,
    },
  },
}

.env 파일 구조

.env 파일은 KEY=VALUE 형식으로 작성합니다.

# 프로젝트 설정
PROJECT_NAME=MyProject

# 데이터베이스
DB_HOST=localhost
DB_PORT=5432
DB_USER=postgres
DB_PASSWORD=your-db-password

# 세션
SESSION_SECRET=your-session-secret  # 최소 64자
SESSION_SALT=your-session-salt  # 최소 16자

# 스토리지 (fs 또는 s3)
DRIVE_DISK=fs

# AWS S3 (DRIVE_DISK=s3일 때)
AWS_ACCESS_KEY_ID=your-aws-access-key-id
AWS_SECRET_ACCESS_KEY=your-aws-secret-access-key
S3_REGION=ap-northeast-2
S3_BUCKET=my-bucket

# 외부 API
OPENAI_API_KEY=your-openai-api-key

# 워커
DISABLE_WORKER=false

주석은 #으로 시작합니다. 빈 줄은 무시됩니다.

환경별 설정

개발 환경
스테이징
프로덕션

.env.development

# 로컬 개발용 설정
PROJECT_NAME=MyProject-Dev

DB_HOST=localhost
DB_PORT=5432
DB_USER=postgres
DB_PASSWORD=your-dev-password
DATABASE_NAME=myproject_dev

SESSION_SECRET=your-dev-session-secret
SESSION_SALT=your-dev-session-salt

DRIVE_DISK=fs

# 개발용 OpenAI (선택)
OPENAI_API_KEY=sk-***

DISABLE_WORKER=false

특징:

로컬 데이터베이스 사용
파일 시스템 스토리지
간단한 비밀키 (보안 불필요)

.env.staging

# 테스트 서버용 설정
PROJECT_NAME=MyProject-Staging

DB_HOST=staging-db.example.com
DB_PORT=5432
DB_USER=myproject_user
DB_PASSWORD=your-staging-password  # 최소 32자
DATABASE_NAME=myproject_staging

SESSION_SECRET=your-staging-session-secret  # 최소 64자
SESSION_SALT=your-staging-session-salt

DRIVE_DISK=s3
AWS_ACCESS_KEY_ID=your-staging-aws-key-id
AWS_SECRET_ACCESS_KEY=your-staging-aws-secret-key
S3_REGION=ap-northeast-2
S3_BUCKET=myproject-staging

OPENAI_API_KEY=your-staging-openai-key

DISABLE_WORKER=false

특징:

원격 데이터베이스
S3 스토리지
프로덕션과 유사한 환경

.env.production

# 실서버용 설정
PROJECT_NAME=MyProject

DB_HOST=prod-db.example.com
DB_PORT=5432
DB_USER=myproject_prod
DB_PASSWORD=your-production-password  # 최소 64자
DATABASE_NAME=myproject_prod

SESSION_SECRET=your-production-session-secret  # 최소 64자
SESSION_SALT=your-production-session-salt

DRIVE_DISK=s3
AWS_ACCESS_KEY_ID=your-production-aws-key-id
AWS_SECRET_ACCESS_KEY=your-production-aws-secret-key
S3_REGION=ap-northeast-2
S3_BUCKET=myproject-production

OPENAI_API_KEY=your-production-openai-key

DISABLE_WORKER=false

특징:

고가용성 데이터베이스
S3 스토리지 (확장성)
강력한 보안 키

sonamu.config.ts 연동

환경변수를 sonamu.config.ts에서 사용하는 방법입니다.

기본 패턴

import { defineConfig } from "sonamu";

export default defineConfig({
  projectName: process.env.PROJECT_NAME ?? "DefaultName",
  
  database: {
    name: process.env.DATABASE_NAME ?? "database_name",
    defaultOptions: {
      connection: {
        host: process.env.DB_HOST || "0.0.0.0",
        port: Number(process.env.DB_PORT) || 5432,
        user: process.env.DB_USER || "postgres",
        password: process.env.DB_PASSWORD,
      },
    },
  },
  
  // ...
});

Nullish Coalescing vs OR

// 권장: undefined/null만 대체
const name = process.env.PROJECT_NAME ?? "DefaultName";

// undefined, null → "DefaultName"
// ""(빈 문자열) → "" 유지
// 0 → 0 유지

환경변수가 설정되지 않았을 때만 기본값을 사용하려면 ??를 사용하세요. ||는 빈 문자열도 falsy로 처리합니다.

숫자 변환

// ✅ 올바른 방법
port: Number(process.env.DB_PORT) || 5432

// ❌ 잘못된 방법
port: process.env.DB_PORT || 5432  // 문자열 "5432"가 될 수 있음

불린 변환

// ✅ 올바른 방법
enableWorker: !["true", "1"].includes(process.env.DISABLE_WORKER ?? "false")

// 또는
enableCache: process.env.ENABLE_CACHE === "true"

// ❌ 잘못된 방법
enableCache: process.env.ENABLE_CACHE || false  // "false"도 truthy

보안 모범 사례

비밀키 생성

강력한 비밀키 생성하기

# 64자 랜덤 문자열 생성
openssl rand -base64 48

# 또는
node -e "console.log(require('crypto').randomBytes(48).toString('base64'))"

SESSION_SECRET 예시:

SESSION_SECRET=your-64-character-random-session-secret-change-in-production

최소 길이:

SESSION_SECRET: 64자 이상
SESSION_SALT: 16자 이상
DB_PASSWORD: 32자 이상 (프로덕션)

Git 보안

.gitignore 설정

.gitignore

# 환경변수
.env
.env.local
.env.*.local

# 프로덕션 환경변수는 절대 커밋 금지
.env.production

# 테스트용도 허용할 수 있음 (민감 정보 없다면)
# .env.test

.env.example 유지

.env.example

# 실제 값 없이 키만 나열
PROJECT_NAME=

DB_HOST=localhost
DB_PORT=5432
DB_USER=
DB_PASSWORD=

SESSION_SECRET=
SESSION_SALT=

.env.example은 Git에 커밋하여 팀원들이 참고하도록 합니다.

권한 관리

파일 권한 설정

# .env 파일 권한을 소유자만 읽기/쓰기
chmod 600 .env

# 확인
ls -la .env
# -rw------- 1 user user 512 Jan 09 10:00 .env

환경변수 접근 제한

// ✅ 필요한 곳에서만 접근
const dbPassword = process.env.DB_PASSWORD;

// ❌ 로그에 출력 금지
console.log("Password:", process.env.DB_PASSWORD);

// ❌ 클라이언트에 노출 금지
res.send({ secret: process.env.SESSION_SECRET });

CI/CD 환경변수

GitHub Actions

.github/workflows/deploy.yml

jobs:
  deploy:
    steps:
      - name: Deploy
        env:
          DB_HOST: ${{ secrets.DB_HOST }}
          DB_PASSWORD: ${{ secrets.DB_PASSWORD }}
          SESSION_SECRET: ${{ secrets.SESSION_SECRET }}
        run: |
          npm run deploy

Vercel/Netlify

프로젝트 설정 → Environment Variables
각 변수를 개별 추가
환경별로 다른 값 설정 (Production/Preview/Development)

프로덕션 비밀키는 절대 개발/스테이징 환경에 사용하지 마세요!

문제 해결

환경변수가 undefined

증상: process.env.DB_PASSWORD가 undefined원인:

.env 파일이 없음
.env 파일 위치가 잘못됨
변수 이름 오타
서버 재시작 안 함

해결:

# 1. .env 파일 확인
cat .env | grep DB_PASSWORD

# 2. .env 파일 위치 확인 (프로젝트 루트)
ls -la .env

# 3. 서버 재시작
npm run dev

환경변수 값이 적용 안 됨

증상: 환경변수 변경했는데 여전히 이전 값 사용원인:

Node.js 프로세스가 시작할 때만 .env 파일을 읽음
파일 변경 후 서버 재시작 필요

해결:

# 개발 서버 재시작
# Ctrl+C로 종료 후
npm run dev

HMR(Hot Module Replacement)은 코드만 자동 리로드하며, 환경변수는 재시작해야 적용됩니다.

프로덕션에서 환경변수 로드 실패

증상: 로컬은 되는데 프로덕션에서 undefined원인:

프로덕션 서버에 .env 파일이 없음
호스팅 플랫폼의 환경변수 설정 미비

해결:방법 1: 서버에 .env 파일 배포

# SSH로 접속 후
cd /path/to/app
nano .env
# 내용 붙여넣기 후 저장

방법 2: 호스팅 플랫폼 환경변수 사용

Vercel: Project Settings → Environment Variables
AWS EC2: /etc/environment 또는 ~/.bashrc
Docker: docker run -e DB_HOST=... -e DB_PASSWORD=...

다음 단계

데이터베이스 인증 정보

DB 연결 정보를 안전하게 설정하세요

API 키 관리

외부 서비스 API 키를 안전하게 관리하세요

sonamu.config.ts

프로젝트 전체 설정을 구성하세요

인증 설정

인증 및 세션 보안을 설정하세요

시작하기

핵심 개념

데이터베이스

API 개발

프론트엔드 통합

테스팅

고급 기능

도구 & CLI

설정

API 레퍼런스

문제 해결

자주 묻는 질문

빠른 시작

.env 파일 구조

환경별 설정

sonamu.config.ts 연동

기본 패턴

Nullish Coalescing vs OR

숫자 변환

불린 변환

보안 모범 사례

강력한 비밀키 생성하기

.gitignore 설정

.env.example 유지

파일 권한 설정

환경변수 접근 제한

GitHub Actions

Vercel/Netlify

문제 해결

다음 단계

데이터베이스 인증 정보

API 키 관리

sonamu.config.ts

인증 설정

시작하기

핵심 개념

데이터베이스

API 개발

프론트엔드 통합

테스팅

고급 기능

도구 & CLI

설정

API 레퍼런스

문제 해결

자주 묻는 질문

​빠른 시작

​.env 파일 구조

​환경별 설정

​sonamu.config.ts 연동

​기본 패턴

​Nullish Coalescing vs OR

​숫자 변환

​불린 변환

​보안 모범 사례

​강력한 비밀키 생성하기

​.gitignore 설정

​.env.example 유지

​파일 권한 설정

​환경변수 접근 제한

​GitHub Actions

​Vercel/Netlify

​문제 해결

​다음 단계

데이터베이스 인증 정보

API 키 관리

sonamu.config.ts

인증 설정

빠른 시작

.env 파일 구조

환경별 설정

sonamu.config.ts 연동

기본 패턴

Nullish Coalescing vs OR

숫자 변환

불린 변환

보안 모범 사례

강력한 비밀키 생성하기

.gitignore 설정

.env.example 유지

파일 권한 설정

환경변수 접근 제한

GitHub Actions

Vercel/Netlify

문제 해결

다음 단계