1
0
forked from baron/baron-sso

5 Commits

Author SHA1 Message Date
7b207d1b36 chore: document local WSL setup fixes 2026-06-18 11:18:54 +09:00
9464c15698 merge upstream 2026-06-18 11:12:58 +09:00
4089455985 Update docs/setup/WSL · Ubuntu · Docker 이해하기.md 2026-06-12 07:57:24 +09:00
a6e2b9bc29 WSL · Ubuntu · Docker 이해하기
내가 사용할 개발환경에 대한 이해를 돕기 위하여 작성
2026-06-12 07:56:52 +09:00
bbf25683ce WSL2 Docker Engine 개발환경 구축 문서 추가
2026-06-11 작업 내용 정리

- WSL2 설치
- Ubuntu 환경 구성
- Docker Engine 설치
- Ory Stack 기동
- CRLF 문제 해결
- Gateway/UserFront/Backend 정상화
- 기능검증 전 개발환경 구축 완료
2026-06-11 16:51:22 +09:00
6 changed files with 1513 additions and 0 deletions

View File

@@ -78,6 +78,9 @@ func (s *RedisService) Ping(ctx context.Context) error {
// StoreVerificationCode saves the SMS verification code with a 3-minute expiration
func (s *RedisService) StoreVerificationCode(phone, code string) error {
if s == nil || s.Client == nil {
return os.ErrInvalid
}
// Key format: "sms_verify:01012345678"
key := "sms_verify:" + phone
expiration := 3 * time.Minute
@@ -87,6 +90,9 @@ func (s *RedisService) StoreVerificationCode(phone, code string) error {
// GetVerificationCode retrieves the SMS verification code
func (s *RedisService) GetVerificationCode(phone string) (string, error) {
if s == nil || s.Client == nil {
return "", os.ErrInvalid
}
key := "sms_verify:" + phone
code, err := s.Client.Get(ctx, key).Result()
if err == redis.Nil {
@@ -100,17 +106,26 @@ func (s *RedisService) GetVerificationCode(phone string) (string, error) {
// DeleteVerificationCode removes the verification code after successful verification
func (s *RedisService) DeleteVerificationCode(phone string) error {
if s == nil || s.Client == nil {
return os.ErrInvalid
}
key := "sms_verify:" + phone
return s.Client.Del(ctx, key).Err()
}
// Set stores a key-value pair with expiration
func (s *RedisService) Set(key string, value string, expiration time.Duration) error {
if s == nil || s.Client == nil {
return os.ErrInvalid
}
return s.Client.Set(ctx, key, value, expiration).Err()
}
// Get retrieves a value by key
func (s *RedisService) Get(key string) (string, error) {
if s == nil || s.Client == nil {
return "", os.ErrInvalid
}
val, err := s.Client.Get(ctx, key).Result()
if err == redis.Nil {
return "", nil
@@ -120,6 +135,9 @@ func (s *RedisService) Get(key string) (string, error) {
// Delete removes a key
func (s *RedisService) Delete(key string) error {
if s == nil || s.Client == nil {
return os.ErrInvalid
}
return s.Client.Del(ctx, key).Err()
}

View File

@@ -70,6 +70,7 @@ services:
- API_PROXY_TARGET=http://baron_backend:3000
- USERFRONT_URL=${USERFRONT_URL}
- VITE_CLIENT_LOG_DEBUG=${VITE_CLIENT_LOG_DEBUG:-false}
- VITE_OIDC_CLIENT_ID=orgfront
- DEV_SERVER_WATCH_POLLING=${DEV_SERVER_WATCH_POLLING:-true}
ports:
- "${ADMINFRONT_PORT:-5173}:5173"
@@ -136,6 +137,7 @@ services:
- API_PROXY_TARGET=http://baron_backend:3000
- USERFRONT_URL=${USERFRONT_URL}
- VITE_CLIENT_LOG_DEBUG=${VITE_CLIENT_LOG_DEBUG:-false}
- VITE_OIDC_CLIENT_ID=orgfront
- DEV_SERVER_WATCH_POLLING=${DEV_SERVER_WATCH_POLLING:-true}
ports:
- "${ORGFRONT_PORT:-5175}:5175"

View File

@@ -0,0 +1,65 @@
# WSL Local Run Notes - 2026-06-18
## Environment
- Host path: `/home/ubuntu/workspace/baron-sso`
- Runtime: WSL Ubuntu
- Docker Compose: available via `docker compose`
- Working branch: `dev`
## Local URLs
- UserFront: `http://localhost:5000`
- AdminFront: `http://localhost:5173`
- DevFront: `http://localhost:5174`
- OrgFront: `http://localhost:5175`
## Run Sequence
```bash
make build-auth-config
make validate-auth-config
make up-dev
make dev
```
## Verified State
- `baron_backend`: healthy
- `baron_userfront`: healthy
- `baron_gateway`: healthy
- `baron_postgres`: healthy
- `baron_redis`: running
- `ory_kratos`, `ory_hydra`, `ory_keto`, `ory_oathkeeper`: running
Backend health check:
```json
{"checks":{"clickhouse":"ok","oathkeeper":"ok","redis":"ok"},"status":"ok"}
```
## Local Fixes Applied
- `.env`
- Switched `APP_ENV` to `dev`.
- Removed inline comments from key env values that were leaking trailing spaces.
- Set public local URLs to `localhost`.
- Removed staging callback URLs from local callback lists.
- `backend/internal/service/redis_service.go`
- Added nil guards to Redis helper methods to prevent backend panic when Redis is not initialized.
- `docker-compose.yaml`
- Set OrgFront runtime `VITE_OIDC_CLIENT_ID=orgfront` so it does not inherit `devfront` from `.env`.
## Browser Verification
- UserFront opens and reaches the login screen.
- AdminFront opens.
- DevFront opens.
- OrgFront opens and reaches the login screen after fixing the OIDC client id.
## Next Tasks
- Connect Gitea MCP.
- Connect Playwright MCP.
- Use local browser checks and repository inspection for architecture and feature analysis.
- Prepare roadmap proposal after architecture and feature review.

View File

@@ -0,0 +1,377 @@
# WSL Local Setup Issue Notes - 2026-06-18
## Issue 1. 작업 위치를 Windows 로컬 소스에서 WSL Ubuntu 소스로 전환
### 배경
팀장 요구사항은 Gitea의 `baron/baron-sso` 저장소를 Ubuntu/WSL 내부에 클론하고, 그 소스코드를 기준으로 로컬 구동, 아키텍처 분석, 기능 분석, 로드맵 제안을 진행하는 것이다.
### 확인 내용
- 작업 경로: `/home/ubuntu/workspace/baron-sso`
- 브랜치: `dev`
- VS Code 상태: `WSL: Ubuntu`
- Docker Compose 사용 가능
### 결과
WSL 내부 Baron SSO 소스코드 기준으로 작업 위치를 확정했다.
---
## Issue 2. `.env` 파일 부재 및 로컬 env 복원
### 증상
WSL 저장소 루트에 실제 `.env` 파일이 없고 `.env.sample`만 존재했다.
### 확인 내용
- 기존 Windows 로컬 env 발견:
- `/mnt/e/h_workspace/baron-sso/.env`
- WSL 저장소의 `.env.sample`과 키 목록을 비교했다.
- 기존 env에는 현재 샘플 대비 일부 키가 부족했다.
### 조치
- 기존 Windows 로컬 `.env`를 WSL 저장소 루트로 복사했다.
- 부족한 로컬 기본 키를 보강했다.
- 로컬 실행 기준으로 URL 값을 정리했다.
### 주요 로컬 값
```env
APP_ENV=dev
USERFRONT_URL=http://localhost:5000
ADMINFRONT_URL=http://localhost:5173
DEVFRONT_URL=http://localhost:5174
ORGFRONT_URL=http://localhost:5175
OATHKEEPER_PUBLIC_URL=${USERFRONT_URL}
HYDRA_PUBLIC_URL=${OATHKEEPER_PUBLIC_URL}/oidc
VITE_OIDC_AUTHORITY=http://localhost:5000/oidc
```
### 결과
로컬 실행용 `.env`가 준비되었다. `.env`는 git ignored 상태라 저장소 변경 목록에는 포함되지 않는다.
---
## Issue 3. `.env` 인라인 주석으로 인한 환경변수 값 오염
### 증상
backend health check에서 Redis가 초기화되지 않았다.
```json
{"checks":{"clickhouse":"ok","oathkeeper":"ok","redis":"not_initialized"},"status":"degraded"}
```
컨테이너 내부 환경변수 확인 결과 `REDIS_ADDR` 끝에 공백이 포함되어 있었다.
```text
redis:6389
```
### 원인
`.env`에서 아래처럼 값 뒤에 인라인 주석이 붙어 있어 Docker/앱 환경변수로 전달될 때 값에 공백이 섞였다.
```env
REDIS_ADDR=redis:6389 # compose.infra.yaml의 redis 포트
APP_ENV=dev # 애플리케이션 실행 환경
```
### 조치
주석을 별도 줄로 분리했다.
```env
# 애플리케이션 실행 환경 (dev, stage, production)
APP_ENV=dev
# compose.infra.yaml의 redis 포트(컨테이너 내부 기준)
REDIS_ADDR=redis:6389
```
### 결과
backend health check가 정상화되었다.
```json
{"checks":{"clickhouse":"ok","oathkeeper":"ok","redis":"ok"},"status":"ok"}
```
---
## Issue 4. Backend Redis nil panic
### 증상
`make dev` 실행 중 backend가 panic으로 종료되었다.
```text
panic: runtime error: invalid memory address or nil pointer dereference
baron-sso-backend/internal/service.(*RedisService).Set(...)
```
### 원인
Redis 초기화 실패 시 `redisService`가 nil 상태가 될 수 있는데, 일부 워밍업 경로에서 nil RedisService의 `Set`, `Get`, `Delete` 계열 메서드가 호출되어 panic이 발생했다.
### 조치
`backend/internal/service/redis_service.go`에 nil guard를 추가했다.
대상 메서드:
- `StoreVerificationCode`
- `GetVerificationCode`
- `DeleteVerificationCode`
- `Set`
- `Get`
- `Delete`
### 결과
Redis 초기화 실패 상황에서도 backend 전체가 panic으로 죽지 않도록 방어했다.
### 참고
현재 WSL 환경에는 `gofmt`가 설치되어 있지 않아 `gofmt`는 실행하지 못했다.
---
## Issue 5. Auth/Ory 설정을 로컬 callback 기준으로 재생성
### 증상
기존 env에 staging callback URL이 섞여 있었다.
예:
```env
https://sso.hmac.kr/...
```
로컬 구동 목적상 OAuth/OIDC callback은 WSL 로컬 프론트 주소를 바라봐야 한다.
### 조치
로컬 callback만 남겼다.
```env
ADMINFRONT_CALLBACK_URLS=http://localhost:5173/auth/callback
DEVFRONT_CALLBACK_URLS=http://localhost:5174/auth/callback
ORGFRONT_CALLBACK_URLS=http://localhost:5175/auth/callback
```
이후 auth config를 재생성 및 검증했다.
```bash
make build-auth-config
make validate-auth-config
make up-dev
```
### 결과
로컬 callback 기준으로 Ory/Kratos/Hydra 설정이 렌더링되었다.
---
## Issue 6. OrgFront OIDC client id 오설정
### 증상
`http://localhost:5175` 접속 시 OrgFront에서 다음 에러가 발생했다.
```text
오류: invalid_request
redirect_uri parameter does not match any of the OAuth 2.0 Client's pre-registered redirect urls.
```
### 확인 내용
OrgFront 컨테이너 내부 환경변수 확인:
```bash
docker exec baron_orgfront printenv VITE_OIDC_CLIENT_ID
```
초기 값:
```text
devfront
```
### 원인
OrgFront가 `orgfront` OIDC client가 아니라 `devfront` client id를 사용하고 있었다. 따라서 `http://localhost:5175/auth/callback``devfront` client의 redirect URI와 맞지 않아 Hydra가 요청을 거부했다.
### 조치
`docker-compose.yaml`의 OrgFront runtime environment에 아래 값을 명시했다.
```yaml
- VITE_OIDC_CLIENT_ID=orgfront
```
### 결과
OrgFront 컨테이너 내부 값이 정상화되었다.
```text
orgfront
```
브라우저에서 `http://localhost:5175` 접속 시 로그인 화면이 정상 표시되었다.
---
## Issue 7. 로컬 서비스 구동 확인
### 실행 명령
```bash
make up-dev
make dev
```
### 최종 컨테이너 상태
- `baron_backend`: healthy
- `baron_userfront`: healthy
- `baron_gateway`: healthy
- `baron_postgres`: healthy
- `baron_redis`: running
- `baron_adminfront`: running
- `baron_devfront`: running
- `baron_orgfront`: running
- `ory_kratos`: running
- `ory_hydra`: running
- `ory_keto`: running
- `ory_oathkeeper`: running
### 브라우저 확인
- `http://localhost:5000`: UserFront 로그인 화면 정상
- `http://localhost:5173`: AdminFront 정상
- `http://localhost:5174`: DevFront 정상
- `http://localhost:5175`: OrgFront 로그인 화면 정상
### 참고
`5173`, `5174`는 dev mode에서 로그인 없이 대시보드가 보이는 동작이 확인되었다. 이후 기능 분석 단계에서 개발 모드 인증 우회 정책을 별도 확인할 필요가 있다.
---
## Issue 8. Gitea MCP 등록
### 배경
팀장 과업상 Gitea 저장소/이슈/코드 확인을 MCP로 연결할 필요가 있다.
### 참고 받은 설정
Codex는 `config.toml`에 MCP를 등록한다.
기본 위치:
```text
~/.codex/config.toml
```
### 실행 파일 위치
Windows에 받은 `gitea-mcp.exe`를 WSL에서 실행 가능함을 확인했다.
```text
/mnt/e/900.tools/gitea-mcp_Windows_x86_64/gitea-mcp.exe
```
### 확인 명령
```bash
/mnt/e/900.tools/gitea-mcp_Windows_x86_64/gitea-mcp.exe --help
```
### 설정 추가
`~/.codex/config.toml`에 아래 구조를 추가했다.
```toml
[mcp_servers.gitea]
command = "/mnt/e/900.tools/gitea-mcp_Windows_x86_64/gitea-mcp.exe"
args = ["-t", "stdio", "--host", "https://gitea.hmac.kr"]
[mcp_servers.gitea.env]
GITEA_ACCESS_TOKEN = "***"
```
### 결과
Gitea MCP 설정 등록 완료. 실제 활성화 확인은 새 Codex 세션에서 `/mcp`로 확인해야 한다.
---
## Issue 9. Playwright MCP 등록
### 배경
브라우저 자동 확인 및 로컬 화면 점검을 위해 Playwright MCP 연결이 필요하다.
### 확인 내용
`npx` 사용 가능:
```bash
npx --version
```
확인된 버전:
```text
11.13.0
```
### 설정 추가
`~/.codex/config.toml`에 아래 구조를 추가했다.
```toml
[mcp_servers.playwright]
command = "npx"
args = ["-y", "@playwright/mcp"]
startup_timeout_sec = 30
tool_timeout_sec = 120
```
### 결과
Playwright MCP 설정 등록 완료. 실제 활성화 확인은 새 Codex 세션에서 `/mcp`로 확인해야 한다.
---
## Current Git Changes
현재 git 추적 변경:
```text
M backend/internal/service/redis_service.go
M docker-compose.yaml
?? docs/local-run-notes/
```
`.env``~/.codex/config.toml`은 로컬 설정 성격이므로 저장소 변경 목록에는 일반적으로 포함되지 않는다.
---
## Next Actions
1. 새 Codex 세션 또는 VS Code 재시작 후 `/mcp`에서 `gitea`, `playwright` 활성화 여부 확인.
2. Gitea MCP로 저장소 이슈/PR/코드 흐름 확인.
3. Playwright MCP로 로컬 화면 자동 점검.
4. Baron SSO 아키텍처 분석 문서 작성.
5. 기능 분석 문서 작성.
6. 추가 로드맵 제안 문서 작성.

View File

@@ -0,0 +1,412 @@
# [요청과업1] Baron-SSO 개발환경 구축 (WSL2 + Docker Engine)
## 1. 작업 개요
| 항목 | 내용 |
| ------ | ----------------------------- |
| 작업명 | 요청과업1 - Docker 설치 및 WSL 환경 구축 |
| 작업일 | 2026-06-11 |
| 시작 | 08:00 |
| 종료 | 15:00 |
| 휴게시간 | 12:00 ~ 13:00 |
| 총 작업시간 | 6시간 |
| 작업자 | ERP기획팀 |
---
# 2. 작업 배경
기존 Windows 환경에서 Baron-SSO 프로젝트를 실행하기 위해 Docker Desktop 기반으로 개발환경 구축을 진행하였다.
그러나 설치 과정에서 반복적인 오류가 발생하였고, 09:00 ~ 09:30 팀 회의 중 팀장님 의견에 따라 Docker Desktop 사용을 중단하였다.
회의 종료 후 개발환경 전략을 다음과 같이 변경하였다.
```text
기존
Windows + Docker Desktop
변경
Windows + WSL2(Ubuntu) + Docker Engine
```
---
# 3. 작업 목표
Baron-SSO 프로젝트 실행을 위한 개발환경 구축
## 목표 범위
* WSL2 설치
* Ubuntu 설치
* Docker Engine 설치
* Docker Compose 설치
* Baron Infra 실행
* Ory Stack 실행
* Baron App 실행
* UserFront / Backend 정상 기동 확인
---
# 4. 최종 결과
## 완료 항목
* WSL2 구축 완료
* Ubuntu 환경 구축 완료
* Docker Engine 설치 완료
* Docker Compose 설치 완료
* PostgreSQL 정상
* Redis 정상
* ClickHouse 정상
* Ory Kratos 정상
* Ory Hydra 정상
* Ory Keto 정상
* Ory Oathkeeper 정상
* Gateway 정상
* UserFront 정상
* Backend 정상
---
# 5. 실행 순서
```mermaid
flowchart TD
A[WSL2 설치]
--> B[Ubuntu 설치]
B
--> C[Docker Engine 설치]
C
--> D[Docker Compose 설치]
D
--> E[Docker Network 생성]
E
--> F[Baron Infra 실행]
F
--> G[Auth Config 생성]
G
--> H[Ory Config 생성]
H
--> I[Ory Stack 실행]
I
--> J[Baron App 실행]
J
--> K[Gateway 확인]
K
--> L[UserFront 확인]
L
--> M[Backend 확인]
M
--> N[전체 Healthy 상태 확인]
```
---
# 6. 시스템 구성도
```mermaid
flowchart LR
USER[Developer]
USER
--> GATEWAY[Gateway]
GATEWAY
--> USERFRONT[UserFront]
GATEWAY
--> BACKEND[Backend]
BACKEND
--> PG[(PostgreSQL)]
BACKEND
--> REDIS[(Redis)]
BACKEND
--> CLICKHOUSE[(ClickHouse)]
BACKEND
--> KRATOS[Kratos]
BACKEND
--> HYDRA[Hydra]
BACKEND
--> KETO[Keto]
BACKEND
--> OATHKEEPER[Oathkeeper]
```
---
# 7. 주요 문제 발생 내역
## 문제 1
### Windows Git Bash 환경
증상
```text
make 명령 실행 불가
```
원인
```text
Linux 기반 개발환경 전제 프로젝트
```
조치
```text
WSL2 + Ubuntu 환경으로 전환
```
---
## 문제 2
### Docker Desktop 설치 오류
증상
```text
설치 중 반복 오류 발생
```
조치
```text
Docker Desktop 사용 중단
Docker Engine 직접 설치 방식 적용
```
---
## 문제 3
### CRLF(Line Ending) 문제
가장 많은 시간을 소모한 원인
증상
```text
set: pipefail: invalid option
$'\\r': command not found
cannot execute: required file not found
set: Illegal option -
': No such file or directory
```
원인
```text
Windows CRLF 줄바꿈
Linux는 LF 필요
```
---
# 8. 수정 파일 목록
```text
.env
scripts/auth_config.sh
scripts/render_ory_config.sh
docker/ory/init-db/01_create_dbs.sh
userfront/scripts/dev-server.sh
scripts/sync_userfront_locales.sh
config/.generated/ory/oathkeeper/entrypoint.sh
```
---
# 9. 추가 문제 및 해결
## Ory DB 생성 실패
필요 DB
```text
ory_hydra
ory_keto
ory_kratos
```
조치
```sql
CREATE DATABASE ory_hydra;
CREATE DATABASE ory_keto;
CREATE DATABASE ory_kratos;
```
---
## Kratos 설정 오류
문제 값
```env
KRATOS_ALLOWED_RETURN_URLS_EXTRA=[]
```
수정
```env
KRATOS_ALLOWED_RETURN_URLS_EXTRA=
```
---
## Gateway Unhealthy
원인
```text
baron_userfront 컨테이너 종료
```
조치
```bash
dos2unix userfront/scripts/dev-server.sh
dos2unix scripts/sync_userfront_locales.sh
docker restart baron_userfront
```
---
## Backend Unhealthy
원인
```text
Oathkeeper 기동 실패
```
조치
```bash
dos2unix config/.generated/ory/oathkeeper/entrypoint.sh
docker restart ory_oathkeeper
docker restart baron_backend
```
---
# 10. 작업 시간 초과 원인 분석
## 계획
```text
Docker 설치
→ Baron 실행
→ 기능 테스트
```
예상 2~3시간
````
## 실제
```text
Docker Desktop 설치 실패
→ WSL 환경 전환
→ Linux 환경 구성
→ 다수의 CRLF 문제 발견
→ Ory DB 재구성
→ Oathkeeper 복구
→ Backend Health 복구
````
결과
```text
총 6시간 소요
```
---
# 11. 재발 방지 방안
## Git 정책 검토
```gitattributes
*.sh text eol=lf
*.env text eol=lf
*.yaml text eol=lf
*.yml text eol=lf
```
검토 필요
---
## 개발환경 표준화
권장
```text
Windows
WSL2 Ubuntu
Docker Engine
Baron-SSO
```
팀 공통 환경으로 통일 시
환경 이슈 감소 예상
---
# 12. 작업 결과 요약
금일 WSL2 + Ubuntu 기반 Docker Engine 개발환경 구축을 완료하였다.
Docker Desktop 기반 접근은 설치 오류로 인해 중단하였으며, 팀장님 조언에 따라 WSL2 + Docker Engine 방식으로 전환하였다.
구축 과정에서 다수의 CRLF(Line Ending) 문제가 확인되었으며, 관련 Shell Script 및 환경설정 파일을 수정하여 해결하였다.
최종적으로 Baron-SSO의 Infra, Ory Stack, Gateway, UserFront, Backend가 모두 정상 기동되었으며 Healthy 상태를 확인하였다.
다음 단계는 기능 검증 및 인증 흐름 테스트이다.

View File

@@ -0,0 +1,639 @@
# WSL · Ubuntu · Docker 이해하기 (초보자용 가이드)
## 문서 정보
| 항목 | 내용 |
| ---- | -------------------------- |
| 문서명 | WSL · Ubuntu · Docker 이해하기 |
| 대상 | 개발 입문자, 신규 팀원 |
| 작성목적 | Baron SSO 개발환경 이해 |
| 작성일 | 2026-06-12 |
---
# 1. 개요
현재 Baron SSO 개발환경은 다음과 같은 구조로 구성되어 있습니다.
```text
Windows
WSL
Ubuntu
Docker
Baron 서비스들
```
처음 접하는 사람은 용어가 많아 어렵게 느껴질 수 있지만,
사실은 다음과 같이 이해하면 쉽습니다.
| 구성요소 | 비유 |
| -------------- | ---------- |
| Windows | 집 |
| WSL | 집 안의 리눅스 방 |
| Ubuntu | 방에 사는 사람 |
| Docker | 작업실 |
| Container | 개별 작업실 |
| Baron Backend | 백엔드 작업실 |
| Baron Frontend | 프론트엔드 작업실 |
| ClickHouse | 데이터 저장 작업실 |
---
# 2. 전체 구조 이해하기
## 실제 개발환경 구조
```text
┌─────────────────────────┐
│ Windows 11 │
│ │
│ VS Code │
│ Chrome │
│ Git │
└──────────┬──────────────┘
┌─────────────────────────┐
│ WSL │
│ (Windows Linux Layer) │
└──────────┬──────────────┘
┌─────────────────────────┐
│ Ubuntu │
│ (Linux) │
└──────────┬──────────────┘
┌─────────────────────────┐
│ Docker │
└──────────┬──────────────┘
┌─────────┼─────────┬─────────┐
▼ ▼ ▼ ▼
Backend UserFront AdminFront ClickHouse
```
---
# 3. Windows란?
현재 우리가 사용하는 기본 운영체제(OS)입니다.
예)
```text
C:\Users
D:\Project
E:\Workspace
```
Windows 환경에서 사용하는 경로입니다.
주요 프로그램
* VS Code
* Chrome
* Edge
* Explorer
* Git GUI
등이 Windows 위에서 실행됩니다.
---
# 4. WSL이란?
## WSL
Windows Subsystem for Linux
즉,
"Windows 안에서 Linux를 실행할 수 있게 해주는 기능"
입니다.
---
## WSL이 없던 시절
Linux를 사용하려면
```text
PC
├─ Windows
└─ Virtual Machine
└─ Ubuntu
```
구조를 사용했습니다.
문제점
* 느림
* 무거움
* 메모리 많이 사용
---
## WSL 사용
```text
PC
├─ Windows
└─ WSL
└─ Ubuntu
```
장점
* 빠름
* 가벼움
* 실제 Linux와 거의 동일
---
# 5. Ubuntu란?
Ubuntu는 Linux 운영체제입니다.
Windows와 같은 OS입니다.
비교하면
| Windows | Linux |
| ---------- | -------- |
| Windows 11 | Ubuntu |
| 탐색기 | Shell |
| CMD | Terminal |
| PowerShell | Bash |
---
Ubuntu 접속 예시
```bash
wsl
```
또는
```bash
ubuntu
```
실행 후
```bash
ubuntu@DESKTOP-XXXX:~$
```
가 보이면 Ubuntu 안에 들어온 상태입니다.
---
# 6. Docker란?
Docker는
"프로그램을 독립적으로 실행하는 기술"
입니다.
---
예를 들어
Baron 프로젝트에 필요한 것
```text
NodeJS
Database
Backend
Frontend
ClickHouse
```
를 직접 설치하면
PC가 복잡해집니다.
---
Docker 사용 시
```text
┌────────────┐
│ Backend │
└────────────┘
┌────────────┐
│ Frontend │
└────────────┘
┌────────────┐
│ Database │
└────────────┘
┌────────────┐
│ ClickHouse │
└────────────┘
```
각각 독립적으로 실행됩니다.
---
# 7. Container란?
Docker 안에서 실행되는 작은 서버입니다.
쉽게 말하면
"미니 컴퓨터"
라고 생각하면 됩니다.
---
현재 Baron 환경 예시
```text
Container 1
baron_backend
Container 2
baron_userfront
Container 3
baron_adminfront
Container 4
baron_clickhouse
```
각 컨테이너는
* 독립 실행
* 독립 설정
* 독립 포트
를 가집니다.
---
# 8. Image와 Container 차이
많이 헷갈리는 부분입니다.
## Image
설치 파일
예)
```text
Windows 설치 ISO
```
와 비슷
---
## Container
실행 중인 프로그램
예)
```text
설치 완료 후 실행된 Windows
```
와 비슷
---
관계
```text
Docker Image
실행
Container
```
---
# 9. 실제 Baron 프로젝트 구조
현재 개발환경
```text
Windows
├─ VS Code
├─ Git
└─ E:\h_workspace\baron-sso
```
---
WSL에서 보면
```text
/mnt/e/h_workspace/baron-sso
```
가 됩니다.
---
같은 폴더를
Windows와 Ubuntu가
다르게 표현하는 것입니다.
| Windows | Ubuntu |
| ------------------------ | ---------------------------- |
| E:\h_workspace\baron-sso | /mnt/e/h_workspace/baron-sso |
---
# 10. VS Code는 어디서 실행되는가?
VS Code 자체는 Windows에서 실행됩니다.
```text
Windows
└─ VS Code
```
하지만
Remote WSL 기능을 사용하면
```text
VS Code
WSL
Ubuntu
```
에 연결됩니다.
---
좌측 하단에
```text
WSL: Ubuntu
```
가 보이면
Ubuntu 내부를 편집 중인 상태입니다.
---
# 11. Docker Compose란?
여러 컨테이너를 한 번에 실행하는 기능입니다.
예)
docker-compose.yml
```yaml
services:
backend:
...
userfront:
...
adminfront:
...
clickhouse:
...
```
---
실행
```bash
docker compose up -d
```
---
Docker가 자동으로
```text
Backend 시작
UserFront 시작
AdminFront 시작
ClickHouse 시작
```
을 수행합니다.
---
# 12. Baron SSO 실행 흐름
```text
개발자
VS Code 수정
Git 저장
Docker Compose 실행
Backend Container
UserFront Container
AdminFront Container
ClickHouse Container
웹 브라우저 접속
```
---
# 13. 자주 사용하는 명령어
## 현재 컨테이너 보기
```bash
docker ps
```
---
## 전체 컨테이너 보기
```bash
docker ps -a
```
---
## 로그 보기
```bash
docker logs 컨테이너명
```
예)
```bash
docker logs baron_backend
```
---
## 컨테이너 접속
```bash
docker exec -it 컨테이너명 bash
```
예)
```bash
docker exec -it baron_backend bash
```
---
## 컨테이너 중지
```bash
docker stop 컨테이너명
```
---
## 컨테이너 재시작
```bash
docker restart 컨테이너명
```
---
# 14. 최종 정리
## 한 문장 설명
### Windows
사용자가 사용하는 실제 운영체제
---
### WSL
Windows 안에서 Linux를 사용할 수 있게 해주는 기능
---
### Ubuntu
WSL 안에서 실행되는 Linux 운영체제
---
### Docker
프로그램을 독립된 환경에서 실행하는 기술
---
### Container
Docker 안에서 실행되는 개별 서비스
---
## Baron SSO 전체 구조
```text
사용자
Windows
VS Code
WSL
Ubuntu
Docker
├─ baron_backend
├─ baron_userfront
├─ baron_adminfront
└─ baron_clickhouse
브라우저 접속
```
---
## 기억해야 할 핵심
"Windows 위에서 WSL이 동작하고,
WSL 안에서 Ubuntu가 실행되며,
Ubuntu 안에서 Docker가 실행되고,
Docker 안에서 Baron 서비스들이 실행된다."