Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .claude/skills/git-conventions/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -38,7 +38,7 @@ description: Rodi의 commit/PR/issue/브랜치 작성 규칙. 커밋 메시지
- subject는 50자 이내
- body는 필요할 때만 — 이유나 변경 맥락을 설명
- Claude가 작성하는 커밋은 마지막에 트레일러를 붙인다:
`Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>`
`Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>`

### 예시

Expand Down
8 changes: 8 additions & 0 deletions .dockerignore
Original file line number Diff line number Diff line change
Expand Up @@ -9,3 +9,11 @@ build
docs
.claude
*.md
# bootJar는 src/main만 쓴다 — 테스트·로컬 전용 코드가 바뀌어도 이미지 레이어 캐시가 깨지지 않게(최종 이미지엔 jar만 들어감)
src/test
src/dev
# 배포·로컬 설정은 이미지에 불필요
deploy
db
.github
compose.yaml
162 changes: 162 additions & 0 deletions .github/workflows/cd-dev.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,162 @@
name: CD (dev · pi2)

# develop push 시: 테스트 → ARM64 이미지 빌드/GHCR push → Raspberry Pi 개발 서버(pi2) 배포 — 스펙 023
# pi2는 가정용 사설망이라 배포 잡만 Tailscale(OIDC, 임시 노드)로 tailnet에 들어와 SSH로 배포한다(인바운드 포트 없음).
# 운영(main → Lightsail)은 cd.yml 이 따로 담당한다.
on:
push:
branches: [develop]
workflow_dispatch:
inputs:
image_tag:
description: "재배포·롤백할 기존 이미지 태그(예: dev-<sha>). 비우면 현재 커밋을 빌드해 배포"
required: false
default: ""

concurrency:
group: cd-dev # 운영 cd-deploy 와 별개. 개발 서버 배포끼리만 직렬화
cancel-in-progress: false # 배포는 중간에 취소하지 않음

permissions: {} # 기본 권한 없음 — 잡마다 필요한 것만 연다

jobs:
test:
if: inputs.image_tag == ''
runs-on: ubuntu-latest
permissions:
contents: read
steps:
- uses: actions/checkout@v4
- name: Set up JDK 21
uses: actions/setup-java@v4
with:
distribution: temurin
java-version: '21'
cache: gradle
- name: Test
run: |
chmod +x ./gradlew
./gradlew build --no-daemon

build-push:
needs: test
runs-on: ubuntu-24.04-arm # ARM 호스티드 러너에서 네이티브 빌드(QEMU 없음). public 레포는 무료
permissions:
contents: read
packages: write # GHCR push
steps:
- uses: actions/checkout@v4

- name: Set lowercase image name
id: img
run: echo "name=ghcr.io/${GITHUB_REPOSITORY,,}" >> "$GITHUB_OUTPUT"

- uses: docker/setup-buildx-action@v3

- name: Login to GHCR
uses: docker/login-action@v3
with:
registry: ghcr.io
username: ${{ github.actor }}
password: ${{ secrets.GITHUB_TOKEN }}

- name: Build & push (arm64)
uses: docker/build-push-action@v6
with:
context: .
platforms: linux/arm64
push: true
# :dev-<sha> 는 배포에 사용(운영 :<sha> 와 접두어로 구분 — 아키텍처가 다른 이미지가 같은 태그를 덮지 않게), :develop 은 이동 태그
tags: |
${{ steps.img.outputs.name }}:dev-${{ github.sha }}
${{ steps.img.outputs.name }}:develop
cache-from: type=gha,scope=dev-arm64
cache-to: type=gha,mode=max,scope=dev-arm64 # 운영(amd64) 캐시와 분리

deploy:
needs: [test, build-push]
# 빌드 성공 시, 또는 image_tag 지정 재배포 시. Tailscale OIDC subject가 develop 이라 develop 에서만 실행
if: >-
!cancelled() && github.ref == 'refs/heads/develop' &&
(needs.build-push.result == 'success' || inputs.image_tag != '')
runs-on: ubuntu-latest
permissions:
contents: read
packages: read # pi2가 GHCR에서 pull (잡 토큰으로 로그인)
id-token: write # Tailscale OIDC(Workload Identity Federation) 토큰 발급
env:
IMAGE_TAG: ${{ inputs.image_tag || format('dev-{0}', github.sha) }}
PI2_HOST: ${{ secrets.PI2_HOST }}
steps:
- uses: actions/checkout@v4

# 장기 비밀값 없이 GitHub OIDC 토큰으로 인증. 임시 노드라 잡이 끝나면 사라지고, ACL로 tag:server 의 22번만 접근 가능
- name: Connect to Tailscale
uses: tailscale/github-action@v4
with:
oauth-client-id: ${{ secrets.TS_OAUTH_CLIENT_ID }}
audience: ${{ secrets.TS_AUDIENCE }}
tags: tag:ci

# 호스트 키 검증: known_hosts 를 레포 시크릿(pi2 공개 호스트 키)으로 고정 → 다른 서버면 접속 거부
- name: Set up SSH
env:
PI2_SSH_KEY: ${{ secrets.PI2_SSH_KEY }}
PI2_SSH_HOST_KEY: ${{ secrets.PI2_SSH_HOST_KEY }}
PI2_SSH_USER: ${{ vars.PI2_SSH_USER }} # 비밀값이 아니라 Variable — Secret이면 로그의 "deploy" 단어가 전부 *** 로 가려진다
run: |
: "${PI2_HOST:?secrets.PI2_HOST 미설정}" "${PI2_SSH_USER:?vars.PI2_SSH_USER 미설정}"
: "${PI2_SSH_KEY:?secrets.PI2_SSH_KEY 미설정}"
: "${PI2_SSH_HOST_KEY:?secrets.PI2_SSH_HOST_KEY 미설정 — pi2의 /etc/ssh/ssh_host_ed25519_key.pub 내용}"
install -m 700 -d ~/.ssh
printf '%s\n' "$PI2_SSH_KEY" > ~/.ssh/pi2 && chmod 600 ~/.ssh/pi2
printf '%s %s\n' "$PI2_HOST" "$PI2_SSH_HOST_KEY" > ~/.ssh/known_hosts
# 이후 스텝은 `ssh pi2` / `scp ... pi2:` 로 접속. 호스트 키가 known_hosts 와 다르면 접속 거부
cat > ~/.ssh/config <<EOF
Host pi2
HostName $PI2_HOST
User $PI2_SSH_USER
IdentityFile ~/.ssh/pi2
UserKnownHostsFile ~/.ssh/known_hosts
StrictHostKeyChecking yes
BatchMode yes
ConnectTimeout 10
EOF

# 사전 점검: 네트워크·인증 문제를 배포 실패와 구분해 바로 원인이 보이게
- name: Check Tailscale & SSH reachability
run: |
tailscale status --self --peers=false || true # 정보 출력용
for i in $(seq 1 10); do
nc -z -w 5 "$PI2_HOST" 22 && break
[ "$i" = 10 ] && { echo "::error::pi2:22 에 닿지 않음(Tailscale ACL·pi2 상태 확인)"; exit 1; }
sleep 3
done
ssh pi2 'echo "ssh ok: $(hostname)"; docker version --format "docker {{.Server.Version}}"'

- name: Copy deploy files
run: scp deploy/compose.dev.yaml deploy/deploy-dev.sh pi2:/opt/rodi-app/

# GHCR 로그인은 잡 토큰(이 잡 동안만 유효)으로 — pi2에 PAT를 두지 않는다. 마지막 스텝에서 로그아웃
- name: Login pi2 to GHCR
env:
GHCR_TOKEN: ${{ secrets.GITHUB_TOKEN }}
run: printf '%s' "$GHCR_TOKEN" | ssh pi2 "docker login ghcr.io -u $(printf %q "$GITHUB_ACTOR") --password-stdin"

# 헬스체크 통과까지 대기, 실패하면 컨테이너 로그 출력 + 직전 성공 태그로 자동 롤백 후 잡 실패
# 배포 메타데이터는 스크립트에 직접 넣지 않고 printf %q 로 이스케이프해 전달(주입 안전)
- name: Deploy
env:
DEPLOY_BRANCH: ${{ github.ref_name }}
DEPLOY_COMMIT: ${{ github.sha }}
DEPLOY_MESSAGE: ${{ github.event.head_commit.message }}
DEPLOY_REPO: ${{ github.repository }}
run: |
DEPLOY_MESSAGE="$(printf '%s' "$DEPLOY_MESSAGE" | head -n1)"
printf 'export IMAGE_TAG=%q DEPLOY_BRANCH=%q DEPLOY_COMMIT=%q DEPLOY_MESSAGE=%q DEPLOY_REPO=%q\nexec bash /opt/rodi-app/deploy-dev.sh\n' \
"$IMAGE_TAG" "$DEPLOY_BRANCH" "$DEPLOY_COMMIT" "$DEPLOY_MESSAGE" "$DEPLOY_REPO" \
| ssh pi2 'bash -s'

- name: Logout pi2 from GHCR
if: always()
run: ssh pi2 'docker logout ghcr.io' || true
10 changes: 6 additions & 4 deletions .github/workflows/cd.yml
Original file line number Diff line number Diff line change
@@ -1,18 +1,20 @@
name: CD

# main·develop push 시: 테스트 → 이미지 빌드/GHCR push → Lightsail 단일 app 재배포
# (별도 스테이징 없음 — 서버 메모리 제약. 어느 브랜치를 push하든 같은 app에 배포되며 나중 push가 반영됨)
# main push 시: 테스트 → 이미지 빌드/GHCR push → Lightsail(운영) app 재배포
# develop 은 개발 서버(Raspberry Pi pi2)로 따로 배포된다 — cd-dev.yml, 스펙 023
on:
push:
branches: [main, develop]
branches: [main]
workflow_dispatch: {} # 수동 재배포/롤백용

concurrency:
group: cd-deploy # main·develop 배포를 한 그룹으로 직렬화(같은 app을 동시에 안 건드리게)
group: cd-deploy # 운영 배포를 직렬화(같은 app을 동시에 안 건드리게)
cancel-in-progress: false # 배포는 중간에 취소하지 않음

jobs:
test:
# 수동 실행을 다른 브랜치에서 해도 운영에 배포되지 않게(test가 건너뛰면 이후 잡도 건너뜀)
if: github.ref == 'refs/heads/main'
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
Expand Down
4 changes: 2 additions & 2 deletions CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@ Rodi는 **초보 운전자를 위한 맞춤형 연습 장소 및 코스 탐색
| API 문서 | SpringDoc OpenAPI (Swagger UI) |
| 테스트 | JUnit 5, Testcontainers, Mockito, AssertJ |
| 품질/검사 | Spotless, SonarCloud, JaCoCo, CodeRabbit |
| CI/CD·배포 | GitHub Actions, Docker, GHCR, AWS Lightsail, Caddy |
| CI/CD·배포 | GitHub Actions, Docker, GHCR · 운영(`main`): AWS Lightsail, Caddy · 개발(`develop`): Raspberry Pi, Tailscale, Cloudflare Tunnel |
| 의존성 | Dependabot |
| 기타 | Lombok, DevTools, Actuator, Bean Validation |

Expand Down Expand Up @@ -56,6 +56,6 @@ DDD + **package-by-feature**로 시작, 도메인이 복잡해지면 feature 단
- 루트 패키지 `cmc.rodi`, 진입점 [RodiApplication.java](src/main/java/cmc/rodi/RodiApplication.java).
- 패키지: `global`(공통·인프라 — config·exception·response·auth 등) · `domain`(비즈니스 도메인 — member 등). feature 하위는 `entity`/`repository`/`service`/`controller`/`dto` 계층으로 나눈다.
- **컨트롤러 분리 기준**: **자체 오퍼레이션 묶음을 가진 하위 리소스는 전용 컨트롤러**로 분리하고, **단발 엔드포인트는 소유(가장 가까운) 컨트롤러**에 둔다. 같은 URL 스코프여도 이 기준을 우선한다. 예: `recent-searches`(GET·DELETE·DELETE/{id}) → `RecentSearchController`; `filter-tags`(PUT 1개) → `MemberController`. URL 일관성이 아니라 **기준의 일관 적용**이 목표다.
- 문서 — 데이터 모델: [docs/erd.md](docs/erd.md) · 아키텍처 결정: [docs/adr/](docs/adr/) · 기능 스펙: [docs/specs/](docs/specs/) ([템플릿](docs/specs/TEMPLATE.md)). 작업 전 먼저 확인.
- 문서 — 데이터 모델: [docs/erd.md](docs/erd.md) · 인프라 구성: [docs/infra.md](docs/infra.md) · 아키텍처 결정: [docs/adr/](docs/adr/) · 기능 스펙: [docs/specs/](docs/specs/) ([템플릿](docs/specs/TEMPLATE.md)). 작업 전 먼저 확인.
- 시크릿(DB·OAuth2·JWT)은 환경변수/프로파일로 주입, 커밋 금지.
- API 경로는 `/api/v1` prefix로 버전을 명시한다 (예: `/api/v1/auth/oauth/{provider}`).
7 changes: 5 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@
| 인증 | OAuth2 Client + JWT |
| API 문서 | SpringDoc OpenAPI (Swagger UI) |
| 품질 | Spotless, SonarCloud, JaCoCo, CodeRabbit |
| 인프라 | Docker Compose, Caddy, GitHub Actions, AWS Lightsail |
| 인프라 | Docker Compose, GitHub Actions, GHCR · 운영: AWS Lightsail, Caddy · 개발: Raspberry Pi, Tailscale, Cloudflare Tunnel |

## 로컬 실행

Expand Down Expand Up @@ -46,5 +46,8 @@ DDD + package-by-feature로 시작, 도메인이 복잡해지면 feature 단위
## 브랜치 & 배포

- 기능 개발: `feat/#이슈번호-기능` → `develop` PR → 리뷰·CI 통과 후 머지
- 개발 서버: `develop` 머지 시 **ARM64 이미지 빌드 → GHCR → Raspberry Pi(pi2) 자동 배포** (Tailscale OIDC + SSH, 실패 시 자동 롤백)
- 릴리즈: `develop` → `main` PR → 머지 시 **GitHub Actions가 이미지 빌드 → GHCR → Lightsail 자동 배포**
- 배포 인프라 결정: [ADR 0005](docs/adr/0005-hosting-aws-lightsail.md)
- 서버 주소: 운영 `https://api.stillstar.store` · 개발 `https://dev-api.stillstar.store`
- 인프라 구성도·접근 제어·설정값: [docs/infra.md](docs/infra.md)
- 배포 인프라 결정: [ADR 0005](docs/adr/0005-hosting-aws-lightsail.md)(운영) · [ADR 0017](docs/adr/0017-dev-server-raspberry-pi-and-tailscale-deploy.md)(개발 서버)
25 changes: 25 additions & 0 deletions build.gradle
Original file line number Diff line number Diff line change
Expand Up @@ -64,6 +64,31 @@ dependencies {
implementation 'org.springframework.boot:spring-boot-starter-actuator'
}

// === 로컬 전용 dev 소스셋(스펙 021) ===
// src/dev: 마커 클러스터링 튜닝 페이지처럼 로컬 실행(bootRun)에서만 쓰는 코드. 배포 jar(bootJar)·운영 이미지에는 넣지 않는다.
// 운영 코드가 바뀌어 dev 코드가 깨지면 바로 알 수 있도록 check(= build)가 컴파일한다.
sourceSets {
dev {
compileClasspath += sourceSets.main.output
runtimeClasspath += sourceSets.main.output
}
}

configurations {
devImplementation.extendsFrom implementation
devCompileOnly.extendsFrom compileOnly
devAnnotationProcessor.extendsFrom annotationProcessor
devRuntimeOnly.extendsFrom runtimeOnly
}

tasks.named('bootRun') {
classpath += sourceSets.dev.output
}

tasks.named('check') {
dependsOn tasks.named('devClasses')
}

tasks.named('test') {
useJUnitPlatform()
finalizedBy tasks.named('jacocoTestReport')
Expand Down
29 changes: 29 additions & 0 deletions deploy/.env.dev.example
Original file line number Diff line number Diff line change
@@ -0,0 +1,29 @@
# 이 파일을 pi2의 /opt/rodi-app/.env 로 복사해 실제 값으로 채우세요 (chmod 600, 소유자 deploy).
# .env 는 git에 커밋하지 않습니다 (.gitignore 처리됨).

# --- DB (pi, PostgreSQL + PostGIS) ---
DB_HOST=192.168.0.11
DB_PORT=5432
DB_NAME=rodi_dev
DB_USERNAME=rodi
DB_PASSWORD=

# --- JWT — 운영과 다른 값 (openssl rand -base64 48) ---
JWT_SECRET=

# --- 애플 로그인 (운영과 같은 앱이면 같은 값) ---
# APPLE_PRIVATE_KEY = .p8 내용을 한 줄로(-----BEGIN/END----- 및 개행 제거한 base64 본문)
APPLE_TEAM_ID=
APPLE_KEY_ID=
APPLE_CLIENT_ID=
APPLE_PRIVATE_KEY=

# --- 카카오 Admin 키 (탈퇴 시 unlink). 카카오 콘솔 허용 IP에 집 공인 IP 등록 필요 ---
KAKAO_ADMIN_KEY=

# --- Discord 알림 (운영과 같은 웹훅, 메시지에 [dev] 라벨). 비우면 전송 안 함 ---
DISCORD_ERROR_WEBHOOK_URL=
DISCORD_HEALTH_WEBHOOK_URL=

# --- 이미지 태그·배포 메타데이터는 CD(deploy-dev.sh)가 주입. 수동 실행 시 생략하면 develop ---
# IMAGE_TAG=develop
42 changes: 42 additions & 0 deletions deploy/compose.dev.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,42 @@
# 개발 서버(Raspberry Pi pi2) 배포용 Compose — 스펙 023. 서버 /opt/rodi-app/ 에 위치(cd-dev.yml이 매 배포 시 전송).
# DB는 별도 Pi(pi)에 있어 app 하나만 띄운다. 같은 디렉터리의 .env 에서 값 주입(.env 는 git 커밋 금지, .env.dev.example 참고).
# 운영 compose(compose.prod.yaml)와 마찬가지로 새 환경변수는 environment에 명시해야 컨테이너로 전달된다.
name: rodi-dev

services:
app:
image: ghcr.io/central-makeus/rodi-server:${IMAGE_TAG:-develop}
restart: unless-stopped
environment:
SPRING_PROFILES_ACTIVE: dev
DB_URL: jdbc:postgresql://${DB_HOST:?DB_HOST를 .env에 설정하세요}:${DB_PORT:-5432}/${DB_NAME:-rodi_dev}
DB_USERNAME: ${DB_USERNAME:?DB_USERNAME을 .env에 설정하세요}
DB_PASSWORD: ${DB_PASSWORD:?DB_PASSWORD를 .env에 설정하세요}
JWT_SECRET: ${JWT_SECRET:?JWT_SECRET을 .env에 설정하세요} # 운영과 다른 값
APPLE_TEAM_ID: ${APPLE_TEAM_ID:-}
APPLE_KEY_ID: ${APPLE_KEY_ID:-}
APPLE_CLIENT_ID: ${APPLE_CLIENT_ID:-}
APPLE_PRIVATE_KEY: ${APPLE_PRIVATE_KEY:-}
KAKAO_ADMIN_KEY: ${KAKAO_ADMIN_KEY:-} # 탈퇴 시 카카오 unlink
DISCORD_ERROR_WEBHOOK_URL: ${DISCORD_ERROR_WEBHOOK_URL:-} # 운영과 같은 웹훅 — 메시지에 [dev] 라벨
DISCORD_HEALTH_WEBHOOK_URL: ${DISCORD_HEALTH_WEBHOOK_URL:-}
DEPLOY_BRANCH: ${DEPLOY_BRANCH:-} # 기동 알림용 배포 메타데이터(CD 주입)
DEPLOY_COMMIT: ${DEPLOY_COMMIT:-}
DEPLOY_MESSAGE: ${DEPLOY_MESSAGE:-}
DEPLOY_REPO: ${DEPLOY_REPO:-}
# pi2(4GB): 힙 상한 640MB. OOM이면 바로 종료해 restart 정책으로 다시 띄운다(반쯤 죽은 상태로 남지 않게)
JAVA_OPTS: "-Xms256m -Xmx640m -XX:+ExitOnOutOfMemoryError"
mem_limit: 1g # 힙 640MB + 메타스페이스·스레드·코드캐시
ports:
- "127.0.0.1:8080:8080" # pi2 자신만 접근. 외부는 Cloudflare Tunnel(dev-api.stillstar.store)로만 — cloudflared는 pi2 호스트(또는 network_mode: host)에서 localhost:8080으로 프록시해야 함
healthcheck:
test: ["CMD", "curl", "-fsS", "-o", "/dev/null", "http://localhost:8080/actuator/health"]
interval: 15s
timeout: 5s
retries: 5
start_period: 120s # Pi는 기동·Flyway 검증이 느림
logging:
driver: json-file
options:
max-size: "10m" # 16GB USB 보호
max-file: "3"
Loading
Loading