From e219adf249ba939a85585f30ed3118ba21cc0c10 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=EB=AC=B8=ED=98=95=EC=84=9D?= Date: Fri, 19 Jun 2026 16:06:50 +0900 Subject: [PATCH] =?UTF-8?q?Update=20Baron=20SSO=20=EA=B0=9C=EB=B0=9C?= =?UTF-8?q?=ED=99=98=EA=B2=BD=20=EB=B3=B5=EA=B5=AC=20Runbook.md?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- Baron SSO 개발환경 복구 Runbook.md | 157 +++++++++++++++++------------ 1 file changed, 94 insertions(+), 63 deletions(-) diff --git a/Baron SSO 개발환경 복구 Runbook.md b/Baron SSO 개발환경 복구 Runbook.md index c934205..cf97f3b 100644 --- a/Baron SSO 개발환경 복구 Runbook.md +++ b/Baron SSO 개발환경 복구 Runbook.md @@ -6,27 +6,46 @@ - [2. 전체 요약](#2-전체-요약) - [3. 구성 요소 역할](#3-구성-요소-역할) - [4. 현재 Baron SSO 기준 정보](#4-현재-baron-sso-기준-정보) -- [5. 사전 준비 체크리스트](#5-사전-준비-체크리스트) -- [6. 설치 전 필요한 계정정보와 민감정보](#6-설치-전-필요한-계정정보와-민감정보) -- [7. 절대 스크립트에 넣지 말아야 할 값](#7-절대-스크립트에-넣지-말아야-할-값) -- [8. Gitea 인증 권장 방식](#8-gitea-인증-권장-방식) -- [9. 수동과 자동 진행 방식 구분](#9-수동과-자동-진행-방식-구분) -- [10. 수동 단계별 진행 요약](#10-수동-단계별-진행-요약) -- [11. 수동 절차 상세](#11-수동-절차-상세) -- [12. 자동 단계별 진행 요약](#12-자동-단계별-진행-요약) -- [13. 자동화 파일 구조](#13-자동화-파일-구조) -- [14. 자동화 실행 방법](#14-자동화-실행-방법) -- [15. 자동화 시 입력받거나 확인해야 하는 값](#15-자동화-시-입력받거나-확인해야-하는-값) -- [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-관련-문서) +- [5. 사전 준비](#5-사전-준비) + - [5.1 사전 준비 체크리스트](#51-사전-준비-체크리스트) + - [5.2 설치 전 필요한 계정정보와 민감정보](#52-설치-전-필요한-계정정보와-민감정보) + - [5.3 절대 스크립트에 넣지 말아야 할 값](#53-절대-스크립트에-넣지-말아야-할-값) + - [5.4 Gitea 인증 권장 방식](#54-gitea-인증-권장-방식) +- [6. 설치 방식 선택](#6-설치-방식-선택) + - [6.1 수동과 자동 진행 방식 구분](#61-수동과-자동-진행-방식-구분) +- [7. 수동 설치](#7-수동-설치) + - [7.1 수동 단계별 진행 요약](#71-수동-단계별-진행-요약) + - [7.2 Windows에서 WSL 설치](#72-windows에서-wsl-설치) + - [7.3 Ubuntu 기본 패키지 설치](#73-ubuntu-기본-패키지-설치) + - [7.4 Docker 준비](#74-docker-준비) + - [7.5 Baron SSO 소스코드 clone](#75-baron-sso-소스코드-clone) + - [7.6 저장소 주요 파일 이해](#76-저장소-주요-파일-이해) + - [7.7 `.env` 파일 준비](#77-env-파일-준비) + - [7.8 인증 설정 생성 및 검증](#78-인증-설정-생성-및-검증) + - [7.9 Baron SSO 실행](#79-baron-sso-실행) +- [8. 자동 설치](#8-자동-설치) + - [8.1 자동 단계별 진행 요약](#81-자동-단계별-진행-요약) + - [8.2 자동화 파일 구조](#82-자동화-파일-구조) + - [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. 수동 절차 상세 - -### 11.1 Windows에서 WSL 설치 +### 7.2 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`