Setup

Customer Management — Setup Guide

How to get the project running locally, plus the main ways to run and deploy it.

Live demo: https://customer-management-hj57iqzdmq-nw.a.run.app — sign in with admin / admin123.

Prerequisites

Tool	Version	Needed for
JDK	21	backend (the Gradle wrapper is included)
Node.js	18+ (20 recommended)	frontend
Docker	recent	container run + the Testcontainers Redis test
gcloud + Terraform	optional	Cloud Run deployment

1. Clone

git clone https://github.com/stdOWL/customermanagement.git
cd customermanagement

2. Run the backend

./gradlew bootRun

Starts on http://localhost:8080 with the in-memory (local) profile. bootRun injects a development JWT_SECRET automatically, and Flyway creates the schema and seeds the accounts.

Seeded accounts

Username	Password	Role
admin	admin123	ADMIN
user	user123	USER

Quick smoke test

TOKEN=$(curl -s localhost:8080/api/auth/login -H 'Content-Type: application/json' \
  -d '{"username":"admin","password":"admin123"}' | jq -r .accessToken)
curl -s localhost:8080/api/me -H "Authorization: Bearer $TOKEN"

3. Run the frontend

cd frontend
npm install
npm run dev

Opens http://localhost:5173 and calls the API at http://localhost:8080 (override with VITE_API_BASE_URL). The backend already allows the Vite dev origin via CORS.

4. API docs

• Swagger UI: http://localhost:8080/swagger-ui.html — run the login operation and the bearer token is applied automatically.
• OpenAPI JSON: http://localhost:8080/v3/api-docs
• Postman: the collection + environment live in postman/ (see postman/README.md).

5. Run the tests

./gradlew test

Unit + integration tests (including a Testcontainers-backed Redis test — needs Docker). Coverage report: build/reports/jacoco/test/html/index.html.

6. Run with Docker

docker compose up --build

Builds the full-stack image (the React SPA is bundled into the backend jar) plus Redis, served on http://localhost:8080.

7. Deploy (optional)

terraform/ provisions a minimal, scale-to-zero Cloud Run stack — see terraform/README.md. CI/CD (GitHub Actions) builds the image and deploys to Cloud Run on every push to main.

Configuration

Variable	Purpose	Default
JWT_SECRET	HS256 signing key, ≥ 32 bytes (required)	dev/test injected
SPRING_PROFILES_ACTIVE	active environment profile	local
RATELIMIT_ENABLED	toggle rate limiting	true
CORS_ALLOWED_ORIGINS	allowed browser origins (comma-separated)	http://localhost:5173