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

# Baron SSO 개발환경 복구 Runbook

## 1. 문서 목적

이 문서는 Windows 기준의 빈 PC에서 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
```

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

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

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

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

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

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

설치 상태를 확인한다.

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

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

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

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

## 8. Ubuntu 기본 패키지 설치

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

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

기본 도구를 설치한다.

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

설치 확인:

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

## 9. Docker 준비

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

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

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한다.

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

정상적인 시작 상태에서는 작업 트리가 깨끗해야 한다.

```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`를 로컬 개발 환경에 맞게 작성한다.

작성 규칙:

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

잘못된 예:

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

올바른 예:

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

로컬 개발에서 자주 보는 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 URL과 return URL 설정이 올바른지 확인한다.

생성되는 주요 파일:

```bash
config/.generated/auth-config.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 단계별 실행

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

개발 기본 스택을 준비한다.

```bash
make up-dev
```

앱 스택을 실행한다.

```bash
make up-app
```

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

```bash
make dev
```

디버그 로그를 켜고 실행하려면 다음 명령을 사용한다.

```bash
make dev-debug
```

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

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

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

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`