production 푸시 초안

deploy/deploy_guide.md

@@ -43,12 +43,64 @@ 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` 주소 등이 인스턴스 포트에 맞게 자동 치환됩니다.