From 07740d3980c78e3e24ec8dce2cfa87125bba69ac Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=EB=AC=B8=ED=98=95=EC=84=9D?= Date: Fri, 19 Jun 2026 15:50:09 +0900 Subject: [PATCH] =?UTF-8?q?Update=20Baron=20SSO=20=EA=B0=9C=EB=B0=9C?= =?UTF-8?q?=ED=99=98=EA=B2=BD=20=EB=B3=B5=EA=B5=AC=20Runbook.md?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- Baron SSO 개발환경 복구 Runbook.md | 960 +++++++++++++++++------------ 1 file changed, 576 insertions(+), 384 deletions(-) diff --git a/Baron SSO 개발환경 복구 Runbook.md b/Baron SSO 개발환경 복구 Runbook.md index 7b7eed5..6b342a5 100644 --- a/Baron SSO 개발환경 복구 Runbook.md +++ b/Baron SSO 개발환경 복구 Runbook.md @@ -3,20 +3,20 @@ ## 목차 - [1. 문서 목적](#1-문서-목적) -- [2. 단계별 진행 요약](#2-단계별-진행-요약) -- [3. 전체 요약](#3-전체-요약) +- [2. 전체 요약](#2-전체-요약) +- [3. 구성 요소 역할](#3-구성-요소-역할) - [4. 현재 Baron SSO 기준 정보](#4-현재-baron-sso-기준-정보) -- [5. 구성 요소 역할](#5-구성-요소-역할) -- [6. 사전 준비 체크리스트](#6-사전-준비-체크리스트) -- [7. 설치 전 필요한 계정정보와 민감정보](#7-설치-전-필요한-계정정보와-민감정보) -- [8. Windows에서 WSL 설치](#8-windows에서-wsl-설치) -- [9. Ubuntu 기본 패키지 설치](#9-ubuntu-기본-패키지-설치) -- [10. Docker 준비](#10-docker-준비) -- [11. Baron SSO 소스코드 clone](#11-baron-sso-소스코드-clone) -- [12. 저장소 주요 파일 이해](#12-저장소-주요-파일-이해) -- [13. `.env` 파일 준비](#13-env-파일-준비) -- [14. 인증 설정 생성 및 검증](#14-인증-설정-생성-및-검증) -- [15. Baron SSO 실행](#15-baron-sso-실행) +- [5. 사전 준비 체크리스트](#5-사전-준비-체크리스트) +- [6. 설치 전 필요한 계정정보와 민감정보](#6-설치-전-필요한-계정정보와-민감정보) +- [7. 절대 스크립트에 넣지 말아야 할 값](#7-절대-스크립트에-넣지-말아야-할-값) +- [8. Gitea 인증 권장 방식](#8-gitea-인증-권장-방식) +- [9. 수동과 자동 진행 방식 구분](#9-수동과-자동-진행-방식-구분) +- [10. 수동 단계별 진행 요약](#10-수동-단계별-진행-요약) +- [11. 수동 절차 상세](#11-수동-절차-상세) +- [12. 자동 단계별 진행 요약](#12-자동-단계별-진행-요약) +- [13. 자동화 파일 구조](#13-자동화-파일-구조) +- [14. 자동화 실행 방법](#14-자동화-실행-방법) +- [15. 자동화 시 입력받거나 확인해야 하는 값](#15-자동화-시-입력받거나-확인해야-하는-값) - [16. 정상 접속 URL](#16-정상-접속-url) - [17. 컨테이너 상태 확인](#17-컨테이너-상태-확인) - [18. 정상 복구 완료 기준](#18-정상-복구-완료-기준) @@ -24,8 +24,8 @@ - [20. VS Code 저장과 Gitea 반영 흐름](#20-vs-code-저장과-gitea-반영-흐름) - [21. 자주 발생하는 문제와 대응](#21-자주-발생하는-문제와-대응) - [22. 업무 복귀 시간 단축 방안](#22-업무-복귀-시간-단축-방안) -- [23. 자동화 파일 분리 방향](#23-자동화-파일-분리-방향) -- [24. 빠른 복구 명령 모음](#24-빠른-복구-명령-모음) +- [23. 빠른 복구 명령 모음](#23-빠른-복구-명령-모음) +- [24. 초기화 자동화 파일 사용법](#24-초기화-자동화-파일-사용법) - [25. 관련 문서](#25-관련-문서) ## 1. 문서 목적 @@ -36,40 +36,11 @@ - PC 교체, 장애, 초기 입사자 장비 지급 상황에서 개발환경 복구 시간을 줄인다. - WSL, Ubuntu, Docker, Gitea, Baron SSO 실행 절차를 하나의 흐름으로 정리한다. -- "설치는 했는데 무엇이 정상 상태인지 모르는 문제"를 줄인다. +- 수동 설치 절차와 자동화 파일 실행 절차를 구분한다. +- 설치 전 필요한 계정정보, 토큰, secret을 명확히 구분한다. - 복구 완료 여부를 명령어와 접속 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. 전체 요약 +## 2. 전체 요약 Baron SSO 로컬 개발환경은 Windows 위에 WSL Ubuntu를 설치하고, 그 안에서 Gitea 저장소의 소스코드를 받아 Docker Compose로 여러 서비스를 실행하는 방식이다. @@ -89,41 +60,14 @@ Windows PC └─ App stack ``` -복구 절차의 핵심 순서는 다음과 같다. +복구 절차는 크게 두 가지 방식으로 진행할 수 있다. -1. Windows에서 WSL 설치 -2. Ubuntu 설치 및 기본 패키지 준비 -3. Docker 사용 가능 상태 확인 -4. Gitea에서 Baron SSO 저장소 clone -5. `.env` 작성 -6. 인증 설정 검증 -7. Docker Compose 스택 실행 -8. 브라우저 접속 및 상태 확인 +| 방식 | 설명 | 권장 상황 | +| --- | --- | --- | +| 수동 진행 | 명령어를 단계별로 직접 실행한다. | 최초 검증, 장애 원인 파악, 교육용 | +| 자동 진행 | 준비된 스크립트로 공통 설치와 프로젝트 설정을 실행한다. | 반복 설치, 신규 PC 세팅, 업무 복귀 시간 단축 | -## 4. 현재 Baron SSO 기준 정보 - -현재 로컬 작업 디렉터리는 다음 위치를 기준으로 한다. - -```bash -/home/ubuntu/workspace/baron-sso -``` - -현재 확인된 주요 원격 저장소는 다음과 같다. - -```bash -origin https://gitea.hmac.kr/baron/baron-sso.git -fork https://kevin@gitea.hmac.kr/kevin/baron-sso.git -``` - -현재 작업 브랜치 예시는 다음과 같다. - -```bash -feature/local-dev-setup-clean -``` - -새 PC에서 복구할 때는 팀에서 지정한 브랜치를 기준으로 checkout한다. 운영 중인 표준 브랜치가 별도로 정해지면 이 문서의 브랜치 예시는 갱신해야 한다. - -## 5. 구성 요소 역할 +## 3. 구성 요소 역할 Baron SSO는 단일 서버 하나만 실행하는 프로젝트가 아니다. 여러 컨테이너가 함께 떠야 정상 동작한다. @@ -132,34 +76,103 @@ Baron SSO는 단일 서버 하나만 실행하는 프로젝트가 아니다. 여 | Windows | Windows 10/11 | 사용자의 기본 PC 환경 | | WSL | Windows Subsystem for Linux | Windows 안에서 Linux 개발환경 실행 | | Ubuntu | WSL 배포판 | 실제 개발 명령어를 실행하는 Linux 환경 | -| Docker | Docker Engine/Desktop | Baron SSO 관련 서버들을 컨테이너로 실행 | +| Docker | Ubuntu 내부 Docker Engine | Baron SSO 관련 서버들을 컨테이너로 실행 | | Git | git CLI | 소스코드 변경 이력 관리 | -| Gitea | gitea.hmac.kr | Baron SSO 원격 저장소 | +| Gitea | `gitea.hmac.kr` | Baron SSO 원격 저장소 | | Ory Stack | Kratos, Hydra, Keto, Oathkeeper | 인증/인가 기반 서비스 | | Baron App | backend, userfront, adminfront, devfront, orgfront | Baron SSO 자체 애플리케이션 | -## 6. 사전 준비 체크리스트 +## 4. 현재 Baron SSO 기준 정보 + +현재 로컬 작업 디렉터리는 다음 위치를 기준으로 한다. + +참고 위치: **WSL Ubuntu 파일 경로** + +```bash +/home/ubuntu/workspace/baron-sso +``` + +현재 확인된 주요 원격 저장소는 다음과 같다. + +참고 정보: **Git 원격 저장소 URL** + +```bash +origin https://gitea.hmac.kr/baron/baron-sso.git +fork https://kevin@gitea.hmac.kr/kevin/baron-sso.git +``` + +현재 작업 브랜치 예시는 다음과 같다. + +참고 정보: **Git 브랜치명** + +```bash +feature/local-dev-setup-clean +``` + +새 PC에서 복구할 때는 팀에서 지정한 브랜치를 기준으로 checkout한다. + +Git 저장소에는 하나의 소스코드만 있는 것이 아니라, 작업 목적에 따라 여러 갈래의 코드 흐름이 있을 수 있다. 이 갈래를 `브랜치(branch)`라고 한다. 예를 들어 `dev` 브랜치는 개발 기준 코드일 수 있고, `feature/local-dev-setup-clean` 브랜치는 로컬 개발환경 정리를 위해 따로 만든 작업 브랜치일 수 있다. + +따라서 새 PC에서 소스코드를 clone한 뒤 아무 브랜치에서 작업하면 안 된다. 팀에서 현재 기준으로 삼는 브랜치가 무엇인지 확인한 뒤, 그 브랜치로 이동해야 한다. 이때 사용하는 명령이 `git checkout <브랜치명>`이다. + +예: + +실행 위치: **Ubuntu 터미널, Baron SSO 루트** + +```bash +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 저장소 접근 권한 -- Docker Desktop 설치 권한 또는 Docker Engine 설치 권한 -- 필요한 경우 VPN 또는 사내 DNS 접근 +- Ubuntu 내부 Docker Engine 설치 권한 - Baron SSO `.env` 작성에 필요한 민감 설정값 +- 팀에서 지정한 표준 브랜치명 민감 설정값은 문서에 직접 기록하지 않는다. `.env` 파일, 사내 보안 저장소, 담당자 전달 절차 등 별도 관리 방식을 따른다. -## 7. 설치 전 필요한 계정정보와 민감정보 +## 6. 설치 전 필요한 계정정보와 민감정보 개발환경 자동화는 설치 시간을 줄여주지만, 계정정보와 비밀번호를 잘못 다루면 보안 사고로 이어질 수 있다. 특히 자동화 스크립트 안에 사이트 비밀번호, Gitea 비밀번호, 운영 secret을 직접 적으면 안 된다. 반드시 기억할 원칙은 다음과 같다. ```text -자동화 파일에는 절차만 넣고, +자동화 파일에는 절차와 기본값만 넣고, 비밀번호와 토큰은 사용자 입력 또는 보안 저장소로 관리한다. ``` @@ -167,7 +180,7 @@ Baron SSO는 단일 서버 하나만 실행하는 프로젝트가 아니다. 여 | 구분 | 필요한 정보 | 사용 시점 | 보관/입력 권장 방식 | | --- | --- | --- | --- | -| Windows | Windows 관리자 권한 | WSL 설치, Docker Desktop 설치 시 | 사용자 계정 권한으로 처리 | +| 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 | @@ -182,7 +195,7 @@ Baron SSO는 단일 서버 하나만 실행하는 프로젝트가 아니다. 여 | 외부 연동 | AWS SES key | 이메일 발송 기능 테스트 시 | 보안 저장소 | | 외부 연동 | WORKS Drive OAuth 값 | 백업 업로드 테스트 시 | 보안 저장소 | -### 7.1 절대 스크립트에 넣지 말아야 할 값 +## 7. 절대 스크립트에 넣지 말아야 할 값 다음 값은 `.ps1`, `.sh`, `.md`, `.env.example` 파일에 직접 적지 않는다. @@ -198,7 +211,7 @@ Baron SSO는 단일 서버 하나만 실행하는 프로젝트가 아니다. 여 - WORKS OAuth client secret, refresh token, access token - 운영 환경의 `COOKIE_SECRET`, `JWT_SECRET` -### 7.2 Gitea 인증 권장 방식 +## 8. Gitea 인증 권장 방식 Gitea 저장소 연결은 다음 둘 중 하나를 권장한다. @@ -222,28 +235,52 @@ https://gitea.hmac.kr/baron/baron-sso.git git@gitea.hmac.kr:baron/baron-sso.git ``` -### 7.3 자동화 파일이 입력받거나 확인해야 하는 값 +## 9. 수동과 자동 진행 방식 구분 -자동화 파일을 실제 운영 수준으로 확장할 때는 다음 값을 사용자에게 입력받거나 설정 파일로 분리한다. +수동 절차와 자동 절차는 목적이 다르다. -| 항목 | 기본값 예시 | 설명 | +| 구분 | 수동 진행 | 자동 진행 | | --- | --- | --- | -| 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` 확인 전 자동 실행을 막기 위함 | +| 목적 | 각 단계 이해와 문제 원인 확인 | 반복 설치 시간 단축 | +| 실행 방식 | 사용자가 명령어를 직접 실행 | 스크립트가 공통 작업을 실행 | +| 장점 | 어디서 실패했는지 알기 쉽다 | 새 PC 복구가 빠르다 | +| 주의점 | 시간이 오래 걸린다 | secret을 스크립트에 넣지 않도록 주의해야 한다 | +| 권장 사용 | 첫 설치, 교육, 장애 대응 | 검증된 표준 절차 반복 | -이 값 중 저장소 URL, 브랜치명, workspace 경로는 설정 파일에 저장해도 된다. 비밀번호, token, secret은 설정 파일에 저장하지 않는다. +처음에는 수동 절차로 한 번 성공시킨 뒤, 같은 절차를 자동화 파일로 옮기는 방식이 가장 안전하다. -## 8. Windows에서 WSL 설치 +## 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을 관리자 권한으로 실행한다. -WSL을 설치한다. +실행 위치: **Windows PowerShell, 관리자 권한** ```powershell wsl --install @@ -253,6 +290,8 @@ wsl --install 설치 상태를 확인한다. +실행 위치: **Windows PowerShell** + ```powershell wsl --status wsl --list --verbose @@ -260,16 +299,20 @@ wsl --list --verbose Ubuntu가 설치되어 있지 않으면 다음 명령으로 설치한다. +실행 위치: **Windows PowerShell** + ```powershell wsl --install -d Ubuntu ``` 설치 후 Ubuntu를 실행하고 Linux 사용자 계정과 비밀번호를 만든다. -## 9. Ubuntu 기본 패키지 설치 +### 11.2 Ubuntu 기본 패키지 설치 Ubuntu 터미널에서 패키지 목록을 갱신한다. +실행 위치: **Ubuntu 터미널** + ```bash sudo apt update sudo apt upgrade -y @@ -277,51 +320,81 @@ sudo apt upgrade -y 기본 도구를 설치한다. +실행 위치: **Ubuntu 터미널** + ```bash sudo apt install -y git make curl ca-certificates ``` 설치 확인: +실행 위치: **Ubuntu 터미널** + ```bash git --version make --version curl --version ``` -## 10. Docker 준비 +### 11.3 Docker 준비 Baron SSO는 Docker Compose 기반으로 실행한다. Ubuntu 터미널에서 다음 명령이 동작해야 한다. +실행 위치: **Ubuntu 터미널** + ```bash docker --version docker compose version ``` -Docker Desktop을 사용하는 경우 확인할 항목: +Docker Desktop 사용은 지양한다. 팀 표준은 WSL Ubuntu 내부에 Docker Engine을 직접 설치하는 방식이다. -- Docker Desktop이 실행 중인지 확인한다. -- Docker Desktop 설정에서 WSL integration이 켜져 있는지 확인한다. -- 대상 Ubuntu 배포판에 integration이 활성화되어 있는지 확인한다. +Docker Engine은 팀 표준 설치 스크립트 또는 Docker 공식 apt repository 방식으로 설치한다. -Docker 권한 문제가 발생하면 대표적으로 다음 메시지가 나온다. +Ubuntu 24.04.4 기준으로, Ubuntu 기본 archive mirror가 느린 경우 apt mirror를 카카오 mirror로 바꾸고 Docker Engine을 설치할 수 있다. 이 명령은 WSL Ubuntu 터미널에 붙여 넣어 실행한다. -```text -permission denied while trying to connect to the docker API at unix:///var/run/docker.sock +실행 위치: **Ubuntu 터미널** + +```bash +# 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 ``` -이 경우 다음 순서로 확인한다. +위 명령의 의미는 다음과 같다. -1. Docker Desktop 실행 여부 확인 -2. Docker Desktop WSL integration 확인 -3. Windows Terminal과 Ubuntu 재시작 -4. 필요 시 Windows 재부팅 -5. Docker socket 권한 또는 사용자 그룹 확인 +| 명령 | 설명 | +| --- | --- | +| `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 명령을 실행할 수 있게 한다. | -## 11. Baron SSO 소스코드 clone +`usermod -aG docker $USER` 실행 후에도 `docker ps`가 권한 오류를 내면 Ubuntu 터미널을 닫고 다시 열거나 다음 명령을 실행한다. + +실행 위치: **Ubuntu 터미널** + +```bash +newgrp docker +``` + +운영체제 선택 기준은 팀 표준을 따른다. 특별한 이유가 없으면 WSL 배포판은 Ubuntu 24.04 LTS 계열을 우선 권장하고, Ubuntu 26.04 계열은 커널/패키지 호환성 검증 전까지 보류한다. Docker 이미지의 base image는 운영 환경과 libc/패키지 계열 차이가 적은 Debian trixie slim 계열을 우선 검토한다. + +### 11.4 Baron SSO 소스코드 clone 작업 디렉터리를 만든다. +실행 위치: **Ubuntu 터미널** + ```bash mkdir -p ~/workspace cd ~/workspace @@ -329,6 +402,8 @@ cd ~/workspace Gitea 저장소에서 Baron SSO 소스코드를 clone한다. +실행 위치: **Ubuntu 터미널, `~/workspace` 경로** + ```bash git clone https://gitea.hmac.kr/baron/baron-sso.git cd baron-sso @@ -336,60 +411,51 @@ cd baron-sso 원격 저장소 연결을 확인한다. +실행 위치: **Ubuntu 터미널, Baron SSO 루트** + ```bash git remote -v ``` 팀에서 지정한 브랜치로 전환한다. +실행 위치: **Ubuntu 터미널, Baron SSO 루트** + ```bash git checkout feature/local-dev-setup-clean ``` 현재 상태를 확인한다. +실행 위치: **Ubuntu 터미널, Baron SSO 루트** + ```bash git status ``` -정상적인 시작 상태에서는 작업 트리가 깨끗해야 한다. +### 11.5 저장소 주요 파일 이해 -```text -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/` | 운영/개발 문서 | +| `Makefile` | 실행/검증 명령 모음 | +| `compose.infra.yaml` | 인프라 컨테이너 | +| `compose.ory.yaml` | Ory Stack 컨테이너 | +| `docker-compose.yaml` | Baron SSO 앱 컨테이너 | -## 13. `.env` 파일 준비 +### 11.6 `.env` 파일 준비 최초 clone 직후에는 `.env.sample`을 복사한다. +실행 위치: **Ubuntu 터미널, Baron SSO 루트** + ```bash cp .env.sample .env ``` -그 다음 `.env`를 로컬 개발 환경에 맞게 작성한다. - 작성 규칙: - `KEY=value` 형식으로 작성한다. @@ -401,12 +467,16 @@ cp .env.sample .env 잘못된 예: +편집 위치: **`.env` 파일** + ```env USERFRONT_URL=http://localhost:5000 # 로컬 주소 ``` 올바른 예: +편집 위치: **`.env` 파일** + ```env # 로컬 UserFront 주소 USERFRONT_URL=http://localhost:5000 @@ -414,6 +484,8 @@ USERFRONT_URL=http://localhost:5000 로컬 개발에서 자주 보는 URL 예시는 다음과 같다. +편집 위치: **`.env` 파일** + ```env USERFRONT_URL=http://localhost:5000 ADMINFRONT_URL=http://localhost:5173 @@ -421,74 +493,258 @@ DEVFRONT_URL=http://localhost:5174 ORGFRONT_URL=http://localhost:5175 ``` -실제 필요한 값은 현재 `.env.sample`과 팀 표준 설정을 기준으로 작성한다. - -## 14. 인증 설정 생성 및 검증 +### 11.7 인증 설정 생성 및 검증 `.env` 작성 후 Baron SSO 인증 설정을 검증한다. +실행 위치: **Ubuntu 터미널, Baron SSO 루트** + ```bash make validate-auth-config ``` -이 명령은 인증 설정을 생성하고, callback URL과 return URL 설정이 올바른지 확인한다. - 생성되는 주요 파일: +실행 위치: **파일 경로 참고** + ```bash config/.generated/auth-config.env ``` 검증에 실패하면 Docker Compose 스택을 올리기 전에 `.env`를 먼저 수정한다. -필요 시 아래 명령을 단계별로 사용할 수 있다. +### 11.8 Baron SSO 실행 -```bash -make build-auth-config -make validate-auth-config -make verify-auth-config -``` +전체 스택을 한 번에 실행한다. -## 15. Baron SSO 실행 - -### 15.1 전체 스택 한 번에 실행 - -가장 단순한 실행 명령은 다음이다. +실행 위치: **Ubuntu 터미널, Baron SSO 루트** ```bash make up-all ``` -이 명령은 인프라, Ory Stack, 앱 스택을 함께 실행한다. - -### 15.2 단계별 실행 - 문제 원인을 나누어 보기 위해 단계별로 실행할 수도 있다. -개발 기본 스택을 준비한다. +실행 위치: **Ubuntu 터미널, Baron SSO 루트** ```bash make up-dev -``` - -앱 스택을 실행한다. - -```bash make up-app ``` 프론트 개발 중 파일 변경을 바로 반영하는 개발 모드로 실행하려면 다음 명령을 사용한다. +실행 위치: **Ubuntu 터미널, Baron SSO 루트** + ```bash make dev ``` -디버그 로그를 켜고 실행하려면 다음 명령을 사용한다. +## 12. 자동 단계별 진행 요약 + +자동화는 WSL 이후의 반복 작업을 줄이기 위한 방식이다. 다만 Ubuntu 최초 사용자 생성, Gitea 인증, `.env` 민감값 작성은 완전 무인 처리 대상으로 보지 않는다. + +중요한 점은 **Baron SSO 전체 소스코드가 미리 로컬 PC에 없어도 자동화 진행이 가능하다**는 것이다. 단, 자동화를 시작하려면 `bootstrap-automation` 자동화 스크립트 폴더 안의 파일들은 먼저 확보되어 있어야 한다. + +즉 관계는 다음과 같다. + +```text +빈 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에만 묶지 않고, 다른 프로젝트에도 재사용할 수 있도록 공통 설치 영역과 프로젝트별 설정 영역을 분리한다. + +사용자가 준비해야 하는 자동화 파일 묶음 이름: + +```text +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한다. + +파일 구조: + +```text +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** + +```powershell +Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass +``` + +먼저 `bootstrap-automation` 자동화 스크립트 폴더를 PC에 준비한다. 예를 들어 사내 공유폴더, USB, 압축 파일, 또는 Gitea에서 받은 폴더를 사용할 수 있다. + +실행 위치: **Windows PowerShell** + +아래 명령은 Windows PowerShell에서 실행한다. 먼저 `cd` 명령으로 자동화 스크립트 파일들이 들어있는 폴더로 이동한 뒤, 현재 폴더의 `windows-wsl-bootstrap.ps1` 파일을 실행한다. + +```powershell +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` 파일을 실행한다. + +```powershell +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` 배포판 이름으로 실행한다. + +```powershell +.\windows-wsl-bootstrap.ps1 -DistroName Ubuntu-24.04 +``` + +Ubuntu가 없고 스크립트에서 설치까지 시도하려면 다음처럼 실행할 수 있다. + +실행 위치: **Windows PowerShell** + +아래 명령은 Windows PowerShell에서 실행한다. 먼저 자동화 스크립트 폴더로 이동한 상태에서, 현재 폴더의 `windows-wsl-bootstrap.ps1` 파일을 Ubuntu 설치 옵션과 함께 실행한다. + +```powershell +.\windows-wsl-bootstrap.ps1 -InstallUbuntu +``` + +### 14.2 Ubuntu에서 공통 설치 직접 실행 + +Windows bootstrap 없이 Ubuntu 터미널에서 직접 실행할 수도 있다. 이 경우에도 Baron SSO 전체 저장소가 미리 있을 필요는 없고, `bootstrap-automation` 자동화 스크립트 폴더만 있으면 된다. + +실행 위치: **Ubuntu 터미널** + +아래 명령은 Ubuntu 터미널에서 실행한다. 먼저 `cd` 명령으로 자동화 스크립트 파일들이 들어있는 폴더로 이동한 뒤, 현재 폴더의 `ubuntu-common-dev-setup.sh` 파일을 실행한다. ```bash -make dev-debug +cd ~/bootstrap-automation +bash ./ubuntu-common-dev-setup.sh ``` +이미 Baron SSO 저장소가 로컬에 있는 경우에는 저장소 안의 자동화 스크립트 폴더에서 실행해도 된다. + +실행 위치: **Ubuntu 터미널** + +아래 명령은 Ubuntu 터미널에서 실행한다. 먼저 `cd` 명령으로 Baron SSO 저장소 안의 자동화 스크립트 폴더로 이동한 뒤, 현재 폴더의 `ubuntu-common-dev-setup.sh` 파일을 실행한다. + +```bash +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` 파일을 실행한다. + +```bash +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` 파일을 실행한다. + +```bash +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` 또는 복사한 프로젝트 설정 파일** + +```bash +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은 다음과 같다. @@ -506,6 +762,8 @@ make dev-debug 브라우저에서 최소한 다음 주소를 확인한다. +확인 위치: **Windows 브라우저** + ```text http://localhost:5000 http://localhost:5173 @@ -515,6 +773,8 @@ http://localhost:5175 backend health check는 다음으로 확인한다. +실행 위치: **Ubuntu 터미널 또는 Windows PowerShell** + ```bash curl http://localhost:3000/health ``` @@ -523,24 +783,32 @@ curl http://localhost:3000/health 실행 중인 컨테이너만 확인한다. +실행 위치: **Ubuntu 터미널** + ```bash docker ps ``` Baron SSO 전체 Compose 기준으로 중지된 컨테이너까지 확인한다. +실행 위치: **Ubuntu 터미널, Baron SSO 루트** + ```bash docker compose -f compose.infra.yaml -f compose.ory.yaml -f docker-compose.yaml ps -a ``` Makefile 타깃을 사용할 수도 있다. +실행 위치: **Ubuntu 터미널, Baron SSO 루트** + ```bash make ps ``` 로그 확인: +실행 위치: **Ubuntu 터미널, Baron SSO 루트** + ```bash make logs-infra make logs-ory @@ -592,6 +860,8 @@ make logs-app 전체를 다시 올리는 기본 명령은 다음이다. +실행 위치: **Ubuntu 터미널, Baron SSO 루트** + ```bash make validate-auth-config make up-dev @@ -600,6 +870,8 @@ make up-app 또는 다음 명령을 사용한다. +실행 위치: **Ubuntu 터미널, Baron SSO 루트** + ```bash make up-all ``` @@ -656,8 +928,8 @@ permission denied while trying to connect to the docker API at unix:///var/run/d 확인: -- Docker Desktop 실행 여부 -- WSL integration 활성화 여부 +- Docker daemon 실행 여부 +- 현재 사용자의 `docker` 그룹 포함 여부 - Ubuntu 재시작 여부 - Docker socket 접근 권한 @@ -672,6 +944,8 @@ permission denied while trying to connect to the docker API at unix:///var/run/d 대응: +실행 위치: **Ubuntu 터미널, Baron SSO 루트** + ```bash make validate-auth-config ``` @@ -688,12 +962,16 @@ make validate-auth-config 확인: +실행 위치: **Ubuntu 터미널, Baron SSO 루트** + ```bash docker compose -f compose.infra.yaml -f compose.ory.yaml -f docker-compose.yaml ps -a ``` 복구: +실행 위치: **Ubuntu 터미널, Baron SSO 루트** + ```bash make up-dev make up-app @@ -708,6 +986,8 @@ make up-app 확인: +실행 위치: **Ubuntu 터미널** + ```bash docker ps ``` @@ -719,225 +999,19 @@ docker ps 복구 시간을 줄이기 위해 다음 항목을 팀 표준으로 관리하는 것이 좋다. 1. Windows/WSL/Ubuntu/Docker 설치 체크리스트를 별도 관리한다. -2. Docker Desktop WSL integration 설정 화면을 캡처해 둔다. +2. Ubuntu 내부 Docker Engine 설치와 docker 그룹 권한 설정 절차를 표준화한다. 3. Baron SSO 로컬 개발용 `.env` 작성 가이드를 별도 관리한다. 4. `make validate-auth-config`, `make up-all`, `make ps`를 표준 복구 명령으로 정한다. 5. 정상 접속 URL과 정상 컨테이너 목록을 문서화한다. 6. 신규 PC 지급 시 이 문서 기준으로 실제 복구 시간을 측정한다. 7. 반복적으로 막히는 지점은 스크립트화하거나 Makefile 타깃으로 추가한다. -## 23. 자동화 파일 분리 방향 - -빈 PC 자동화 파일은 Baron SSO에만 묶지 않고, 다른 프로젝트에도 재사용할 수 있도록 공통 설치 영역과 프로젝트별 설정 영역을 분리하는 것이 좋다. - -핵심 원칙은 다음과 같다. - -```text -Windows/WSL 공통 준비 - | - v -Ubuntu 공통 개발환경 준비 - | - v -프로젝트별 소스 clone 및 실행 -``` - -### 23.1 권장 파일 구조 - -자동화 파일은 다음처럼 나누는 것을 권장한다. - -```text -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 쪽 공통 파일은 다음 역할만 맡는다. - -```text -windows-wsl-bootstrap.ps1 -├─ WSL 설치 여부 확인 -├─ Ubuntu 설치 여부 확인 -├─ WSL 2 여부 확인 -└─ Ubuntu 내부 common setup script 실행 -``` - -예시 흐름: - -```powershell -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 공통 파일은 특정 프로젝트를 모르는 상태로 개발 기본 환경만 준비한다. - -```text -ubuntu-common-dev-setup.sh -├─ apt update -├─ git/make/curl 설치 -├─ Docker Engine 설치 -├─ Docker compose 확인 -├─ Docker 권한 설정 -└─ ~/workspace 생성 -``` - -대표 명령은 다음과 같다. - -```bash -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 전용 파일은 공통 개발환경이 준비된 뒤 실행한다. - -```text -project-baron-sso-setup.sh -├─ ~/workspace 이동 -├─ Baron SSO 저장소 clone -├─ 브랜치 checkout -├─ .env.sample -> .env 복사 -├─ 사용자에게 .env 작성 안내 -├─ make validate-auth-config -└─ make up-all -``` - -대표 명령은 다음과 같다. - -```bash -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 -``` - -다른 프로젝트는 이 파일만 교체하면 된다. - -예를 들어 다른 프로젝트는 다음처럼 별도 파일을 둔다. - -```text -project-sample-api-setup.sh -project-sample-web-setup.sh -project-internal-admin-setup.sh -``` - -각 프로젝트 파일에는 해당 프로젝트의 저장소 URL, 브랜치명, 환경 파일 생성 방식, 실행 명령만 넣는다. - -### 23.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를 사용한다. - -### 23.7 최종 권장 실행 흐름 - -사용자 입장에서의 목표 흐름은 다음과 같다. - -```text -1. WSL은 사용자가 수동 설치 -2. PowerShell에서 공통 bootstrap 실행 -3. Ubuntu 공통 개발환경 자동 설치 -4. 프로젝트 선택 -5. 선택한 프로젝트 setup 실행 -6. 필요한 민감값만 사용자 입력 -7. 프로젝트 실행 및 접속 확인 -``` - -Baron SSO를 선택한 경우의 흐름은 다음과 같다. - -```text -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 기반의 다른 사내 프로젝트에도 확장할 수 있다. - -## 24. 빠른 복구 명령 모음 +## 23. 빠른 복구 명령 모음 새 PC에서 기본 도구와 Docker가 준비된 뒤 Baron SSO만 복구하는 핵심 명령은 다음과 같다. +실행 위치: **Ubuntu 터미널** + ```bash mkdir -p ~/workspace cd ~/workspace @@ -949,6 +1023,8 @@ cp .env.sample .env `.env`를 작성한 뒤 다음 명령을 실행한다. +실행 위치: **Ubuntu 터미널, Baron SSO 루트** + ```bash make validate-auth-config make up-all @@ -957,6 +1033,8 @@ make ps 브라우저에서 다음 주소를 확인한다. +확인 위치: **Windows 브라우저** + ```text http://localhost:5000 http://localhost:5173 @@ -964,10 +1042,124 @@ http://localhost:5174 http://localhost:5175 ``` +## 24. 초기화 자동화 파일 사용법 + +프로젝트 진행 중에는 전체 재설치가 아니라 일부만 초기화해야 할 때가 있다. 이를 위해 초기화 스크립트를 단계별로 분리한다. + +초기화 스크립트는 모두 **삭제 작업**을 수행한다. 실수 실행을 막기 위해 확인 문구를 입력해야만 동작하도록 작성한다. + +초기화 파일 위치: + +참고 위치: **자동화 스크립트 폴더** + +```text +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` 파일을 실행한다. + +```powershell +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` 파일을 실행한다. + +```powershell +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` 파일을 실행한다. + +```bash +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` 파일을 실행한다. + +```bash +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` 파일을 실행한다. + +```bash +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` 파일을 실행한다. + +```bash +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`