로컬 실행 매뉴얼

# 처음
git clone https://github.com/fdxchatgpt/hwss-investigation-agent.git hwss
cd hwss

# 이미 받아 둔 경우 — dev 최신으로
git fetch origin
git switch dev
git pull --ff-only

아래의 모든 경로는 이렇게 받은 hwss 폴더를 기준으로 합니다. 다른 이름으로 받았다면 경로의 hwss 만 바꾸면 됩니다.

1PostgreSQL 띄우기

cd hwss-investigation-agent-backend
docker compose up -d   # postgres:16 · DB/계정/비밀번호 모두 hwss · 5432

5432 를 다른 PostgreSQL 이 이미 쓰고 있으면(기동 로그에 role "hwss" does not exist) 컨테이너를 5433 으로 띄우고 아래 .env 의 DB_URL 포트를 5433 으로 바꿉니다 — §막힐 때.

2.env 만들기

cd hwss-investigation-agent-backend
cp apps/hwss-api/.env.example apps/hwss-api/.env

cd hwss-investigation-agent-backend
Copy-Item apps\hwss-api\.env.example apps\hwss-api\.env

복사한 apps/hwss-api/.env 를 열어 꺾쇠 자리를 채웁니다. 개인 로컬 값은 이렇습니다.

SPRING_PROFILES_ACTIVE=local
DB_URL=jdbc:postgresql://127.0.0.1:5432/hwss
DB_USERNAME=hwss
DB_PASSWORD=hwss
IMAGE_INCOMING_ROOT=runtime/incoming
IMAGE_PROCESSING_ROOT=runtime/image-processing
COLLECTION_STORAGE_ROOT=runtime/collections
AUTH_JWT_SECRET=local-dev-only-secret-key-32bytes-min
AUTH_LOCAL_PASSWORD=devpass

.env 는 Git 에서 제외돼 있고, 백엔드가 뜰 때 알아서 읽습니다(spring.config.import). DB_PASSWORD·AUTH_JWT_SECRET 은 기본값이 일부러 없어서 빠뜨리면 기동이 실패합니다. 상대 경로 runtime/… 은 apps/hwss-api/ 아래에 생깁니다.

3서버 기동

cd hwss-investigation-agent-backend
./gradlew :hwss-api:bootRun

cd hwss-investigation-agent-backend
.\gradlew.bat :hwss-api:bootRun

로그에 The following 1 profile is active: "local", Successfully applied … migrations, Started HwssApiApplication 이 보이면 성공. http://localhost:8080/actuator/health 가 UP 입니다. 테이블은 앱이 기동하면서 Flyway 로 만듭니다.

1최초 1회 — Tailscale 연결 후 설정 스크립트

# hwss 저장소 루트에서. Homebrew 필요
chmod +x ./scripts/setup-dev-shared-macos.sh
./scripts/setup-dev-shared-macos.sh

# hwss 저장소 루트의 일반 PowerShell 에서. WinGet 필요
powershell -ExecutionPolicy Bypass -File .\scripts\setup-dev-shared-windows.ps1

macFUSE 첫 설치 시스템 설정에서 확장을 승인하고 재시작을 요구하면 재시작 뒤 같은 스크립트를 다시 실행합니다. Windows 도 WinFsp 직후 드라이브 등록이 실패하면 재시작 후 재실행 — 이미 끝난 단계는 건너뜁니다.

2연결 확인 — 기동 전마다 한 번

nc -vz 127.0.0.1 15432
ls ./hwss-investigation-agent-backend/apps/hwss-api/runtime/dev-shared

Test-NetConnection 127.0.0.1 -Port 15432
Get-ChildItem .\hwss-investigation-agent-backend\apps\hwss-api\runtime\dev-shared

포트가 열려 있고(succeeded / TcpTestSucceeded : True) 폴더 세 개가 보이면 준비된 것입니다. 안 되면 Tailscale 부터 봅니다 — §막힐 때.

3.env 를 공용 값으로

A 모드와 같은 apps/hwss-api/.env 에서 네 줄만 다릅니다. 파일 경로(IMAGE_*_ROOT·COLLECTION_STORAGE_ROOT)는 그대로 둬도 됩니다 — dev-shared 프로필이 runtime/dev-shared/… 로 덮어쓰고, 운영체제별 절대 경로를 적을 필요가 없습니다.

SPRING_PROFILES_ACTIVE=local,dev-shared
DB_URL=jdbc:postgresql://127.0.0.1:15432/hwss_dev
DB_USERNAME=hwss_dev
DB_PASSWORD=<공용 DB 비밀번호>
AUTH_JWT_SECRET=local-dev-only-secret-key-32bytes-min
AUTH_LOCAL_PASSWORD=devpass

4서버 기동 — A 모드와 같은 명령

cd hwss-investigation-agent-backend
./gradlew :hwss-api:bootRun

cd hwss-investigation-agent-backend
.\gradlew.bat :hwss-api:bootRun

로그에 The following 2 profiles are active: "local", "dev-shared" 가 보여야 공용 모드입니다. dev-shared 프로필은 DB_URL·DB_USERNAME·DB_PASSWORD 에 기본값을 두지 않아, 빠뜨리면 엉뚱한 DB 에 조용히 붙는 대신 기동이 실패합니다.

cd hwss-investigation-agent-frontend
corepack enable
pnpm install
pnpm dev                       # http://localhost:3000

http://localhost:3000 으로 열면 /login 으로 갑니다. 사번 H2016-0071 / 비밀번호는 .env 의 AUTH_LOCAL_PASSWORD. 브라우저는 같은 오리진의 /api/v1 만 부르고 Next.js 가 BACKEND_ORIGIN(기본 http://localhost:8080)으로 넘기므로, 백엔드가 A·B 어느 모드든 프론트는 손댈 것이 없습니다.

1받아서 띄우기 — hwss 옆에

# hwss 와 같은 상위 폴더에서
git clone https://github.com/fdxchatgpt/hwss-pipeline-testbench.git
cd hwss-pipeline-testbench
cp .env.example .env.local
pnpm install
pnpm dev                       # http://127.0.0.1:3300

# hwss 와 같은 상위 폴더에서 (백엔드 env 파일을 bash 로 읽으므로 Git for Windows 의 bash 가 PATH 에 있어야 한다)
git clone https://github.com/fdxchatgpt/hwss-pipeline-testbench.git
cd hwss-pipeline-testbench
Copy-Item .env.example .env.local
pnpm install
pnpm dev                       # http://127.0.0.1:3300

hwss 와 나란히 두는 이유: 연동 계약 파일(docs/specs/contracts/image-system-api.yaml)을 기본으로 ../hwss 에서 읽습니다. 다른 곳에 두면 .env.local 에 TESTBENCH_CONTRACT_REPO 로 알려 줍니다.

2.env.local — 백엔드 .env 를 가리킨다

# hwss 를 받은 경로로 바꾼다
TESTBENCH_BACKEND_ENV_FILE=~/IdeaProjects/hwss/hwss-investigation-agent-backend/apps/hwss-api/.env
TESTBENCH_BACKEND_URL=http://localhost:8080
TESTBENCH_APP_URL=http://localhost:3000
TESTBENCH_DATA_DIR=~/hwss/testbench

테스트벤치는 이 파일에서 DB_URL·DB_USERNAME·DB_PASSWORD·파일 폴더·AUTH_LOCAL_PASSWORD 를 읽습니다. 화면 오른쪽 위에 지금 붙은 DB 와 백엔드가 항상 표시됩니다. 체크포인트는 TESTBENCH_DATA_DIR 아래 쌓입니다.

3개발 DB·저장소를 바라보게 하기

백엔드 .env 가 B 모드(SPRING_PROFILES_ACTIVE=local,dev-shared)면 테스트벤치도 저절로 공용 DB·저장소를 봅니다. 따로 적을 값이 없습니다.

두 모드를 번갈아 쓸 때는 §모드 전환의 .env.local-mode·.env.dev-shared 를 환경 프로필로 등록해 둡니다 — 「환경」 화면의 「＋ 환경 추가」 에서 env 파일 경로를 적거나, 앱 폴더의 profiles.local.json 에 아래처럼 둡니다. 「이 환경으로」 를 누르면 재시작 없이 그 DB 로 붙습니다.

{
  "profiles": [
    { "id": "local", "label": "개인 로컬",
      "backendEnvFile": "~/IdeaProjects/hwss/hwss-investigation-agent-backend/apps/hwss-api/.env.local-mode" },
    { "id": "dev-shared", "label": "개발서버 공용",
      "backendEnvFile": "~/IdeaProjects/hwss/hwss-investigation-agent-backend/apps/hwss-api/.env.dev-shared" }
  ]
}

주의 테스트벤치가 보는 DB 와 백엔드가 떠 있는 DB 는 같아야 합니다. 백엔드는 A 모드인데 테스트벤치만 공용 프로필을 고르면, 되돌린 결과가 화면에 안 보이거나 「실행」 이 엉뚱한 DB 의 사건을 찾습니다. 공용 DB 에서의 복원·되돌리기·사건 삭제는 남의 사건에도 그대로 적용됩니다 — 내 접수번호만 다룹니다. Studio 쪽 상태는 되돌릴 수 없다는 한계는 모드와 무관합니다.

자주 쓰는 것

2백엔드 로그를 Loki 로 — 선택

bootRun 은 호스트 JVM 이라 컨테이너 로그 수집에 안 잡힙니다. 출력을 runtime/logs/ 로 흘리면 Alloy 가 파일을 읽어 {container="hwss-api"} 라벨로 보냅니다. LOG_FORMAT 은 Logback 이 Spring 보다 먼저 읽으므로 .env 가 아니라 셸 환경변수로 줍니다 — 나머지 값은 .env 가 채웁니다.

mkdir -p hwss-investigation-agent-backend/runtime/logs
cd hwss-investigation-agent-backend
LOG_FORMAT=json ./gradlew -q :hwss-api:bootRun | tee runtime/logs/app.log

New-Item -ItemType Directory -Force hwss-investigation-agent-backend\runtime\logs | Out-Null
cd hwss-investigation-agent-backend
$env:LOG_FORMAT="json"; .\gradlew.bat -q :hwss-api:bootRun | Tee-Object -FilePath runtime\logs\app.log

Grafana → Explore → 데이터소스 Loki → {container="hwss-api"} |= "ERROR". 한 요청의 줄만 보려면 응답 헤더 X-Request-Id 값으로 | json | mdc_requestId="…". 자세한 질의와 구성은 백엔드 가이드 · 관측 스택, 설정 파일은 infra/observability/README.md.

docs-site/ 를 고친 PR 은 올리기 전에

node --test docs-site/test/*.test.mjs
python3 -m unittest discover -s docs-site/generators -p "test_*.py"

CI 는 dev 머지 때만 돌아 PR 에서는 잡아 주지 않습니다. 구조·설정 전체는 docs-site/README.md.