Add Baron SSO 개발환경 복구 Runbook.md
This commit is contained in:
259
Baron SSO 개발환경 복구 Runbook.md
Normal file
259
Baron SSO 개발환경 복구 Runbook.md
Normal file
@@ -0,0 +1,259 @@
|
||||
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
|
||||
Reference in New Issue
Block a user