baron-sso/docs/staging-deployment-flow.md

스테이징 배포 및 DB 초기화 프로세스 분석

현재 Gitea Actions(staging_release.yml)를 통해 스테이징 서버에 배포가 진행될 때 발생하는 데이터 초기화(Wipe) 및 초기 관리자 계정 생성(Seed) 과정을 설명하는 다이어그램입니다.

---

1. 스테이징 배포 파이프라인 (데이터가 날아가는 이유)

배포 스크립트에 포함된 docker compose down -v 명령어의 -v 옵션으로 인해, 컨테이너가 내려갈 때 영구 저장소(Volumes)까지 통째로 삭제되는 흐름입니다.

graph TD
    Start[Gitea Action 수동 실행<br/>Release Baron SSO to Staging] --> SSH(Staging 서버 SSH 접속)
    SSH --> Env[최신 환경변수 및 .env 파일 생성]
    Env --> Pull[docker compose pull<br/>최신 이미지 다운로드]
    
    Pull --> DownV{docker compose down -v}
    style DownV fill:#ffebee,stroke:#ff0000,stroke-width:2px
    
    DownV -->|1. 컨테이너 종료| StopC[Backend, Frontend, Kratos 등<br/>모든 컨테이너 중지]
    DownV -->|2. 볼륨 완전 삭제| WipeDB[(데이터베이스 볼륨 파괴<br/>postgres_data<br/>ory_postgres_data<br/>clickhouse_data)]
    
    StopC --> Up[docker compose up -d]
    WipeDB --> Up
    
    Up --> CleanState[새로운 컨테이너 시작<br/>완전히 텅 빈 Clean DB 상태]

📌 분석 포인트:

• 배포할 때마다 붉은색으로 칠해진 down -v 단계가 실행됩니다.
• 이 단계에서 기존에 생성해두었던 테넌트, 일반 유저, 조직도, 권한 등 모든 데이터가 공장 초기화됩니다. (Dev 서버와 DB를 공유하지 않습니다)

---

2. 백엔드 Bootstrap (어드민 계정이 새로 생성되는 이유)

데이터베이스가 완전히 텅 빈 상태로 컨테이너가 새로 시작된 직후, 백엔드 서버가 부팅되면서 .env에 정의된 시스템 관리자 계정을 자동으로 생성(Seed)하는 흐름입니다.

sequenceDiagram
    autonumber
    participant Docker as Staging Server
    participant BE as Backend (kratos_seed.go)
    participant Kratos as Ory Kratos (DB)
    participant Keto as Ory Keto (RBAC)

    Docker->>BE: 1. 컨테이너 시작 (Bootstrapping)
    activate BE
    
    Note over BE: 백엔드 서버 구동 전 초기화 스크립트 실행
    
    BE->>BE: 2. .env 읽기<br/>(ADMIN_EMAIL, ADMIN_PASSWORD)
    
    BE->>Kratos: 3. CreateUser API 호출<br/>(email, password, role: "super_admin")
    activate Kratos
    Note over Kratos: 텅 빈 DB에<br/>최초의 계정 1개 생성
    Kratos-->>BE: 4. Identity ID 반환
    deactivate Kratos
    
    BE->>Keto: 5. 권한 동기화 API 호출<br/>(System 네임스페이스에 super_admin 할당)
    activate Keto
    Keto-->>BE: 6. 권한 부여 완료
    deactivate Keto
    
    Note over BE: 백엔드 서버 HTTP 요청 수신 준비 완료
    deactivate BE

📌 분석 포인트:

• 이전 단계에서 DB가 모두 날아갔기 때문에 기존 계정은 하나도 없습니다.
• 하지만 백엔드가 구동되면서 (3)번 과정을 통해 Gitea Secrets에 저장된 STG_ADMIN_PASSWORD 정보로 가장 권한이 높은 슈퍼 어드민 계정 단 1개를 Kratos DB에 밀어 넣습니다.
• 그래서 방금 전 배포가 끝난 스테이징 서버에 들어가면, 예전에 만든 데이터는 없지만 이 스크립트가 방금 만들어준 어드민 계정으로는 로그인이 성공하게 되는 것입니다.

---

💡 (참고) 데이터를 유지하고 싶다면?

스테이징 배포 시마다 데이터가 날아가는 것을 방지하려면, .gitea/workflows/staging_release.yml 파일 내부의 배포 스크립트에서 -v 옵션을 제거해야 합니다.

# 수정 전 (데이터 완전 삭제)
docker compose -f compose.infra.yml -f compose.ory.yml -f docker-compose.yml down -v || true

# 수정 후 (컨테이너만 재시작, DB 볼륨 유지)
docker compose -f compose.infra.yml -f compose.ory.yml -f docker-compose.yml down || true