From 56f17393dae3ed2af1806050a5e682cedc92faa1 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 13:21:22 +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 | 967 +++++++++++++++++++++++------ 1 file changed, 781 insertions(+), 186 deletions(-) diff --git a/Baron SSO 개발환경 복구 Runbook.md b/Baron SSO 개발환경 복구 Runbook.md index 289e88b..6dca393 100644 --- a/Baron SSO 개발환경 복구 Runbook.md +++ b/Baron SSO 개발환경 복구 Runbook.md @@ -1,262 +1,857 @@ -Windows 빈 PC 기준 Baron SSO 개발환경 복구 Runbook +# Baron SSO 개발환경 복구 Runbook -목적 -이 문서는 Windows 기준의 빈 PC에서 Baron SSO 개발환경을 다시 구성하고, -업무에 복귀하기까지의 흐름을 설명한다. +## 1. 문서 목적 -요구사항의 핵심은 단순히 개발환경을 한 번 설치하는 것이 아니라, -회사 PC나 서버에 문제가 생겼을 때 새 PC에서 개발환경을 최대한 빨리 복구하는 것이다. +이 문서는 Windows 기준의 빈 PC에서 Baron SSO 개발환경을 새로 구성하고, 개발자가 업무에 복귀하기까지의 표준 절차를 정리한다. -따라서 이 문서는 다음 상황을 기준으로 한다. +목표는 다음과 같다. -로컬 Windows PC에 개발환경이 전혀 설치되어 있지 않다. -WSL, Ubuntu, Docker, Git, Gitea clone부터 다시 진행해야 한다. -Baron SSO 소스코드를 Ubuntu 안에 올려 Docker Compose 기반으로 실행한다. -복구 완료 여부를 명령어와 접속 URL로 확인한다. -현재 Baron SSO 로컬 설치 기준 -현재 확인한 작업 위치는 다음과 같다. +- PC 교체, 장애, 초기 입사자 장비 지급 상황에서 개발환경 복구 시간을 줄인다. +- WSL, Ubuntu, Docker, Gitea, Baron SSO 실행 절차를 하나의 흐름으로 정리한다. +- "설치는 했는데 무엇이 정상 상태인지 모르는 문제"를 줄인다. +- 복구 완료 여부를 명령어와 접속 URL로 판정할 수 있게 한다. +이 문서는 현재 Baron SSO 저장소 구조와 실행 방식 기준으로 작성한다. + +## 2. 단계별 진행 요약 + +아래 표는 빈 Windows PC에서 Baron SSO 개발환경을 복구할 때의 전체 진행 순서다. 각 단계의 명령어는 대표 예시이며, 실제 환경에 따라 관리자 권한, VPN, Gitea 인증, `.env` 값 준비가 먼저 필요할 수 있다. + +| No | 단계 | 명령어 또는 작업 | 설명 | +| --- | --- | --- | --- | +| 1 | WSL 설치 | `wsl --install` | Windows 안에서 Linux를 실행할 수 있도록 WSL을 설치한다. 설치 후 재부팅이 필요할 수 있다. | +| 2 | Ubuntu 설치 확인 | `wsl --list --verbose` | Ubuntu 배포판이 설치되어 있고 실행 가능한지 확인한다. 없으면 `wsl --install -d Ubuntu`로 설치한다. | +| 3 | Ubuntu 패키지 갱신 | `sudo apt update` | Ubuntu 안의 패키지 목록을 최신 상태로 갱신한다. | +| 4 | 기본 도구 설치 | `sudo apt install -y git make curl ca-certificates` | Git clone, Makefile 실행, HTTP 확인에 필요한 기본 도구를 설치한다. | +| 5 | Docker 확인 | `docker --version` / `docker compose version` | Baron SSO는 Docker Compose로 실행되므로 Ubuntu 터미널에서 Docker 명령이 동작해야 한다. | +| 6 | 작업 폴더 생성 | `mkdir -p ~/workspace && cd ~/workspace` | WSL Ubuntu 안에 프로젝트 소스코드를 둘 작업 위치를 만든다. | +| 7 | Gitea 저장소 clone | `git clone https://gitea.hmac.kr/baron/baron-sso.git` | Gitea의 Baron SSO 원격 저장소를 로컬 WSL Ubuntu로 내려받는다. | +| 8 | 저장소 이동 | `cd baron-sso` | 내려받은 Baron SSO 프로젝트 루트로 이동한다. 이후 명령은 이 위치에서 실행한다. | +| 9 | 브랜치 전환 | `git checkout feature/local-dev-setup-clean` | 팀에서 지정한 작업 브랜치로 전환한다. 표준 브랜치가 바뀌면 이 값도 바꾼다. | +| 10 | 환경 파일 생성 | `cp .env.sample .env` | 샘플 환경 파일을 복사해 로컬 실행용 `.env` 파일을 만든다. | +| 11 | 환경값 작성 | `.env` 편집 | URL, callback, secret 등 로컬 실행에 필요한 값을 작성한다. 민감정보는 Git에 올리지 않는다. | +| 12 | 인증 설정 검증 | `make validate-auth-config` | `.env` 기반 인증 설정을 생성하고 callback/return URL 설정 오류를 사전에 확인한다. | +| 13 | 전체 스택 실행 | `make up-all` | 인프라, Ory Stack, Baron SSO 앱 컨테이너를 한 번에 실행한다. | +| 14 | 상태 확인 | `make ps` 또는 `docker ps` | 컨테이너가 정상적으로 실행 중인지 확인한다. 문제가 있으면 `logs-*` 명령으로 로그를 본다. | +| 15 | 접속 확인 | `http://localhost:5000` | 브라우저에서 UserFront/gateway에 접속해 Baron SSO 화면이 열리는지 확인한다. | +| 16 | 추가 화면 확인 | `http://localhost:5173`, `5174`, `5175` | AdminFront, DevFront, OrgFront 개발 화면이 필요한 경우 각 포트 접속을 확인한다. | +| 17 | Backend 확인 | `curl http://localhost:3000/health` | backend health check가 정상 응답하는지 확인한다. | +| 18 | 변경사항 저장 흐름 | `git add` → `git commit` → `git push` | VS Code 저장만으로는 Gitea에 올라가지 않는다. Gitea 반영은 반드시 `git push`까지 해야 한다. | + +## 3. 전체 요약 + +Baron SSO 로컬 개발환경은 Windows 위에 WSL Ubuntu를 설치하고, 그 안에서 Gitea 저장소의 소스코드를 받아 Docker Compose로 여러 서비스를 실행하는 방식이다. + +전체 구조는 다음과 같다. + +```text +Windows PC +└─ WSL + └─ Ubuntu + ├─ Baron SSO source + │ └─ /home/ubuntu/workspace/baron-sso + ├─ Git + │ └─ Gitea 저장소 clone/pull/push + └─ Docker + ├─ Infra stack + ├─ Ory stack + └─ App stack +``` + +복구 절차의 핵심 순서는 다음과 같다. + +1. Windows에서 WSL 설치 +2. Ubuntu 설치 및 기본 패키지 준비 +3. Docker 사용 가능 상태 확인 +4. Gitea에서 Baron SSO 저장소 clone +5. `.env` 작성 +6. 인증 설정 검증 +7. Docker Compose 스택 실행 +8. 브라우저 접속 및 상태 확인 + +## 4. 현재 Baron SSO 기준 정보 + +현재 로컬 작업 디렉터리는 다음 위치를 기준으로 한다. + +```bash /home/ubuntu/workspace/baron-sso -현재 브랜치는 다음과 같다. +``` -feature/local-dev-setup-clean -현재 Gitea 원격 저장소는 다음 기준으로 연결되어 있다. +현재 확인된 주요 원격 저장소는 다음과 같다. +```bash 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 개발환경을 복구하는 큰 흐름은 다음과 같다. +```bash +feature/local-dev-setup-clean +``` -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을 설치한다. +새 PC에서 복구할 때는 팀에서 지정한 브랜치를 기준으로 checkout한다. 운영 중인 표준 브랜치가 별도로 정해지면 이 문서의 브랜치 예시는 갱신해야 한다. +## 5. 구성 요소 역할 + +Baron SSO는 단일 서버 하나만 실행하는 프로젝트가 아니다. 여러 컨테이너가 함께 떠야 정상 동작한다. + +| 영역 | 주요 구성 | 역할 | +| --- | --- | --- | +| Windows | Windows 10/11 | 사용자의 기본 PC 환경 | +| WSL | Windows Subsystem for Linux | Windows 안에서 Linux 개발환경 실행 | +| Ubuntu | WSL 배포판 | 실제 개발 명령어를 실행하는 Linux 환경 | +| Docker | Docker Engine/Desktop | Baron SSO 관련 서버들을 컨테이너로 실행 | +| Git | git CLI | 소스코드 변경 이력 관리 | +| Gitea | gitea.hmac.kr | Baron SSO 원격 저장소 | +| Ory Stack | Kratos, Hydra, Keto, Oathkeeper | 인증/인가 기반 서비스 | +| Baron App | backend, userfront, adminfront, devfront, orgfront | Baron SSO 자체 애플리케이션 | + +## 6. 사전 준비 체크리스트 + +빈 PC에서 시작할 때 다음 항목이 준비되어야 한다. + +- Windows 관리자 권한 계정 +- 인터넷 또는 사내망 접속 +- Gitea 계정 +- Gitea 저장소 접근 권한 +- Docker Desktop 설치 권한 또는 Docker Engine 설치 권한 +- 필요한 경우 VPN 또는 사내 DNS 접근 +- Baron SSO `.env` 작성에 필요한 민감 설정값 + +민감 설정값은 문서에 직접 기록하지 않는다. `.env` 파일, 사내 보안 저장소, 담당자 전달 절차 등 별도 관리 방식을 따른다. + +## 7. Windows에서 WSL 설치 + +Windows Terminal 또는 PowerShell을 관리자 권한으로 실행한다. + +WSL을 설치한다. + +```powershell wsl --install -설치 후 PC 재부팅이 필요할 수 있다. +``` -설치 상태는 다음 명령으로 확인한다. +설치 후 재부팅이 필요할 수 있다. +설치 상태를 확인한다. + +```powershell wsl --status wsl --list --verbose -Ubuntu가 설치되어 있지 않으면 Microsoft Store 또는 wsl --install -d Ubuntu 방식으로 Ubuntu를 설치한다. +``` +Ubuntu가 설치되어 있지 않으면 다음 명령으로 설치한다. + +```powershell wsl --install -d Ubuntu -Ubuntu 기본 준비 -Ubuntu 터미널을 열고 패키지 목록을 갱신한다. +``` +설치 후 Ubuntu를 실행하고 Linux 사용자 계정과 비밀번호를 만든다. + +## 8. Ubuntu 기본 패키지 설치 + +Ubuntu 터미널에서 패키지 목록을 갱신한다. + +```bash sudo apt update sudo apt upgrade -y +``` + 기본 도구를 설치한다. +```bash sudo apt install -y git make curl ca-certificates -Docker는 Docker Desktop의 WSL integration을 사용하거나, Ubuntu 안에 Docker Engine을 직접 설치하는 방식 중 하나를 선택한다. +``` -팀 복구 절차에서는 한 가지 표준 방식을 정해두는 것이 좋다. 현재 Baron SSO 실행 기준에서는 Ubuntu 터미널에서 아래 명령이 동작해야 한다. +설치 확인: +```bash +git --version +make --version +curl --version +``` + +## 9. Docker 준비 + +Baron SSO는 Docker Compose 기반으로 실행한다. Ubuntu 터미널에서 다음 명령이 동작해야 한다. + +```bash docker --version docker compose version -Baron SSO 소스코드 clone +``` + +Docker Desktop을 사용하는 경우 확인할 항목: + +- Docker Desktop이 실행 중인지 확인한다. +- Docker Desktop 설정에서 WSL integration이 켜져 있는지 확인한다. +- 대상 Ubuntu 배포판에 integration이 활성화되어 있는지 확인한다. + +Docker 권한 문제가 발생하면 대표적으로 다음 메시지가 나온다. + +```text +permission denied while trying to connect to the docker API at unix:///var/run/docker.sock +``` + +이 경우 다음 순서로 확인한다. + +1. Docker Desktop 실행 여부 확인 +2. Docker Desktop WSL integration 확인 +3. Windows Terminal과 Ubuntu 재시작 +4. 필요 시 Windows 재부팅 +5. Docker socket 권한 또는 사용자 그룹 확인 + +## 10. Baron SSO 소스코드 clone + 작업 디렉터리를 만든다. +```bash mkdir -p ~/workspace cd ~/workspace -Gitea 저장소에서 Baron SSO를 clone한다. +``` +Gitea 저장소에서 Baron SSO 소스코드를 clone한다. + +```bash git clone https://gitea.hmac.kr/baron/baron-sso.git cd baron-sso -필요한 브랜치가 있다면 전환한다. +``` +원격 저장소 연결을 확인한다. + +```bash +git remote -v +``` + +팀에서 지정한 브랜치로 전환한다. + +```bash git checkout feature/local-dev-setup-clean +``` + 현재 상태를 확인한다. +```bash git status -git remote -v -환경 변수 파일 준비 -Baron SSO는 .env 파일을 기준으로 로컬 실행 설정을 읽는다. +``` -최초에는 샘플 파일을 복사한다. +정상적인 시작 상태에서는 작업 트리가 깨끗해야 한다. +```text +nothing to commit, working tree clean +``` + +단, 기존 작업이 있거나 문서/테스트 산출물이 있다면 변경 파일이 표시될 수 있다. + +## 11. 저장소 주요 파일 이해 + +Baron SSO 로컬 실행에서 자주 보는 파일은 다음과 같다. + +| 파일 | 설명 | +| --- | --- | +| `README.md` | 프로젝트 전체 설명과 기본 실행 가이드 | +| `Makefile` | 로컬 실행, 검증, 백업, 복구 명령 모음 | +| `.env.sample` | 환경 변수 샘플 | +| `.env` | 실제 로컬 환경 변수 파일 | +| `compose.infra.yaml` | 인프라 컨테이너 정의 | +| `compose.ory.yaml` | Ory Stack 컨테이너 정의 | +| `docker-compose.yaml` | Baron SSO 앱 컨테이너 정의 | +| `backend/` | Go backend | +| `userfront/` | Flutter 기반 UserFront | +| `adminfront/` | React 기반 AdminFront | +| `devfront/` | React 기반 DevFront | +| `orgfront/` | React 기반 OrgFront | +| `docs/` | 운영/개발 문서 | + +## 12. `.env` 파일 준비 + +최초 clone 직후에는 `.env.sample`을 복사한다. + +```bash cp .env.sample .env -그 다음 .env를 로컬 개발 환경에 맞게 수정한다. +``` -주의할 점은 다음과 같다. +그 다음 `.env`를 로컬 개발 환경에 맞게 작성한다. -KEY=value 형식으로 한 줄에 하나만 작성한다. -값 뒤에 같은 줄 주석을 붙이지 않는다. -URL 값 끝에 공백을 넣지 않는다. -callback URL 끝에 불필요한 /를 붙이지 않는다. -잘못된 예시는 다음과 같다. +작성 규칙: -USERFRONT_URL=http://localhost:5000 # 같은 줄 주석 금지 -올바른 예시는 다음과 같다. +- `KEY=value` 형식으로 작성한다. +- 한 줄에는 하나의 값만 작성한다. +- 값 뒤에 같은 줄 주석을 붙이지 않는다. +- URL 뒤에 공백을 넣지 않는다. +- callback URL 끝에 불필요한 `/`를 붙이지 않는다. +- 민감정보는 Git에 commit하지 않는다. -# UserFront 로컬 공개 URL +잘못된 예: + +```env +USERFRONT_URL=http://localhost:5000 # 로컬 주소 +``` + +올바른 예: + +```env +# 로컬 UserFront 주소 USERFRONT_URL=http://localhost:5000 -인증 설정 검증 -.env 작성 후 인증 설정을 생성하고 검증한다. +``` +로컬 개발에서 자주 보는 URL 예시는 다음과 같다. + +```env +USERFRONT_URL=http://localhost:5000 +ADMINFRONT_URL=http://localhost:5173 +DEVFRONT_URL=http://localhost:5174 +ORGFRONT_URL=http://localhost:5175 +``` + +실제 필요한 값은 현재 `.env.sample`과 팀 표준 설정을 기준으로 작성한다. + +## 13. 인증 설정 생성 및 검증 + +`.env` 작성 후 Baron SSO 인증 설정을 검증한다. + +```bash make validate-auth-config -이 명령은 내부적으로 다음 파일을 생성하고 callback, allowed return URL, gateway 매핑 등을 점검한다. +``` +이 명령은 인증 설정을 생성하고, callback URL과 return URL 설정이 올바른지 확인한다. + +생성되는 주요 파일: + +```bash config/.generated/auth-config.env -문제가 있으면 Baron SSO를 올리기 전에 .env 값을 먼저 수정한다. +``` + +검증에 실패하면 Docker Compose 스택을 올리기 전에 `.env`를 먼저 수정한다. + +필요 시 아래 명령을 단계별로 사용할 수 있다. + +```bash +make build-auth-config +make validate-auth-config +make verify-auth-config +``` + +## 14. Baron SSO 실행 + +### 14.1 전체 스택 한 번에 실행 + +가장 단순한 실행 명령은 다음이다. + +```bash +make up-all +``` + +이 명령은 인프라, Ory Stack, 앱 스택을 함께 실행한다. + +### 14.2 단계별 실행 + +문제 원인을 나누어 보기 위해 단계별로 실행할 수도 있다. -Baron SSO 실행 개발 기본 스택을 준비한다. +```bash make up-dev +``` + 앱 스택을 실행한다. +```bash make up-app -처음부터 전체를 한 번에 올릴 수도 있다. +``` -make up-all -프론트엔드 개발 중 HMR까지 포함해 포그라운드로 실행하려면 다음 명령을 사용한다. +프론트 개발 중 파일 변경을 바로 반영하는 개발 모드로 실행하려면 다음 명령을 사용한다. +```bash make dev -디버그 로그가 필요하면 다음 명령을 사용한다. +``` +디버그 로그를 켜고 실행하려면 다음 명령을 사용한다. + +```bash 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 -복구 완료 기준은 최소한 다음 항목을 만족하는 것이다. +## 15. 정상 접속 URL -Docker Compose 컨테이너가 정상적으로 올라온다. -http://localhost:5000에서 UserFront 또는 로그인 화면에 접근된다. -필요 시 http://localhost:5173, http://localhost:5174, http://localhost:5175에 각 React front가 접근된다. -backend health check가 정상 응답한다. -컨테이너 상태 확인 -전체 Compose 기준 상태는 다음 명령으로 확인한다. +로컬 실행 후 확인할 기본 URL은 다음과 같다. -docker compose -f compose.infra.yaml -f compose.ory.yaml -f docker-compose.yaml ps -a -실행 중인 컨테이너만 빠르게 보려면 다음 명령을 사용한다. +| 서비스 | 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 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 -브라우저에서는 다음 주소를 확인한다. +브라우저에서 최소한 다음 주소를 확인한다. +```text 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 +``` + +backend health check는 다음으로 확인한다. + +```bash +curl http://localhost:3000/health +``` + +## 16. 컨테이너 상태 확인 + +실행 중인 컨테이너만 확인한다. + +```bash +docker ps +``` + +Baron SSO 전체 Compose 기준으로 중지된 컨테이너까지 확인한다. + +```bash +docker compose -f compose.infra.yaml -f compose.ory.yaml -f docker-compose.yaml ps -a +``` + +Makefile 타깃을 사용할 수도 있다. + +```bash +make ps +``` + +로그 확인: + +```bash +make logs-infra +make logs-ory +make logs-app +``` + +## 17. 정상 복구 완료 기준 + +빈 PC에서 복구가 완료되었다고 판단하려면 다음 기준을 만족해야 한다. + +- Ubuntu 터미널에서 `docker --version`과 `docker compose version`이 정상 출력된다. +- Baron SSO 저장소가 `/home/ubuntu/workspace/baron-sso`에 clone되어 있다. +- `git remote -v`에서 Gitea 저장소가 보인다. +- `.env`가 작성되어 있다. +- `make validate-auth-config`가 통과한다. +- `make up-all` 또는 `make up-dev` + `make up-app` 실행 후 주요 컨테이너가 올라온다. +- `http://localhost:5000`에 접속할 수 있다. +- 필요한 경우 AdminFront, DevFront, OrgFront 포트에 접속할 수 있다. +- backend health check가 정상 응답한다. + +## 18. 현재 환경 복기 + +현재 설치된 Baron SSO 환경을 확인했을 때, 일부 인프라 컨테이너는 실행 중이고 앱/Ory 컨테이너 일부는 중지 상태였다. + +실행 중으로 확인된 컨테이너 예시: + +- `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 개발 스택이 완전히 실행 중인 상태는 아님"으로 판단할 수 있다. + +전체를 다시 올리는 기본 명령은 다음이다. + +```bash +make validate-auth-config +make up-dev +make up-app +``` + +또는 다음 명령을 사용한다. + +```bash +make up-all +``` + +## 19. VS Code 저장과 Gitea 반영 흐름 + +VS Code에서 파일을 수정하고 저장해도 Gitea 서버에 바로 반영되지는 않는다. + +흐름은 다음과 같다. + +```text +VS Code에서 파일 수정 + | + v +Ctrl+S 저장 + | + v +WSL Ubuntu 로컬 파일 변경 + | + v +git add + | + v +git commit + | + v +git push + | + v +Gitea 서버 반영 +``` + +각 단계의 의미는 다음과 같다. + +| 단계 | 의미 | Gitea 반영 여부 | +| --- | --- | --- | +| VS Code 수정 | 편집 화면에서 내용 변경 | 반영 안 됨 | +| 저장 | WSL 로컬 파일 변경 | 반영 안 됨 | +| `git add` | commit 대상에 포함 | 반영 안 됨 | +| `git commit` | 로컬 Git 이력 생성 | 반영 안 됨 | +| `git push` | 원격 Gitea 저장소로 업로드 | 반영됨 | + +따라서 팀원이 Gitea 웹에서 변경사항을 보려면 반드시 `git push`까지 완료해야 한다. + +## 20. 자주 발생하는 문제와 대응 + +### 20.1 Docker socket 권한 오류 + +증상: + +```text +permission denied while trying to connect to the docker API at unix:///var/run/docker.sock +``` + +확인: + +- Docker Desktop 실행 여부 +- WSL integration 활성화 여부 +- Ubuntu 재시작 여부 +- Docker socket 접근 권한 + +### 20.2 `.env` 작성 오류 + +증상: + +- `make validate-auth-config` 실패 +- Hydra/Kratos 기동 실패 +- callback URL 관련 오류 +- 로그인 후 redirect 실패 + +대응: + +```bash +make validate-auth-config +``` + +실패 메시지를 보고 `.env`의 URL, callback, return URL 값을 수정한다. + +### 20.3 일부 컨테이너만 실행됨 + +증상: + +- `docker ps`에는 일부 컨테이너만 보인다. +- 로그인 화면이 열리지 않는다. +- backend 또는 Ory 관련 오류가 발생한다. + +확인: + +```bash +docker compose -f compose.infra.yaml -f compose.ory.yaml -f docker-compose.yaml ps -a +``` + +복구: + +```bash +make up-dev +make up-app +``` + +### 20.4 포트 충돌 + +증상: + +- 특정 포트를 bind할 수 없다는 오류 발생 +- `localhost:5000`, `5173`, `5174`, `5175` 중 일부 접속 실패 + +확인: + +```bash +docker ps +``` + +필요 시 이미 떠 있는 컨테이너나 다른 프로세스가 같은 포트를 사용하는지 확인한다. + +## 21. 업무 복귀 시간 단축 방안 + +복구 시간을 줄이기 위해 다음 항목을 팀 표준으로 관리하는 것이 좋다. + +1. Windows/WSL/Ubuntu/Docker 설치 체크리스트를 별도 관리한다. +2. Docker Desktop WSL integration 설정 화면을 캡처해 둔다. +3. Baron SSO 로컬 개발용 `.env` 작성 가이드를 별도 관리한다. +4. `make validate-auth-config`, `make up-all`, `make ps`를 표준 복구 명령으로 정한다. +5. 정상 접속 URL과 정상 컨테이너 목록을 문서화한다. +6. 신규 PC 지급 시 이 문서 기준으로 실제 복구 시간을 측정한다. +7. 반복적으로 막히는 지점은 스크립트화하거나 Makefile 타깃으로 추가한다. + +## 22. 자동화 파일 분리 방향 + +빈 PC 자동화 파일은 Baron SSO에만 묶지 않고, 다른 프로젝트에도 재사용할 수 있도록 공통 설치 영역과 프로젝트별 설정 영역을 분리하는 것이 좋다. + +핵심 원칙은 다음과 같다. + +```text +Windows/WSL 공통 준비 + | + v +Ubuntu 공통 개발환경 준비 + | + v +프로젝트별 소스 clone 및 실행 +``` + +### 22.1 권장 파일 구조 + +자동화 파일은 다음처럼 나누는 것을 권장한다. + +```text +bootstrap/ +├─ windows-wsl-bootstrap.ps1 +├─ ubuntu-common-dev-setup.sh +├─ project-baron-sso-setup.sh +└─ projects/ + └─ baron-sso.env.example +``` + +각 파일의 책임은 다음과 같다. + +| 파일 | 실행 위치 | 성격 | 역할 | +| --- | --- | --- | --- | +| `windows-wsl-bootstrap.ps1` | Windows PowerShell | 공통 | WSL/Ubuntu 설치 여부 확인, WSL 2 확인, Ubuntu 내부 스크립트 실행 | +| `ubuntu-common-dev-setup.sh` | Ubuntu | 공통 | apt 갱신, git/make/curl 설치, Docker Engine 설치, Docker 권한 설정 | +| `project-baron-sso-setup.sh` | Ubuntu | Baron SSO 전용 | Baron SSO clone, 브랜치 checkout, `.env` 준비, `make validate-auth-config`, `make up-all` | +| `projects/baron-sso.env.example` | 설정 파일 | Baron SSO 전용 | 저장소 URL, 브랜치명, 프로젝트 경로, 실행 명령 등 프로젝트별 값 | + +이렇게 나누면 다른 프로젝트를 추가할 때 공통 설치 파일은 그대로 두고, `project-프로젝트명-setup.sh`와 설정 파일만 추가하면 된다. + +### 22.2 공통 영역과 프로젝트 전용 영역 구분 + +자동화 범위를 다음처럼 구분한다. + +| 영역 | 자동화 항목 | 공통/전용 | +| --- | --- | --- | +| Windows | WSL 설치 여부 확인 | 공통 | +| Windows | Ubuntu 설치 여부 확인 | 공통 | +| Windows | WSL 2 여부 확인 | 공통 | +| Windows | Ubuntu 내부 setup script 실행 | 공통 | +| Ubuntu | `apt update` | 공통 | +| Ubuntu | `git`, `make`, `curl`, `ca-certificates` 설치 | 공통 | +| Ubuntu | Docker Engine 설치 | 공통 | +| Ubuntu | Docker 권한 설정 | 공통 | +| Ubuntu | workspace 폴더 생성 | 공통 | +| Git | 저장소 clone | 프로젝트 전용 | +| Git | 브랜치 checkout | 프로젝트 전용 | +| 프로젝트 | `.env` 생성 또는 템플릿 복사 | 프로젝트 전용 | +| 프로젝트 | 설정 검증 명령 실행 | 프로젝트 전용 | +| 프로젝트 | 실행 명령 실행 | 프로젝트 전용 | + +캡처 기준으로 보면 빨간 영역은 `windows-wsl-bootstrap.ps1`에 해당하고, 노란 영역 중 `Docker 권한 설정`까지는 `ubuntu-common-dev-setup.sh`에 해당한다. 그 이후의 `Baron SSO git clone`, 브랜치 checkout, `.env`, `make` 실행은 Baron SSO 전용 파일로 분리한다. + +### 22.3 공통 Windows 부트스트랩 예시 + +Windows 쪽 공통 파일은 다음 역할만 맡는다. + +```text +windows-wsl-bootstrap.ps1 +├─ WSL 설치 여부 확인 +├─ Ubuntu 설치 여부 확인 +├─ WSL 2 여부 확인 +└─ Ubuntu 내부 common setup script 실행 +``` + +예시 흐름: + +```powershell +wsl --status +wsl --list --verbose +wsl -d Ubuntu -- bash -lc "./bootstrap/ubuntu-common-dev-setup.sh" +``` + +주의할 점: + +- Windows 관리자 권한이 필요할 수 있다. +- WSL 또는 Ubuntu 최초 설치 후 재부팅이 필요할 수 있다. +- Ubuntu 최초 실행 시 Linux 사용자명/비밀번호 생성은 수동 단계로 남을 수 있다. + +### 22.4 공통 Ubuntu 개발환경 setup 예시 + +Ubuntu 공통 파일은 특정 프로젝트를 모르는 상태로 개발 기본 환경만 준비한다. + +```text +ubuntu-common-dev-setup.sh +├─ apt update +├─ git/make/curl 설치 +├─ Docker Engine 설치 +├─ Docker compose 확인 +├─ Docker 권한 설정 +└─ ~/workspace 생성 +``` + +대표 명령은 다음과 같다. + +```bash +sudo apt update +sudo apt install -y git make curl ca-certificates +docker --version +docker compose version +mkdir -p ~/workspace +``` + +Docker 권한 설정은 팀 표준 Docker 설치 방식에 맞춰 작성한다. Docker Desktop WSL integration을 쓸지, Ubuntu 내부 Docker Engine을 쓸지 먼저 정해야 한다. + +### 22.5 프로젝트별 setup 예시 + +Baron SSO 전용 파일은 공통 개발환경이 준비된 뒤 실행한다. + +```text +project-baron-sso-setup.sh +├─ ~/workspace 이동 +├─ Baron SSO 저장소 clone +├─ 브랜치 checkout +├─ .env.sample -> .env 복사 +├─ 사용자에게 .env 작성 안내 +├─ make validate-auth-config +└─ make up-all +``` + +대표 명령은 다음과 같다. + +```bash +cd ~/workspace +git clone https://gitea.hmac.kr/baron/baron-sso.git +cd baron-sso +git checkout feature/local-dev-setup-clean +cp .env.sample .env +make validate-auth-config +make up-all +``` + +다른 프로젝트는 이 파일만 교체하면 된다. + +예를 들어 다른 프로젝트는 다음처럼 별도 파일을 둔다. + +```text +project-sample-api-setup.sh +project-sample-web-setup.sh +project-internal-admin-setup.sh +``` + +각 프로젝트 파일에는 해당 프로젝트의 저장소 URL, 브랜치명, 환경 파일 생성 방식, 실행 명령만 넣는다. + +### 22.6 자동화 시 입력받아야 하는 값 + +공통 자동화에서 필요한 값은 다음과 같다. + +| 값 | 필요한 이유 | 공통/전용 | 보관 방식 | +| --- | --- | --- | --- | +| Ubuntu 배포판 이름 | `wsl -d Ubuntu` 실행에 필요 | 공통 | 기본값 가능 | +| Ubuntu Linux 사용자명 | 경로와 권한 확인에 필요 | 공통 | 사용자 입력 또는 자동 감지 | +| workspace 경로 | 소스코드 clone 위치 | 공통 | 기본값 `~/workspace` | +| Docker 설치 방식 | Docker Desktop 연동 또는 Ubuntu Engine 선택 | 공통 | 팀 표준값 | +| Gitea 저장소 URL | clone 대상 | 프로젝트 전용 | 프로젝트 설정 파일 | +| Git 브랜치명 | checkout 대상 | 프로젝트 전용 | 프로젝트 설정 파일 | +| Gitea 인증 방식 | HTTPS token 또는 SSH key | 프로젝트 전용 | 사용자 입력 | +| Gitea Personal Access Token | HTTPS clone/push 인증 | 프로젝트 전용 | 스크립트 저장 금지 | +| SSH private key 경로 | SSH clone/push 인증 | 프로젝트 전용 | 사용자 PC 또는 보안 저장소 | +| `.env` 값 | 프로젝트 실행 설정 | 프로젝트 전용 | `.env` 또는 보안 저장소 | +| 관리자 계정 초기값 | Baron SSO 초기 admin seed | Baron SSO 전용 | 보안 저장소 | + +사이트 비밀번호나 Gitea 계정 비밀번호를 스크립트에 직접 저장하지 않는다. HTTPS 방식이면 Personal Access Token을 사용하고, SSH 방식이면 SSH key를 사용한다. + +### 22.7 최종 권장 실행 흐름 + +사용자 입장에서의 목표 흐름은 다음과 같다. + +```text +1. WSL은 사용자가 수동 설치 +2. PowerShell에서 공통 bootstrap 실행 +3. Ubuntu 공통 개발환경 자동 설치 +4. 프로젝트 선택 +5. 선택한 프로젝트 setup 실행 +6. 필요한 민감값만 사용자 입력 +7. 프로젝트 실행 및 접속 확인 +``` + +Baron SSO를 선택한 경우의 흐름은 다음과 같다. + +```text +windows-wsl-bootstrap.ps1 + | + v +ubuntu-common-dev-setup.sh + | + v +project-baron-sso-setup.sh + | + v +make validate-auth-config + | + v +make up-all +``` + +이 방식은 Baron SSO뿐 아니라 Docker Compose 기반의 다른 사내 프로젝트에도 확장할 수 있다. + +## 23. 빠른 복구 명령 모음 + +새 PC에서 기본 도구와 Docker가 준비된 뒤 Baron SSO만 복구하는 핵심 명령은 다음과 같다. + +```bash +mkdir -p ~/workspace +cd ~/workspace +git clone https://gitea.hmac.kr/baron/baron-sso.git +cd baron-sso +git checkout feature/local-dev-setup-clean +cp .env.sample .env +``` + +`.env`를 작성한 뒤 다음 명령을 실행한다. + +```bash +make validate-auth-config +make up-all +make ps +``` + +브라우저에서 다음 주소를 확인한다. + +```text +http://localhost:5000 +http://localhost:5173 +http://localhost:5174 +http://localhost:5175 +``` + +## 24. 관련 문서 + +- `README.md` +- `Makefile` +- `docs/local-run-notes/windows-empty-pc-baron-sso-recovery-runbook.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`