MyDoc/Baron SSO 개발환경 복구 Runbook.md

# Baron SSO 개발환경 설치 및 복구 Runbook

## 목차

- [1. 문서 목적](#1-문서-목적)
- [2. 전체 요약](#2-전체-요약)
- [3. 구성 요소 역할](#3-구성-요소-역할)
- [4. 현재 Baron SSO 기준 정보](#4-현재-baron-sso-기준-정보)
- [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. 문서 목적

이 문서는 Windows 기준의 빈 PC에서 Baron SSO 개발환경을 새로 구성하고, 개발자가 업무에 복귀하기까지의 표준 절차를 정리한다.

목표는 다음과 같다.

- PC 교체, 장애, 초기 입사자 장비 지급 상황에서 개발환경 복구 시간을 줄인다.
- WSL, Ubuntu, Docker, Gitea, Baron SSO 실행 절차를 하나의 흐름으로 정리한다.
- 수동 설치 절차와 자동화 파일 실행 절차를 구분한다.
- 설치 전 필요한 계정정보, 토큰, secret을 명확히 구분한다.
- 복구 완료 여부를 명령어와 접속 URL로 판정할 수 있게 한다.

## 2. 전체 요약

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
```

복구 절차는 크게 두 가지 방식으로 진행할 수 있다.

| 방식 | 설명 | 권장 상황 |
| --- | --- | --- |
| 수동 진행 | 명령어를 단계별로 직접 실행한다. | 최초 검증, 장애 원인 파악, 교육용 |
| 자동 진행 | 준비된 스크립트로 공통 설치와 프로젝트 설정을 실행한다. | 반복 설치, 신규 PC 세팅, 업무 복귀 시간 단축 |

## 3. 구성 요소 역할

Baron SSO는 단일 서버 하나만 실행하는 프로젝트가 아니다. 여러 컨테이너가 함께 떠야 정상 동작한다.

| 영역 | 주요 구성 | 역할 |
| --- | --- | --- |
| Windows | Windows 10/11 | 사용자의 기본 PC 환경 |
| WSL | Windows Subsystem for Linux | Windows 안에서 Linux 개발환경 실행 |
| Ubuntu | WSL 배포판 | 실제 개발 명령어를 실행하는 Linux 환경 |
| Docker | Ubuntu 내부 Docker Engine | 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 자체 애플리케이션 |

## 4. 현재 Baron SSO 기준 정보

현재 로컬 작업 디렉터리는 다음 위치를 기준으로 한다.

참고 위치: **WSL Ubuntu 파일 경로**

```bash
/home/ubuntu/workspace/baron-sso
```

현재 확인된 주요 원격 저장소는 다음과 같다.

참고 정보: **Git 원격 저장소 URL**

```bash
origin  https://gitea.hmac.kr/baron/baron-sso.git
fork    https://kevin@gitea.hmac.kr/kevin/baron-sso.git
```

현재 작업 브랜치 예시는 다음과 같다.

참고 정보: **Git 브랜치명**

```bash
feature/local-dev-setup-clean
```

새 PC에서 복구할 때는 팀에서 지정한 브랜치를 기준으로 checkout한다.

Git 저장소에는 하나의 소스코드만 있는 것이 아니라, 작업 목적에 따라 여러 갈래의 코드 흐름이 있을 수 있다. 이 갈래를 `브랜치(branch)`라고 한다. 예를 들어 `dev` 브랜치는 개발 기준 코드일 수 있고, `feature/local-dev-setup-clean` 브랜치는 로컬 개발환경 정리를 위해 따로 만든 작업 브랜치일 수 있다.

따라서 새 PC에서 소스코드를 clone한 뒤 아무 브랜치에서 작업하면 안 된다. 팀에서 현재 기준으로 삼는 브랜치가 무엇인지 확인한 뒤, 그 브랜치로 이동해야 한다. 이때 사용하는 명령이 `git checkout <브랜치명>`이다.

예:

실행 위치: **Ubuntu 터미널, Baron SSO 루트**

```bash
git checkout feature/local-dev-setup-clean
```

브랜치를 잘못 선택하면 다음 문제가 생길 수 있다.

- 문서에 적힌 파일이나 명령어가 현재 소스코드와 다를 수 있다.
- `.env.sample`, `Makefile`, Docker Compose 설정이 다를 수 있다.
- 팀원이 보고 있는 코드와 내 PC의 코드가 달라져 같은 문제를 재현하지 못할 수 있다.
- 수정한 내용을 push하거나 PR로 올릴 때 엉뚱한 브랜치 기준으로 작업할 수 있다.

운영 중인 표준 브랜치가 `dev`, `main`, `master`, 또는 다른 feature 브랜치로 바뀌면 이 문서의 예시 브랜치명도 함께 갱신해야 한다. 즉, 이 문서의 `feature/local-dev-setup-clean`은 현재 복기 기준의 예시이며, 항상 팀장이 지정한 최신 기준 브랜치를 우선한다.

주요 파일은 다음과 같다.

| 파일 | 설명 |
| --- | --- |
| `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 |
| `bootstrap-automation` | 개발환경 복구 자동화 파일 묶음 |

## 5. 사전 준비

### 5.1 사전 준비 체크리스트

빈 PC에서 시작할 때 다음 항목이 준비되어야 한다.

- Windows 관리자 권한 계정
- 인터넷 또는 사내망 접속
- 필요한 경우 VPN 또는 사내 DNS 접근
- Gitea 계정
- Gitea 저장소 접근 권한
- Ubuntu 내부 Docker Engine 설치 권한
- Baron SSO `.env` 작성에 필요한 민감 설정값
- 팀에서 지정한 표준 브랜치명

민감 설정값은 문서에 직접 기록하지 않는다. `.env` 파일, 사내 보안 저장소, 담당자 전달 절차 등 별도 관리 방식을 따른다.

### 5.2 설치 전 필요한 계정정보와 민감정보

개발환경 자동화는 설치 시간을 줄여주지만, 계정정보와 비밀번호를 잘못 다루면 보안 사고로 이어질 수 있다. 특히 자동화 스크립트 안에 사이트 비밀번호, Gitea 비밀번호, 운영 secret을 직접 적으면 안 된다.

반드시 기억할 원칙은 다음과 같다.

```text
자동화 파일에는 절차와 기본값만 넣고,
비밀번호와 토큰은 사용자 입력 또는 보안 저장소로 관리한다.
```

설치 전에 준비해야 하는 정보는 다음과 같다.

| 구분 | 필요한 정보 | 사용 시점 | 보관/입력 권장 방식 |
| --- | --- | --- | --- |
| Windows | Windows 관리자 권한 | WSL 설치 시 | 사용자 계정 권한으로 처리 |
| 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 값 | 백업 업로드 테스트 시 | 보안 저장소 |

### 5.3 절대 스크립트에 넣지 말아야 할 값

다음 값은 `.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`

### 5.4 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
```

## 6. 설치 방식 선택

### 6.1 수동과 자동 진행 방식 구분

수동 절차와 자동 절차는 목적이 다르다.

| 구분 | 수동 진행 | 자동 진행 |
| --- | --- | --- |
| 목적 | 각 단계 이해와 문제 원인 확인 | 반복 설치 시간 단축 |
| 실행 방식 | 사용자가 명령어를 직접 실행 | 스크립트가 공통 작업을 실행 |
| 장점 | 어디서 실패했는지 알기 쉽다 | 새 PC 복구가 빠르다 |
| 주의점 | 시간이 오래 걸린다 | secret을 스크립트에 넣지 않도록 주의해야 한다 |
| 권장 사용 | 첫 설치, 교육, 장애 대응 | 검증된 표준 절차 반복 |

처음에는 수동 절차로 한 번 성공시킨 뒤, 같은 절차를 자동화 파일로 옮기는 방식이 가장 안전하다.

## 7. 수동 설치

### 7.1 수동 단계별 진행 요약

아래 표는 빈 Windows PC에서 Baron SSO 개발환경을 수동으로 복구할 때의 전체 진행 순서다. `Windows PowerShell`은 Windows Terminal 또는 PowerShell에서 실행하고, `Ubuntu 터미널`은 WSL Ubuntu 안에서 실행한다.

| No | 단계 | 실행 위치 | 명령어 또는 작업 | 설명 |
| --- | --- | --- | --- | --- |
| 1 | WSL 설치 | Windows PowerShell, 관리자 권한 | `wsl --install` | Windows 안에서 Linux를 실행할 수 있도록 WSL을 설치한다. 이미 수동 설치했다면 확인만 한다. |
| 2 | Ubuntu 설치 확인 | Windows PowerShell | `wsl --list --verbose` | Ubuntu 배포판이 설치되어 있고 실행 가능한지 확인한다. 없으면 `wsl --install -d Ubuntu`로 설치한다. |
| 3 | Ubuntu 실행 | Windows 시작 메뉴 또는 Windows PowerShell | `wsl -d Ubuntu` | Ubuntu 터미널로 진입한다. 이후 Linux 명령어는 Ubuntu 터미널 안에서 실행한다. |
| 4 | Ubuntu 패키지 갱신 | Ubuntu 터미널 | `sudo apt update` | Ubuntu 패키지 목록을 최신 상태로 갱신한다. |
| 5 | 기본 도구 설치 | Ubuntu 터미널 | `sudo apt install -y git make curl ca-certificates` | Git clone, Makefile 실행, HTTP 확인에 필요한 기본 도구를 설치한다. |
| 6 | Docker 확인 | Ubuntu 터미널 | `docker --version` / `docker compose version` | Docker 명령이 동작하는지 확인한다. 동작하지 않으면 Ubuntu 내부 Docker Engine 설치와 권한 설정을 먼저 처리한다. |
| 7 | 작업 폴더 생성 | Ubuntu 터미널 | `mkdir -p ~/workspace && cd ~/workspace` | 프로젝트 소스코드를 둘 작업 위치를 만든다. |
| 8 | Gitea 저장소 clone | Ubuntu 터미널 | `git clone https://gitea.hmac.kr/baron/baron-sso.git` | Baron SSO 원격 저장소를 로컬 WSL Ubuntu로 내려받는다. |
| 9 | 저장소 이동 | Ubuntu 터미널 | `cd baron-sso` | Baron SSO 프로젝트 루트로 이동한다. 이후 Baron SSO 명령은 이 위치에서 실행한다. |
| 10 | 브랜치 전환 | Ubuntu 터미널 | `git checkout feature/local-dev-setup-clean` | 팀에서 지정한 작업 브랜치로 전환한다. |
| 11 | 환경 파일 생성 | Ubuntu 터미널 | `cp .env.sample .env` | 샘플 환경 파일을 복사해 로컬 실행용 `.env` 파일을 만든다. |
| 12 | 환경값 작성 | VS Code 또는 Ubuntu 편집기 | `.env` 편집 | URL, callback, secret 등 로컬 실행에 필요한 값을 작성한다. 민감정보는 Git에 올리지 않는다. |
| 13 | 인증 설정 검증 | Ubuntu 터미널, Baron SSO 루트 | `make validate-auth-config` | `.env` 기반 인증 설정과 callback/return URL 설정 오류를 사전에 확인한다. |
| 14 | 전체 스택 실행 | Ubuntu 터미널, Baron SSO 루트 | `make up-all` | 인프라, Ory Stack, Baron SSO 앱 컨테이너를 한 번에 실행한다. |
| 15 | 상태 확인 | Ubuntu 터미널, Baron SSO 루트 | `make ps` 또는 `docker ps` | 컨테이너가 정상적으로 실행 중인지 확인한다. |
| 16 | 접속 확인 | Windows 브라우저 | `http://localhost:5000` | UserFront/gateway에 접속해 Baron SSO 화면이 열리는지 확인한다. |
| 17 | 추가 화면 확인 | Windows 브라우저 | `http://localhost:5173`, `5174`, `5175` | AdminFront, DevFront, OrgFront 개발 화면이 필요한 경우 각 포트 접속을 확인한다. |
| 18 | Backend 확인 | Ubuntu 터미널 또는 Windows PowerShell | `curl http://localhost:3000/health` | backend health check가 정상 응답하는지 확인한다. |

### 7.2 Windows에서 WSL 설치

Windows Terminal 또는 PowerShell을 관리자 권한으로 실행한다.

실행 위치: **Windows PowerShell, 관리자 권한**

```powershell
wsl --install
```

설치 후 재부팅이 필요할 수 있다.

설치 상태를 확인한다.

실행 위치: **Windows PowerShell**

```powershell
wsl --status
wsl --list --verbose
```

Ubuntu가 설치되어 있지 않으면 다음 명령으로 설치한다.

실행 위치: **Windows PowerShell**

```powershell
wsl --install -d Ubuntu
```

설치 후 Ubuntu를 실행하고 Linux 사용자 계정과 비밀번호를 만든다.

### 7.3 Ubuntu 기본 패키지 설치

Ubuntu 터미널에서 패키지 목록을 갱신한다.

실행 위치: **Ubuntu 터미널**

```bash
sudo apt update
sudo apt upgrade -y
```

기본 도구를 설치한다.

실행 위치: **Ubuntu 터미널**

```bash
sudo apt install -y git make curl ca-certificates
```

설치 확인:

실행 위치: **Ubuntu 터미널**

```bash
git --version
make --version
curl --version
```

### 7.4 Docker 준비

Baron SSO는 Docker Compose 기반으로 실행한다. Ubuntu 터미널에서 다음 명령이 동작해야 한다.

실행 위치: **Ubuntu 터미널**

```bash
docker --version
docker compose version
```

Docker Desktop 사용은 지양한다. 팀 표준은 WSL Ubuntu 내부에 Docker Engine을 직접 설치하는 방식이다.

Docker Engine은 팀 표준 설치 스크립트 또는 Docker 공식 apt repository 방식으로 설치한다.

Ubuntu 24.04.4 기준으로, Ubuntu 기본 archive mirror가 느린 경우 apt mirror를 카카오 mirror로 바꾸고 Docker Engine을 설치할 수 있다. 이 명령은 WSL Ubuntu 터미널에 붙여 넣어 실행한다.

실행 위치: **Ubuntu 터미널**

```bash
# Ubuntu 24.04.4 기준
sudo sed -i 's/archive.ubuntu.com/mirror.kakao.com/g' /etc/apt/sources.list
sudo mkdir -p /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
sudo chmod a+r /etc/apt/keyrings/docker.gpg
sudo apt-get update
sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin python3-pip
sudo usermod -aG docker $USER
```

위 명령의 의미는 다음과 같다.

| 명령 | 설명 |
| --- | --- |
| `sed -i ... /etc/apt/sources.list` | Ubuntu 패키지 다운로드 mirror를 `archive.ubuntu.com`에서 `mirror.kakao.com`으로 변경한다. 기본 mirror가 느릴 때 설치 속도 개선을 기대할 수 있다. |
| `mkdir -p /etc/apt/keyrings` | Docker repository 서명키를 저장할 디렉터리를 만든다. |
| `curl ... \| gpg --dearmor ... docker.gpg` | Docker 공식 패키지 저장소의 GPG key를 받아 apt가 검증할 수 있는 형식으로 저장한다. |
| `echo "deb ... docker.list"` | 현재 Ubuntu 버전에 맞는 Docker apt repository를 추가한다. |
| `apt-get update` | Ubuntu와 Docker repository의 패키지 목록을 갱신한다. |
| `apt-get install ...` | Docker Engine, Docker Compose plugin, `python3-pip`를 설치한다. |
| `usermod -aG docker $USER` | 현재 사용자를 `docker` 그룹에 추가해 `sudo` 없이 Docker 명령을 실행할 수 있게 한다. |

`usermod -aG docker $USER` 실행 후에도 `docker ps`가 권한 오류를 내면 Ubuntu 터미널을 닫고 다시 열거나 다음 명령을 실행한다.

실행 위치: **Ubuntu 터미널**

```bash
newgrp docker
```

운영체제 선택 기준은 팀 표준을 따른다. 특별한 이유가 없으면 WSL 배포판은 Ubuntu 24.04 LTS 계열을 우선 권장하고, Ubuntu 26.04 계열은 커널/패키지 호환성 검증 전까지 보류한다. Docker 이미지의 base image는 운영 환경과 libc/패키지 계열 차이가 적은 Debian trixie slim 계열을 우선 검토한다.

### 7.5 Baron SSO 소스코드 clone

작업 디렉터리를 만든다.

실행 위치: **Ubuntu 터미널**

```bash
mkdir -p ~/workspace
cd ~/workspace
```

Gitea 저장소에서 Baron SSO 소스코드를 clone한다.

실행 위치: **Ubuntu 터미널, `~/workspace` 경로**

```bash
git clone https://gitea.hmac.kr/baron/baron-sso.git
cd baron-sso
```

원격 저장소 연결을 확인한다.

실행 위치: **Ubuntu 터미널, Baron SSO 루트**

```bash
git remote -v
```

팀에서 지정한 브랜치로 전환한다.

실행 위치: **Ubuntu 터미널, Baron SSO 루트**

```bash
git checkout feature/local-dev-setup-clean
```

현재 상태를 확인한다.

실행 위치: **Ubuntu 터미널, Baron SSO 루트**

```bash
git status
```

### 7.6 저장소 주요 파일 이해

로컬 실행에서 특히 자주 보는 파일은 다음이다.

| 파일 | 설명 |
| --- | --- |
| `.env.sample` | 환경 변수 샘플 |
| `.env` | 실제 로컬 환경 변수 파일 |
| `Makefile` | 실행/검증 명령 모음 |
| `compose.infra.yaml` | 인프라 컨테이너 |
| `compose.ory.yaml` | Ory Stack 컨테이너 |
| `docker-compose.yaml` | Baron SSO 앱 컨테이너 |

### 7.7 `.env` 파일 준비

최초 clone 직후에는 `.env.sample`을 복사한다.

실행 위치: **Ubuntu 터미널, Baron SSO 루트**

```bash
cp .env.sample .env
```

작성 규칙:

- `KEY=value` 형식으로 작성한다.
- 한 줄에는 하나의 값만 작성한다.
- 값 뒤에 같은 줄 주석을 붙이지 않는다.
- URL 뒤에 공백을 넣지 않는다.
- callback URL 끝에 불필요한 `/`를 붙이지 않는다.
- 민감정보는 Git에 commit하지 않는다.

잘못된 예:

편집 위치: **`.env` 파일**

```env
USERFRONT_URL=http://localhost:5000 # 로컬 주소
```

올바른 예:

편집 위치: **`.env` 파일**

```env
# 로컬 UserFront 주소
USERFRONT_URL=http://localhost:5000
```

로컬 개발에서 자주 보는 URL 예시는 다음과 같다.

편집 위치: **`.env` 파일**

```env
USERFRONT_URL=http://localhost:5000
ADMINFRONT_URL=http://localhost:5173
DEVFRONT_URL=http://localhost:5174
ORGFRONT_URL=http://localhost:5175
```

### 7.8 인증 설정 생성 및 검증

`.env` 작성 후 Baron SSO 인증 설정을 검증한다.

실행 위치: **Ubuntu 터미널, Baron SSO 루트**

```bash
make validate-auth-config
```

생성되는 주요 파일:

실행 위치: **파일 경로 참고**

```bash
config/.generated/auth-config.env
```

검증에 실패하면 Docker Compose 스택을 올리기 전에 `.env`를 먼저 수정한다.

### 7.9 Baron SSO 실행

전체 스택을 한 번에 실행한다.

실행 위치: **Ubuntu 터미널, Baron SSO 루트**

```bash
make up-all
```

문제 원인을 나누어 보기 위해 단계별로 실행할 수도 있다.

실행 위치: **Ubuntu 터미널, Baron SSO 루트**

```bash
make up-dev
make up-app
```

프론트 개발 중 파일 변경을 바로 반영하는 개발 모드로 실행하려면 다음 명령을 사용한다.

실행 위치: **Ubuntu 터미널, Baron SSO 루트**

```bash
make dev
```

## 8. 자동 설치

### 8.1 자동 단계별 진행 요약

자동화는 WSL 이후의 반복 작업을 줄이기 위한 방식이다. 다만 Ubuntu 최초 사용자 생성, Gitea 인증, `.env` 민감값 작성은 완전 무인 처리 대상으로 보지 않는다.

중요한 점은 **Baron SSO 전체 소스코드가 미리 로컬 PC에 없어도 자동화 진행이 가능하다**는 것이다. 단, 자동화를 시작하려면 `bootstrap-automation` 자동화 스크립트 폴더 안의 파일들은 먼저 확보되어 있어야 한다.

즉 관계는 다음과 같다.

```text
빈 PC
└─ bootstrap-automation 자동화 스크립트 폴더만 먼저 확보
   ├─ 사내 공유폴더
   ├─ USB
   ├─ 압축 파일
   └─ Gitea에서 bootstrap-automation만 다운로드
        |
        v
공통 설치 스크립트 실행
        |
        v
project-baron-sso-setup.sh가 Baron SSO 전체 소스코드 clone
```

| No | 단계 | 실행 위치 | 자동화 파일 | 설명 |
| --- | --- | --- | --- | --- |
| 1 | WSL 수동 설치 | Windows PowerShell | 해당 없음 | WSL은 사용자가 수동 설치한다고 가정한다. |
| 2 | Ubuntu 최초 실행 | Windows 시작 메뉴 또는 PowerShell | 해당 없음 | 최초 Linux 사용자명/비밀번호 생성은 사용자가 직접 처리한다. |
| 3 | 자동화 파일 확보 | Windows 파일 탐색기 또는 Ubuntu 터미널 | `bootstrap-automation` 자동화 스크립트 폴더 | Baron SSO 전체 소스가 아니라 자동화 스크립트 폴더만 먼저 준비한다. |
| 4 | Windows/WSL 확인 | Windows PowerShell | `windows-wsl-bootstrap.ps1` | WSL 명령, Ubuntu 배포판, WSL 상태를 확인한다. |
| 5 | Ubuntu 공통 설치 | Ubuntu 터미널 | `ubuntu-common-dev-setup.sh` | apt 갱신, git/make/curl 설치, Docker Engine 설치, Docker 권한 설정, workspace 생성을 수행한다. |
| 6 | Baron SSO 프로젝트 준비 | Ubuntu 터미널 | `project-baron-sso-setup.sh` | Baron SSO 저장소가 없으면 Gitea에서 clone하고, 있으면 기존 저장소를 사용한다. |
| 7 | `.env` 민감값 확인 | VS Code 또는 Ubuntu 편집기 | 수동 | secret, token, 관리자 비밀번호 등은 직접 확인하고 입력한다. |
| 8 | 인증 설정 검증 | Ubuntu 터미널 | `make validate-auth-config` | `.env` 확인 후 실행한다. 설정에 따라 자동 실행도 가능하다. |
| 9 | 전체 스택 실행 | Ubuntu 터미널 | `make up-all` | 설정에 따라 자동 실행도 가능하지만, 기본값은 수동 실행 권장이다. |

### 8.2 자동화 파일 구조

자동화 파일은 Baron SSO에만 묶지 않고, 다른 프로젝트에도 재사용할 수 있도록 공통 설치 영역과 프로젝트별 설정 영역을 분리한다.

사용자가 준비해야 하는 자동화 파일 묶음 이름:

```text
bootstrap-automation
```

현재 Baron SSO 저장소 안에서는 이 폴더가 `docs/local-run-notes/bootstrap-automation/` 경로에 보관되어 있다. 다만 빈 PC에서 자동화를 시작할 때 Baron SSO 전체 저장소가 이미 있어야 한다는 뜻은 아니다. 사용자는 `bootstrap-automation` 폴더만 별도로 복사하거나 다운로드해 실행할 수 있다. 이후 `project-baron-sso-setup.sh`가 Baron SSO 전체 저장소를 `~/workspace/baron-sso` 아래로 clone한다.

파일 구조:

```text
bootstrap-automation/
├─ README.md
├─ 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` 실행 |
| `projects/baron-sso.env.example` | 설정 파일 | Baron SSO 전용 | 저장소 URL, 브랜치명, 프로젝트 경로, 실행 명령 여부 |

다른 프로젝트를 추가할 때는 공통 설치 파일은 그대로 두고, `project-프로젝트명-setup.sh`와 `projects/프로젝트명.env.example`만 추가한다.

### 8.3 자동화 실행 방법

#### 8.3.1 Windows PowerShell에서 공통 bootstrap 실행

PowerShell 실행 정책 때문에 스크립트 실행이 막히면 현재 세션에서만 우회한다.

실행 위치: **Windows PowerShell**

```powershell
Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
```

먼저 `bootstrap-automation` 자동화 스크립트 폴더를 PC에 준비한다. 예를 들어 사내 공유폴더, USB, 압축 파일, 또는 Gitea에서 받은 폴더를 사용할 수 있다.

실행 위치: **Windows PowerShell**

아래 명령은 Windows PowerShell에서 실행한다. 먼저 `cd` 명령으로 자동화 스크립트 파일들이 들어있는 폴더로 이동한 뒤, 현재 폴더의 `windows-wsl-bootstrap.ps1` 파일을 실행한다.

```powershell
cd $HOME\Downloads\bootstrap-automation
.\windows-wsl-bootstrap.ps1
```

`.\windows-wsl-bootstrap.ps1` 앞의 `.\`는 "현재 내가 들어와 있는 폴더 안에 있는 파일을 실행한다"는 뜻이다.

이미 Baron SSO 저장소가 로컬에 있는 경우에는 저장소 안의 자동화 스크립트 폴더에서 실행해도 된다.

실행 위치: **Windows PowerShell**

아래 명령은 Windows PowerShell에서 실행한다. 먼저 `cd` 명령으로 WSL 안에 있는 Baron SSO 저장소의 자동화 스크립트 폴더로 이동한 뒤, 현재 폴더의 `windows-wsl-bootstrap.ps1` 파일을 실행한다.

```powershell
cd \\wsl.localhost\Ubuntu\home\ubuntu\workspace\baron-sso\docs\local-run-notes\bootstrap-automation
.\windows-wsl-bootstrap.ps1
```

Ubuntu 배포판 이름이 다르면 지정한다.

실행 위치: **Windows PowerShell**

아래 명령은 Windows PowerShell에서 실행한다. 먼저 자동화 스크립트 폴더로 이동한 상태에서, 현재 폴더의 `windows-wsl-bootstrap.ps1` 파일을 `Ubuntu-24.04` 배포판 이름으로 실행한다.

```powershell
.\windows-wsl-bootstrap.ps1 -DistroName Ubuntu-24.04
```

Ubuntu가 없고 스크립트에서 설치까지 시도하려면 다음처럼 실행할 수 있다.

실행 위치: **Windows PowerShell**

아래 명령은 Windows PowerShell에서 실행한다. 먼저 자동화 스크립트 폴더로 이동한 상태에서, 현재 폴더의 `windows-wsl-bootstrap.ps1` 파일을 Ubuntu 설치 옵션과 함께 실행한다.

```powershell
.\windows-wsl-bootstrap.ps1 -InstallUbuntu
```

#### 8.3.2 Ubuntu에서 공통 설치 직접 실행

Windows bootstrap 없이 Ubuntu 터미널에서 직접 실행할 수도 있다. 이 경우에도 Baron SSO 전체 저장소가 미리 있을 필요는 없고, `bootstrap-automation` 자동화 스크립트 폴더만 있으면 된다.

실행 위치: **Ubuntu 터미널**

아래 명령은 Ubuntu 터미널에서 실행한다. 먼저 `cd` 명령으로 자동화 스크립트 파일들이 들어있는 폴더로 이동한 뒤, 현재 폴더의 `ubuntu-common-dev-setup.sh` 파일을 실행한다.

```bash
cd ~/bootstrap-automation
bash ./ubuntu-common-dev-setup.sh
```

이미 Baron SSO 저장소가 로컬에 있는 경우에는 저장소 안의 자동화 스크립트 폴더에서 실행해도 된다.

실행 위치: **Ubuntu 터미널**

아래 명령은 Ubuntu 터미널에서 실행한다. 먼저 `cd` 명령으로 Baron SSO 저장소 안의 자동화 스크립트 폴더로 이동한 뒤, 현재 폴더의 `ubuntu-common-dev-setup.sh` 파일을 실행한다.

```bash
cd /home/ubuntu/workspace/baron-sso/docs/local-run-notes/bootstrap-automation
bash ./ubuntu-common-dev-setup.sh
```

#### 8.3.3 Baron SSO 프로젝트 setup 실행

공통 설치가 끝난 뒤 Baron SSO 전용 setup을 실행한다.

실행 위치: **Ubuntu 터미널**

아래 명령은 Ubuntu 터미널에서 실행한다. 먼저 `cd` 명령으로 자동화 스크립트 파일들이 들어있는 폴더로 이동한 뒤, 현재 폴더의 `project-baron-sso-setup.sh` 파일을 실행한다.

```bash
cd ~/bootstrap-automation
bash ./project-baron-sso-setup.sh
```

이 명령은 `~/workspace/baron-sso`가 없으면 Gitea에서 Baron SSO 전체 소스코드를 clone한다. 이미 `~/workspace/baron-sso`가 있으면 새로 clone하지 않고 기존 저장소를 사용한다.

이미 Baron SSO 저장소 안의 자동화 스크립트 폴더에서 실행 중이라면 다음처럼 실행해도 된다.

실행 위치: **Ubuntu 터미널**

아래 명령은 Ubuntu 터미널에서 실행한다. 먼저 `cd` 명령으로 Baron SSO 저장소 안의 자동화 스크립트 폴더로 이동한 뒤, 현재 폴더의 `project-baron-sso-setup.sh` 파일을 실행한다.

```bash
cd /home/ubuntu/workspace/baron-sso/docs/local-run-notes/bootstrap-automation
bash ./project-baron-sso-setup.sh
```

기본값으로는 `.env` 확인 전 `make validate-auth-config`와 `make up-all`을 자동 실행하지 않는다. 자동 실행하려면 설정 파일에서 다음 값을 바꾼다.

편집 위치: **`projects/baron-sso.env.example` 또는 복사한 프로젝트 설정 파일**

```bash
RUN_VALIDATE=true
RUN_UP_ALL=true
```

### 8.4 자동화 시 입력받거나 확인해야 하는 값

자동화 파일을 실제 운영 수준으로 확장할 때는 다음 값을 사용자에게 입력받거나 설정 파일로 분리한다.

| 항목 | 기본값 예시 | 설명 | 저장 가능 여부 |
| --- | --- | --- | --- |
| 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 설치 방식 | Ubuntu 내부 Docker Engine | 팀 표준 설치 방식 | 가능 |
| apt mirror 변경 여부 | `USE_KAKAO_MIRROR=true` | Ubuntu archive mirror가 느릴 때 카카오 mirror로 변경 | 가능 |
| `.env` 생성 방식 | `.env.sample` 복사 | 이후 민감값은 직접 입력 | 가능 |
| `make` 자동 실행 여부 | `false` 권장 | `.env` 확인 전 자동 실행을 막기 위함 | 가능 |
| Gitea PAT | 없음 | HTTPS Git 인증 | 저장 금지 |
| SSH private key | 없음 | SSH Git 인증 | 원문 저장 금지 |
| Baron SSO 관리자 비밀번호 | 없음 | 초기 관리자 또는 테스트 | 저장 금지 |
| 외부 연동 secret | 없음 | SMS, email, backup 테스트 | 저장 금지 |

## 9. 설치 후 확인

### 9.1 정상 접속 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` |

브라우저에서 최소한 다음 주소를 확인한다.

확인 위치: **Windows 브라우저**

```text
http://localhost:5000
http://localhost:5173
http://localhost:5174
http://localhost:5175
```

backend health check는 다음으로 확인한다.

실행 위치: **Ubuntu 터미널 또는 Windows PowerShell**

```bash
curl http://localhost:3000/health
```

### 9.2 컨테이너 상태 확인

실행 중인 컨테이너만 확인한다.

실행 위치: **Ubuntu 터미널**

```bash
docker ps
```

Baron SSO 전체 Compose 기준으로 중지된 컨테이너까지 확인한다.

실행 위치: **Ubuntu 터미널, Baron SSO 루트**

```bash
docker compose -f compose.infra.yaml -f compose.ory.yaml -f docker-compose.yaml ps -a
```

Makefile 타깃을 사용할 수도 있다.

실행 위치: **Ubuntu 터미널, Baron SSO 루트**

```bash
make ps
```

로그 확인:

실행 위치: **Ubuntu 터미널, Baron SSO 루트**

```bash
make logs-infra
make logs-ory
make logs-app
```

### 9.3 정상 복구 완료 기준

빈 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가 정상 응답한다.

### 9.4 현재 환경 복기

현재 설치된 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 개발 스택이 완전히 실행 중인 상태는 아님"으로 판단할 수 있다.

전체를 다시 올리는 기본 명령은 다음이다.

실행 위치: **Ubuntu 터미널, Baron SSO 루트**

```bash
make validate-auth-config
make up-dev
make up-app
```

또는 다음 명령을 사용한다.

실행 위치: **Ubuntu 터미널, Baron SSO 루트**

```bash
make up-all
```

## 10. 작업 흐름과 문제 대응

### 10.1 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`까지 완료해야 한다.

### 10.2 자주 발생하는 문제와 대응

#### 10.2.1 Docker socket 권한 오류

증상:

```text
permission denied while trying to connect to the docker API at unix:///var/run/docker.sock
```

확인:

- Docker daemon 실행 여부
- 현재 사용자의 `docker` 그룹 포함 여부
- Ubuntu 재시작 여부
- Docker socket 접근 권한

#### 10.2.2 `.env` 작성 오류

증상:

- `make validate-auth-config` 실패
- Hydra/Kratos 기동 실패
- callback URL 관련 오류
- 로그인 후 redirect 실패

대응:

실행 위치: **Ubuntu 터미널, Baron SSO 루트**

```bash
make validate-auth-config
```

실패 메시지를 보고 `.env`의 URL, callback, return URL 값을 수정한다.

#### 10.2.3 일부 컨테이너만 실행됨

증상:

- `docker ps`에는 일부 컨테이너만 보인다.
- 로그인 화면이 열리지 않는다.
- backend 또는 Ory 관련 오류가 발생한다.

확인:

실행 위치: **Ubuntu 터미널, Baron SSO 루트**

```bash
docker compose -f compose.infra.yaml -f compose.ory.yaml -f docker-compose.yaml ps -a
```

복구:

실행 위치: **Ubuntu 터미널, Baron SSO 루트**

```bash
make up-dev
make up-app
```

#### 10.2.4 포트 충돌

증상:

- 특정 포트를 bind할 수 없다는 오류 발생
- `localhost:5000`, `5173`, `5174`, `5175` 중 일부 접속 실패

확인:

실행 위치: **Ubuntu 터미널**

```bash
docker ps
```

필요 시 이미 떠 있는 컨테이너나 다른 프로세스가 같은 포트를 사용하는지 확인한다.

### 10.3 업무 복귀 시간 단축 방안

복구 시간을 줄이기 위해 다음 항목을 팀 표준으로 관리하는 것이 좋다.

1. Windows/WSL/Ubuntu/Docker 설치 체크리스트를 별도 관리한다.
2. Ubuntu 내부 Docker Engine 설치와 docker 그룹 권한 설정 절차를 표준화한다.
3. Baron SSO 로컬 개발용 `.env` 작성 가이드를 별도 관리한다.
4. `make validate-auth-config`, `make up-all`, `make ps`를 표준 복구 명령으로 정한다.
5. 정상 접속 URL과 정상 컨테이너 목록을 문서화한다.
6. 신규 PC 지급 시 이 문서 기준으로 실제 복구 시간을 측정한다.
7. 반복적으로 막히는 지점은 스크립트화하거나 Makefile 타깃으로 추가한다.

### 10.4 빠른 복구 명령 모음

새 PC에서 기본 도구와 Docker가 준비된 뒤 Baron SSO만 복구하는 핵심 명령은 다음과 같다.

실행 위치: **Ubuntu 터미널**

```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`를 작성한 뒤 다음 명령을 실행한다.

실행 위치: **Ubuntu 터미널, Baron SSO 루트**

```bash
make validate-auth-config
make up-all
make ps
```

브라우저에서 다음 주소를 확인한다.

확인 위치: **Windows 브라우저**

```text
http://localhost:5000
http://localhost:5173
http://localhost:5174
http://localhost:5175
```

## 11. 초기화

### 11.1 초기화 자동화 파일 사용법

프로젝트 진행 중에는 전체 재설치가 아니라 일부만 초기화해야 할 때가 있다. 이를 위해 초기화 스크립트를 단계별로 분리한다.

초기화 스크립트는 모두 **삭제 작업**을 수행한다. 실수 실행을 막기 위해 확인 문구를 입력해야만 동작하도록 작성한다.

초기화 파일 위치:

참고 위치: **자동화 스크립트 폴더**

```text
bootstrap-automation
```

초기화 범위는 다음과 같다.

| 구분 | 삭제 범위 | 실행 파일 | 실행 위치 |
| --- | --- | --- | --- |
| 모두 삭제 | WSL 기능 비활성화, Ubuntu 배포판, Docker, Baron SSO | `reset-all-wsl-ubuntu.ps1` | Windows PowerShell |
| 부분 삭제 1 | Ubuntu 배포판, Docker, Baron SSO | `reset-ubuntu-distro.ps1` | Windows PowerShell |
| 부분 삭제 2 | Docker, Baron SSO | `reset-docker-and-baron.sh` | Ubuntu 터미널 |
| 부분 삭제 3 | Baron SSO 소스 폴더만 | `reset-baron-sso-project.sh` | Ubuntu 터미널 |

### 11.2 모두 삭제 (`reset-all-wsl-ubuntu.ps1`)

이 방식은 **WSL까지 삭제한다는 의미**다. 정확히는 선택한 Ubuntu 배포판을 WSL에서 제거한 뒤, Windows의 WSL 관련 기능도 비활성화한다. Ubuntu 안에 있던 Docker, Docker image/volume, Baron SSO 소스코드도 함께 삭제된다.

이 작업 후에는 Windows 재부팅이 필요할 수 있다. WSL은 유지하고 Ubuntu 배포판만 삭제하려면 `부분 삭제 1`을 사용한다.

실행 위치: **Windows PowerShell**

아래 명령은 Windows PowerShell에서 실행한다. 먼저 `cd` 명령으로 자동화 스크립트 파일들이 들어있는 폴더로 이동한 뒤, 현재 폴더의 `reset-all-wsl-ubuntu.ps1` 파일을 실행한다.

```powershell
cd $HOME\Downloads\bootstrap-automation
.\reset-all-wsl-ubuntu.ps1 -DistroName Ubuntu -ConfirmText DELETE-WSL-UBUNTU
```

### 11.3 부분 삭제 1: Ubuntu, Docker, Baron SSO 삭제 (`reset-ubuntu-distro.ps1`)

WSL 기능은 유지하고, 특정 Ubuntu 배포판만 삭제한다. Ubuntu 안에 있던 Docker와 Baron SSO도 함께 삭제된다.

실행 위치: **Windows PowerShell**

아래 명령은 Windows PowerShell에서 실행한다. 먼저 `cd` 명령으로 자동화 스크립트 파일들이 들어있는 폴더로 이동한 뒤, 현재 폴더의 `reset-ubuntu-distro.ps1` 파일을 실행한다.

```powershell
cd $HOME\Downloads\bootstrap-automation
.\reset-ubuntu-distro.ps1 -DistroName Ubuntu -ConfirmText DELETE-UBUNTU
```

### 11.4 부분 삭제 2: Docker, Baron SSO 삭제 (`reset-docker-and-baron.sh`)

Ubuntu는 유지하고, Ubuntu 안의 Docker 패키지/데이터와 Baron SSO 소스 폴더를 삭제한다.

실행 위치: **Ubuntu 터미널**

아래 명령은 Ubuntu 터미널에서 실행한다. 먼저 `cd` 명령으로 자동화 스크립트 파일들이 들어있는 폴더로 이동한 뒤, 현재 폴더의 `reset-docker-and-baron.sh` 파일을 실행한다.

```bash
cd ~/bootstrap-automation
CONFIRM_TEXT=DELETE-DOCKER-BARON bash ./reset-docker-and-baron.sh
```

Baron SSO 폴더 경로가 기본값인 `~/workspace/baron-sso`가 아니라면 `PROJECT_DIR`로 지정한다.

실행 위치: **Ubuntu 터미널**

아래 명령은 Ubuntu 터미널에서 실행한다. 먼저 `cd` 명령으로 자동화 스크립트 파일들이 들어있는 폴더로 이동한 뒤, `PROJECT_DIR` 값과 확인 문구를 함께 지정해 현재 폴더의 `reset-docker-and-baron.sh` 파일을 실행한다.

```bash
cd ~/bootstrap-automation
PROJECT_DIR=/home/ubuntu/workspace/baron-sso CONFIRM_TEXT=DELETE-DOCKER-BARON bash ./reset-docker-and-baron.sh
```

### 11.5 부분 삭제 3: Baron SSO만 삭제 (`reset-baron-sso-project.sh`)

WSL, Ubuntu, Docker는 유지하고 Baron SSO 소스 폴더만 삭제한다. 프로젝트 소스만 다시 clone하고 싶을 때 사용한다.

실행 위치: **Ubuntu 터미널**

아래 명령은 Ubuntu 터미널에서 실행한다. 먼저 `cd` 명령으로 자동화 스크립트 파일들이 들어있는 폴더로 이동한 뒤, 현재 폴더의 `reset-baron-sso-project.sh` 파일을 실행한다.

```bash
cd ~/bootstrap-automation
CONFIRM_TEXT=DELETE-BARON bash ./reset-baron-sso-project.sh
```

Baron SSO 폴더 경로가 기본값인 `~/workspace/baron-sso`가 아니라면 `PROJECT_DIR`로 지정한다.

실행 위치: **Ubuntu 터미널**

아래 명령은 Ubuntu 터미널에서 실행한다. 먼저 `cd` 명령으로 자동화 스크립트 파일들이 들어있는 폴더로 이동한 뒤, `PROJECT_DIR` 값과 확인 문구를 함께 지정해 현재 폴더의 `reset-baron-sso-project.sh` 파일을 실행한다.

```bash
cd ~/bootstrap-automation
PROJECT_DIR=/home/ubuntu/workspace/baron-sso CONFIRM_TEXT=DELETE-BARON bash ./reset-baron-sso-project.sh
```

### 11.6 초기화 선택 기준

어떤 초기화를 선택할지는 다음 기준으로 판단한다.

| 상황 | 권장 초기화 |
| --- | --- |
| WSL/Ubuntu 자체가 꼬였거나 완전히 새로 시작해야 함 | 모두 삭제 또는 부분 삭제 1 |
| Docker image/volume이 꼬였고 Ubuntu는 유지하고 싶음 | 부분 삭제 2 |
| Baron SSO 소스코드만 다시 받고 싶음 | 부분 삭제 3 |
| `.env`만 잘못 작성됨 | 초기화 스크립트 사용하지 않고 `.env`만 수정 |
| 컨테이너만 재기동하면 됨 | 초기화 스크립트 사용하지 않고 `make down`, `make up-all` 사용 |

초기화 전에는 필요한 파일이 Git에 commit/push 되었는지 확인한다. VS Code에서 저장만 한 파일은 Gitea에 올라간 것이 아니다.

## 12. 관련 문서

- `README.md`
- `Makefile`
- `bootstrap-automation/README.md`
- `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`