Getting Started

Prerequisites

Requirement	Version	Notes
Java	21	Temurin or GraalVM
Maven	3.9+	Or use the project's mvn wrapper
Docker	24+	For PostgreSQL, Redis, LocalStack
Redis	7+	Must run separately on port 6379

---

1. Start infrastructure

```bash

From backend/

docker-compose up -d postgres localstack ```

Start Redis separately (Docker or local):

bash docker run -d -p 6379:6379 redis:7-alpine

Wait for postgres to pass its healthcheck before proceeding:

bash docker-compose ps # postgres should show "healthy"

---

2. Environment variables

The app uses sane defaults for local development. Override in production.

Variable	Default	Description
DB_HOST	localhost	PostgreSQL host
DB_PORT	5432	PostgreSQL port
DB_NAME	viana_db	Database name
DB_USER	viana_user	Database user
DB_PASSWORD	viana3123	Change in production
JWT_SECRET	hardcoded hex	256-bit HMAC secret — change in production
JWT_EXPIRATION	3600000	Access token TTL in ms (1 hour)
JWT_REFRESH_EXPIRATION_DAYS	30	Refresh token TTL in days
AWS_REGION	us-east-1	S3 region
AWS_ACCESS_KEY	test	S3 access key (LocalStack default)
AWS_SECRET_KEY	test	S3 secret key (LocalStack default)
AWS_BUCKET	viana-documents	S3 bucket name
AWS_S3_ENDPOINT	http://localhost:4566	Override for LocalStack; unset in production

Create backend/src/main/resources/application-local.properties (gitignored) to override locally without touching tracked files.

---

3. Create the S3 bucket (LocalStack)

bash aws --endpoint-url=http://localhost:4566 \ s3 mb s3://viana-documents \ --region us-east-1

---

4. Run the application

bash cd backend mvn spring-boot:run

The app starts on port 8080. On first run with ddl-auto=update, Hibernate creates all tables automatically.

---

5. Verify

bash curl http://localhost:8080/actuator/health

Expected response:

json { "status": "UP" }

---

6. Your first API call

Register a customer:

bash curl -X POST http://localhost:8080/api/register/customer \ -H "Content-Type: application/json" \ -d '{ "firstName": "Jane", "lastName": "Doe", "email": "jane@example.com", "password": "secret123", "phoneNumber": "+14165550100" }'

Response:

json { "email": "jane@example.com", "access_token": "<jwt>", "refresh_token": "<uuid>" }

Use access_token in all subsequent requests:

bash Authorization: Bearer <access_token>

---

Local tools

Tool	URL	Description
Swagger UI	http://localhost:8080/swagger-ui.html	Interactive API explorer (requires app running)
Actuator health	http://localhost:8080/actuator/health	App health + DB + Redis status
Prometheus metrics	http://localhost:8080/actuator/prometheus	Raw metrics
Prometheus UI	http://localhost:9090	Requires docker-compose up prometheus