Baron SSO 다중 인스턴스 배포 템플릿

deploy/deploy_guide.md

@@ -0,0 +1,64 @@
+# Baron SSO 다중 인스턴스 배포 가이드
+
+이 프로젝트는 한 대의 서버(머신)에서 여러 개의 독립된 서비스 인스턴스(예: stg, test2, prod 등)를 충돌 없이 실행하기 위한 **템플릿 기반 자동 배포 시스템**을 사용합니다.
+
+## 1. 폴더 구조
+- `deploy/templates/`: 모든 설정의 원천이 되는 마스터 템플릿.
+- `deploy/create-instance.sh`: 새로운 인스턴스를 생성하는 마법사 스크립트.
+- `instances/`: (자동 생성) 실제 실행되는 인스턴스별 설정 파일들이 저장되는 곳.
+
+## 2. 핵심 배포 전략
+
+### 2.1 포트 Prefix 시스템
+모든 포트는 환경 변수 `P` (Port Prefix)를 기반으로 자동 계산됩니다.
+- 예: 포트 Prefix를 `23`으로 설정 시:
+  - Backend: `23000`
+  - PostgreSQL: `23432`
+  - UserFront: `23500`
+  - AdminFront: `23173`
+
+### 2.2 네임스페이스 격리
+모든 리소스 이름에 `${INSTANCE_NAME}`이 자동으로 붙어 도커 엔진 내에서 격리됩니다.
+- 컨테이너: `baron-sso-test2_backend`
+- 네트워크: `baron-sso-test2_net`
+- 볼륨: `db_data_test2`
+
+## 3. 새로운 인스턴스 배포 방법
+
+### Step 1: 인스턴스 생성
+`deploy/` 폴더로 이동하여 스크립트를 실행합니다.
+```bash
+cd deploy
+./create-instance.sh [인스턴스이름] [포트앞자리]
+```
+> **예시**: `test3` 환경을 `24xxx` 포트 대역으로 만들고 싶을 때
+> ```bash
+> ./create-instance.sh test3 24
+> ```
+
+### Step 2: 서비스 실행
+생성된 인스턴스 폴더로 이동하여 도커 컴포즈를 실행합니다.
+```bash
+cd instances/test3
+docker compose up -d
+```
+
+## 4. 도메인 및 URL 규칙
+스크립트 실행 시 인스턴스 이름에 따라 다음 도메인이 자동으로 설정 파일에 주입됩니다. (`DOMAIN_SUFFIX`는 `.env`에서 수정 가능)
+- **SSO/UserFront**: `https://[이름]-sso.hmac.kr`
+- **AdminFront**: `https://[이름]-admin.hmac.kr`
+- **DevFront**: `https://[이름]-dev.hmac.kr`
+
+## 5. 주요 설정 파일 관리
+- **Nginx (Gateway & UserFront)**: 각 인스턴스의 백엔드 포트를 자동으로 감지하여 리버스 프록시를 수행합니다.
+- **Ory Kratos**: `allowed_origins`, `allowed_return_urls`, `webhook` 주소 등이 인스턴스 포트에 맞게 자동 치환됩니다.
+- **Ory Oathkeeper (`rules.json`, `rules.active.json`)**: 인증 규칙 내의 업스트림 주소가 현재 인스턴스 포트에 맞게 자동 치환됩니다.
+- **Environment (`.env`)**: 모든 시크릿과 URL 설정이 중앙에서 관리됩니다.
+
+## 6. Vite 프론트엔드 주의사항
+Vite 개발 서버나 Preview 모드를 사용하는 경우, `vite.config.ts`의 `allowedHosts` 설정이 새로운 도메인을 차단할 수 있습니다. 
+여러 인스턴스를 동적 도메인으로 운영할 경우, `vite.config.ts`에서 `allowedHosts: true` (Vite 5.1+) 설정을 권장합니다.
+
+
+---
+**주의**: 새로운 인스턴스 생성 후 외부에서 접속하려면, 앞단의 메인 리버스 프록시(Nginx 등)나 DNS 설정에서 해당 인스턴스의 포트(`USERFRONT_PORT`)로 라우팅해주는 작업이 필요합니다.