kevin/MyDoc

Fork 0

Files

문형석 07740d3980 Update Baron SSO 개발환경 복구 Runbook.md

2026-06-19 15:50:09 +09:00

46 KiB

Raw Blame History

Baron SSO 개발환경 복구 Runbook

1. 문서 목적
2. 전체 요약
3. 구성 요소 역할
4. 현재 Baron SSO 기준 정보
5. 사전 준비 체크리스트
6. 설치 전 필요한 계정정보와 민감정보
7. 절대 스크립트에 넣지 말아야 할 값
8. Gitea 인증 권장 방식
9. 수동과 자동 진행 방식 구분
10. 수동 단계별 진행 요약
11. 수동 절차 상세
12. 자동 단계별 진행 요약
13. 자동화 파일 구조
14. 자동화 실행 방법
15. 자동화 시 입력받거나 확인해야 하는 값
16. 정상 접속 URL
17. 컨테이너 상태 확인
18. 정상 복구 완료 기준
19. 현재 환경 복기
20. VS Code 저장과 Gitea 반영 흐름
21. 자주 발생하는 문제와 대응
22. 업무 복귀 시간 단축 방안
23. 빠른 복구 명령 모음
24. 초기화 자동화 파일 사용법
25. 관련 문서

1. 문서 목적

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

목표는 다음과 같다.

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

2. 전체 요약

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

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

방식	설명	권장 상황
수동 진행	명령어를 단계별로 직접 실행한다.	최초 검증, 장애 원인 파악, 교육용
자동 진행	준비된 스크립트로 공통 설치와 프로젝트 설정을 실행한다.	반복 설치, 신규 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 파일 경로

/home/ubuntu/workspace/baron-sso

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

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

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

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

참고 정보: Git 브랜치명

feature/local-dev-setup-clean

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

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

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

예:

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

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. 사전 준비 체크리스트

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

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

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

6. 설치 전 필요한 계정정보와 민감정보

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

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

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

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

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

7. 절대 스크립트에 넣지 말아야 할 값

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

8. 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에 포함하는 방식은 사용하지 않는다.

잘못된 예:

https://username:password@gitea.hmac.kr/baron/baron-sso.git

권장 예:

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

9. 수동과 자동 진행 방식 구분

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

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

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

10. 수동 단계별 진행 요약

아래 표는 빈 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가 정상 응답하는지 확인한다.

11. 수동 절차 상세

11.1 Windows에서 WSL 설치

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

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

wsl --install

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

설치 상태를 확인한다.

실행 위치: Windows PowerShell

wsl --status
wsl --list --verbose

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

실행 위치: Windows PowerShell

wsl --install -d Ubuntu

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

11.2 Ubuntu 기본 패키지 설치

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

실행 위치: Ubuntu 터미널

sudo apt update
sudo apt upgrade -y

기본 도구를 설치한다.

실행 위치: Ubuntu 터미널

sudo apt install -y git make curl ca-certificates

설치 확인:

실행 위치: Ubuntu 터미널

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

11.3 Docker 준비

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

실행 위치: Ubuntu 터미널

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 터미널

# 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 터미널

newgrp docker

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

11.4 Baron SSO 소스코드 clone

작업 디렉터리를 만든다.

실행 위치: Ubuntu 터미널

mkdir -p ~/workspace
cd ~/workspace

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

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

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

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

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

git remote -v

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

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

git checkout feature/local-dev-setup-clean

현재 상태를 확인한다.

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

git status

11.5 저장소 주요 파일 이해

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

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

11.6 `.env` 파일 준비

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

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

cp .env.sample .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

11.7 인증 설정 생성 및 검증

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

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

make validate-auth-config

생성되는 주요 파일:

실행 위치: 파일 경로 참고

config/.generated/auth-config.env

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

11.8 Baron SSO 실행

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

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

make up-all

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

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

make up-dev
make up-app

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

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

make dev

12. 자동 단계별 진행 요약

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

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

즉 관계는 다음과 같다.

빈 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`	설정에 따라 자동 실행도 가능하지만, 기본값은 수동 실행 권장이다.

13. 자동화 파일 구조

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

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

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

파일 구조:

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만 추가한다.

14. 자동화 실행 방법

14.1 Windows PowerShell에서 공통 bootstrap 실행

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

실행 위치: Windows PowerShell

Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass

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

실행 위치: Windows PowerShell

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

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 파일을 실행한다.

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 배포판 이름으로 실행한다.

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

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

실행 위치: Windows PowerShell

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

.\windows-wsl-bootstrap.ps1 -InstallUbuntu

14.2 Ubuntu에서 공통 설치 직접 실행

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

실행 위치: Ubuntu 터미널

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

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

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

실행 위치: Ubuntu 터미널

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

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

14.3 Baron SSO 프로젝트 setup 실행

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

실행 위치: Ubuntu 터미널

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

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 파일을 실행한다.

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 또는 복사한 프로젝트 설정 파일

RUN_VALIDATE=true
RUN_UP_ALL=true

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

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

항목	기본값 예시	설명	저장 가능 여부
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 테스트	저장 금지

16. 정상 접속 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 브라우저

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

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

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

curl http://localhost:3000/health

17. 컨테이너 상태 확인

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

실행 위치: Ubuntu 터미널

docker ps

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

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

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

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

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

make ps

로그 확인:

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

make logs-infra
make logs-ory
make logs-app

18. 정상 복구 완료 기준

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

19. 현재 환경 복기

현재 설치된 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 루트

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

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

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

make up-all

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

21. 자주 발생하는 문제와 대응

21.1 Docker socket 권한 오류

증상:

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

확인:

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

21.2 `.env` 작성 오류

증상:

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

대응:

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

make validate-auth-config

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

21.3 일부 컨테이너만 실행됨

증상:

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

확인:

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

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

복구:

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

make up-dev
make up-app

21.4 포트 충돌

증상:

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

확인:

실행 위치: Ubuntu 터미널

docker ps

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

22. 업무 복귀 시간 단축 방안

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

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

23. 빠른 복구 명령 모음

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

실행 위치: Ubuntu 터미널

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 루트

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

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

확인 위치: Windows 브라우저

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

24. 초기화 자동화 파일 사용법

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

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

초기화 파일 위치:

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

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 터미널

24.1 모두 삭제 (`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 파일을 실행한다.

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

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

실행 위치: Windows PowerShell

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

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

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

실행 위치: Ubuntu 터미널

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

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 파일을 실행한다.

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

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

실행 위치: Ubuntu 터미널

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

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 파일을 실행한다.

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

24.5 초기화 선택 기준

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

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

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

25. 관련 문서

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

46 KiB Raw Blame History

Baron SSO 개발환경 복구 Runbook

목차

1. 문서 목적

2. 전체 요약

3. 구성 요소 역할

4. 현재 Baron SSO 기준 정보

5. 사전 준비 체크리스트

6. 설치 전 필요한 계정정보와 민감정보

7. 절대 스크립트에 넣지 말아야 할 값

8. Gitea 인증 권장 방식

9. 수동과 자동 진행 방식 구분

10. 수동 단계별 진행 요약

11. 수동 절차 상세

11.1 Windows에서 WSL 설치

11.2 Ubuntu 기본 패키지 설치

11.3 Docker 준비

11.4 Baron SSO 소스코드 clone

11.5 저장소 주요 파일 이해

11.6 .env 파일 준비

11.7 인증 설정 생성 및 검증

11.8 Baron SSO 실행

12. 자동 단계별 진행 요약

13. 자동화 파일 구조

14. 자동화 실행 방법

14.1 Windows PowerShell에서 공통 bootstrap 실행

14.2 Ubuntu에서 공통 설치 직접 실행

14.3 Baron SSO 프로젝트 setup 실행

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

16. 정상 접속 URL

17. 컨테이너 상태 확인

18. 정상 복구 완료 기준

19. 현재 환경 복기

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

21. 자주 발생하는 문제와 대응

21.1 Docker socket 권한 오류

21.2 .env 작성 오류

21.3 일부 컨테이너만 실행됨

21.4 포트 충돌

22. 업무 복귀 시간 단축 방안

23. 빠른 복구 명령 모음

24. 초기화 자동화 파일 사용법

24.1 모두 삭제 (reset-all-wsl-ubuntu.ps1)

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

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

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

24.5 초기화 선택 기준

25. 관련 문서

46 KiB

Raw Blame History

11.6 `.env` 파일 준비

21.2 `.env` 작성 오류

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

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

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

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