Getting Started

Getting Started

로컬 PostgreSQL로 척척학사 백엔드를 실행하고 기본 검증을 마치는 과정입니다.

준비 사항

항목	기준
JDK	Java 17
빌드	저장소의 Gradle Wrapper
DB	PostgreSQL
기본 포트	8080
기본 프로필	local

Docker는 애플리케이션 실행에 필수는 아닙니다. 로컬 Loki 스택이나 Flyway Docker 명령을 사용할 때만 필요합니다.

저장소 준비

git clone https://github.com/cchaksa/cchaksa-backend.git
cd cchaksa-backend
./gradlew --version

Gradle 출력에서 JVM이 17인지 확인합니다. 별도 Gradle 설치는 필요하지 않습니다.

환경 변수

루트의 .env를 Spring이 optional:file:.env[.properties]로 읽습니다. .env는 Git에서 제외되며 실제 값은 팀의 비밀정보 관리 경로에서 받아야 합니다.

로컬 부팅에 필요한 기본 변수입니다.

변수	역할
LOCAL_DB_URL	로컬 프로필 PostgreSQL JDBC URL
LOCAL_DB_USERNAME	DB 사용자
LOCAL_DB_PASSWORD	DB 비밀번호
JWT_SECRET	Access Token과 Refresh Token의 JWT 서명 키
JWT_ACCESS_EXPIRATION	Access Token 만료 시간
JWT_REFRESH_EXPIRATION	Refresh Token 만료 시간
APP_KEY	Kakao OIDC audience 검증 키
APPLE_CLIENT_ID	Apple OIDC 기본 client ID
CRAWLER_BASE_URL	포털 연동 시스템의 기준 URL

기능별 선택 변수입니다.

변수	역할
APP_NATIVE_KEY	Android Kakao OIDC audience 허용 값
APPLE_ALLOWED_CLIENT_IDS	추가 Apple client ID 목록
SCRAPING_JOB_QUEUE_URL	포털 작업을 발행할 SQS Queue URL
SCRAPING_CALLBACK_HMAC_SECRET	내부 결과 콜백 HMAC 키
SCRAPING_RESULT_BUCKET	결과 JSON을 읽는 S3 Bucket
SCRAPING_RESULT_PREFIX	허용할 S3 Key Prefix
SCRAPING_RESULT_REGION	결과 Bucket의 AWS Region
MANAGEMENT_OTLP_TRACING_ENDPOINT	OTLP Trace 주소. 현재 exporter 자동 설정이 제외되어 이 값만으로 전송되지 않음
MANAGEMENT_OTLP_METRICS_EXPORT_URL	OTLP Metric 수집 주소

.env를 출력하거나 Wiki, Issue, PR 본문에 붙이지 않습니다. 변수 이름만 공유합니다.

로컬 실행

./gradlew bootRun --args='--spring.profiles.active=local'

기본값도 local이지만 명령에 프로필을 적어두면 실행 환경을 오해할 가능성이 줄어듭니다.

서버가 올라오면 아래 순서로 확인합니다.

curl -sS http://localhost:8080/health
curl -sS http://localhost:8080/actuator/health
curl -sS http://localhost:8080/v3/api-docs

브라우저에서는 http://localhost:8080/swagger-ui/index.html을 엽니다.

첫 테스트

./gradlew test
./gradlew check

check는 테스트를 포함한 CI 기준 명령입니다. 특정 테스트만 반복할 때는 클래스명을 지정합니다.

./gradlew test --tests 'com.chukchuk.haksa.application.portal.PortalLinkJobServiceUnitTests'

로컬 DB 주의 사항

• local은 spring.jpa.hibernate.ddl-auto=update를 사용합니다.
• dev·prod는 ddl-auto=validate이며 애플리케이션 내부 Flyway 실행도 꺼져 있습니다.
• dev·prod 마이그레이션은 GitHub Actions의 Flyway Migration for DB schema가 담당합니다.
• 로컬에서 자동 생성된 스키마를 기준으로 dev·prod 변경이 완료됐다고 판단하면 안 됩니다.

Lambda의 프로필 선택은 로컬 부팅과 다릅니다. Lambda 실행 시 SPRING_PROFILES_ACTIVE가 없으면 develop-shadow를 사용합니다. prod Lambda에는 외부 인프라 설정으로 SPRING_PROFILES_ACTIVE=prod가 반드시 주입돼야 합니다.

포털 연동을 로컬에서 호출할 때

애플리케이션 부팅과 포털 연동 성공은 별개의 검증입니다. 포털 연동에는 SQS, AWS 자격 증명, HMAC, Worker, S3 결과 저장소가 모두 필요합니다.

로컬에서 인프라를 연결하지 않는다면 다음 범위만 검증합니다.

• 서버 부팅과 DB 연결.
• Swagger와 공개 Health endpoint.
• 단위·통합 테스트.
• 포털 연동 요청의 유효성 검증과 인증 동작.

실제 비동기 연동을 검증하려면 dev 환경을 사용하고 Core Domain Flows와 Troubleshooting을 함께 확인합니다.