forked from baron/baron-sso
117 lines
5.9 KiB
Markdown
117 lines
5.9 KiB
Markdown
# 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
|
|
```
|
|
|
|
프로덕션처럼 고정 경로에 바로 생성해야 하면 `TARGET_DIR`를 지정합니다.
|
|
|
|
```bash
|
|
cd deploy
|
|
TARGET_DIR=/home/user/prod.baron-sso ./create-instance.sh prod 30
|
|
cd /home/user/prod.baron-sso
|
|
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`
|
|
|
|
프로덕션 도메인이 `app.brsw.kr`처럼 인스턴스 기본 규칙과 다르면 생성 후 `.env`에서 다음 값을 운영 도메인으로 고정합니다.
|
|
|
|
```dotenv
|
|
USERFRONT_URL=https://app.brsw.kr
|
|
PUBLIC_HOST=app.brsw.kr
|
|
HYDRA_PUBLIC_URL=https://app.brsw.kr/oidc
|
|
VITE_OIDC_AUTHORITY=https://app.brsw.kr/oidc
|
|
```
|
|
|
|
## 4.1 Traefik 연동
|
|
|
|
생성된 `docker-compose.yaml`은 외부 진입 서비스에 Traefik docker provider label을 포함합니다.
|
|
|
|
- `gateway`: `${PUBLIC_HOST}`로 라우팅하며 `app.brsw.kr` 같은 SSO 메인 도메인을 담당합니다.
|
|
- `adminfront`: `${ADMINFRONT_HOST}`로 라우팅합니다.
|
|
- `devfront`: `${DEVFRONT_HOST}`로 라우팅합니다.
|
|
- `orgfront`: `${ORGFRONT_HOST}`로 라우팅합니다.
|
|
|
|
`deploy/create-instance.sh`는 `.env`의 `TRAEFIK_PUBLIC_NETWORK` 값을 읽어 기본 `traefik-public` external network가 없으면 생성합니다. Traefik은 별도 경로(`/home/user/traefik`)에서 먼저 실행되어 있어야 하며, Baron SSO compose는 public-facing 서비스만 이 external network에 붙입니다.
|
|
|
|
## 4.2 프로덕션 이미지 버전 규칙
|
|
|
|
프로덕션 후보 이미지는 `.gitea/workflows/production_image_publish.yml`에서 `dev` 브랜치를 checkout해 빌드하고 공용 저장소에 push합니다. 운영자가 입력하는 값은 `version_prefix`이며 형식은 `vX.YYMM`입니다.
|
|
|
|
최종 이미지 태그는 워크플로우가 checkout된 커밋의 4자리 short SHA를 마지막 자리로 붙여 자동 생성합니다.
|
|
|
|
```text
|
|
v1.2606.ab12
|
|
```
|
|
|
|
배포는 먼저 `.gitea/workflows/staging_image_deploy.yml`에서 최종 `image_tag`를 입력해 staging에 적용하고, 같은 `image_tag`를 `.gitea/workflows/production_image_deploy.yml`에 입력해 production에 적용합니다. 두 deploy workflow는 모두 `vX.YYMM.<커밋해시4자리>` 형식만 허용하고, 해당 태그의 이미지를 pull한 뒤 각 환경의 `APP_ENV`로 실행합니다.
|
|
|
|
같은 이미지를 사용하기 위한 계약은 다음과 같습니다.
|
|
|
|
```text
|
|
dev 브랜치 검증
|
|
-> production_image_publish.yml에서 vX.YYMM.<commit4> 이미지 build/push
|
|
-> staging_image_deploy.yml에서 같은 image_tag pull/up
|
|
-> production_image_deploy.yml에서 같은 image_tag pull/up
|
|
```
|
|
|
|
WORKS Drive archive를 켜면 publish workflow가 registry에 push한 이미지를 다시 pull한 뒤 `scripts/docker-image/upload_works_drive.sh`로 `docker-build-image/<repository-path>/<tag>/` 아래에 `image.tar.zst`, `image.tar.zst.sha256`, `manifest.json`을 저장합니다. 이 archive도 staging/production과 같은 `image_tag` 기준입니다.
|
|
|
|
## 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`)로 라우팅해주는 작업이 필요합니다.
|