diff --git a/Baron SSO 개발환경 복구 Runbook.md b/Baron SSO 개발환경 복구 Runbook.md
new file mode 100644
index 0000000..c8032d1
--- /dev/null
+++ b/Baron SSO 개발환경 복구 Runbook.md	
@@ -0,0 +1,259 @@
+Windows 빈 PC 기준 Baron SSO 개발환경 복구 Runbook
+목적
+이 문서는 Windows 기준의 빈 PC에서 Baron SSO 개발환경을 다시 구성하고, 업무에 복귀하기까지의 흐름을 복기한 기록이다.
+
+팀장 요구사항의 핵심은 단순히 개발환경을 한 번 설치하는 것이 아니라, 회사 PC나 서버에 문제가 생겼을 때 새 PC에서 개발환경을 최대한 빨리 복구하는 것이다.
+
+따라서 이 문서는 다음 상황을 기준으로 한다.
+
+로컬 Windows PC에 개발환경이 전혀 설치되어 있지 않다.
+WSL, Ubuntu, Docker, Git, Gitea clone부터 다시 진행해야 한다.
+Baron SSO 소스코드를 Ubuntu 안에 올려 Docker Compose 기반으로 실행한다.
+복구 완료 여부를 명령어와 접속 URL로 확인한다.
+현재 Baron SSO 로컬 설치 기준
+현재 확인한 작업 위치는 다음과 같다.
+
+/home/ubuntu/workspace/baron-sso
+현재 브랜치는 다음과 같다.
+
+feature/local-dev-setup-clean
+현재 Gitea 원격 저장소는 다음 기준으로 연결되어 있다.
+
+origin  https://gitea.hmac.kr/baron/baron-sso.git
+fork    https://kevin@gitea.hmac.kr/kevin/baron-sso.git
+Baron SSO는 단일 프로세스가 아니라 여러 구성요소를 Docker Compose로 함께 실행하는 구조다.
+
+주요 Compose 파일은 다음과 같다.
+
+파일	역할
+compose.infra.yaml	Baron SSO 인프라. Postgres, ClickHouse, Redis, gateway 등
+compose.ory.yaml	Ory Stack. Kratos, Hydra, Keto, Oathkeeper 등
+docker-compose.yaml	Baron SSO 앱. backend, userfront, adminfront, devfront, orgfront 등
+Makefile	실행, 검증, 백업, 복구 명령 자동화
+.env.sample	로컬 환경 변수 템플릿
+.env	현재 로컬 실행 설정
+전체 복구 흐름
+빈 PC에서 Baron SSO 개발환경을 복구하는 큰 흐름은 다음과 같다.
+
+Windows PC 준비
+WSL 설치
+WSL 안에 Ubuntu 설치
+Ubuntu에서 Docker 또는 Docker Desktop WSL 연동 구성
+Ubuntu에 Git 등 기본 도구 준비
+Gitea에서 Baron SSO 저장소 clone
+/home/ubuntu/workspace/baron-sso 경로에 소스 배치
+.env.sample을 기준으로 .env 작성
+make validate-auth-config로 인증 설정 생성 및 검증
+make up-dev, make up-app 또는 make up-all로 로컬 스택 실행
+브라우저에서 Baron SSO 접속 확인
+Windows에서 WSL 설치
+Windows PowerShell 또는 Windows Terminal을 관리자 권한으로 실행한 뒤 WSL을 설치한다.
+
+wsl --install
+설치 후 PC 재부팅이 필요할 수 있다.
+
+설치 상태는 다음 명령으로 확인한다.
+
+wsl --status
+wsl --list --verbose
+Ubuntu가 설치되어 있지 않으면 Microsoft Store 또는 wsl --install -d Ubuntu 방식으로 Ubuntu를 설치한다.
+
+wsl --install -d Ubuntu
+Ubuntu 기본 준비
+Ubuntu 터미널을 열고 패키지 목록을 갱신한다.
+
+sudo apt update
+sudo apt upgrade -y
+기본 도구를 설치한다.
+
+sudo apt install -y git make curl ca-certificates
+Docker는 Docker Desktop의 WSL integration을 사용하거나, Ubuntu 안에 Docker Engine을 직접 설치하는 방식 중 하나를 선택한다.
+
+팀 복구 절차에서는 한 가지 표준 방식을 정해두는 것이 좋다. 현재 Baron SSO 실행 기준에서는 Ubuntu 터미널에서 아래 명령이 동작해야 한다.
+
+docker --version
+docker compose version
+Baron SSO 소스코드 clone
+작업 디렉터리를 만든다.
+
+mkdir -p ~/workspace
+cd ~/workspace
+Gitea 저장소에서 Baron SSO를 clone한다.
+
+git clone https://gitea.hmac.kr/baron/baron-sso.git
+cd baron-sso
+필요한 브랜치가 있다면 전환한다.
+
+git checkout feature/local-dev-setup-clean
+현재 상태를 확인한다.
+
+git status
+git remote -v
+환경 변수 파일 준비
+Baron SSO는 .env 파일을 기준으로 로컬 실행 설정을 읽는다.
+
+최초에는 샘플 파일을 복사한다.
+
+cp .env.sample .env
+그 다음 .env를 로컬 개발 환경에 맞게 수정한다.
+
+주의할 점은 다음과 같다.
+
+KEY=value 형식으로 한 줄에 하나만 작성한다.
+값 뒤에 같은 줄 주석을 붙이지 않는다.
+URL 값 끝에 공백을 넣지 않는다.
+callback URL 끝에 불필요한 /를 붙이지 않는다.
+잘못된 예시는 다음과 같다.
+
+USERFRONT_URL=http://localhost:5000 # 같은 줄 주석 금지
+올바른 예시는 다음과 같다.
+
+# UserFront 로컬 공개 URL
+USERFRONT_URL=http://localhost:5000
+인증 설정 검증
+.env 작성 후 인증 설정을 생성하고 검증한다.
+
+make validate-auth-config
+이 명령은 내부적으로 다음 파일을 생성하고 callback, allowed return URL, gateway 매핑 등을 점검한다.
+
+config/.generated/auth-config.env
+문제가 있으면 Baron SSO를 올리기 전에 .env 값을 먼저 수정한다.
+
+Baron SSO 실행
+개발 기본 스택을 준비한다.
+
+make up-dev
+앱 스택을 실행한다.
+
+make up-app
+처음부터 전체를 한 번에 올릴 수도 있다.
+
+make up-all
+프론트엔드 개발 중 HMR까지 포함해 포그라운드로 실행하려면 다음 명령을 사용한다.
+
+make dev
+디버그 로그가 필요하면 다음 명령을 사용한다.
+
+make dev-debug
+접속 URL
+로컬 실행 후 기본 접속 URL은 다음과 같다.
+
+서비스	URL
+UserFront / gateway	http://localhost:5000
+Backend API	http://localhost:3000
+AdminFront	http://localhost:5173
+DevFront	http://localhost:5174
+OrgFront	http://localhost:5175
+ClickHouse	http://localhost:8123
+Kratos Public	http://localhost:4433
+Hydra Public	http://localhost:4444
+복구 완료 기준은 최소한 다음 항목을 만족하는 것이다.
+
+Docker Compose 컨테이너가 정상적으로 올라온다.
+http://localhost:5000에서 UserFront 또는 로그인 화면에 접근된다.
+필요 시 http://localhost:5173, http://localhost:5174, http://localhost:5175에 각 React front가 접근된다.
+backend health check가 정상 응답한다.
+컨테이너 상태 확인
+전체 Compose 기준 상태는 다음 명령으로 확인한다.
+
+docker compose -f compose.infra.yaml -f compose.ory.yaml -f docker-compose.yaml ps -a
+실행 중인 컨테이너만 빠르게 보려면 다음 명령을 사용한다.
+
+docker ps
+Makefile에서도 상태 조회 타깃을 제공한다.
+
+make ps
+로그 확인은 다음 명령을 사용한다.
+
+make logs-infra
+make logs-ory
+make logs-app
+현재 확인된 컨테이너 상태 예시
+현재 환경을 확인했을 때 실행 중이던 컨테이너는 주로 인프라 영역이었다.
+
+실행 중:
+
+baron_postgres
+baron_redis
+baron_clickhouse
+baron_gateway
+baron_promtail
+baron_blackbox_exporter
+중지 상태:
+
+baron_backend
+baron_userfront
+baron_adminfront
+baron_devfront
+baron_orgfront
+ory_kratos
+ory_hydra
+ory_keto
+ory_oathkeeper
+ory_postgres
+ory_clickhouse
+따라서 현재 상태는 "설치 흔적과 구성은 남아 있고 일부 인프라는 올라와 있지만, Baron SSO 전체 개발 스택이 완전히 기동 중인 상태는 아님"으로 볼 수 있다.
+
+전체 개발환경을 다시 올리려면 다음 흐름으로 복구한다.
+
+make validate-auth-config
+make up-dev
+make up-app
+또는 다음 명령으로 전체를 한 번에 올린다.
+
+make up-all
+자주 막히는 지점
+Docker 명령 권한 문제
+Ubuntu에서 docker ps 실행 시 Docker socket 권한 오류가 발생할 수 있다.
+
+대표 증상:
+
+permission denied while trying to connect to the docker API at unix:///var/run/docker.sock
+이 경우 다음 항목을 확인한다.
+
+Docker Desktop이 실행 중인지 확인한다.
+Docker Desktop의 WSL integration이 Ubuntu에 대해 켜져 있는지 확인한다.
+Ubuntu 사용자가 Docker socket에 접근 가능한지 확인한다.
+필요 시 Windows와 WSL을 재시작한다.
+.env 오류
+.env에 URL 뒤 공백, 같은 줄 주석, 잘못된 callback URL이 있으면 Hydra, Kratos, Ory 설정이 실패할 수 있다.
+
+Baron SSO 실행 전에는 반드시 다음 명령을 먼저 통과시킨다.
+
+make validate-auth-config
+일부 컨테이너만 떠 있는 상태
+인프라 컨테이너만 떠 있고 Ory나 앱 컨테이너가 중지되어 있으면 로그인 화면이 정상 동작하지 않을 수 있다.
+
+이때는 전체 상태를 확인한다.
+
+docker compose -f compose.infra.yaml -f compose.ory.yaml -f docker-compose.yaml ps -a
+그 다음 필요한 스택을 다시 올린다.
+
+make up-dev
+make up-app
+업무 복귀 시간 단축을 위한 개선 포인트
+현재 절차를 더 빠르게 만들기 위해 다음 항목을 표준화하면 좋다.
+
+Windows/WSL/Ubuntu/Docker 설치 절차를 체크리스트화한다.
+Gitea clone부터 .env 준비까지 표준 절차를 고정한다.
+로컬 개발용 .env에서 반드시 바꿔야 하는 값만 별도 표로 정리한다.
+make validate-auth-config, make up-dev, make up-app를 복구 기본 명령으로 정한다.
+Docker 권한 문제, WSL 재시작, 컨테이너 일부 중지 같은 반복 이슈의 해결 절차를 문서화한다.
+복구 완료 판정 기준을 명확히 한다.
+복구 완료 판정 기준 예시는 다음과 같다.
+
+docker ps
+make ps
+curl http://localhost:3000/health
+브라우저에서는 다음 주소를 확인한다.
+
+http://localhost:5000
+http://localhost:5173
+http://localhost:5174
+http://localhost:5175
+관련 문서
+README.md
+docs/local-run-notes/wsl-docker-gitea-mcp-guide.md
+docs/local-run-notes/wsl-local-run-2026-06-18.md
+docs/local-run-notes/wsl-setup-issues-2026-06-18.md
+docs/make-dev-vite-hmr-policy.md
\ No newline at end of file