WSL2 Docker Engine 개발환경 구축 문서 추가

2026-06-11 작업 내용 정리

- WSL2 설치
- Ubuntu 환경 구성
- Docker Engine 설치
- Ory Stack 기동
- CRLF 문제 해결
- Gateway/UserFront/Backend 정상화
- 기능검증 전 개발환경 구축 완료

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