Files

kevin 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

5.6 KiB

Raw Blame History

[요청과업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 사용을 중단하였다.

회의 종료 후 개발환경 전략을 다음과 같이 변경하였다.

기존
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. 실행 순서

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. 시스템 구성도

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 환경

증상

make 명령 실행 불가

원인

Linux 기반 개발환경 전제 프로젝트

조치

WSL2 + Ubuntu 환경으로 전환

문제 2

Docker Desktop 설치 오류

증상

설치 중 반복 오류 발생

조치

Docker Desktop 사용 중단
Docker Engine 직접 설치 방식 적용

문제 3

CRLF(Line Ending) 문제

가장 많은 시간을 소모한 원인

증상

set: pipefail: invalid option
$'\\r': command not found
cannot execute: required file not found
set: Illegal option -
': No such file or directory

원인

Windows CRLF 줄바꿈

Linux는 LF 필요

8. 수정 파일 목록

.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

ory_hydra
ory_keto
ory_kratos

조치

CREATE DATABASE ory_hydra;
CREATE DATABASE ory_keto;
CREATE DATABASE ory_kratos;

Kratos 설정 오류

문제 값

KRATOS_ALLOWED_RETURN_URLS_EXTRA=[]

수정

KRATOS_ALLOWED_RETURN_URLS_EXTRA=

Gateway Unhealthy

원인

baron_userfront 컨테이너 종료

조치

dos2unix userfront/scripts/dev-server.sh
dos2unix scripts/sync_userfront_locales.sh
docker restart baron_userfront

Backend Unhealthy

원인

Oathkeeper 기동 실패

조치

dos2unix config/.generated/ory/oathkeeper/entrypoint.sh
docker restart ory_oathkeeper
docker restart baron_backend

10. 작업 시간 초과 원인 분석

계획

Docker 설치
→ Baron 실행
→ 기능 테스트

예상 2~3시간


## 실제

```text
Docker Desktop 설치 실패

→ WSL 환경 전환

→ Linux 환경 구성

→ 다수의 CRLF 문제 발견

→ Ory DB 재구성

→ Oathkeeper 복구

→ Backend Health 복구

결과

총 6시간 소요

11. 재발 방지 방안

Git 정책 검토

*.sh text eol=lf
*.env text eol=lf
*.yaml text eol=lf
*.yml text eol=lf

검토 필요

개발환경 표준화

권장

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 상태를 확인하였다.

다음 단계는 기능 검증 및 인증 흐름 테스트이다.

5.6 KiB Raw Blame History