kevin/MyDoc

Fork 0

Files

문형석 298799f8b7 Update Baron SSO 개발환경 복구 Runbook.md

2026-06-19 13:54:47 +09:00

33 KiB

Raw Blame History

Baron SSO 개발환경 복구 Runbook

1. 문서 목적
2. 단계별 진행 요약
3. 전체 요약
4. 현재 Baron SSO 기준 정보
5. 구성 요소 역할
6. 사전 준비 체크리스트
7. 설치 전 필요한 계정정보와 민감정보
8. Windows에서 WSL 설치
9. Ubuntu 기본 패키지 설치
10. Docker 준비
11. Baron SSO 소스코드 clone
12. 저장소 주요 파일 이해
13. .env 파일 준비
14. 인증 설정 생성 및 검증
15. Baron SSO 실행
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 실행 절차를 하나의 흐름으로 정리한다.
"설치는 했는데 무엇이 정상 상태인지 모르는 문제"를 줄인다.
복구 완료 여부를 명령어와 접속 URL로 판정할 수 있게 한다.

이 문서는 현재 Baron SSO 저장소 구조와 실행 방식 기준으로 작성한다.

2. 단계별 진행 요약

아래 표는 빈 Windows PC에서 Baron SSO 개발환경을 복구할 때의 전체 진행 순서다. 각 단계의 명령어는 대표 예시이며, 실제 환경에 따라 관리자 권한, VPN, Gitea 인증, .env 값 준비가 먼저 필요할 수 있다.

명령어 실행 위치는 반드시 구분한다. Windows PowerShell은 Windows Terminal 또는 PowerShell에서 실행하고, Ubuntu 터미널은 WSL Ubuntu 안에서 실행한다.

No	단계	실행 위치	명령어 또는 작업	설명
1	WSL 설치	Windows PowerShell, 관리자 권한	`wsl --install`	Windows 안에서 Linux를 실행할 수 있도록 WSL을 설치한다. 설치 후 재부팅이 필요할 수 있다. 이미 WSL을 수동 설치했다면 이 단계는 확인만 한다.
2	Ubuntu 설치 확인	Windows PowerShell	`wsl --list --verbose`	Ubuntu 배포판이 설치되어 있고 실행 가능한지 확인한다. 없으면 Windows PowerShell에서 `wsl --install -d Ubuntu`로 설치한다.
3	Ubuntu 실행	Windows 시작 메뉴 또는 Windows PowerShell	`wsl -d Ubuntu`	Ubuntu 터미널로 진입한다. 이후 Linux 명령어는 Ubuntu 터미널 안에서 실행한다.
4	Ubuntu 패키지 갱신	Ubuntu 터미널	`sudo apt update`	Ubuntu 안의 패키지 목록을 최신 상태로 갱신한다. `sudo` 비밀번호 입력이 필요할 수 있다.
5	기본 도구 설치	Ubuntu 터미널	`sudo apt install -y git make curl ca-certificates`	Git clone, Makefile 실행, HTTP 확인에 필요한 기본 도구를 설치한다.
6	Docker 확인	Ubuntu 터미널	`docker --version` / `docker compose version`	Baron SSO는 Docker Compose로 실행되므로 Ubuntu 터미널에서 Docker 명령이 동작해야 한다. 동작하지 않으면 Docker 설치 또는 WSL integration 설정을 먼저 처리한다.
7	작업 폴더 생성	Ubuntu 터미널	`mkdir -p ~/workspace && cd ~/workspace`	WSL Ubuntu 안에 프로젝트 소스코드를 둘 작업 위치를 만든다.
8	Gitea 저장소 clone	Ubuntu 터미널	`git clone https://gitea.hmac.kr/baron/baron-sso.git`	Gitea의 Baron SSO 원격 저장소를 로컬 WSL Ubuntu로 내려받는다. HTTPS 인증 또는 SSH key 인증이 필요할 수 있다.
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`	컨테이너가 정상적으로 실행 중인지 확인한다. 문제가 있으면 `make logs-infra`, `make logs-ory`, `make logs-app`으로 로그를 본다.
16	접속 확인	Windows 브라우저	`http://localhost:5000`	브라우저에서 UserFront/gateway에 접속해 Baron SSO 화면이 열리는지 확인한다.
17	추가 화면 확인	Windows 브라우저	`http://localhost:5173`, `http://localhost:5174`, `http://localhost:5175`	AdminFront, DevFront, OrgFront 개발 화면이 필요한 경우 각 포트 접속을 확인한다.
18	Backend 확인	Ubuntu 터미널 또는 Windows PowerShell	`curl http://localhost:3000/health`	backend health check가 정상 응답하는지 확인한다.
19	변경사항 저장 흐름	Ubuntu 터미널 또는 VS Code Source Control	`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

복구 절차의 핵심 순서는 다음과 같다.

Windows에서 WSL 설치
Ubuntu 설치 및 기본 패키지 준비
Docker 사용 가능 상태 확인
Gitea에서 Baron SSO 저장소 clone
.env 작성
인증 설정 검증
Docker Compose 스택 실행
브라우저 접속 및 상태 확인

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. 설치 전 필요한 계정정보와 민감정보

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

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

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

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

구분	필요한 정보	사용 시점	보관/입력 권장 방식
Windows	Windows 관리자 권한	WSL 설치, Docker Desktop 설치 시	사용자 계정 권한으로 처리
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.1 절대 스크립트에 넣지 말아야 할 값

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

7.2 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

7.3 자동화 파일이 입력받거나 확인해야 하는 값

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

항목	기본값 예시	설명
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 설치 방식	Docker Engine 또는 Docker Desktop WSL integration	팀 표준에 맞춰 선택
`.env` 생성 방식	`.env.sample` 복사	이후 민감값은 직접 입력
`make` 자동 실행 여부	`false` 권장	`.env` 확인 전 자동 실행을 막기 위함

이 값 중 저장소 URL, 브랜치명, workspace 경로는 설정 파일에 저장해도 된다. 비밀번호, token, secret은 설정 파일에 저장하지 않는다.

8. Windows에서 WSL 설치

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

WSL을 설치한다.

wsl --install

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

설치 상태를 확인한다.

wsl --status
wsl --list --verbose

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

wsl --install -d Ubuntu

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

9. Ubuntu 기본 패키지 설치

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

sudo apt update
sudo apt upgrade -y

기본 도구를 설치한다.

sudo apt install -y git make curl ca-certificates

설치 확인:

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

10. 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

이 경우 다음 순서로 확인한다.

Docker Desktop 실행 여부 확인
Docker Desktop WSL integration 확인
Windows Terminal과 Ubuntu 재시작
필요 시 Windows 재부팅
Docker socket 권한 또는 사용자 그룹 확인

11. 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

단, 기존 작업이 있거나 문서/테스트 산출물이 있다면 변경 파일이 표시될 수 있다.

12. 저장소 주요 파일 이해

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/`	운영/개발 문서

13. `.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과 팀 표준 설정을 기준으로 작성한다.

14. 인증 설정 생성 및 검증

.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

15. Baron SSO 실행

15.1 전체 스택 한 번에 실행

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

make up-all

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

15.2 단계별 실행

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

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

make up-dev

앱 스택을 실행한다.

make up-app

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

make dev

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

make dev-debug

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`

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

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

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

curl http://localhost:3000/health

17. 컨테이너 상태 확인

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

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

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

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

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

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

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 Desktop 실행 여부
WSL integration 활성화 여부
Ubuntu 재시작 여부
Docker socket 접근 권한

21.2 `.env` 작성 오류

증상:

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

대응:

make validate-auth-config

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

21.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

21.4 포트 충돌

증상:

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

확인:

docker ps

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

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

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

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

23. 자동화 파일 분리 방향

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

핵심 원칙은 다음과 같다.

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

23.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와 설정 파일만 추가하면 된다.

23.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 전용 파일로 분리한다.

23.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 사용자명/비밀번호 생성은 수동 단계로 남을 수 있다.

23.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을 쓸지 먼저 정해야 한다.

23.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