Update Baron SSO 개발환경 복구 Runbook.md

Baron SSO 개발환경 복구 Runbook.md

@@ -1,5 +1,33 @@
 # Baron SSO 개발환경 복구 Runbook
 
+## 목차
+
+- [1. 문서 목적](#1-문서-목적)
+- [2. 단계별 진행 요약](#2-단계별-진행-요약)
+- [3. 전체 요약](#3-전체-요약)
+- [4. 현재 Baron SSO 기준 정보](#4-현재-baron-sso-기준-정보)
+- [5. 구성 요소 역할](#5-구성-요소-역할)
+- [6. 사전 준비 체크리스트](#6-사전-준비-체크리스트)
+- [7. 설치 전 필요한 계정정보와 민감정보](#7-설치-전-필요한-계정정보와-민감정보)
+- [8. Windows에서 WSL 설치](#8-windows에서-wsl-설치)
+- [9. Ubuntu 기본 패키지 설치](#9-ubuntu-기본-패키지-설치)
+- [10. Docker 준비](#10-docker-준비)
+- [11. Baron SSO 소스코드 clone](#11-baron-sso-소스코드-clone)
+- [12. 저장소 주요 파일 이해](#12-저장소-주요-파일-이해)
+- [13. `.env` 파일 준비](#13-env-파일-준비)
+- [14. 인증 설정 생성 및 검증](#14-인증-설정-생성-및-검증)
+- [15. Baron SSO 실행](#15-baron-sso-실행)
+- [16. 정상 접속 URL](#16-정상-접속-url)
+- [17. 컨테이너 상태 확인](#17-컨테이너-상태-확인)
+- [18. 정상 복구 완료 기준](#18-정상-복구-완료-기준)
+- [19. 현재 환경 복기](#19-현재-환경-복기)
+- [20. VS Code 저장과 Gitea 반영 흐름](#20-vs-code-저장과-gitea-반영-흐름)
+- [21. 자주 발생하는 문제와 대응](#21-자주-발생하는-문제와-대응)
+- [22. 업무 복귀 시간 단축 방안](#22-업무-복귀-시간-단축-방안)
+- [23. 자동화 파일 분리 방향](#23-자동화-파일-분리-방향)
+- [24. 빠른 복구 명령 모음](#24-빠른-복구-명령-모음)
+- [25. 관련 문서](#25-관련-문서)
+
 ## 1. 문서 목적
 
 이 문서는 Windows 기준의 빈 PC에서 Baron SSO 개발환경을 새로 구성하고, 개발자가 업무에 복귀하기까지의 표준 절차를 정리한다.
@@ -17,26 +45,29 @@
 
 아래 표는 빈 Windows PC에서 Baron SSO 개발환경을 복구할 때의 전체 진행 순서다. 각 단계의 명령어는 대표 예시이며, 실제 환경에 따라 관리자 권한, VPN, Gitea 인증, `.env` 값 준비가 먼저 필요할 수 있다.
 
-| No | 단계 | 명령어 또는 작업 | 설명 |
+명령어 실행 위치는 반드시 구분한다. `Windows PowerShell`은 Windows Terminal 또는 PowerShell에서 실행하고, `Ubuntu 터미널`은 WSL Ubuntu 안에서 실행한다.
-| --- | --- | --- | --- |
+
-| 1 | WSL 설치 | `wsl --install` | Windows 안에서 Linux를 실행할 수 있도록 WSL을 설치한다. 설치 후 재부팅이 필요할 수 있다. |
+| No | 단계 | 실행 위치 | 명령어 또는 작업 | 설명 |
-| 2 | Ubuntu 설치 확인 | `wsl --list --verbose` | Ubuntu 배포판이 설치되어 있고 실행 가능한지 확인한다. 없으면 `wsl --install -d Ubuntu`로 설치한다. |
+| --- | --- | --- | --- | --- |
-| 3 | Ubuntu 패키지 갱신 | `sudo apt update` | Ubuntu 안의 패키지 목록을 최신 상태로 갱신한다. |
+| 1 | WSL 설치 | Windows PowerShell, 관리자 권한 | `wsl --install` | Windows 안에서 Linux를 실행할 수 있도록 WSL을 설치한다. 설치 후 재부팅이 필요할 수 있다. 이미 WSL을 수동 설치했다면 이 단계는 확인만 한다. |
-| 4 | 기본 도구 설치 | `sudo apt install -y git make curl ca-certificates` | Git clone, Makefile 실행, HTTP 확인에 필요한 기본 도구를 설치한다. |
+| 2 | Ubuntu 설치 확인 | Windows PowerShell | `wsl --list --verbose` | Ubuntu 배포판이 설치되어 있고 실행 가능한지 확인한다. 없으면 Windows PowerShell에서 `wsl --install -d Ubuntu`로 설치한다. |
-| 5 | Docker 확인 | `docker --version` / `docker compose version` | Baron SSO는 Docker Compose로 실행되므로 Ubuntu 터미널에서 Docker 명령이 동작해야 한다. |
+| 3 | Ubuntu 실행 | Windows 시작 메뉴 또는 Windows PowerShell | `wsl -d Ubuntu` | Ubuntu 터미널로 진입한다. 이후 Linux 명령어는 Ubuntu 터미널 안에서 실행한다. |
-| 6 | 작업 폴더 생성 | `mkdir -p ~/workspace && cd ~/workspace` | WSL Ubuntu 안에 프로젝트 소스코드를 둘 작업 위치를 만든다. |
+| 4 | Ubuntu 패키지 갱신 | Ubuntu 터미널 | `sudo apt update` | Ubuntu 안의 패키지 목록을 최신 상태로 갱신한다. `sudo` 비밀번호 입력이 필요할 수 있다. |
-| 7 | Gitea 저장소 clone | `git clone https://gitea.hmac.kr/baron/baron-sso.git` | Gitea의 Baron SSO 원격 저장소를 로컬 WSL Ubuntu로 내려받는다. |
+| 5 | 기본 도구 설치 | Ubuntu 터미널 | `sudo apt install -y git make curl ca-certificates` | Git clone, Makefile 실행, HTTP 확인에 필요한 기본 도구를 설치한다. |
-| 8 | 저장소 이동 | `cd baron-sso` | 내려받은 Baron SSO 프로젝트 루트로 이동한다. 이후 명령은 이 위치에서 실행한다. |
+| 6 | Docker 확인 | Ubuntu 터미널 | `docker --version` / `docker compose version` | Baron SSO는 Docker Compose로 실행되므로 Ubuntu 터미널에서 Docker 명령이 동작해야 한다. 동작하지 않으면 Docker 설치 또는 WSL integration 설정을 먼저 처리한다. |
-| 9 | 브랜치 전환 | `git checkout feature/local-dev-setup-clean` | 팀에서 지정한 작업 브랜치로 전환한다. 표준 브랜치가 바뀌면 이 값도 바꾼다. |
+| 7 | 작업 폴더 생성 | Ubuntu 터미널 | `mkdir -p ~/workspace && cd ~/workspace` | WSL Ubuntu 안에 프로젝트 소스코드를 둘 작업 위치를 만든다. |
-| 10 | 환경 파일 생성 | `cp .env.sample .env` | 샘플 환경 파일을 복사해 로컬 실행용 `.env` 파일을 만든다. |
+| 8 | Gitea 저장소 clone | Ubuntu 터미널 | `git clone https://gitea.hmac.kr/baron/baron-sso.git` | Gitea의 Baron SSO 원격 저장소를 로컬 WSL Ubuntu로 내려받는다. HTTPS 인증 또는 SSH key 인증이 필요할 수 있다. |
-| 11 | 환경값 작성 | `.env` 편집 | URL, callback, secret 등 로컬 실행에 필요한 값을 작성한다. 민감정보는 Git에 올리지 않는다. |
+| 9 | 저장소 이동 | Ubuntu 터미널 | `cd baron-sso` | 내려받은 Baron SSO 프로젝트 루트로 이동한다. 이후 Baron SSO 관련 명령은 이 위치에서 실행한다. |
-| 12 | 인증 설정 검증 | `make validate-auth-config` | `.env` 기반 인증 설정을 생성하고 callback/return URL 설정 오류를 사전에 확인한다. |
+| 10 | 브랜치 전환 | Ubuntu 터미널 | `git checkout feature/local-dev-setup-clean` | 팀에서 지정한 작업 브랜치로 전환한다. 표준 브랜치가 바뀌면 이 값도 바꾼다. |
-| 13 | 전체 스택 실행 | `make up-all` | 인프라, Ory Stack, Baron SSO 앱 컨테이너를 한 번에 실행한다. |
+| 11 | 환경 파일 생성 | Ubuntu 터미널 | `cp .env.sample .env` | 샘플 환경 파일을 복사해 로컬 실행용 `.env` 파일을 만든다. |
-| 14 | 상태 확인 | `make ps` 또는 `docker ps` | 컨테이너가 정상적으로 실행 중인지 확인한다. 문제가 있으면 `logs-*` 명령으로 로그를 본다. |
+| 12 | 환경값 작성 | VS Code 또는 Ubuntu 편집기 | `.env` 편집 | URL, callback, secret 등 로컬 실행에 필요한 값을 작성한다. 민감정보는 Git에 올리지 않는다. |
-| 15 | 접속 확인 | `http://localhost:5000` | 브라우저에서 UserFront/gateway에 접속해 Baron SSO 화면이 열리는지 확인한다. |
+| 13 | 인증 설정 검증 | Ubuntu 터미널, Baron SSO 루트 | `make validate-auth-config` | `.env` 기반 인증 설정을 생성하고 callback/return URL 설정 오류를 사전에 확인한다. |
-| 16 | 추가 화면 확인 | `http://localhost:5173`, `5174`, `5175` | AdminFront, DevFront, OrgFront 개발 화면이 필요한 경우 각 포트 접속을 확인한다. |
+| 14 | 전체 스택 실행 | Ubuntu 터미널, Baron SSO 루트 | `make up-all` | 인프라, Ory Stack, Baron SSO 앱 컨테이너를 한 번에 실행한다. |
-| 17 | Backend 확인 | `curl http://localhost:3000/health` | backend health check가 정상 응답하는지 확인한다. |
+| 15 | 상태 확인 | Ubuntu 터미널, Baron SSO 루트 | `make ps` 또는 `docker ps` | 컨테이너가 정상적으로 실행 중인지 확인한다. 문제가 있으면 `make logs-infra`, `make logs-ory`, `make logs-app`으로 로그를 본다. |
-| 18 | 변경사항 저장 흐름 | `git add` → `git commit` → `git push` | VS Code 저장만으로는 Gitea에 올라가지 않는다. Gitea 반영은 반드시 `git push`까지 해야 한다. |
+| 16 | 접속 확인 | Windows 브라우저 | `http://localhost:5000` | 브라우저에서 UserFront/gateway에 접속해 Baron SSO 화면이 열리는지 확인한다. |
+| 17 | 추가 화면 확인 | Windows 브라우저 | `http://localhost:5173`, `http://localhost:5174`, `http://localhost:5175` | AdminFront, DevFront, OrgFront 개발 화면이 필요한 경우 각 포트 접속을 확인한다. |
+| 18 | Backend 확인 | Ubuntu 터미널 또는 Windows PowerShell | `curl http://localhost:3000/health` | backend health check가 정상 응답하는지 확인한다. |
+| 19 | 변경사항 저장 흐름 | Ubuntu 터미널 또는 VS Code Source Control | `git add` → `git commit` → `git push` | VS Code 저장만으로는 Gitea에 올라가지 않는다. Gitea 반영은 반드시 `git push`까지 해야 한다. |
 
 ## 3. 전체 요약
 
@@ -121,7 +152,94 @@ Baron SSO는 단일 서버 하나만 실행하는 프로젝트가 아니다. 여
 
 민감 설정값은 문서에 직접 기록하지 않는다. `.env` 파일, 사내 보안 저장소, 담당자 전달 절차 등 별도 관리 방식을 따른다.
 
-## 7. Windows에서 WSL 설치
+## 7. 설치 전 필요한 계정정보와 민감정보
+
+개발환경 자동화는 설치 시간을 줄여주지만, 계정정보와 비밀번호를 잘못 다루면 보안 사고로 이어질 수 있다. 특히 자동화 스크립트 안에 사이트 비밀번호, Gitea 비밀번호, 운영 secret을 직접 적으면 안 된다.
+
+반드시 기억할 원칙은 다음과 같다.
+
+```text
+자동화 파일에는 절차만 넣고,
+비밀번호와 토큰은 사용자 입력 또는 보안 저장소로 관리한다.
+```
+
+설치 전에 준비해야 하는 정보는 다음과 같다.
+
+| 구분 | 필요한 정보 | 사용 시점 | 보관/입력 권장 방식 |
+| --- | --- | --- | --- |
+| Windows | Windows 관리자 권한 | WSL 설치, Docker Desktop 설치 시 | 사용자 계정 권한으로 처리 |
+| WSL/Ubuntu | Ubuntu Linux 사용자명 | Ubuntu 최초 실행, 파일 경로, sudo 실행 시 | 사용자가 최초 실행 시 직접 생성 |
+| WSL/Ubuntu | Ubuntu Linux 비밀번호 | `sudo apt install`, Docker 설치 시 | 스크립트에 저장 금지. 필요 시 터미널에서 직접 입력 |
+| Gitea | Gitea 사용자명 | 저장소 clone, pull, push 시 | 사용자 입력 또는 Git credential manager |
+| Gitea | Gitea Personal Access Token | HTTPS 방식 Git 인증 시 | 사이트 비밀번호 대신 사용. 파일에 저장 금지 |
+| Gitea | SSH public/private key | SSH 방식 Git 인증 시 | public key는 Gitea 등록, private key는 사용자 PC에 안전하게 보관 |
+| Baron SSO | 저장소 URL | `git clone` 시 | 프로젝트 설정 파일에 저장 가능 |
+| Baron SSO | 브랜치명 | `git checkout` 시 | 프로젝트 설정 파일에 저장 가능 |
+| Baron SSO | `.env` 설정값 | Baron SSO 실행 전 | `.env` 또는 사내 보안 저장소 |
+| Baron SSO | `ADMIN_EMAIL`, `ADMIN_PASSWORD` | 초기 관리자 계정 또는 로컬 테스트 | 사내 보안 저장소 또는 사용자 직접 입력 |
+| Baron SSO | `COOKIE_SECRET`, `JWT_SECRET` | backend/session/token 보안값 | 로컬은 자동 생성 가능, 운영값 재사용 금지 |
+| 외부 연동 | Naver Cloud SMS key | SMS 발송 기능 테스트 시 | 보안 저장소 |
+| 외부 연동 | AWS SES key | 이메일 발송 기능 테스트 시 | 보안 저장소 |
+| 외부 연동 | WORKS Drive OAuth 값 | 백업 업로드 테스트 시 | 보안 저장소 |
+
+### 7.1 절대 스크립트에 넣지 말아야 할 값
+
+다음 값은 `.ps1`, `.sh`, `.md`, `.env.example` 파일에 직접 적지 않는다.
+
+- 개인 Windows 비밀번호
+- Ubuntu sudo 비밀번호
+- Gitea 사이트 로그인 비밀번호
+- Gitea Personal Access Token 원문
+- SSH private key 원문
+- Baron SSO 관리자 비밀번호
+- 운영 DB 비밀번호
+- Naver Cloud access key/secret key
+- AWS access key/secret key
+- WORKS OAuth client secret, refresh token, access token
+- 운영 환경의 `COOKIE_SECRET`, `JWT_SECRET`
+
+### 7.2 Gitea 인증 권장 방식
+
+Gitea 저장소 연결은 다음 둘 중 하나를 권장한다.
+
+| 방식 | 예시 | 특징 |
+| --- | --- | --- |
+| HTTPS + Personal Access Token | `https://gitea.hmac.kr/baron/baron-sso.git` | 비밀번호 대신 토큰을 사용한다. 토큰은 필요한 권한만 부여하고 유출 시 폐기한다. |
+| SSH key | `git@gitea.hmac.kr:baron/baron-sso.git` | 매번 토큰 입력을 줄일 수 있다. private key 보관과 passphrase 관리가 중요하다. |
+
+사이트 로그인 비밀번호를 `git clone` URL에 포함하는 방식은 사용하지 않는다.
+
+잘못된 예:
+
+```text
+https://username:password@gitea.hmac.kr/baron/baron-sso.git
+```
+
+권장 예:
+
+```text
+https://gitea.hmac.kr/baron/baron-sso.git
+git@gitea.hmac.kr:baron/baron-sso.git
+```
+
+### 7.3 자동화 파일이 입력받거나 확인해야 하는 값
+
+자동화 파일을 실제 운영 수준으로 확장할 때는 다음 값을 사용자에게 입력받거나 설정 파일로 분리한다.
+
+| 항목 | 기본값 예시 | 설명 |
+| --- | --- | --- |
+| Ubuntu 배포판 이름 | `Ubuntu` | `wsl -d Ubuntu` 실행에 사용 |
+| workspace 경로 | `~/workspace` | 소스코드 clone 위치 |
+| 프로젝트 이름 | `baron-sso` | workspace 아래 폴더명 |
+| 저장소 URL | `https://gitea.hmac.kr/baron/baron-sso.git` | HTTPS 또는 SSH URL |
+| 브랜치명 | `feature/local-dev-setup-clean` | 팀 표준 브랜치 |
+| Docker 설치 방식 | Docker Engine 또는 Docker Desktop WSL integration | 팀 표준에 맞춰 선택 |
+| `.env` 생성 방식 | `.env.sample` 복사 | 이후 민감값은 직접 입력 |
+| `make` 자동 실행 여부 | `false` 권장 | `.env` 확인 전 자동 실행을 막기 위함 |
+
+이 값 중 저장소 URL, 브랜치명, workspace 경로는 설정 파일에 저장해도 된다. 비밀번호, token, secret은 설정 파일에 저장하지 않는다.
+
+## 8. Windows에서 WSL 설치
 
 Windows Terminal 또는 PowerShell을 관리자 권한으로 실행한다.
 
@@ -148,7 +266,7 @@ wsl --install -d Ubuntu
 
 설치 후 Ubuntu를 실행하고 Linux 사용자 계정과 비밀번호를 만든다.
 
-## 8. Ubuntu 기본 패키지 설치
+## 9. Ubuntu 기본 패키지 설치
 
 Ubuntu 터미널에서 패키지 목록을 갱신한다.
 
@@ -171,7 +289,7 @@ make --version
 curl --version
 ```
 
-## 9. Docker 준비
+## 10. Docker 준비
 
 Baron SSO는 Docker Compose 기반으로 실행한다. Ubuntu 터미널에서 다음 명령이 동작해야 한다.
 
@@ -200,7 +318,7 @@ permission denied while trying to connect to the docker API at unix:///var/run/d
 4. 필요 시 Windows 재부팅
 5. Docker socket 권한 또는 사용자 그룹 확인
 
-## 10. Baron SSO 소스코드 clone
+## 11. Baron SSO 소스코드 clone
 
 작업 디렉터리를 만든다.
 
@@ -242,7 +360,7 @@ nothing to commit, working tree clean
 
 단, 기존 작업이 있거나 문서/테스트 산출물이 있다면 변경 파일이 표시될 수 있다.
 
-## 11. 저장소 주요 파일 이해
+## 12. 저장소 주요 파일 이해
 
 Baron SSO 로컬 실행에서 자주 보는 파일은 다음과 같다.
 
@@ -262,7 +380,7 @@ Baron SSO 로컬 실행에서 자주 보는 파일은 다음과 같다.
 | `orgfront/` | React 기반 OrgFront |
 | `docs/` | 운영/개발 문서 |
 
-## 12. `.env` 파일 준비
+## 13. `.env` 파일 준비
 
 최초 clone 직후에는 `.env.sample`을 복사한다.
 
@@ -305,7 +423,7 @@ ORGFRONT_URL=http://localhost:5175
 
 실제 필요한 값은 현재 `.env.sample`과 팀 표준 설정을 기준으로 작성한다.
 
-## 13. 인증 설정 생성 및 검증
+## 14. 인증 설정 생성 및 검증
 
 `.env` 작성 후 Baron SSO 인증 설정을 검증한다.
 
@@ -331,9 +449,9 @@ make validate-auth-config
 make verify-auth-config
 ```
 
-## 14. Baron SSO 실행
+## 15. Baron SSO 실행
 
-### 14.1 전체 스택 한 번에 실행
+### 15.1 전체 스택 한 번에 실행
 
 가장 단순한 실행 명령은 다음이다.
 
@@ -343,7 +461,7 @@ make up-all
 
 이 명령은 인프라, Ory Stack, 앱 스택을 함께 실행한다.
 
-### 14.2 단계별 실행
+### 15.2 단계별 실행
 
 문제 원인을 나누어 보기 위해 단계별로 실행할 수도 있다.
 
@@ -371,7 +489,7 @@ make dev
 make dev-debug
 ```
 
-## 15. 정상 접속 URL
+## 16. 정상 접속 URL
 
 로컬 실행 후 확인할 기본 URL은 다음과 같다.
 
@@ -401,7 +519,7 @@ backend health check는 다음으로 확인한다.
 curl http://localhost:3000/health
 ```
 
-## 16. 컨테이너 상태 확인
+## 17. 컨테이너 상태 확인
 
 실행 중인 컨테이너만 확인한다.
 
@@ -429,7 +547,7 @@ make logs-ory
 make logs-app
 ```
 
-## 17. 정상 복구 완료 기준
+## 18. 정상 복구 완료 기준
 
 빈 PC에서 복구가 완료되었다고 판단하려면 다음 기준을 만족해야 한다.
 
@@ -443,7 +561,7 @@ make logs-app
 - 필요한 경우 AdminFront, DevFront, OrgFront 포트에 접속할 수 있다.
 - backend health check가 정상 응답한다.
 
-## 18. 현재 환경 복기
+## 19. 현재 환경 복기
 
 현재 설치된 Baron SSO 환경을 확인했을 때, 일부 인프라 컨테이너는 실행 중이고 앱/Ory 컨테이너 일부는 중지 상태였다.
 
@@ -486,7 +604,7 @@ make up-app
 make up-all
 ```
 
-## 19. VS Code 저장과 Gitea 반영 흐름
+## 20. VS Code 저장과 Gitea 반영 흐름
 
 VS Code에서 파일을 수정하고 저장해도 Gitea 서버에 바로 반영되지는 않는다.
 
@@ -526,9 +644,9 @@ Gitea 서버 반영
 
 따라서 팀원이 Gitea 웹에서 변경사항을 보려면 반드시 `git push`까지 완료해야 한다.
 
-## 20. 자주 발생하는 문제와 대응
+## 21. 자주 발생하는 문제와 대응
 
-### 20.1 Docker socket 권한 오류
+### 21.1 Docker socket 권한 오류
 
 증상:
 
@@ -543,7 +661,7 @@ permission denied while trying to connect to the docker API at unix:///var/run/d
 - Ubuntu 재시작 여부
 - Docker socket 접근 권한
 
-### 20.2 `.env` 작성 오류
+### 21.2 `.env` 작성 오류
 
 증상:
 
@@ -560,7 +678,7 @@ make validate-auth-config
 
 실패 메시지를 보고 `.env`의 URL, callback, return URL 값을 수정한다.
 
-### 20.3 일부 컨테이너만 실행됨
+### 21.3 일부 컨테이너만 실행됨
 
 증상:
 
@@ -581,7 +699,7 @@ make up-dev
 make up-app
 ```
 
-### 20.4 포트 충돌
+### 21.4 포트 충돌
 
 증상:
 
@@ -596,7 +714,7 @@ docker ps
 
 필요 시 이미 떠 있는 컨테이너나 다른 프로세스가 같은 포트를 사용하는지 확인한다.
 
-## 21. 업무 복귀 시간 단축 방안
+## 22. 업무 복귀 시간 단축 방안
 
 복구 시간을 줄이기 위해 다음 항목을 팀 표준으로 관리하는 것이 좋다.
 
@@ -608,7 +726,7 @@ docker ps
 6. 신규 PC 지급 시 이 문서 기준으로 실제 복구 시간을 측정한다.
 7. 반복적으로 막히는 지점은 스크립트화하거나 Makefile 타깃으로 추가한다.
 
-## 22. 자동화 파일 분리 방향
+## 23. 자동화 파일 분리 방향
 
 빈 PC 자동화 파일은 Baron SSO에만 묶지 않고, 다른 프로젝트에도 재사용할 수 있도록 공통 설치 영역과 프로젝트별 설정 영역을 분리하는 것이 좋다.
 
@@ -624,7 +742,7 @@ Ubuntu 공통 개발환경 준비
 프로젝트별 소스 clone 및 실행
 ```
 
-### 22.1 권장 파일 구조
+### 23.1 권장 파일 구조
 
 자동화 파일은 다음처럼 나누는 것을 권장한다.
 
@@ -648,7 +766,7 @@ bootstrap/
 
 이렇게 나누면 다른 프로젝트를 추가할 때 공통 설치 파일은 그대로 두고, `project-프로젝트명-setup.sh`와 설정 파일만 추가하면 된다.
 
-### 22.2 공통 영역과 프로젝트 전용 영역 구분
+### 23.2 공통 영역과 프로젝트 전용 영역 구분
 
 자동화 범위를 다음처럼 구분한다.
 
@@ -671,7 +789,7 @@ bootstrap/
 
 캡처 기준으로 보면 빨간 영역은 `windows-wsl-bootstrap.ps1`에 해당하고, 노란 영역 중 `Docker 권한 설정`까지는 `ubuntu-common-dev-setup.sh`에 해당한다. 그 이후의 `Baron SSO git clone`, 브랜치 checkout, `.env`, `make` 실행은 Baron SSO 전용 파일로 분리한다.
 
-### 22.3 공통 Windows 부트스트랩 예시
+### 23.3 공통 Windows 부트스트랩 예시
 
 Windows 쪽 공통 파일은 다음 역할만 맡는다.
 
@@ -697,7 +815,7 @@ wsl -d Ubuntu -- bash -lc "./bootstrap/ubuntu-common-dev-setup.sh"
 - WSL 또는 Ubuntu 최초 설치 후 재부팅이 필요할 수 있다.
 - Ubuntu 최초 실행 시 Linux 사용자명/비밀번호 생성은 수동 단계로 남을 수 있다.
 
-### 22.4 공통 Ubuntu 개발환경 setup 예시
+### 23.4 공통 Ubuntu 개발환경 setup 예시
 
 Ubuntu 공통 파일은 특정 프로젝트를 모르는 상태로 개발 기본 환경만 준비한다.
 
@@ -723,7 +841,7 @@ mkdir -p ~/workspace
 
 Docker 권한 설정은 팀 표준 Docker 설치 방식에 맞춰 작성한다. Docker Desktop WSL integration을 쓸지, Ubuntu 내부 Docker Engine을 쓸지 먼저 정해야 한다.
 
-### 22.5 프로젝트별 setup 예시
+### 23.5 프로젝트별 setup 예시
 
 Baron SSO 전용 파일은 공통 개발환경이 준비된 뒤 실행한다.
 
@@ -762,7 +880,7 @@ project-internal-admin-setup.sh
 
 각 프로젝트 파일에는 해당 프로젝트의 저장소 URL, 브랜치명, 환경 파일 생성 방식, 실행 명령만 넣는다.
 
-### 22.6 자동화 시 입력받아야 하는 값
+### 23.6 자동화 시 입력받아야 하는 값
 
 공통 자동화에서 필요한 값은 다음과 같다.
 
@@ -782,7 +900,7 @@ project-internal-admin-setup.sh
 
 사이트 비밀번호나 Gitea 계정 비밀번호를 스크립트에 직접 저장하지 않는다. HTTPS 방식이면 Personal Access Token을 사용하고, SSH 방식이면 SSH key를 사용한다.
 
-### 22.7 최종 권장 실행 흐름
+### 23.7 최종 권장 실행 흐름
 
 사용자 입장에서의 목표 흐름은 다음과 같다.
 
@@ -816,7 +934,7 @@ make up-all
 
 이 방식은 Baron SSO뿐 아니라 Docker Compose 기반의 다른 사내 프로젝트에도 확장할 수 있다.
 
-## 23. 빠른 복구 명령 모음
+## 24. 빠른 복구 명령 모음
 
 새 PC에서 기본 도구와 Docker가 준비된 뒤 Baron SSO만 복구하는 핵심 명령은 다음과 같다.
 
@@ -846,7 +964,7 @@ http://localhost:5174
 http://localhost:5175
 ```
 
-## 24. 관련 문서
+## 25. 관련 문서
 
 - `README.md`
 - `Makefile`