merge upstream

내가 사용할 개발환경에 대한 이해를 돕기 위하여 작성

docs/setup/2026-06-11_요청과업01_WSL2_DockerEngine_개발환경구축.md

@@ -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 상태를 확인하였다.
+
+다음 단계는 기능 검증 및 인증 흐름 테스트이다.

docs/setup/WSL · Ubuntu · Docker 이해하기.md

@@ -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 서비스들이 실행된다."