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로 여러 서비스를 실행하는 방식이다.

전체 구조는 다음과 같다.

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 기준 정보

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

/home/ubuntu/workspace/baron-sso

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

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

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

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을 설치한다.

wsl --install

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

설치 상태를 확인한다.

wsl --status
wsl --list --verbose

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

wsl --install -d Ubuntu

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

8. Ubuntu 기본 패키지 설치

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

sudo apt update
sudo apt upgrade -y

기본 도구를 설치한다.

sudo apt install -y git make curl ca-certificates

설치 확인:

git --version
make --version
curl --version

9. Docker 준비

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

docker --version
docker compose version

Docker Desktop을 사용하는 경우 확인할 항목:

• Docker Desktop이 실행 중인지 확인한다.
• Docker Desktop 설정에서 WSL integration이 켜져 있는지 확인한다.
• 대상 Ubuntu 배포판에 integration이 활성화되어 있는지 확인한다.

Docker 권한 문제가 발생하면 대표적으로 다음 메시지가 나온다.

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

작업 디렉터리를 만든다.

mkdir -p ~/workspace
cd ~/workspace

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

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

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

git remote -v

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

git checkout feature/local-dev-setup-clean

현재 상태를 확인한다.

git status

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

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을 복사한다.

cp .env.sample .env

그 다음 .env를 로컬 개발 환경에 맞게 작성한다.

작성 규칙:

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

잘못된 예:

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

올바른 예:

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

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

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 인증 설정을 검증한다.

make validate-auth-config

이 명령은 인증 설정을 생성하고, callback URL과 return URL 설정이 올바른지 확인한다.

생성되는 주요 파일:

config/.generated/auth-config.env

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

필요 시 아래 명령을 단계별로 사용할 수 있다.

make build-auth-config
make validate-auth-config
make verify-auth-config

14. Baron SSO 실행

14.1 전체 스택 한 번에 실행

가장 단순한 실행 명령은 다음이다.

make up-all

이 명령은 인프라, Ory Stack, 앱 스택을 함께 실행한다.

14.2 단계별 실행

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

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

make up-dev

앱 스택을 실행한다.

make up-app

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

make dev

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

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

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

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

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

curl http://localhost:3000/health

16. 컨테이너 상태 확인

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

docker ps

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

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

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

make ps

로그 확인:

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

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

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

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

make up-all

19. VS Code 저장과 Gitea 반영 흐름

VS Code에서 파일을 수정하고 저장해도 Gitea 서버에 바로 반영되지는 않는다.

흐름은 다음과 같다.

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 권한 오류

증상:

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 실패

대응:

make validate-auth-config

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

20.3 일부 컨테이너만 실행됨

증상:

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

확인:

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

복구:

make up-dev
make up-app

20.4 포트 충돌

증상:

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

확인:

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에만 묶지 않고, 다른 프로젝트에도 재사용할 수 있도록 공통 설치 영역과 프로젝트별 설정 영역을 분리하는 것이 좋다.

핵심 원칙은 다음과 같다.

Windows/WSL 공통 준비
        |
        v
Ubuntu 공통 개발환경 준비
        |
        v
프로젝트별 소스 clone 및 실행

22.1 권장 파일 구조

자동화 파일은 다음처럼 나누는 것을 권장한다.

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 쪽 공통 파일은 다음 역할만 맡는다.

windows-wsl-bootstrap.ps1
├─ WSL 설치 여부 확인
├─ Ubuntu 설치 여부 확인
├─ WSL 2 여부 확인
└─ Ubuntu 내부 common setup script 실행

예시 흐름:

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 공통 파일은 특정 프로젝트를 모르는 상태로 개발 기본 환경만 준비한다.

ubuntu-common-dev-setup.sh
├─ apt update
├─ git/make/curl 설치
├─ Docker Engine 설치
├─ Docker compose 확인
├─ Docker 권한 설정
└─ ~/workspace 생성

대표 명령은 다음과 같다.

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 전용 파일은 공통 개발환경이 준비된 뒤 실행한다.

project-baron-sso-setup.sh
├─ ~/workspace 이동
├─ Baron SSO 저장소 clone
├─ 브랜치 checkout
├─ .env.sample -> .env 복사
├─ 사용자에게 .env 작성 안내
├─ make validate-auth-config
└─ make up-all

대표 명령은 다음과 같다.

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

다른 프로젝트는 이 파일만 교체하면 된다.

예를 들어 다른 프로젝트는 다음처럼 별도 파일을 둔다.

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 최종 권장 실행 흐름

사용자 입장에서의 목표 흐름은 다음과 같다.

1. WSL은 사용자가 수동 설치
2. PowerShell에서 공통 bootstrap 실행
3. Ubuntu 공통 개발환경 자동 설치
4. 프로젝트 선택
5. 선택한 프로젝트 setup 실행
6. 필요한 민감값만 사용자 입력
7. 프로젝트 실행 및 접속 확인

Baron SSO를 선택한 경우의 흐름은 다음과 같다.

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만 복구하는 핵심 명령은 다음과 같다.

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

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

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

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