From 298799f8b7090e0ac5fc92ea927b82478de2b678 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 13:54:47 +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 | 220 ++++++++++++++++++++++------- 1 file changed, 169 insertions(+), 51 deletions(-) diff --git a/Baron SSO 개발환경 복구 Runbook.md b/Baron SSO 개발환경 복구 Runbook.md index 6dca393..7b7eed5 100644 --- a/Baron SSO 개발환경 복구 Runbook.md +++ b/Baron SSO 개발환경 복구 Runbook.md @@ -1,5 +1,33 @@ # Baron SSO 개발환경 복구 Runbook +## 목차 + +- [1. 문서 목적](#1-문서-목적) +- [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-실행) +- [16. 정상 접속 URL](#16-정상-접속-url) +- [17. 컨테이너 상태 확인](#17-컨테이너-상태-확인) +- [18. 정상 복구 완료 기준](#18-정상-복구-완료-기준) +- [19. 현재 환경 복기](#19-현재-환경-복기) +- [20. VS Code 저장과 Gitea 반영 흐름](#20-vs-code-저장과-gitea-반영-흐름) +- [21. 자주 발생하는 문제와 대응](#21-자주-발생하는-문제와-대응) +- [22. 업무 복귀 시간 단축 방안](#22-업무-복귀-시간-단축-방안) +- [23. 자동화 파일 분리 방향](#23-자동화-파일-분리-방향) +- [24. 빠른 복구 명령 모음](#24-빠른-복구-명령-모음) +- [25. 관련 문서](#25-관련-문서) + ## 1. 문서 목적 이 문서는 Windows 기준의 빈 PC에서 Baron SSO 개발환경을 새로 구성하고, 개발자가 업무에 복귀하기까지의 표준 절차를 정리한다. @@ -17,26 +45,29 @@ 아래 표는 빈 Windows PC에서 Baron SSO 개발환경을 복구할 때의 전체 진행 순서다. 각 단계의 명령어는 대표 예시이며, 실제 환경에 따라 관리자 권한, VPN, Gitea 인증, `.env` 값 준비가 먼저 필요할 수 있다. -| No | 단계 | 명령어 또는 작업 | 설명 | -| --- | --- | --- | --- | -| 1 | WSL 설치 | `wsl --install` | Windows 안에서 Linux를 실행할 수 있도록 WSL을 설치한다. 설치 후 재부팅이 필요할 수 있다. | -| 2 | Ubuntu 설치 확인 | `wsl --list --verbose` | Ubuntu 배포판이 설치되어 있고 실행 가능한지 확인한다. 없으면 `wsl --install -d Ubuntu`로 설치한다. | -| 3 | Ubuntu 패키지 갱신 | `sudo apt update` | Ubuntu 안의 패키지 목록을 최신 상태로 갱신한다. | -| 4 | 기본 도구 설치 | `sudo apt install -y git make curl ca-certificates` | Git clone, Makefile 실행, HTTP 확인에 필요한 기본 도구를 설치한다. | -| 5 | Docker 확인 | `docker --version` / `docker compose version` | Baron SSO는 Docker Compose로 실행되므로 Ubuntu 터미널에서 Docker 명령이 동작해야 한다. | -| 6 | 작업 폴더 생성 | `mkdir -p ~/workspace && cd ~/workspace` | WSL Ubuntu 안에 프로젝트 소스코드를 둘 작업 위치를 만든다. | -| 7 | Gitea 저장소 clone | `git clone https://gitea.hmac.kr/baron/baron-sso.git` | Gitea의 Baron SSO 원격 저장소를 로컬 WSL Ubuntu로 내려받는다. | -| 8 | 저장소 이동 | `cd baron-sso` | 내려받은 Baron SSO 프로젝트 루트로 이동한다. 이후 명령은 이 위치에서 실행한다. | -| 9 | 브랜치 전환 | `git checkout feature/local-dev-setup-clean` | 팀에서 지정한 작업 브랜치로 전환한다. 표준 브랜치가 바뀌면 이 값도 바꾼다. | -| 10 | 환경 파일 생성 | `cp .env.sample .env` | 샘플 환경 파일을 복사해 로컬 실행용 `.env` 파일을 만든다. | -| 11 | 환경값 작성 | `.env` 편집 | URL, callback, secret 등 로컬 실행에 필요한 값을 작성한다. 민감정보는 Git에 올리지 않는다. | -| 12 | 인증 설정 검증 | `make validate-auth-config` | `.env` 기반 인증 설정을 생성하고 callback/return URL 설정 오류를 사전에 확인한다. | -| 13 | 전체 스택 실행 | `make up-all` | 인프라, Ory Stack, Baron SSO 앱 컨테이너를 한 번에 실행한다. | -| 14 | 상태 확인 | `make ps` 또는 `docker ps` | 컨테이너가 정상적으로 실행 중인지 확인한다. 문제가 있으면 `logs-*` 명령으로 로그를 본다. | -| 15 | 접속 확인 | `http://localhost:5000` | 브라우저에서 UserFront/gateway에 접속해 Baron SSO 화면이 열리는지 확인한다. | -| 16 | 추가 화면 확인 | `http://localhost:5173`, `5174`, `5175` | AdminFront, DevFront, OrgFront 개발 화면이 필요한 경우 각 포트 접속을 확인한다. | -| 17 | Backend 확인 | `curl http://localhost:3000/health` | backend health check가 정상 응답하는지 확인한다. | -| 18 | 변경사항 저장 흐름 | `git add` → `git commit` → `git push` | VS Code 저장만으로는 Gitea에 올라가지 않는다. Gitea 반영은 반드시 `git push`까지 해야 한다. | +명령어 실행 위치는 반드시 구분한다. `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. 전체 요약 @@ -121,7 +152,94 @@ Baron SSO는 단일 서버 하나만 실행하는 프로젝트가 아니다. 여 민감 설정값은 문서에 직접 기록하지 않는다. `.env` 파일, 사내 보안 저장소, 담당자 전달 절차 등 별도 관리 방식을 따른다. -## 7. Windows에서 WSL 설치 +## 7. 설치 전 필요한 계정정보와 민감정보 + +개발환경 자동화는 설치 시간을 줄여주지만, 계정정보와 비밀번호를 잘못 다루면 보안 사고로 이어질 수 있다. 특히 자동화 스크립트 안에 사이트 비밀번호, Gitea 비밀번호, 운영 secret을 직접 적으면 안 된다. + +반드시 기억할 원칙은 다음과 같다. + +```text +자동화 파일에는 절차만 넣고, +비밀번호와 토큰은 사용자 입력 또는 보안 저장소로 관리한다. +``` + +설치 전에 준비해야 하는 정보는 다음과 같다. + +| 구분 | 필요한 정보 | 사용 시점 | 보관/입력 권장 방식 | +| --- | --- | --- | --- | +| 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에 포함하는 방식은 사용하지 않는다. + +잘못된 예: + +```text +https://username:password@gitea.hmac.kr/baron/baron-sso.git +``` + +권장 예: + +```text +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을 관리자 권한으로 실행한다. @@ -148,7 +266,7 @@ wsl --install -d Ubuntu 설치 후 Ubuntu를 실행하고 Linux 사용자 계정과 비밀번호를 만든다. -## 8. Ubuntu 기본 패키지 설치 +## 9. Ubuntu 기본 패키지 설치 Ubuntu 터미널에서 패키지 목록을 갱신한다. @@ -171,7 +289,7 @@ make --version curl --version ``` -## 9. Docker 준비 +## 10. Docker 준비 Baron SSO는 Docker Compose 기반으로 실행한다. Ubuntu 터미널에서 다음 명령이 동작해야 한다. @@ -200,7 +318,7 @@ permission denied while trying to connect to the docker API at unix:///var/run/d 4. 필요 시 Windows 재부팅 5. Docker socket 권한 또는 사용자 그룹 확인 -## 10. Baron SSO 소스코드 clone +## 11. Baron SSO 소스코드 clone 작업 디렉터리를 만든다. @@ -242,7 +360,7 @@ nothing to commit, working tree clean 단, 기존 작업이 있거나 문서/테스트 산출물이 있다면 변경 파일이 표시될 수 있다. -## 11. 저장소 주요 파일 이해 +## 12. 저장소 주요 파일 이해 Baron SSO 로컬 실행에서 자주 보는 파일은 다음과 같다. @@ -262,7 +380,7 @@ Baron SSO 로컬 실행에서 자주 보는 파일은 다음과 같다. | `orgfront/` | React 기반 OrgFront | | `docs/` | 운영/개발 문서 | -## 12. `.env` 파일 준비 +## 13. `.env` 파일 준비 최초 clone 직후에는 `.env.sample`을 복사한다. @@ -305,7 +423,7 @@ ORGFRONT_URL=http://localhost:5175 실제 필요한 값은 현재 `.env.sample`과 팀 표준 설정을 기준으로 작성한다. -## 13. 인증 설정 생성 및 검증 +## 14. 인증 설정 생성 및 검증 `.env` 작성 후 Baron SSO 인증 설정을 검증한다. @@ -331,9 +449,9 @@ make validate-auth-config make verify-auth-config ``` -## 14. Baron SSO 실행 +## 15. Baron SSO 실행 -### 14.1 전체 스택 한 번에 실행 +### 15.1 전체 스택 한 번에 실행 가장 단순한 실행 명령은 다음이다. @@ -343,7 +461,7 @@ make up-all 이 명령은 인프라, Ory Stack, 앱 스택을 함께 실행한다. -### 14.2 단계별 실행 +### 15.2 단계별 실행 문제 원인을 나누어 보기 위해 단계별로 실행할 수도 있다. @@ -371,7 +489,7 @@ make dev make dev-debug ``` -## 15. 정상 접속 URL +## 16. 정상 접속 URL 로컬 실행 후 확인할 기본 URL은 다음과 같다. @@ -401,7 +519,7 @@ backend health check는 다음으로 확인한다. curl http://localhost:3000/health ``` -## 16. 컨테이너 상태 확인 +## 17. 컨테이너 상태 확인 실행 중인 컨테이너만 확인한다. @@ -429,7 +547,7 @@ make logs-ory make logs-app ``` -## 17. 정상 복구 완료 기준 +## 18. 정상 복구 완료 기준 빈 PC에서 복구가 완료되었다고 판단하려면 다음 기준을 만족해야 한다. @@ -443,7 +561,7 @@ make logs-app - 필요한 경우 AdminFront, DevFront, OrgFront 포트에 접속할 수 있다. - backend health check가 정상 응답한다. -## 18. 현재 환경 복기 +## 19. 현재 환경 복기 현재 설치된 Baron SSO 환경을 확인했을 때, 일부 인프라 컨테이너는 실행 중이고 앱/Ory 컨테이너 일부는 중지 상태였다. @@ -486,7 +604,7 @@ make up-app make up-all ``` -## 19. VS Code 저장과 Gitea 반영 흐름 +## 20. VS Code 저장과 Gitea 반영 흐름 VS Code에서 파일을 수정하고 저장해도 Gitea 서버에 바로 반영되지는 않는다. @@ -526,9 +644,9 @@ Gitea 서버 반영 따라서 팀원이 Gitea 웹에서 변경사항을 보려면 반드시 `git push`까지 완료해야 한다. -## 20. 자주 발생하는 문제와 대응 +## 21. 자주 발생하는 문제와 대응 -### 20.1 Docker socket 권한 오류 +### 21.1 Docker socket 권한 오류 증상: @@ -543,7 +661,7 @@ permission denied while trying to connect to the docker API at unix:///var/run/d - Ubuntu 재시작 여부 - Docker socket 접근 권한 -### 20.2 `.env` 작성 오류 +### 21.2 `.env` 작성 오류 증상: @@ -560,7 +678,7 @@ make validate-auth-config 실패 메시지를 보고 `.env`의 URL, callback, return URL 값을 수정한다. -### 20.3 일부 컨테이너만 실행됨 +### 21.3 일부 컨테이너만 실행됨 증상: @@ -581,7 +699,7 @@ make up-dev make up-app ``` -### 20.4 포트 충돌 +### 21.4 포트 충돌 증상: @@ -596,7 +714,7 @@ docker ps 필요 시 이미 떠 있는 컨테이너나 다른 프로세스가 같은 포트를 사용하는지 확인한다. -## 21. 업무 복귀 시간 단축 방안 +## 22. 업무 복귀 시간 단축 방안 복구 시간을 줄이기 위해 다음 항목을 팀 표준으로 관리하는 것이 좋다. @@ -608,7 +726,7 @@ docker ps 6. 신규 PC 지급 시 이 문서 기준으로 실제 복구 시간을 측정한다. 7. 반복적으로 막히는 지점은 스크립트화하거나 Makefile 타깃으로 추가한다. -## 22. 자동화 파일 분리 방향 +## 23. 자동화 파일 분리 방향 빈 PC 자동화 파일은 Baron SSO에만 묶지 않고, 다른 프로젝트에도 재사용할 수 있도록 공통 설치 영역과 프로젝트별 설정 영역을 분리하는 것이 좋다. @@ -624,7 +742,7 @@ Ubuntu 공통 개발환경 준비 프로젝트별 소스 clone 및 실행 ``` -### 22.1 권장 파일 구조 +### 23.1 권장 파일 구조 자동화 파일은 다음처럼 나누는 것을 권장한다. @@ -648,7 +766,7 @@ bootstrap/ 이렇게 나누면 다른 프로젝트를 추가할 때 공통 설치 파일은 그대로 두고, `project-프로젝트명-setup.sh`와 설정 파일만 추가하면 된다. -### 22.2 공통 영역과 프로젝트 전용 영역 구분 +### 23.2 공통 영역과 프로젝트 전용 영역 구분 자동화 범위를 다음처럼 구분한다. @@ -671,7 +789,7 @@ bootstrap/ 캡처 기준으로 보면 빨간 영역은 `windows-wsl-bootstrap.ps1`에 해당하고, 노란 영역 중 `Docker 권한 설정`까지는 `ubuntu-common-dev-setup.sh`에 해당한다. 그 이후의 `Baron SSO git clone`, 브랜치 checkout, `.env`, `make` 실행은 Baron SSO 전용 파일로 분리한다. -### 22.3 공통 Windows 부트스트랩 예시 +### 23.3 공통 Windows 부트스트랩 예시 Windows 쪽 공통 파일은 다음 역할만 맡는다. @@ -697,7 +815,7 @@ wsl -d Ubuntu -- bash -lc "./bootstrap/ubuntu-common-dev-setup.sh" - WSL 또는 Ubuntu 최초 설치 후 재부팅이 필요할 수 있다. - Ubuntu 최초 실행 시 Linux 사용자명/비밀번호 생성은 수동 단계로 남을 수 있다. -### 22.4 공통 Ubuntu 개발환경 setup 예시 +### 23.4 공통 Ubuntu 개발환경 setup 예시 Ubuntu 공통 파일은 특정 프로젝트를 모르는 상태로 개발 기본 환경만 준비한다. @@ -723,7 +841,7 @@ mkdir -p ~/workspace Docker 권한 설정은 팀 표준 Docker 설치 방식에 맞춰 작성한다. Docker Desktop WSL integration을 쓸지, Ubuntu 내부 Docker Engine을 쓸지 먼저 정해야 한다. -### 22.5 프로젝트별 setup 예시 +### 23.5 프로젝트별 setup 예시 Baron SSO 전용 파일은 공통 개발환경이 준비된 뒤 실행한다. @@ -762,7 +880,7 @@ project-internal-admin-setup.sh 각 프로젝트 파일에는 해당 프로젝트의 저장소 URL, 브랜치명, 환경 파일 생성 방식, 실행 명령만 넣는다. -### 22.6 자동화 시 입력받아야 하는 값 +### 23.6 자동화 시 입력받아야 하는 값 공통 자동화에서 필요한 값은 다음과 같다. @@ -782,7 +900,7 @@ project-internal-admin-setup.sh 사이트 비밀번호나 Gitea 계정 비밀번호를 스크립트에 직접 저장하지 않는다. HTTPS 방식이면 Personal Access Token을 사용하고, SSH 방식이면 SSH key를 사용한다. -### 22.7 최종 권장 실행 흐름 +### 23.7 최종 권장 실행 흐름 사용자 입장에서의 목표 흐름은 다음과 같다. @@ -816,7 +934,7 @@ make up-all 이 방식은 Baron SSO뿐 아니라 Docker Compose 기반의 다른 사내 프로젝트에도 확장할 수 있다. -## 23. 빠른 복구 명령 모음 +## 24. 빠른 복구 명령 모음 새 PC에서 기본 도구와 Docker가 준비된 뒤 Baron SSO만 복구하는 핵심 명령은 다음과 같다. @@ -846,7 +964,7 @@ http://localhost:5174 http://localhost:5175 ``` -## 24. 관련 문서 +## 25. 관련 문서 - `README.md` - `Makefile`