KO/EN
문서

deployment

환경변수 관리

Doppler를 통한 시크릿 관리와 CF Pages 연동

환경변수 관리

Modfolio 생태계에서 모든 시크릿과 환경변수는 Doppler를 통해 관리됩니다. 각 앱의 API 키, 데이터베이스 URL, OAuth 시크릿 등을 중앙에서 관리하고 CF Pages에 동기화합니다.

Doppler가 Single Source of Truth

환경변수를 CF Dashboard에 직접 입력하는 것은 권장하지 않습니다. Doppler가 유일한 시크릿 저장소이며, 다른 모든 환경은 Doppler에서 동기화됩니다.

Doppler (원본) → CF Pages 환경변수
                → 로컬 .dev.vars
                → CI/CD 파이프라인

이 구조를 통해 시크릿 분산, 버전 불일치, 누락을 방지합니다.

Doppler 프로젝트 네이밍

프로젝트 유형에 따라 Doppler 프로젝트가 구분됩니다.

프로젝트 유형 Doppler 프로젝트 예시
독립 도메인 앱 앱 이름 (1:1) naviaca, gistcore, modfolio-pay
인프라 앱 (*.modfolio.io) modfolio-universe (공동) modfolio-admin, modfolio-dev, modfolio-docs

독립 도메인 앱은 각각 전용 Doppler 프로젝트를 가집니다. 인프라 앱은 modfolio-universe 프로젝트 아래에서 Config 단위로 분리합니다.

# 독립 도메인 앱
doppler setup --project=naviaca --config=prd

# 인프라 앱
doppler setup --project=modfolio-universe --config=modfolio-docs_prd

환경 구분

Doppler Config는 세 환경으로 구분됩니다.

환경 Doppler Config 용도
Development dev 로컬 개발
Staging stg Preview 배포, QA
Production prd 프로덕션 배포

각 환경의 변수 값은 독립적으로 관리됩니다. 예를 들어 DATABASE_URL은 dev에서는 로컬 DB를, prd에서는 프로덕션 DB를 가리킵니다.

Doppler에서 CF Pages로 동기화

CLI로 JSON 다운로드

# Production 환경변수를 JSON으로 확인
doppler secrets download --project=naviaca --config=prd --format=json --no-file

# env 파일로 임시 저장
doppler secrets download --project=naviaca --config=prd --format=env --no-file > .env.production

주의: 다운로드한 파일은 작업 완료 후 즉시 삭제하세요. .env* 파일은 .gitignore에 포함되어야 합니다.

Doppler Integration (자동 동기화)

Doppler Dashboard → 프로젝트 → Integrations → Cloudflare Pages 선택 → API 토큰 입력 → 대상 Pages 프로젝트와 환경 매핑. 통합을 설정하면 Doppler에서 변수를 수정할 때 CF Pages에 자동 반영됩니다.

NPM_TOKEN 설정

Modfolio 생태계의 private 패키지(@modfolio/contracts 등)는 GitHub Packages에 게시됩니다. CF Pages 빌드에서 이 패키지를 설치하려면 NPM_TOKEN이 필요합니다.

# GitHub Personal Access Token (read:packages 권한)
NPM_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

CF Pages 환경변수(Settings → Environment variables → Production & Preview)에 추가합니다. 프로젝트 루트에 .npmrc 파일도 필요합니다.

# .npmrc
@modfolio:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=${NPM_TOKEN}

Preview vs Production 환경변수 분리

CF Pages는 Production과 Preview 환경의 변수를 독립적으로 관리합니다.

환경 대상 브랜치 Doppler Config
Production main prd
Preview main 외 모든 브랜치 stg

Dashboard에서 Settings → Environment variables의 [Production] / [Preview] 탭으로 분리 설정합니다. 프로덕션 시크릿이 Preview에 노출되지 않도록 주의하세요.

필수 분리 항목

변수 Production Preview
DATABASE_URL 프로덕션 DB 스테이징 DB
AUTH_SECRET 프로덕션 시크릿 테스트 시크릿
PUBLIC_APP_URL https://naviaca.com Preview URL
DOPPLER_ENV prd stg

로컬 개발 환경

로컬에서는 Doppler CLI를 통해 환경변수를 주입합니다.

doppler run -- bun run dev                    # 환경변수 주입 후 dev 서버 실행
doppler secrets download --config=dev --format=env --no-file > .dev.vars  # Wrangler용

.dev.vars는 Wrangler 로컬 개발 서버가 읽는 파일입니다. 반드시 .gitignore에 포함시키세요.

다음 단계

ESC

검색어를 입력하세요