9.1 KiB
Windows 빈 PC 기준 Baron SSO 개발환경 복구 Runbook
목적 이 문서는 Windows 기준의 빈 PC에서 Baron SSO 개발환경을 다시 구성하고, 업무에 복귀하기까지의 흐름을 설명한다.
요구사항의 핵심은 단순히 개발환경을 한 번 설치하는 것이 아니라, 회사 PC나 서버에 문제가 생겼을 때 새 PC에서 개발환경을 최대한 빨리 복구하는 것이다.
따라서 이 문서는 다음 상황을 기준으로 한다.
로컬 Windows PC에 개발환경이 전혀 설치되어 있지 않다. WSL, Ubuntu, Docker, Git, Gitea clone부터 다시 진행해야 한다. Baron SSO 소스코드를 Ubuntu 안에 올려 Docker Compose 기반으로 실행한다. 복구 완료 여부를 명령어와 접속 URL로 확인한다. 현재 Baron SSO 로컬 설치 기준 현재 확인한 작업 위치는 다음과 같다.
/home/ubuntu/workspace/baron-sso 현재 브랜치는 다음과 같다.
feature/local-dev-setup-clean 현재 Gitea 원격 저장소는 다음 기준으로 연결되어 있다.
origin https://gitea.hmac.kr/baron/baron-sso.git fork https://kevin@gitea.hmac.kr/kevin/baron-sso.git Baron SSO는 단일 프로세스가 아니라 여러 구성요소를 Docker Compose로 함께 실행하는 구조다.
주요 Compose 파일은 다음과 같다.
파일 역할 compose.infra.yaml Baron SSO 인프라. Postgres, ClickHouse, Redis, gateway 등 compose.ory.yaml Ory Stack. Kratos, Hydra, Keto, Oathkeeper 등 docker-compose.yaml Baron SSO 앱. backend, userfront, adminfront, devfront, orgfront 등 Makefile 실행, 검증, 백업, 복구 명령 자동화 .env.sample 로컬 환경 변수 템플릿 .env 현재 로컬 실행 설정 전체 복구 흐름 빈 PC에서 Baron SSO 개발환경을 복구하는 큰 흐름은 다음과 같다.
Windows PC 준비 WSL 설치 WSL 안에 Ubuntu 설치 Ubuntu에서 Docker 또는 Docker Desktop WSL 연동 구성 Ubuntu에 Git 등 기본 도구 준비 Gitea에서 Baron SSO 저장소 clone /home/ubuntu/workspace/baron-sso 경로에 소스 배치 .env.sample을 기준으로 .env 작성 make validate-auth-config로 인증 설정 생성 및 검증 make up-dev, make up-app 또는 make up-all로 로컬 스택 실행 브라우저에서 Baron SSO 접속 확인 Windows에서 WSL 설치 Windows PowerShell 또는 Windows Terminal을 관리자 권한으로 실행한 뒤 WSL을 설치한다.
wsl --install 설치 후 PC 재부팅이 필요할 수 있다.
설치 상태는 다음 명령으로 확인한다.
wsl --status wsl --list --verbose Ubuntu가 설치되어 있지 않으면 Microsoft Store 또는 wsl --install -d Ubuntu 방식으로 Ubuntu를 설치한다.
wsl --install -d Ubuntu Ubuntu 기본 준비 Ubuntu 터미널을 열고 패키지 목록을 갱신한다.
sudo apt update sudo apt upgrade -y 기본 도구를 설치한다.
sudo apt install -y git make curl ca-certificates Docker는 Docker Desktop의 WSL integration을 사용하거나, Ubuntu 안에 Docker Engine을 직접 설치하는 방식 중 하나를 선택한다.
팀 복구 절차에서는 한 가지 표준 방식을 정해두는 것이 좋다. 현재 Baron SSO 실행 기준에서는 Ubuntu 터미널에서 아래 명령이 동작해야 한다.
docker --version docker compose version 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 checkout feature/local-dev-setup-clean 현재 상태를 확인한다.
git status git remote -v 환경 변수 파일 준비 Baron SSO는 .env 파일을 기준으로 로컬 실행 설정을 읽는다.
최초에는 샘플 파일을 복사한다.
cp .env.sample .env 그 다음 .env를 로컬 개발 환경에 맞게 수정한다.
주의할 점은 다음과 같다.
KEY=value 형식으로 한 줄에 하나만 작성한다. 값 뒤에 같은 줄 주석을 붙이지 않는다. URL 값 끝에 공백을 넣지 않는다. callback URL 끝에 불필요한 /를 붙이지 않는다. 잘못된 예시는 다음과 같다.
USERFRONT_URL=http://localhost:5000 # 같은 줄 주석 금지 올바른 예시는 다음과 같다.
UserFront 로컬 공개 URL
USERFRONT_URL=http://localhost:5000 인증 설정 검증 .env 작성 후 인증 설정을 생성하고 검증한다.
make validate-auth-config 이 명령은 내부적으로 다음 파일을 생성하고 callback, allowed return URL, gateway 매핑 등을 점검한다.
config/.generated/auth-config.env 문제가 있으면 Baron SSO를 올리기 전에 .env 값을 먼저 수정한다.
Baron SSO 실행 개발 기본 스택을 준비한다.
make up-dev 앱 스택을 실행한다.
make up-app 처음부터 전체를 한 번에 올릴 수도 있다.
make up-all 프론트엔드 개발 중 HMR까지 포함해 포그라운드로 실행하려면 다음 명령을 사용한다.
make dev 디버그 로그가 필요하면 다음 명령을 사용한다.
make dev-debug 접속 URL 로컬 실행 후 기본 접속 URL은 다음과 같다.
서비스 URL UserFront / gateway http://localhost:5000 Backend API http://localhost:3000 AdminFront http://localhost:5173 DevFront http://localhost:5174 OrgFront http://localhost:5175 ClickHouse http://localhost:8123 Kratos Public http://localhost:4433 Hydra Public http://localhost:4444 복구 완료 기준은 최소한 다음 항목을 만족하는 것이다.
Docker Compose 컨테이너가 정상적으로 올라온다. http://localhost:5000에서 UserFront 또는 로그인 화면에 접근된다. 필요 시 http://localhost:5173, http://localhost:5174, http://localhost:5175에 각 React front가 접근된다. backend health check가 정상 응답한다. 컨테이너 상태 확인 전체 Compose 기준 상태는 다음 명령으로 확인한다.
docker compose -f compose.infra.yaml -f compose.ory.yaml -f docker-compose.yaml ps -a 실행 중인 컨테이너만 빠르게 보려면 다음 명령을 사용한다.
docker ps Makefile에서도 상태 조회 타깃을 제공한다.
make ps 로그 확인은 다음 명령을 사용한다.
make logs-infra make logs-ory make logs-app 현재 확인된 컨테이너 상태 예시 현재 환경을 확인했을 때 실행 중이던 컨테이너는 주로 인프라 영역이었다.
실행 중:
baron_postgres baron_redis baron_clickhouse baron_gateway baron_promtail baron_blackbox_exporter 중지 상태:
baron_backend baron_userfront baron_adminfront baron_devfront baron_orgfront ory_kratos ory_hydra ory_keto ory_oathkeeper ory_postgres ory_clickhouse 따라서 현재 상태는 "설치 흔적과 구성은 남아 있고 일부 인프라는 올라와 있지만, Baron SSO 전체 개발 스택이 완전히 기동 중인 상태는 아님"으로 볼 수 있다.
전체 개발환경을 다시 올리려면 다음 흐름으로 복구한다.
make validate-auth-config make up-dev make up-app 또는 다음 명령으로 전체를 한 번에 올린다.
make up-all 자주 막히는 지점 Docker 명령 권한 문제 Ubuntu에서 docker ps 실행 시 Docker socket 권한 오류가 발생할 수 있다.
대표 증상:
permission denied while trying to connect to the docker API at unix:///var/run/docker.sock 이 경우 다음 항목을 확인한다.
Docker Desktop이 실행 중인지 확인한다. Docker Desktop의 WSL integration이 Ubuntu에 대해 켜져 있는지 확인한다. Ubuntu 사용자가 Docker socket에 접근 가능한지 확인한다. 필요 시 Windows와 WSL을 재시작한다. .env 오류 .env에 URL 뒤 공백, 같은 줄 주석, 잘못된 callback URL이 있으면 Hydra, Kratos, Ory 설정이 실패할 수 있다.
Baron SSO 실행 전에는 반드시 다음 명령을 먼저 통과시킨다.
make validate-auth-config 일부 컨테이너만 떠 있는 상태 인프라 컨테이너만 떠 있고 Ory나 앱 컨테이너가 중지되어 있으면 로그인 화면이 정상 동작하지 않을 수 있다.
이때는 전체 상태를 확인한다.
docker compose -f compose.infra.yaml -f compose.ory.yaml -f docker-compose.yaml ps -a 그 다음 필요한 스택을 다시 올린다.
make up-dev make up-app 업무 복귀 시간 단축을 위한 개선 포인트 현재 절차를 더 빠르게 만들기 위해 다음 항목을 표준화하면 좋다.
Windows/WSL/Ubuntu/Docker 설치 절차를 체크리스트화한다. Gitea clone부터 .env 준비까지 표준 절차를 고정한다. 로컬 개발용 .env에서 반드시 바꿔야 하는 값만 별도 표로 정리한다. make validate-auth-config, make up-dev, make up-app를 복구 기본 명령으로 정한다. Docker 권한 문제, WSL 재시작, 컨테이너 일부 중지 같은 반복 이슈의 해결 절차를 문서화한다. 복구 완료 판정 기준을 명확히 한다. 복구 완료 판정 기준 예시는 다음과 같다.
docker ps make ps curl http://localhost:3000/health 브라우저에서는 다음 주소를 확인한다.
http://localhost:5000 http://localhost:5173 http://localhost:5174 http://localhost:5175 관련 문서 README.md docs/local-run-notes/wsl-docker-gitea-mcp-guide.md docs/local-run-notes/wsl-local-run-2026-06-18.md docs/local-run-notes/wsl-setup-issues-2026-06-18.md docs/make-dev-vite-hmr-policy.md