From 169dcfba38ca35c41caa6d765b7d0795017964b8 Mon Sep 17 00:00:00 2001 From: AWESOMEDEV Date: Wed, 22 Jul 2026 21:42:04 +0900 Subject: [PATCH] =?UTF-8?q?docs(README):=20=EC=8B=A4=ED=96=89=20=EC=95=88?= =?UTF-8?q?=EB=82=B4=EB=A5=BC=20=EC=8B=A4=EC=A0=9C=EC=99=80=20=EB=A7=9E?= =?UTF-8?q?=EC=B6=A4=20=E2=80=94=20Maven=20=EC=A4=80=EB=B9=84=EB=AC=BC=20?= =?UTF-8?q?=EC=B6=94=EA=B0=80,=20=EC=97=86=EB=8A=94=20mvnw=20=EC=95=88?= =?UTF-8?q?=EB=82=B4=20=EC=A0=9C=EA=B1=B0?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 수습생이 README대로 따라 하면 백엔드 실행 첫 줄에서 막히는 상태였다. - `./mvnw spring-boot:run` → `mvn spring-boot:run` 저장소에 mvnw 래퍼 파일이 없다. 없는 파일을 안내하고 있었다. (CI도 같은 이유로 Maven을 직접 내려받아 쓴다 — ci.yml 주석 참고) - 준비물에 Maven 3.9 이상 추가 Docker·Java·Node만 적혀 있고 Maven이 빠져 있었다. 실제로 이것 때문에 막혔다 — "java는 있는데 왜 안 되지?"의 원인이 여기였다. - 시작 전 확인 명령 4줄 추가(docker -v / java -version / mvn -v / node -v) 준비물이 갖춰졌는지 먼저 확인하는 습관을 들이게 한다. - 자주 겪는 문제 2건 추가 · mvn: command not found — 래퍼가 없어 직접 설치해야 함을 명시 · mvn package가 커버리지로 실패 — -DskipTests로 돌리면 JaCoCo 라인 30% 게이트에 걸린다. 서버만 띄울 땐 spring-boot:run을 쓰면 된다. --- README.md | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 45c90b6..17fc2cd 100644 --- a/README.md +++ b/README.md @@ -60,8 +60,12 @@ mirim-app/ ### 0. 준비물 - Docker Desktop - Java 21 (JDK) +- **Maven 3.9 이상** — `mvn -v`로 확인. 없으면 [maven.apache.org](https://maven.apache.org/download.cgi)에서 받아 PATH에 추가하세요. - Node.js 20 이상 +> 네 개 다 설치됐는지 먼저 확인하세요. `docker -v`, `java -version`, `mvn -v`, `node -v`가 전부 버전을 뱉으면 준비 끝입니다. +> "command not found"가 나오면 그 도구가 없거나 PATH에 안 잡힌 겁니다 — 설치부터 하고 오세요. + ### 1. 데이터베이스 켜기 ```bash # 프로젝트 루트(mirim-app/)에서 @@ -72,7 +76,7 @@ PostgreSQL이 컨테이너로 뜹니다. `docker ps`로 확인하세요. ### 2. 백엔드 켜기 ```bash cd backend -./mvnw spring-boot:run # mvnw가 안 되면: mvn spring-boot:run +mvn spring-boot:run ``` `http://localhost:8080` 에서 API 서버가 돌아갑니다. 첫 실행 시 시드 데이터(문서·체크리스트·과제·계정)가 자동으로 들어갑니다. @@ -116,6 +120,8 @@ npm run dev - **백엔드가 DB에 못 붙어요** → `docker compose up -d`를 먼저 했는지, `docker ps`에 postgres가 있는지 확인. - **5173 화면은 뜨는데 로그인이 안 돼요** → 백엔드(8080)가 켜져 있는지 확인. 프론트는 API를 백엔드로 보냅니다. - **포트가 이미 사용 중이래요** → 이전에 켜 둔 서버가 남아 있을 수 있어요. 터미널을 확인하고 종료하세요. +- **`mvn: command not found`** → Maven이 없거나 PATH에 없습니다. 준비물 0번을 확인하세요. (이 저장소에는 `mvnw` 래퍼가 없어서 Maven을 직접 설치해야 합니다.) +- **`mvn package`가 커버리지 때문에 실패해요** → 테스트를 건너뛰면(`-DskipTests`) JaCoCo 커버리지 게이트(라인 30%)에 걸립니다. 서버를 띄우기만 할 거면 `mvn spring-boot:run`을 쓰세요. 패키징이 목적이면 테스트를 포함해 `mvn package`를 그대로 돌리면 통과합니다. ---