Getting Started

Getting Started

준비 사항

• Java 21
• Docker 및 Docker Compose
• Git

1. Repository 내려받기

git clone https://github.com/UMC-DISPLAYU/Backend.git
cd Backend

2. 환경변수 설정

cp .env.example .env

.env에는 다음 항목을 로컬 환경에 맞게 설정합니다.

• Database: DB_HOST, DB_PORT, DB_NAME, DB_USERNAME, DB_PASSWORD
• OAuth: Google 및 Kakao Client 정보와 Redirect URI
• Security: JWT_SECRET
• Storage: AWS_REGION, S3_BUCKET, CDN_BASE_URL
• Mail: MAIL_USERNAME, MAIL_PASSWORD
• Frontend: FRONTEND_BASE_URL, FRONTEND_ALLOWED_ORIGINS

.env는 Git에 커밋하지 않습니다. 로컬 DB 계정은 docker-compose.yml의 설정과 일치시켜야 합니다.

3. MySQL 실행

docker compose up -d
docker compose ps

로컬 환경은 MySQL 8.4와 DisplayU 데이터베이스를 사용합니다.

4. 애플리케이션 실행

./gradlew bootRun

bootRun은 기본적으로 local Profile을 사용합니다. 직접 지정하려면 다음 명령을 사용합니다.

./gradlew bootRun -Dspring.profiles.active=local

5. 실행 확인

curl http://localhost:8080/api/v1/health

• Swagger UI: http://localhost:8080/swagger-ui/index.html
• OpenAPI JSON: http://localhost:8080/v3/api-docs
• Actuator Health: http://localhost:8081/actuator/health
• Prometheus Metrics: http://localhost:8081/actuator/prometheus

자주 사용하는 명령어

목적	명령어
테스트	./gradlew test
전체 빌드	./gradlew clean build
코드 스타일 검사	./gradlew spotlessCheck
코드 스타일 적용	./gradlew spotlessApply
DB 중지	docker compose down
DB와 볼륨 제거	docker compose down -v

docker compose down -v는 로컬 DB 데이터를 삭제하므로 필요한 경우에만 실행합니다.

실행되지 않을 때

1. docker compose ps에서 MySQL이 healthy인지 확인합니다.
2. .env의 DB 계정과 docker-compose.yml 설정이 같은지 확인합니다.
3. 8080, 8081, 3306 포트가 이미 사용 중인지 확인합니다.
4. Flyway 오류가 발생하면 적용된 마이그레이션 파일을 수정하지 않았는지 확인합니다.