baron-sso/deploy/deploy_guide.md

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/ 폴더로 이동하여 스크립트를 실행합니다.

cd deploy
./create-instance.sh [인스턴스이름] [포트앞자리]

예시: test3 환경을 24xxx 포트 대역으로 만들고 싶을 때

./create-instance.sh test3 24

Step 2: 서비스 실행

생성된 인스턴스 폴더로 이동하여 도커 컴포즈를 실행합니다.

cd instances/test3
docker compose up -d

프로덕션처럼 고정 경로에 바로 생성해야 하면 TARGET_DIR를 지정합니다.

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에서 다음 값을 운영 도메인으로 고정합니다.

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를 마지막 자리로 붙여 자동 생성합니다.

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로 실행합니다.

같은 이미지를 사용하기 위한 계약은 다음과 같습니다.

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)로 라우팅해주는 작업이 필요합니다.