How to run the backend

Start the Kotlin/JVM backend service (backend/platform/) for local development. The backend exposes the REST API, runs the 5-layer pipeline, and connects to PostgreSQL.

Prerequisites

• JDK 21 installed (setup guide)
• PostgreSQL accessible (via port-forward or local instance)
• Azure CLI authenticated (az login)

Steps

Step 1: Start database port-forward

The dev PostgreSQL runs in AKS. Port-forward it to localhost:

kubectl port-forward -n aucert-dev svc/product-pg 5432:5432

tip

Keep this running in a separate terminal. If the connection drops, restart the port-forward.

Step 2: Set environment variables

# Database connection
export DATABASE_URL="jdbc:postgresql://localhost:5432/aucert"
export DATABASE_USER="aucert"
export DATABASE_PASSWORD="$(az keyvault secret show --vault-name aucertdev-kv-41e0x5 --name pg-password --query value -o tsv)"

# LLM config (optional — only needed if running pipeline locally)
export LLM_PROVIDER="azure-foundry"
export FOUNDRY_ENDPOINT="https://aucert-ai.cognitiveservices.azure.com/"
export FOUNDRY_API_KEY="$(az keyvault secret show --vault-name aucertdev-kv-41e0x5 --name foundry-api-key --query value -o tsv)"

Step 3: Start the backend

cd backend/platform
./gradlew bootRun

Expected output:

> Task :bootRun
  .   ____          _            __ _ _
 /\\ / ___'_ __ _ _(_)_ __  __ _ \ \ \ \
...
Started AucertPlatformApplication in 4.2 seconds

Step 4: Verify

# Health check
curl http://localhost:8080/health
# Expected: {"status": "UP"}

# API docs (if enabled)
curl http://localhost:8080/swagger-ui.html

With Tilt (recommended)

Tilt provides hot-reload — file changes trigger automatic rebuild and restart:

tilt up

Tilt watches backend/platform/src/ and runs ./gradlew bootRun on changes. The Tilt dashboard at http://localhost:10350 shows build status and logs.

Running with a local PostgreSQL

If you prefer a local database instead of port-forwarding:

# Start PostgreSQL via Docker
docker run -d \
  --name aucert-pg \
  -e POSTGRES_DB=aucert \
  -e POSTGRES_USER=aucert \
  -e POSTGRES_PASSWORD=localdev \
  -p 5432:5432 \
  postgres:18.3

# Update your env vars
export DATABASE_URL="jdbc:postgresql://localhost:5432/aucert"
export DATABASE_USER="aucert"
export DATABASE_PASSWORD="localdev"

warning

Local PostgreSQL won't have the schema or seed data from dev. You'll need to run Flyway migrations:

cd backend/platform
./gradlew flywayMigrate

Common tasks

Task	Command
Build without running	./gradlew build
Run tests	./gradlew test
Run a specific test	./gradlew test --tests "*.SomeTest"
Clean build	./gradlew clean build
Check dependencies	./gradlew dependencies
Format code	./gradlew ktlintFormat

Troubleshooting

"Connection refused" on database

1. Verify port-forward is running: lsof -i :5432
2. If not, restart: kubectl port-forward -n aucert-dev svc/product-pg 5432:5432
3. If using local PG, check Docker: docker ps | grep aucert-pg

"Class not found" or compilation errors

Generated protobuf classes may be stale. Regenerate and clean:

cd backend/platform
./gradlew clean generateProto build

Backend starts but API returns 500 errors

Check database connectivity and migrations:

# Verify DB connection
curl http://localhost:8080/health

# Check Flyway migration status
./gradlew flywayInfo

If migrations are pending, run ./gradlew flywayMigrate.

What's next

• How to run the frontend — Start the console UI
• How to run tests — Full test suite
• How to add an API endpoint — End-to-end guide