Env Switch

📋 환경별 완벽한 설정

로컬 개발 환경 (.env)

Git에 커밋하지 않음 (.gitignore에 포함됨)

# Application
APP_NAME="YKP ERP (Local)"
APP_ENV=local
APP_DEBUG=true
APP_URL=http://127.0.0.1:8000

# Local PostgreSQL Database
DB_CONNECTION=pgsql_local
DB_HOST_LOCAL=localhost
DB_PORT_LOCAL=5432
DB_DATABASE_LOCAL=ykp_dashboard_local
DB_USERNAME_LOCAL=postgres
DB_PASSWORD_LOCAL=1234  # 본인 로컬 비밀번호

# File-based drivers (빠른 개발)
SESSION_DRIVER=file
SESSION_LIFETIME=120
CACHE_STORE=file
QUEUE_CONNECTION=sync

# Logging
LOG_CHANNEL=stack
LOG_LEVEL=debug

# Feature Flags (로컬 테스트)
FEATURE_EXCEL_INPUT=true
FEATURE_ADVANCED_REPORTS=true
FEATURE_UI_V2=false
FEATURE_SUPABASE_ENHANCED=false

프로덕션 환경 (Railway)

Railway 환경변수 사용 (.env 파일 무시됨!)

# Application
APP_NAME="YKP ERP"
APP_ENV=production
APP_DEBUG=false
APP_URL=${RAILWAY_PUBLIC_DOMAIN}

# Supabase PostgreSQL (Connection Pooler)
DB_CONNECTION=pgsql
DB_HOST=aws-1-ap-southeast-1.pooler.supabase.com
DB_PORT=5432
DB_DATABASE=postgres
DB_USERNAME=postgres.qwafwqxdcfpqqwpmphkm
DB_PASSWORD=<Railway Secrets에 저장>
DB_SSLMODE=require

# Database drivers (분산 환경)
SESSION_DRIVER=database
CACHE_STORE=database
QUEUE_CONNECTION=database

# Logging (Railway stderr)
LOG_CHANNEL=stderr
LOG_LEVEL=error

# Feature Flags (프로덕션)
FEATURE_EXCEL_INPUT=true
FEATURE_ADVANCED_REPORTS=true
FEATURE_UI_V2=false
FEATURE_SUPABASE_ENHANCED=true

🔄 전환 절차

시나리오 1: 프로덕션 → 로컬 전환

사용자 요청: "로컬 개발 환경으로 돌아가고 싶어요"

안내 절차:

1. 현재 상태 확인:

   grep -E "^(APP_ENV|DB_CONNECTION)=" .env
   

   → APP_ENV=production 감지 시 경고!

2. 경고 메시지:

   🚨 프로덕션 설정 감지!

   현재 .env 파일이 프로덕션 설정을 사용하고 있습니다. 로컬 개발용으로 전환하시겠습니까?

   ⚠️ 주의: 프로덕션은 Railway 환경변수로만 관리됩니다!

3. 로컬 설정 템플릿 제공:

   ✅ 로컬 개발 환경 설정

   .env 파일을 다음과 같이 수정하세요:

   APP_NAME="YKP ERP (Local)"
   APP_ENV=local
   APP_DEBUG=true
   APP_URL=http://127.0.0.1:8000
   
   DB_CONNECTION=pgsql_local
   DB_HOST_LOCAL=localhost
   DB_DATABASE_LOCAL=ykp_dashboard_local
   DB_USERNAME_LOCAL=postgres
   DB_PASSWORD_LOCAL=1234
   
   SESSION_DRIVER=file
   CACHE_STORE=file
   QUEUE_CONNECTION=sync
   

   또는 .env.example 파일을 복사:

   cp .env.example .env
   php artisan key:generate
   

4. 후속 조치 안내:

   📋 다음 단계:
   
   1. PostgreSQL 서버 시작:
      postgresql-17.6-2-windows-x64-binaries/bin/pg_ctl.exe -D postgresql-data start
   
   2. 캐시 클리어:
      php artisan optimize:clear
   
   3. 서버 재시작:
      php artisan serve
   
   4. 테스트 로그인:
      http://127.0.0.1:8000
      계정: [email protected] / password
   

시나리오 2: 로컬 → 프로덕션 배포 준비

사용자 요청: "Railway에 배포하려고 하는데, 프로덕션 설정 확인해줘"

안내 절차:

1. 로컬 .env 상태 확인:

   ✅ 로컬 환경 감지

   현재 .env 파일: 로컬 개발 설정 (정상) Git에 커밋되지 않음 (.gitignore로 보호됨)

2. Railway 환경변수 체크리스트 제공:

   📋 Railway 배포 체크리스트

   Railway Dashboard → Your Service → Variables에 다음 설정:

   필수 환경변수:

   • APP_NAME="YKP ERP"
   • APP_ENV=production
   • APP_KEY=<php artisan key:generate --show 출력>
   • APP_DEBUG=false
   • APP_URL=${RAILWAY_PUBLIC_DOMAIN}

   Supabase DB (Railway Secrets에 저장):

   • DB_CONNECTION=pgsql
   • DB_HOST=aws-1-ap-southeast-1.pooler.supabase.com
   • DB_PORT=5432
   • DB_DATABASE=postgres
   • DB_USERNAME=postgres.qwafwqxdcfpqqwpmphkm
   • DB_PASSWORD=<Supabase 비밀번호> 🔒
   • DB_SSLMODE=require

   Session/Cache/Queue:

   • SESSION_DRIVER=database
   • CACHE_STORE=database
   • QUEUE_CONNECTION=database

   Logging:

   • LOG_CHANNEL=stderr
   • LOG_LEVEL=error

3. 보안 경고:

   🔒 보안 주의사항

   ❌ .env 파일을 Git에 커밋하지 마세요! ✅ Railway 환경변수에서 관리 ✅ DB_PASSWORD는 Railway Secrets에 저장 ✅ Supabase 백업 생성 후 배포

🚨 잘못된 설정 감지

혼합 설정 (가장 위험!)

증상: APP_ENV=local인데 DB_CONNECTION=pgsql (Supabase)

경고 메시지:

🚨 위험: 환경 설정 불일치!

현재 설정:
- APP_ENV: local (로컬 개발 모드)
- DB_CONNECTION: pgsql (Supabase 프로덕션 DB!)

⚠️ 이 상태로 작업하면 프로덕션 데이터에 영향을 줄 수 있습니다!

즉시 수정:
APP_ENV=local → DB_CONNECTION=pgsql_local 사용해야 함!

.env 파일 수정:
DB_CONNECTION=pgsql_local
DB_DATABASE_LOCAL=ykp_dashboard_local

수정 후:
php artisan optimize:clear

💡 환경 분리 베스트 프랙티스

절대 규칙

1. 로컬 개발:

   • ✅ .env 파일 사용 (Git ignored)
   • ✅ APP_ENV=local
   • ✅ DB_CONNECTION=pgsql_local
   • ✅ File-based drivers (session/cache/queue)

2. 프로덕션 (Railway):

   • ✅ Railway 환경변수 사용
   • ✅ .env 파일 무시됨
   • ✅ APP_ENV=production
   • ✅ DB_CONNECTION=pgsql (Supabase)
   • ✅ Database drivers (분산 환경)

3. 금지 사항:

   • ❌ .env 파일을 Git에 커밋
   • ❌ 주석 처리로 환경 전환
   • ❌ .env.local 사용 (Laravel 작동 안함!)
   • ❌ 프로덕션 DB를 로컬에서 직접 연결

왜 .env.local은 안되나?

문제 발견 과정 (지금까지 대화 기반):

시도 1: .env에 프로덕션 설정, .env.local에 로컬 설정
결과: ❌ Laravel이 .env.local 무시함

이유: Laravel은 APP_ENV=production일 때 .env.local을 로드하지 않음
→ 닭이 먼저냐 달걀이 먼저냐 문제!

올바른 해결책:

• 로컬: .env (Git ignored)
• 프로덕션: Railway 환경변수 (파일 아님!)

📊 전환 완료 보고서

전환 완료 후 다음 형식으로 보고:

✅ 환경 전환 완료

이전 환경: production (Supabase)
새 환경: local (localhost PostgreSQL)

변경된 설정:
- APP_ENV: production → local
- DB_CONNECTION: pgsql → pgsql_local
- SESSION_DRIVER: database → file
- CACHE_STORE: database → file

✅ 캐시 클리어: 완료
✅ 환경 검증: 통과

📋 다음 단계:
1. 서버 재시작: php artisan serve
2. 로그인 테스트: http://127.0.0.1:8000
3. DB 연결 확인: [email protected] / password

💡 프로덕션 배포 시:
- Railway 환경변수 사용 (`.env` 파일 무시)
- CLAUDE.md "Railway Production Environment" 섹션 참조

🎓 학습 내용 요약

이 Skill을 통해 배운 핵심:

1. Laravel 환경 파일 우선순위:

   • .env > .env.local (단, production 모드에서는 .env.local 무시!)
   • Railway 환경변수 > .env 파일

2. 환경별 드라이버 전략:

   • 로컬: File-based (빠름, 독립적)
   • 프로덕션: Database-based (분산 환경)

3. Git 관리 전략:

   • .env → Git ignored (로컬 비밀정보 포함)
   • .env.example → Git tracked (템플릿)
   • .env.production.example → Git tracked (가이드)
   • Railway 환경변수 → 플랫폼 관리

다음에 환경 전환 필요 시:

1. 절대 주석 처리 금지!
2. .env 파일 전체 교체
3. 캐시 클리어 (php artisan optimize:clear)
4. 서버 재시작