docs(README): 실행 안내를 실제와 맞춤 — Maven 준비물 추가, 없는 mvnw 안내 제거
All checks were successful
CI / backend-test (push) Successful in 2m9s
CI / frontend-build (push) Successful in 46s
CI / backend-dep-scan (push) Successful in 6s

수습생이 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을 쓰면 된다.
This commit is contained in:
AWESOMEDEV 2026-07-22 21:42:04 +09:00
parent 5c9959ce08
commit 169dcfba38

View File

@ -60,8 +60,12 @@ mirim-app/
### 0. 준비물 ### 0. 준비물
- Docker Desktop - Docker Desktop
- Java 21 (JDK) - Java 21 (JDK)
- **Maven 3.9 이상**`mvn -v`로 확인. 없으면 [maven.apache.org](https://maven.apache.org/download.cgi)에서 받아 PATH에 추가하세요.
- Node.js 20 이상 - Node.js 20 이상
> 네 개 다 설치됐는지 먼저 확인하세요. `docker -v`, `java -version`, `mvn -v`, `node -v`가 전부 버전을 뱉으면 준비 끝입니다.
> "command not found"가 나오면 그 도구가 없거나 PATH에 안 잡힌 겁니다 — 설치부터 하고 오세요.
### 1. 데이터베이스 켜기 ### 1. 데이터베이스 켜기
```bash ```bash
# 프로젝트 루트(mirim-app/)에서 # 프로젝트 루트(mirim-app/)에서
@ -72,7 +76,7 @@ PostgreSQL이 컨테이너로 뜹니다. `docker ps`로 확인하세요.
### 2. 백엔드 켜기 ### 2. 백엔드 켜기
```bash ```bash
cd backend cd backend
./mvnw spring-boot:run # mvnw가 안 되면: mvn spring-boot:run mvn spring-boot:run
``` ```
`http://localhost:8080` 에서 API 서버가 돌아갑니다. 첫 실행 시 시드 데이터(문서·체크리스트·과제·계정)가 자동으로 들어갑니다. `http://localhost:8080` 에서 API 서버가 돌아갑니다. 첫 실행 시 시드 데이터(문서·체크리스트·과제·계정)가 자동으로 들어갑니다.
@ -116,6 +120,8 @@ npm run dev
- **백엔드가 DB에 못 붙어요**`docker compose up -d`를 먼저 했는지, `docker ps`에 postgres가 있는지 확인. - **백엔드가 DB에 못 붙어요**`docker compose up -d`를 먼저 했는지, `docker ps`에 postgres가 있는지 확인.
- **5173 화면은 뜨는데 로그인이 안 돼요** → 백엔드(8080)가 켜져 있는지 확인. 프론트는 API를 백엔드로 보냅니다. - **5173 화면은 뜨는데 로그인이 안 돼요** → 백엔드(8080)가 켜져 있는지 확인. 프론트는 API를 백엔드로 보냅니다.
- **포트가 이미 사용 중이래요** → 이전에 켜 둔 서버가 남아 있을 수 있어요. 터미널을 확인하고 종료하세요. - **포트가 이미 사용 중이래요** → 이전에 켜 둔 서버가 남아 있을 수 있어요. 터미널을 확인하고 종료하세요.
- **`mvn: command not found`** → Maven이 없거나 PATH에 없습니다. 준비물 0번을 확인하세요. (이 저장소에는 `mvnw` 래퍼가 없어서 Maven을 직접 설치해야 합니다.)
- **`mvn package`가 커버리지 때문에 실패해요** → 테스트를 건너뛰면(`-DskipTests`) JaCoCo 커버리지 게이트(라인 30%)에 걸립니다. 서버를 띄우기만 할 거면 `mvn spring-boot:run`을 쓰세요. 패키징이 목적이면 테스트를 포함해 `mvn package`를 그대로 돌리면 통과합니다.
--- ---