From bbf25683cee5286f1005539d566c56c208b8aca1 Mon Sep 17 00:00:00 2001 From: kevin Date: Thu, 11 Jun 2026 16:51:22 +0900 Subject: [PATCH] =?UTF-8?q?WSL2=20Docker=20Engine=20=EA=B0=9C=EB=B0=9C?= =?UTF-8?q?=ED=99=98=EA=B2=BD=20=EA=B5=AC=EC=B6=95=20=EB=AC=B8=EC=84=9C=20?= =?UTF-8?q?=EC=B6=94=EA=B0=80?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 2026-06-11 작업 내용 정리 - WSL2 설치 - Ubuntu 환경 구성 - Docker Engine 설치 - Ory Stack 기동 - CRLF 문제 해결 - Gateway/UserFront/Backend 정상화 - 기능검증 전 개발환경 구축 완료 --- ...청과업01_WSL2_DockerEngine_개발환경구축.md | 412 ++++++++++++++++++ 1 file changed, 412 insertions(+) create mode 100644 docs/setup/2026-06-11_요청과업01_WSL2_DockerEngine_개발환경구축.md diff --git a/docs/setup/2026-06-11_요청과업01_WSL2_DockerEngine_개발환경구축.md b/docs/setup/2026-06-11_요청과업01_WSL2_DockerEngine_개발환경구축.md new file mode 100644 index 00000000..09a27cf9 --- /dev/null +++ b/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 상태를 확인하였다. + +다음 단계는 기능 검증 및 인증 흐름 테스트이다.