213 lines
10 KiB
Markdown
213 lines
10 KiB
Markdown
---
|
|
kind: usage
|
|
title: 로컬 개발환경 온보딩
|
|
description: bibimbap 을 로컬에서 기동하는 두 경로(Docker / 직접 실행) 와 DB 스키마 초기화·트러블슈팅을 실행 검증 근거와 함께 정리한 가이드.
|
|
owner: art
|
|
stability: living
|
|
last_reviewed: 2026-06-17
|
|
---
|
|
|
|
# 로컬 개발환경 온보딩
|
|
|
|
이 문서는 bibimbap 을 처음 받는 개발자가 로컬에서 앱을 띄우기까지의 전 과정을 정리한다. 모든 명령·출력은 실제 실행으로 검증된 것만 싣는다.
|
|
|
|
권장 경로는 **A: Docker** 다. 호스트에 직접 띄우려면 **B: 직접 실행** 을 따른다. 두 경로 모두 전 과정 실행 검증을 통과했다.
|
|
|
|
> docs-first: 이 문서를 읽기 전 `../index.md` → `./index.md` 순으로 카테고리 위치를 확인했다고 가정한다. 기술부채 맥락은 `../analysis/2026-06-16-project-analysis.md` 참조.
|
|
|
|
## 1. 사전 요구사항
|
|
|
|
| 항목 | 버전/사실 | 비고 |
|
|
| --- | --- | --- |
|
|
| Java | 21 (검증: Temurin/OpenJDK 21.0.11) | `pom.xml:25` `java.version=21` |
|
|
| Maven | mvnw wrapper 3.9.14 | 별도 `mvn` 설치 불요. `./mvnw` 사용 |
|
|
| Docker | 29.3.1 | 경로 A 권장 |
|
|
| Docker Compose | v5.1.1 | `docker compose` 서브커맨드 |
|
|
| PostgreSQL | 16 (컨테이너) | `docker-compose.yml` db 서비스 |
|
|
|
|
**온라인 빌드 전제**: 이 프로젝트는 `spring-boot 3.5.14-SNAPSHOT` 에 고정돼 있다(`pom.xml:29`, dependencyManagement import 는 `pom.xml:200-219`). SNAPSHOT 의존성은 `repo.spring.io/snapshot` 에서 온라인으로 받아야 하므로 **오프라인 빌드는 불가**하다. 회사 TLS 인터셉션 프록시 환경에서는 §6 트러블슈팅을 먼저 확인한다.
|
|
|
|
## 2. 경로 A: Docker (compose 기반) — 권장
|
|
|
|
전 과정 실행 검증됨.
|
|
|
|
### 단계
|
|
|
|
```bash
|
|
# 1. 환경파일 준비 (이미 있으면 생략). 비밀값은 .env 에 두며 gitignore 된다.
|
|
cp .env.example .env
|
|
|
|
# 2. (회사 TLS 프록시 환경만) certs/ 에 프록시 CA 배치 — §6 참조
|
|
|
|
# 3. 빌드 + 기동
|
|
docker compose up --build # 또는 -d 로 백그라운드
|
|
|
|
# 4. 홈 접속
|
|
open http://localhost:8080/ # HTTP 200
|
|
```
|
|
|
|
### 구성요소
|
|
|
|
- `docker-compose.yml`: **db**(postgres:16, 최초 기동 시 `db/schema.sql` 자동 주입) + **app**(멀티스테이지 JDK21 빌드, 임베디드 Tomcat 실행).
|
|
- **비밀값 주입**: app 은 `SPRING_DATASOURCE_URL` / `SPRING_DATASOURCE_USERNAME` / `SPRING_DATASOURCE_PASSWORD` 환경변수(`.env`)로 db 에 접속한다. 이미지·git 에 비밀값을 포함하지 않는다.
|
|
- **SNAPSHOT 네트워크 의존**: Dockerfile 빌드 스테이지가 온라인으로 의존성을 받는다. TLS 인터셉션 프록시 환경에선 CA 주입이 필요하다(§6).
|
|
- **업로드 경로**: `APP_UPLOAD_GAME_STORAGE_PATH=/app/uploads/game` + named volume `uploads` 로 영속한다.
|
|
- **호스트 DB 포트**: `.env` 의 `DB_PORT`(기본 5432, 충돌 시 변경). 앱→db 통신은 컨테이너 내부 `db:5432` 라 호스트 포트 변경의 영향을 받지 않는다.
|
|
|
|
### 검증 증거
|
|
|
|
```text
|
|
$ docker compose build app
|
|
[INFO] BUILD SUCCESS
|
|
# image bibimbap-app 생성
|
|
|
|
$ docker compose ps
|
|
# db Up (healthy)
|
|
# app Up 0.0.0.0:8080->8080
|
|
|
|
$ curl -s -o /dev/null -w "%{http_code}" http://localhost:8080/
|
|
200 # 홈 35143 bytes 렌더
|
|
|
|
$ curl -s -o /dev/null -w "%{http_code}" http://localhost:8080/recruit
|
|
200
|
|
```
|
|
|
|
- DB: `dev` 스키마에 6테이블 생성 확인. `games` / `users` / `recruit_posts` 조회 0행 무에러.
|
|
- **라운드트립 증거**: `dev.games` 에 행을 삽입 → 홈에 해당 게임명이 1회 노출됨을 확인 → DB → MyBatis → JSP 전체 경로 동작 확인.
|
|
|
|
## 3. 경로 B: 직접 실행 (호스트)
|
|
|
|
전 과정 실행 검증됨 (macOS Apple Silicon 기준).
|
|
|
|
### 단계
|
|
|
|
```bash
|
|
# 1. JDK21 설치 (검증한 방법). keg-only 라 sudo 불요.
|
|
brew install openjdk@21
|
|
export JAVA_HOME=/opt/homebrew/opt/openjdk@21
|
|
|
|
# 2. wrapper 실행권한 (최초 1회 필요했음)
|
|
chmod +x mvnw
|
|
|
|
# 3. (회사 TLS 프록시 환경만) 프록시 CA 를 호스트 JDK cacerts 에 import — §6 참조
|
|
keytool -importcert -noprompt -trustcacerts -cacerts -storepass changeit \
|
|
-alias proxy -file certs/corporate-proxy-ca.crt
|
|
# 중요: curl 이 성공해도 JDK 는 자체 truststore 를 쓰므로 별도 import 가 필요하다.
|
|
|
|
# 4. DB 준비 — Docker DB 단독 사용 (권장) 또는 로컬 PostgreSQL
|
|
docker compose up -d db # localhost:5433 (.env DB_PORT 기준)
|
|
# 로컬 PG 를 쓰면: PostgreSQL 16 설치 후 db/schema.sql 적용
|
|
|
|
# 5. dev datasource 설정 파일 작성 (gitignore)
|
|
cp src/main/resources/dev/db.properties.example src/main/resources/dev/db.properties
|
|
# 편집: url=jdbc:postgresql://localhost:5433/bibimbap?currentSchema=dev , user/pass 실값
|
|
|
|
# 6. 빌드 / 테스트 / 실행 (JAVA_HOME 지정 상태)
|
|
./mvnw -P dev test
|
|
./mvnw -P dev clean package spring-boot:repackage -DskipTests
|
|
./mvnw -P dev spring-boot:run
|
|
|
|
# 7. 홈 접속
|
|
open http://localhost:8080/ # HTTP 200
|
|
```
|
|
|
|
### 검증 증거
|
|
|
|
```text
|
|
$ ./mvnw -P dev test
|
|
Tests run: 6, Failures: 0, Errors: 0 # UserControllerCsrfTest 5 + BibimbapApplicationTests 1
|
|
[INFO] BUILD SUCCESS
|
|
|
|
$ ./mvnw -P dev clean package spring-boot:repackage -DskipTests
|
|
# WAR: target/bibimbap-0.0.1-SNAPSHOT.war (30MB, 실행형)
|
|
|
|
$ ./mvnw -P dev spring-boot:run
|
|
# Tomcat started on port 8080
|
|
# Started BibimbapApplication
|
|
# 홈 / -> 200 (provided tomcat 으로 정상 run)
|
|
```
|
|
|
|
### 중요 주의: `-P dev` 는 필수
|
|
|
|
이 pom 은 `spring-boot-starter-parent` 를 쓰지 않고 dependencyManagement import 만 한다(`pom.xml:200-219`). 그 결과:
|
|
|
|
- (a) profile 을 지정하지 않으면 `application.properties` 의 `@app.profile@` 필터링이 동작하지 않아 `spring.profiles.active` 가 깨진다.
|
|
- (b) `spring-boot:repackage` goal 이 `package` 단계에 자동 바인딩되지 않는다. 명시 호출하지 않으면 비실행 WAR 가 나오고 `no main manifest attribute` 로 실패한다.
|
|
|
|
## 4. DB 스키마 초기화 절차
|
|
|
|
핵심 사실: **flyway / liquibase 가 없다.** 마이그레이션 자동화가 없으며, 작업 시작 시점에 전체 스키마 SQL 도 부재였다. 6테이블 중 `recruit_posts` 만 권위 DDL(`docs/recruit-posts-ddl.sql`)이 존재했다.
|
|
|
|
본 작업에서 `db/schema.sql` 을 **복원**했다:
|
|
|
|
- `recruit_posts` — 권위 DDL 그대로.
|
|
- `user_auth_identities` — security-hardening 의 active-unique index 포함.
|
|
- `users` / `games` / `game_comments` / `game_likes` — **비권위 복원본**. 매퍼 `@Insert`/`@Select` 컬럼과 data POJO Java 타입에서 역추출했다. 컬럼명·유무는 매퍼와 일치 확인했으나, 타입·길이·제약은 추론값이다.
|
|
|
|
적용 방법:
|
|
|
|
- **Docker**: db 컨테이너 최초 기동 시 `db/schema.sql` 이 `docker-entrypoint-initdb.d` 로 자동 1회 실행된다(`dev` 스키마를 채우고, `live` 는 빈 스키마만 생성). 스키마 변경을 재적용하려면 `docker compose down -v` 후 재기동한다.
|
|
- **호스트 로컬 PG**: `psql -f db/schema.sql` 로 수동 적용한다.
|
|
|
|
> 경고: `db/schema.sql` 의 5개 비권위 테이블(users / games / game_comments / game_likes 및 user_auth_identities 의 추론 부분)은 운영 DB `pg_dump` 와 대조하기 전까지 타입을 신뢰하지 말 것. §7 미해결 항목 참조.
|
|
|
|
## 5. 검증 체크리스트
|
|
|
|
실제 통과한 항목은 `[x]` 다.
|
|
|
|
- [x] A: 빈 상태 → 의존성 수신 → 컴파일 (BUILD SUCCESS)
|
|
- [x] A: 앱 기동 후 홈 `/` HTTP 200 + 게임목록 렌더
|
|
- [x] A: DB 연결 정상 (6테이블, 빈 조회 무에러, 삽입 → 홈노출 라운드트립)
|
|
- [x] B: `./mvnw -P dev test` green (6 tests, 0 fail)
|
|
- [x] B: `./mvnw -P dev package` WAR 산출
|
|
- [x] B: `./mvnw -P dev spring-boot:run` 홈 200 (provided tomcat)
|
|
- [x] 신규 환경파일 비밀값 비커밋 (`.env` / `db.properties` / `certs/*.crt` gitignore 확인)
|
|
- [ ] (수동) 실제 사용자 환경에서 회원가입/로그인/게임등록 등 기능 스모크는 미수행 — 사용자 환경 검증 권장.
|
|
|
|
## 6. 트러블슈팅
|
|
|
|
### TLS 인터셉션 프록시로 SNAPSHOT 빌드 실패
|
|
|
|
- 증상: `PKIX path building failed: unable to find valid certification path to requested target` + `Non-resolvable import POM: spring-boot-dependencies:3.5.14-SNAPSHOT`.
|
|
- 원인: `repo.spring.io` 인증서를 회사 프록시(예: Cloudflare Gateway / Zero Trust)가 재서명하는데, JDK truststore 에 그 CA 가 없다. `curl` 은 시스템 키체인을 쓰므로 성공해도 **JDK 는 자체 cacerts** 를 쓰기 때문에 별도 import 가 필요하다.
|
|
- 해결:
|
|
- Docker — `certs/*.crt` 를 Dockerfile 이 자동 주입한다.
|
|
- 호스트 — §3 단계 3 의 `keytool` import 를 수행한다.
|
|
- CA 추출 예시 (macOS):
|
|
|
|
```bash
|
|
security find-certificate -a -c "Gateway CA - Cloudflare Managed" -p \
|
|
~/Library/Keychains/login.keychain-db /Library/Keychains/System.keychain \
|
|
> certs/corporate-proxy-ca.crt
|
|
```
|
|
|
|
자세한 내용은 `certs/README.md` 참조.
|
|
|
|
### db.properties 누락
|
|
|
|
`spring.config.import` 가 `optional:` 이라 컨텍스트는 뜨지만 datasource 가 구성되지 않아 DB 사용 페이지에서 실패한다. `.example` 을 복사하고 실값을 입력한다(§3 단계 5).
|
|
|
|
### 포트 충돌
|
|
|
|
- 호스트 5432 가 다른 postgres 에 점유되면 `.env` 의 `DB_PORT` 를 변경한다(예 5433). 실제로 본 환경에서는 기존 `kord-postgres` 가 5432 를 점유해 5433 으로 회피했다.
|
|
- 8080 이 점유되면 `APP_PORT` 를 변경한다.
|
|
|
|
### Java 미설치
|
|
|
|
`Unable to locate a Java Runtime` → §3 단계 1 의 `brew install openjdk@21`.
|
|
|
|
### "no main manifest attribute"
|
|
|
|
§3 주의 참조 — `spring-boot:repackage` 를 명시 호출해야 실행형 WAR 가 나온다.
|
|
|
|
## 7. 알려진 미해결
|
|
|
|
- **DDL 전체본 부재**: `db/schema.sql` 5테이블은 비권위 복원본(타입 추론)이다. 운영 DB `pg_dump` 대조가 필요하다. (open_question)
|
|
- **spring-boot 3.5.14-SNAPSHOT 고정 결정 대기**: SNAPSHOT 은 비재현·온라인 의존이다. 안정 릴리스 고정 여부가 미결이다 — `../analysis/2026-06-16-project-analysis.md` open_question #4.
|
|
- **기능 스모크 미수행**: 비권위 `db/schema.sql` 타입으로 인해 가입/업로드 등 기능 스모크는 수행하지 않았다.
|
|
|
|
## 참고: 본 가이드가 참조하는 생성 파일
|
|
|
|
- 루트: `docker-compose.yml`, `Dockerfile`, `.env.example`, `.dockerignore`, `db/schema.sql`, `certs/README.md`.
|
|
- gitignore 대상(비밀): `.env`, `src/main/resources/dev/db.properties`, `certs/*.crt`.
|