baron-sso/docs/local-run-notes/wsl-setup-issues-2026-06-18.md

# 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. 추가 로드맵 제안 문서 작성.