# ========================================== # 프로젝트 전역 설정 # ========================================== PROJECT_NAME=project APP_ENV=development BUILD_MODE=development FRONTEND_DIR=frontend BACKEND_DIR=backend # ========================================== # 포트 설정 # # 컨테이너 포트 매핑뿐 아니라 **호스트에서 띄우는 vite dev 서버**도 이 값을 따른다. # (frontend/vite.config.ts 가 이 파일을 직접 읽는다 — FRONTEND_PORT 로 열고 # /api 프록시는 BACKEND_PORT 로 보낸다. 포트를 바꾸면 CORS_ORIGIN 도 함께 고칠 것) # ========================================== FRONTEND_PORT=5173 BACKEND_PORT=3000 WEBSOCKET_PORT=3001 DB_PORT=5432 REDIS_PORT=6379 # ========================================== # 내부 네트워크 (compose app-network · edge) # # 서브넷을 고정한다 — 메일 엔진은 app-network 대역만 신뢰한다 (게이트웨이 로그인·자동 차단 예외, mail/README.md). # APP_NETWORK_SUBNET : backend·db·redis·mail(·mailpit) — 사설 대역, /24 ~ /28 (mail setup 이 검사한다) # EDGE_NETWORK_SUBNET : frontend ↔ backend 전용 (frontend 는 app-network 에 붙지 않는다) # 도커 기본 주소 풀(172.17~31.x, 192.168.x) 밖의 값이라 자동으로 배정되는 네트워크와 겹치지 않는다. # 같은 호스트의 다른 프로젝트와 겹치면 up 이 "Pool overlaps" 로 실패한다 → 다른 /24 로 바꾸고 setup 을 다시 실행한다. # ========================================== APP_NETWORK_SUBNET=172.16.71.0/24 EDGE_NETWORK_SUBNET=172.16.72.0/24 # ========================================== # Database 설정 # ========================================== DB_IMAGE=postgres:15-alpine DB_USER=app_user DB_PASSWORD=change-me-in-local-env DB_NAME=project_db DB_DATA_DIR=./data/postgres # ========================================== # Redis 설정 # ========================================== REDIS_IMAGE=redis:7-alpine REDIS_PASSWORD=change-me-in-local-env REDIS_DATA_DIR=./data/redis # ========================================== # 화면·API 주소 — 같은 주소(origin) 배포 (docs/mail/api-contract.md 머리말) # # 브라우저는 화면과 같은 주소의 /api 를 부른다 (개발은 vite 프록시, 운영은 프론트 nginx 가 백엔드로 넘긴다). # - CORS_ORIGIN : 화면의 주소(origin). 상태 변경 요청의 출처 검사에 쓴다 — FRONTEND_PORT 를 바꾸면 함께 고칠 것 # - BACKEND_API_URL : 화면 주소 + /api. 앱은 쓰지 않고, 운영 기동 때 공개 주소인지 검사하는 데만 쓴다 # - TRUST_PROXY : 백엔드 앞 프록시 홉 수. 개발은 vite 프록시 하나라 1 (비우면 1) # ========================================== BACKEND_API_URL=http://localhost:5173/api CORS_ORIGIN=http://localhost:5173 TRUST_PROXY=1 # ========================================== # Rate Limiting (API 남용 방지) # 미설정 시 백엔드 기본값(60초 / 100회) 사용 # ========================================== THROTTLE_TTL_MS=60000 THROTTLE_LIMIT=100 # ========================================== # DB 스키마 동기화 (개발 전용, 기본 false) # true 로 켜면 엔티티 변경이 DB 에 자동 반영되어 빠르게 실험할 수 있지만, # 그 상태에서는 migration:generate 가 "변경 없음"만 내놓는다. # 운영으로 갈 코드라면 꺼둔 채 마이그레이션으로 관리할 것. # (운영 환경에서는 이 값과 무관하게 항상 비활성화된다) # ========================================== DB_SYNCHRONIZE=false # ========================================== # 선택적 서비스 (Compose profiles) # # 기본값 = mail — 메일 엔진(Stalwart)과 개발용 Mailpit 을 띄운다. # 직원 로그인이 메일 엔진에 의존하므로 개발에서도 켜 두는 것을 권장한다. # (redis 와 frontend 컨테이너는 기동하지 않는다) # # mail 메일 엔진 + Mailpit (기본) → COMPOSE_PROFILES=mail # redis 캐시·세션 공유가 필요해질 때 → COMPOSE_PROFILES=mail,redis # frontend vite 를 컨테이너로 띄워야 할 때 → COMPOSE_PROFILES=mail,frontend # # 일회성으로 켜려면: docker compose --profile redis ... up -d # # ⚠️ 개발 환경의 프론트엔드는 호스트에서 띄우는 것이 기본이다 (`cd frontend && npm run dev`). # 컨테이너 vite 는 바인드 마운트 때문에 첫 서빙까지 수 분이 걸린다. # ========================================== COMPOSE_PROFILES=mail # ========================================== # 파일 업로드 (로컬 디스크) # # UPLOAD_DATA_DIR 는 개발 전용 — 호스트 디렉터리에 바로 쌓여 열어 볼 수 있다 (운영은 named volume _uploads). # 리눅스 호스트는 처음 한 번 mkdir -p data/uploads (없으면 도커가 root 소유로 만들어 backend 가 쓰지 못한다) # ========================================== UPLOAD_DATA_DIR=./data/uploads UPLOAD_MAX_SIZE_MB=5 # ========================================== # 메일 엔진 (Stalwart) — profile `mail` # # 직원 로그인 = 메일 계정. 백엔드는 내부 JMAP 으로 메일 엔진에 붙는다. # 처음 띄운 뒤 한 번 실행한다 (여러 번 실행해도 안전하다): # node --env-file=.env.development mail/scripts/setup.mjs # 자세한 내용: mail/README.md # # 개발 도메인은 외부와 섞이지 않는 예약 TLD(.test)를 쓴다. # ⚠️ 약한 비밀번호는 Stalwart 의 강도 정책이 거부한다. 복사 후 무작위 값으로 교체할 것. # ⚠️ 비밀번호는 영문·숫자로만 만든다. # · 따옴표 · $ · 공백은 compose 와 Node(--env-file)가 # 서로 다르게 읽어(Node 는 # 부터 주석으로 자른다) 컨테이너와 setup 스크립트의 값이 어긋난다. # ========================================== # 패치까지 고정한다 — setup 스크립트가 0.16 의 동작(관리 API·bootstrap)에 맞춰져 있다 (docker 스킬 "이미지 버전 고정") MAIL_IMAGE=stalwartlabs/stalwart:v0.16.27 MAIL_DOMAIN=arasystem.test # 서버 호스트명 — 최초 bootstrap 때만 반영된다 (이후 변경은 관리 화면에서) MAIL_HOSTNAME=mail.arasystem.test # 관리 화면·setup 스크립트용 HTTP 포트 (127.0.0.1 로만 열린다) MAIL_ADMIN_PORT=8180 # JMAP·OAuth 디스커버리 기준 주소. 개발은 관리 화면 주소 — MAIL_ADMIN_PORT 를 바꾸면 함께 고칠 것 MAIL_PUBLIC_URL=http://localhost:8180 # 영구 관리자 아이디 (주소는 <이 값>@MAIL_DOMAIN, 미설정 시 admin) — setup 스크립트가 이 이름으로 관리자를 만들고, # 백엔드는 이 계정의 웹메일 로그인·대리 접근을 막는다 (두 쪽이 이 값 하나를 읽는다). # ⚠️ bootstrap 전에만 정할 수 있다. bootstrap 뒤에 이 값만 바꾸면 엔진 관리자는 그대로 남고 백엔드는 새 이름만 막게 되므로, # setup 이 중단한다 (되돌리는 절차: mail/README.md "문제 해결"). 옮겨 올 메일함에 같은 주소가 있으면 다른 이름으로 정한다. # 영문·숫자·. _ - 만, 앞뒤는 영문·숫자, 64자 이하 (백엔드와 같은 규칙) MAIL_ADMIN_LOCAL_PART=admin # 영구 관리자 비밀번호 — setup 스크립트가 이 값으로 맞춘다 MAIL_ADMIN_PASSWORD=change-me-in-local-env # 최초 기동(bootstrap)용 임시 관리자 "아이디:비밀번호". ⚠️ 값이 있는 동안은 정상 모드에서도 관리자로 로그인된다 # (개발은 127.0.0.1 에만 열려 있어 이 파일에 둔다 — 운영은 파일에 두지 않고 일회성 override 로만 쓴다) MAIL_RECOVERY_ADMIN=admin:change-me-in-local-env # 백엔드가 직원 메일함을 대리 접근(impersonate)할 때 쓰는 서비스 계정 (주소 전체). # ⚠️ 이 비밀번호는 전 직원 메일함의 열쇠다 MAIL_GATEWAY_USER=mail-gateway@arasystem.test MAIL_GATEWAY_PASSWORD=change-me-in-local-env # 백엔드가 쓰는 내부 JMAP 주소 (compose 내부망). 보통 바꿀 일이 없다 MAIL_JMAP_URL=http://mail:8080 # 첨부 1개 최대 크기(MB, 미설정 시 20). 프론트 nginx 의 본문 한도가 이 값 + 1MB 로 따라간다 # (그 앞에 외부 리버스 프록시를 두면 그쪽 한도도 맞춘다 — docker 스킬 "운영 환경") MAIL_ATTACHMENT_MAX_SIZE_MB=20 # 메일 한 통의 첨부 합계(MB, 미설정 시 25) — 파일당 한도 이상이어야 한다 MAIL_ATTACHMENT_TOTAL_MAX_SIZE_MB=25 # 게이트웨이 계정을 쓸 수 있고 자동 차단에서 빠지는 대역 (콤마 구분). # 비우면 APP_NETWORK_SUBNET 과 같다. 그 안의 더 좁은 대역만 쓸 수 있다 — 더 넓으면 setup 이 실패한다 MAIL_TRUSTED_NETWORKS= # (선택) 웹메일 로그인·대리 접근을 막을 계정 — 주소 전체를 콤마로. 비어 있어도 위 관리자(MAIL_ADMIN_LOCAL_PART)는 항상 막힌다. # 관리자를 더 만들었다면 여기에 넣는다 (setup 이 빠진 관리자 계정을 [주의] 로 알려 준다) # MAIL_BLOCKED_ACCOUNTS=ops@arasystem.test # 개발용 테스트 직원 계정(ara.kim@ 등)의 공통 비밀번호 — 개발 환경에서만 만들어진다 MAIL_DEV_USER_PASSWORD=change-me-in-local-env # 개발 전용 메일 수집기 — 사내 도메인 밖으로 보낸 메일이 여기에만 쌓인다 MAILPIT_IMAGE=axllent/mailpit:v1.32.0 MAILPIT_UI_PORT=8025