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

2026-06-19 16:06:50 +09:00
parent 5401fcc80a
commit e219adf249
1 changed files with 94 additions and 63 deletions
--- a/Runbook.md
+++ b/Runbook.md
@@ -6,27 +6,46 @@
 - [2. 전체 요약](#2-전체-요약)
 - [3. 구성 요소 역할](#3-구성-요소-역할)
 - [4. 현재 Baron SSO 기준 정보](#4-현재-baron-sso-기준-정보)
- [5. 사전 준비 체크리스트](#5-사전-준비-체크리스트)
+- [5. 사전 준비](#5-사전-준비)
- [6. 설치 전 필요한 계정정보와 민감정보](#6-설치-전-필요한-계정정보와-민감정보)
+  - [5.1 사전 준비 체크리스트](#51-사전-준비-체크리스트)
- [7. 절대 스크립트에 넣지 말아야 할 값](#7-절대-스크립트에-넣지-말아야-할-값)
+  - [5.2 설치 전 필요한 계정정보와 민감정보](#52-설치-전-필요한-계정정보와-민감정보)
- [8. Gitea 인증 권장 방식](#8-gitea-인증-권장-방식)
+  - [5.3 절대 스크립트에 넣지 말아야 할 값](#53-절대-스크립트에-넣지-말아야-할-값)
- [9. 수동과 자동 진행 방식 구분](#9-수동과-자동-진행-방식-구분)
+  - [5.4 Gitea 인증 권장 방식](#54-gitea-인증-권장-방식)
- [10. 수동 단계별 진행 요약](#10-수동-단계별-진행-요약)
+- [6. 설치 방식 선택](#6-설치-방식-선택)
- [11. 수동 절차 상세](#11-수동-절차-상세)
+  - [6.1 수동과 자동 진행 방식 구분](#61-수동과-자동-진행-방식-구분)
- [12. 자동 단계별 진행 요약](#12-자동-단계별-진행-요약)
+- [7. 수동 설치](#7-수동-설치)
- [13. 자동화 파일 구조](#13-자동화-파일-구조)
+  - [7.1 수동 단계별 진행 요약](#71-수동-단계별-진행-요약)
- [14. 자동화 실행 방법](#14-자동화-실행-방법)
+  - [7.2 Windows에서 WSL 설치](#72-windows에서-wsl-설치)
- [15. 자동화 시 입력받거나 확인해야 하는 값](#15-자동화-시-입력받거나-확인해야-하는-값)
+  - [7.3 Ubuntu 기본 패키지 설치](#73-ubuntu-기본-패키지-설치)
- [16. 정상 접속 URL](#16-정상-접속-url)
+  - [7.4 Docker 준비](#74-docker-준비)
- [17. 컨테이너 상태 확인](#17-컨테이너-상태-확인)
+  - [7.5 Baron SSO 소스코드 clone](#75-baron-sso-소스코드-clone)
- [18. 정상 복구 완료 기준](#18-정상-복구-완료-기준)
+  - [7.6 저장소 주요 파일 이해](#76-저장소-주요-파일-이해)
- [19. 현재 환경 복기](#19-현재-환경-복기)
+  - [7.7 `.env` 파일 준비](#77-env-파일-준비)
- [20. VS Code 저장과 Gitea 반영 흐름](#20-vs-code-저장과-gitea-반영-흐름)
+  - [7.8 인증 설정 생성 및 검증](#78-인증-설정-생성-및-검증)
- [21. 자주 발생하는 문제와 대응](#21-자주-발생하는-문제와-대응)
+  - [7.9 Baron SSO 실행](#79-baron-sso-실행)
- [22. 업무 복귀 시간 단축 방안](#22-업무-복귀-시간-단축-방안)
+- [8. 자동 설치](#8-자동-설치)
- [23. 빠른 복구 명령 모음](#23-빠른-복구-명령-모음)
+  - [8.1 자동 단계별 진행 요약](#81-자동-단계별-진행-요약)
- [24. 초기화 자동화 파일 사용법](#24-초기화-자동화-파일-사용법)
+  - [8.2 자동화 파일 구조](#82-자동화-파일-구조)
- [25. 관련 문서](#25-관련-문서)
+  - [8.3 자동화 실행 방법](#83-자동화-실행-방법)
  - [8.4 자동화 시 입력받거나 확인해야 하는 값](#84-자동화-시-입력받거나-확인해야-하는-값)
 - [9. 설치 후 확인](#9-설치-후-확인)
  - [9.1 정상 접속 URL](#91-정상-접속-url)
  - [9.2 컨테이너 상태 확인](#92-컨테이너-상태-확인)
  - [9.3 정상 복구 완료 기준](#93-정상-복구-완료-기준)
  - [9.4 현재 환경 복기](#94-현재-환경-복기)
 - [10. 작업 흐름과 문제 대응](#10-작업-흐름과-문제-대응)
  - [10.1 VS Code 저장과 Gitea 반영 흐름](#101-vs-code-저장과-gitea-반영-흐름)
  - [10.2 자주 발생하는 문제와 대응](#102-자주-발생하는-문제와-대응)
  - [10.3 업무 복귀 시간 단축 방안](#103-업무-복귀-시간-단축-방안)
  - [10.4 빠른 복구 명령 모음](#104-빠른-복구-명령-모음)
 - [11. 초기화](#11-초기화)
  - [11.1 초기화 자동화 파일 사용법](#111-초기화-자동화-파일-사용법)
  - [11.2 모두 삭제 (`reset-all-wsl-ubuntu.ps1`)](#112-모두-삭제-reset-all-wsl-ubuntups1)
  - [11.3 부분 삭제 1: Ubuntu, Docker, Baron SSO 삭제 (`reset-ubuntu-distro.ps1`)](#113-부분-삭제-1-ubuntu-docker-baron-sso-삭제-reset-ubuntu-distrops1)
  - [11.4 부분 삭제 2: Docker, Baron SSO 삭제 (`reset-docker-and-baron.sh`)](#114-부분-삭제-2-docker-baron-sso-삭제-reset-docker-and-baronsh)
  - [11.5 부분 삭제 3: Baron SSO만 삭제 (`reset-baron-sso-project.sh`)](#115-부분-삭제-3-baron-sso만-삭제-reset-baron-sso-projectsh)
  - [11.6 초기화 선택 기준](#116-초기화-선택-기준)
 - [12. 관련 문서](#12-관련-문서)
 ## 1. 문서 목적
@@ -150,7 +169,9 @@ git checkout feature/local-dev-setup-clean
 | `orgfront/` | React 기반 OrgFront |
 | `bootstrap-automation` | 개발환경 복구 자동화 파일 묶음 |
-## 5. 사전 준비 체크리스트
+## 5. 사전 준비
 ### 5.1 사전 준비 체크리스트
 빈 PC에서 시작할 때 다음 항목이 준비되어야 한다.
@@ -165,7 +186,7 @@ git checkout feature/local-dev-setup-clean
 민감 설정값은 문서에 직접 기록하지 않는다. `.env` 파일, 사내 보안 저장소, 담당자 전달 절차 등 별도 관리 방식을 따른다.
-## 6. 설치 전 필요한 계정정보와 민감정보
+### 5.2 설치 전 필요한 계정정보와 민감정보
 개발환경 자동화는 설치 시간을 줄여주지만, 계정정보와 비밀번호를 잘못 다루면 보안 사고로 이어질 수 있다. 특히 자동화 스크립트 안에 사이트 비밀번호, Gitea 비밀번호, 운영 secret을 직접 적으면 안 된다.
@@ -195,7 +216,7 @@ git checkout feature/local-dev-setup-clean
 | 외부 연동 | AWS SES key | 이메일 발송 기능 테스트 시 | 보안 저장소 |
 | 외부 연동 | WORKS Drive OAuth 값 | 백업 업로드 테스트 시 | 보안 저장소 |
-## 7. 절대 스크립트에 넣지 말아야 할 값
+### 5.3 절대 스크립트에 넣지 말아야 할 값
 다음 값은 `.ps1`, `.sh`, `.md`, `.env.example` 파일에 직접 적지 않는다.
@@ -211,7 +232,7 @@ git checkout feature/local-dev-setup-clean
 - WORKS OAuth client secret, refresh token, access token
 - 운영 환경의 `COOKIE_SECRET`, `JWT_SECRET`
-## 8. Gitea 인증 권장 방식
+### 5.4 Gitea 인증 권장 방식
 Gitea 저장소 연결은 다음 둘 중 하나를 권장한다.
@@ -235,7 +256,9 @@ https://gitea.hmac.kr/baron/baron-sso.git
 git@gitea.hmac.kr:baron/baron-sso.git
 ```
-## 9. 수동과 자동 진행 방식 구분
+## 6. 설치 방식 선택
 ### 6.1 수동과 자동 진행 방식 구분
 수동 절차와 자동 절차는 목적이 다르다.
@@ -249,7 +272,9 @@ git@gitea.hmac.kr:baron/baron-sso.git
 처음에는 수동 절차로 한 번 성공시킨 뒤, 같은 절차를 자동화 파일로 옮기는 방식이 가장 안전하다.
-## 10. 수동 단계별 진행 요약
+## 7. 수동 설치
 ### 7.1 수동 단계별 진행 요약
 아래 표는 빈 Windows PC에서 Baron SSO 개발환경을 수동으로 복구할 때의 전체 진행 순서다. `Windows PowerShell`은 Windows Terminal 또는 PowerShell에서 실행하고, `Ubuntu 터미널`은 WSL Ubuntu 안에서 실행한다.
@@ -274,9 +299,7 @@ git@gitea.hmac.kr:baron/baron-sso.git
 | 17 | 추가 화면 확인 | Windows 브라우저 | `http://localhost:5173`, `5174`, `5175` | AdminFront, DevFront, OrgFront 개발 화면이 필요한 경우 각 포트 접속을 확인한다. |
 | 18 | Backend 확인 | Ubuntu 터미널 또는 Windows PowerShell | `curl http://localhost:3000/health` | backend health check가 정상 응답하는지 확인한다. |
-## 11. 수동 절차 상세
+### 7.2 Windows에서 WSL 설치
 ### 11.1 Windows에서 WSL 설치
 Windows Terminal 또는 PowerShell을 관리자 권한으로 실행한다.
@@ -307,7 +330,7 @@ wsl --install -d Ubuntu
 설치 후 Ubuntu를 실행하고 Linux 사용자 계정과 비밀번호를 만든다.
-### 11.2 Ubuntu 기본 패키지 설치
+### 7.3 Ubuntu 기본 패키지 설치
 Ubuntu 터미널에서 패키지 목록을 갱신한다.
@@ -336,7 +359,7 @@ make --version
 curl --version
 ```
-### 11.3 Docker 준비
+### 7.4 Docker 준비
 Baron SSO는 Docker Compose 기반으로 실행한다. Ubuntu 터미널에서 다음 명령이 동작해야 한다.
@@ -389,7 +412,7 @@ newgrp docker
 운영체제 선택 기준은 팀 표준을 따른다. 특별한 이유가 없으면 WSL 배포판은 Ubuntu 24.04 LTS 계열을 우선 권장하고, Ubuntu 26.04 계열은 커널/패키지 호환성 검증 전까지 보류한다. Docker 이미지의 base image는 운영 환경과 libc/패키지 계열 차이가 적은 Debian trixie slim 계열을 우선 검토한다.
-### 11.4 Baron SSO 소스코드 clone
+### 7.5 Baron SSO 소스코드 clone
 작업 디렉터리를 만든다.
@@ -433,7 +456,7 @@ git checkout feature/local-dev-setup-clean
 git status
 ```
-### 11.5 저장소 주요 파일 이해
+### 7.6 저장소 주요 파일 이해
 로컬 실행에서 특히 자주 보는 파일은 다음이다.
@@ -446,7 +469,7 @@ git status
 | `compose.ory.yaml` | Ory Stack 컨테이너 |
 | `docker-compose.yaml` | Baron SSO 앱 컨테이너 |
-### 11.6 `.env` 파일 준비
+### 7.7 `.env` 파일 준비
 최초 clone 직후에는 `.env.sample`을 복사한다.
@@ -493,7 +516,7 @@ DEVFRONT_URL=http://localhost:5174
 ORGFRONT_URL=http://localhost:5175
 ```
-### 11.7 인증 설정 생성 및 검증
+### 7.8 인증 설정 생성 및 검증
 `.env` 작성 후 Baron SSO 인증 설정을 검증한다.
@@ -513,7 +536,7 @@ config/.generated/auth-config.env
 검증에 실패하면 Docker Compose 스택을 올리기 전에 `.env`를 먼저 수정한다.
-### 11.8 Baron SSO 실행
+### 7.9 Baron SSO 실행
 전체 스택을 한 번에 실행한다.
@@ -540,7 +563,9 @@ make up-app
 make dev
 ```
-## 12. 자동 단계별 진행 요약
+## 8. 자동 설치
 ### 8.1 자동 단계별 진행 요약
 자동화는 WSL 이후의 반복 작업을 줄이기 위한 방식이다. 다만 Ubuntu 최초 사용자 생성, Gitea 인증, `.env` 민감값 작성은 완전 무인 처리 대상으로 보지 않는다.
@@ -575,7 +600,7 @@ project-baron-sso-setup.sh가 Baron SSO 전체 소스코드 clone
 | 8 | 인증 설정 검증 | Ubuntu 터미널 | `make validate-auth-config` | `.env` 확인 후 실행한다. 설정에 따라 자동 실행도 가능하다. |
 | 9 | 전체 스택 실행 | Ubuntu 터미널 | `make up-all` | 설정에 따라 자동 실행도 가능하지만, 기본값은 수동 실행 권장이다. |
-## 13. 자동화 파일 구조
+### 8.2 자동화 파일 구조
 자동화 파일은 Baron SSO에만 묶지 않고, 다른 프로젝트에도 재사용할 수 있도록 공통 설치 영역과 프로젝트별 설정 영역을 분리한다.
@@ -610,9 +635,9 @@ bootstrap-automation/
 다른 프로젝트를 추가할 때는 공통 설치 파일은 그대로 두고, `project-프로젝트명-setup.sh`와 `projects/프로젝트명.env.example`만 추가한다.
-## 14. 자동화 실행 방법
+### 8.3 자동화 실행 방법
-### 14.1 Windows PowerShell에서 공통 bootstrap 실행
+#### 8.3.1 Windows PowerShell에서 공통 bootstrap 실행
 PowerShell 실행 정책 때문에 스크립트 실행이 막히면 현재 세션에서만 우회한다.
@@ -666,7 +691,7 @@ Ubuntu가 없고 스크립트에서 설치까지 시도하려면 다음처럼
 .\windows-wsl-bootstrap.ps1 -InstallUbuntu
 ```
-### 14.2 Ubuntu에서 공통 설치 직접 실행
+#### 8.3.2 Ubuntu에서 공통 설치 직접 실행
 Windows bootstrap 없이 Ubuntu 터미널에서 직접 실행할 수도 있다. 이 경우에도 Baron SSO 전체 저장소가 미리 있을 필요는 없고, `bootstrap-automation` 자동화 스크립트 폴더만 있으면 된다.
@@ -690,7 +715,7 @@ cd /home/ubuntu/workspace/baron-sso/docs/local-run-notes/bootstrap-automation
 bash ./ubuntu-common-dev-setup.sh
 ```
-### 14.3 Baron SSO 프로젝트 setup 실행
+#### 8.3.3 Baron SSO 프로젝트 setup 실행
 공통 설치가 끝난 뒤 Baron SSO 전용 setup을 실행한다.
@@ -725,7 +750,7 @@ RUN_VALIDATE=true
 RUN_UP_ALL=true
 ```
-## 15. 자동화 시 입력받거나 확인해야 하는 값
+### 8.4 자동화 시 입력받거나 확인해야 하는 값
 자동화 파일을 실제 운영 수준으로 확장할 때는 다음 값을 사용자에게 입력받거나 설정 파일로 분리한다.
@@ -745,7 +770,9 @@ RUN_UP_ALL=true
 | Baron SSO 관리자 비밀번호 | 없음 | 초기 관리자 또는 테스트 | 저장 금지 |
 | 외부 연동 secret | 없음 | SMS, email, backup 테스트 | 저장 금지 |
-## 16. 정상 접속 URL
+## 9. 설치 후 확인
 ### 9.1 정상 접속 URL
 로컬 실행 후 확인할 기본 URL은 다음과 같다.
@@ -779,7 +806,7 @@ backend health check는 다음으로 확인한다.
 curl http://localhost:3000/health
 ```
-## 17. 컨테이너 상태 확인
+### 9.2 컨테이너 상태 확인
 실행 중인 컨테이너만 확인한다.
@@ -815,7 +842,7 @@ make logs-ory
 make logs-app
 ```
-## 18. 정상 복구 완료 기준
+### 9.3 정상 복구 완료 기준
 빈 PC에서 복구가 완료되었다고 판단하려면 다음 기준을 만족해야 한다.
@@ -829,7 +856,7 @@ make logs-app
 - 필요한 경우 AdminFront, DevFront, OrgFront 포트에 접속할 수 있다.
 - backend health check가 정상 응답한다.
-## 19. 현재 환경 복기
+### 9.4 현재 환경 복기
 현재 설치된 Baron SSO 환경을 확인했을 때, 일부 인프라 컨테이너는 실행 중이고 앱/Ory 컨테이너 일부는 중지 상태였다.
@@ -876,7 +903,9 @@ make up-app
 make up-all
 ```
-## 20. VS Code 저장과 Gitea 반영 흐름
+## 10. 작업 흐름과 문제 대응
 ### 10.1 VS Code 저장과 Gitea 반영 흐름
 VS Code에서 파일을 수정하고 저장해도 Gitea 서버에 바로 반영되지는 않는다.
@@ -916,9 +945,9 @@ Gitea 서버 반영
 따라서 팀원이 Gitea 웹에서 변경사항을 보려면 반드시 `git push`까지 완료해야 한다.
-## 21. 자주 발생하는 문제와 대응
+### 10.2 자주 발생하는 문제와 대응
-### 21.1 Docker socket 권한 오류
+#### 10.2.1 Docker socket 권한 오류
 증상:
@@ -933,7 +962,7 @@ permission denied while trying to connect to the docker API at unix:///var/run/d
 - Ubuntu 재시작 여부
 - Docker socket 접근 권한
-### 21.2 `.env` 작성 오류
+#### 10.2.2 `.env` 작성 오류
 증상:
@@ -952,7 +981,7 @@ make validate-auth-config
 실패 메시지를 보고 `.env`의 URL, callback, return URL 값을 수정한다.
-### 21.3 일부 컨테이너만 실행됨
+#### 10.2.3 일부 컨테이너만 실행됨
 증상:
@@ -977,7 +1006,7 @@ make up-dev
 make up-app
 ```
-### 21.4 포트 충돌
+#### 10.2.4 포트 충돌
 증상:
@@ -994,7 +1023,7 @@ docker ps
 필요 시 이미 떠 있는 컨테이너나 다른 프로세스가 같은 포트를 사용하는지 확인한다.
-## 22. 업무 복귀 시간 단축 방안
+### 10.3 업무 복귀 시간 단축 방안
 복구 시간을 줄이기 위해 다음 항목을 팀 표준으로 관리하는 것이 좋다.
@@ -1006,7 +1035,7 @@ docker ps
 6. 신규 PC 지급 시 이 문서 기준으로 실제 복구 시간을 측정한다.
 7. 반복적으로 막히는 지점은 스크립트화하거나 Makefile 타깃으로 추가한다.
-## 23. 빠른 복구 명령 모음
+### 10.4 빠른 복구 명령 모음
 새 PC에서 기본 도구와 Docker가 준비된 뒤 Baron SSO만 복구하는 핵심 명령은 다음과 같다.
@@ -1042,7 +1071,9 @@ http://localhost:5174
 http://localhost:5175
 ```
-## 24. 초기화 자동화 파일 사용법
+## 11. 초기화
 ### 11.1 초기화 자동화 파일 사용법
 프로젝트 진행 중에는 전체 재설치가 아니라 일부만 초기화해야 할 때가 있다. 이를 위해 초기화 스크립트를 단계별로 분리한다.
@@ -1065,7 +1096,7 @@ bootstrap-automation
 | 부분 삭제 2 | Docker, Baron SSO | `reset-docker-and-baron.sh` | Ubuntu 터미널 |
 | 부분 삭제 3 | Baron SSO 소스 폴더만 | `reset-baron-sso-project.sh` | Ubuntu 터미널 |
-### 24.1 모두 삭제 (`reset-all-wsl-ubuntu.ps1`)
+### 11.2 모두 삭제 (`reset-all-wsl-ubuntu.ps1`)
 이 방식은 **WSL까지 삭제한다는 의미**다. 정확히는 선택한 Ubuntu 배포판을 WSL에서 제거한 뒤, Windows의 WSL 관련 기능도 비활성화한다. Ubuntu 안에 있던 Docker, Docker image/volume, Baron SSO 소스코드도 함께 삭제된다.
@@ -1080,7 +1111,7 @@ cd $HOME\Downloads\bootstrap-automation
 .\reset-all-wsl-ubuntu.ps1 -DistroName Ubuntu -ConfirmText DELETE-WSL-UBUNTU
 ```
-### 24.2 부분 삭제 1: Ubuntu, Docker, Baron SSO 삭제 (`reset-ubuntu-distro.ps1`)
+### 11.3 부분 삭제 1: Ubuntu, Docker, Baron SSO 삭제 (`reset-ubuntu-distro.ps1`)
 WSL 기능은 유지하고, 특정 Ubuntu 배포판만 삭제한다. Ubuntu 안에 있던 Docker와 Baron SSO도 함께 삭제된다.
@@ -1093,7 +1124,7 @@ cd $HOME\Downloads\bootstrap-automation
 .\reset-ubuntu-distro.ps1 -DistroName Ubuntu -ConfirmText DELETE-UBUNTU
 ```
-### 24.3 부분 삭제 2: Docker, Baron SSO 삭제 (`reset-docker-and-baron.sh`)
+### 11.4 부분 삭제 2: Docker, Baron SSO 삭제 (`reset-docker-and-baron.sh`)
 Ubuntu는 유지하고, Ubuntu 안의 Docker 패키지/데이터와 Baron SSO 소스 폴더를 삭제한다.
@@ -1117,7 +1148,7 @@ cd ~/bootstrap-automation
 PROJECT_DIR=/home/ubuntu/workspace/baron-sso CONFIRM_TEXT=DELETE-DOCKER-BARON bash ./reset-docker-and-baron.sh
 ```
-### 24.4 부분 삭제 3: Baron SSO만 삭제 (`reset-baron-sso-project.sh`)
+### 11.5 부분 삭제 3: Baron SSO만 삭제 (`reset-baron-sso-project.sh`)
 WSL, Ubuntu, Docker는 유지하고 Baron SSO 소스 폴더만 삭제한다. 프로젝트 소스만 다시 clone하고 싶을 때 사용한다.
@@ -1141,7 +1172,7 @@ cd ~/bootstrap-automation
 PROJECT_DIR=/home/ubuntu/workspace/baron-sso CONFIRM_TEXT=DELETE-BARON bash ./reset-baron-sso-project.sh
 ```
-### 24.5 초기화 선택 기준
+### 11.6 초기화 선택 기준
 어떤 초기화를 선택할지는 다음 기준으로 판단한다.
@@ -1155,7 +1186,7 @@ PROJECT_DIR=/home/ubuntu/workspace/baron-sso CONFIRM_TEXT=DELETE-BARON bash ./re
 초기화 전에는 필요한 파일이 Git에 commit/push 되었는지 확인한다. VS Code에서 저장만 한 파일은 Gitea에 올라간 것이 아니다.
-## 25. 관련 문서
+## 12. 관련 문서
 - `README.md`
 - `Makefile`