Getting Started | Identity Service User Guide

Prerequisites

Tool	Requirement	Purpose
Java	JDK 21	Compile and run the Spring Boot application.
Maven	Maven 3.9+ or the included wrapper	Generate sources, test, package, and produce reports.
Docker	Current Docker Desktop or Docker Engine	Run PostgreSQL, Testcontainers, and the complete Compose stack.
Docker Compose	Compose v2 (`docker compose`)	Start the database and application together.
Git	Current stable release	Clone and work with the repository.

Confirm the active toolchain before the first build:

java -version
mvn -version
docker version
docker compose version

The repository includes mvnw and mvnw.cmd. Replace mvn with ./mvnw on Unix-like systems or .\mvnw.cmd on Windows when Maven is not installed globally.

Clone and inspect the project

git clone https://github.com/DanieleMasone/identity-service.git
cd identity-service

The main source locations are:

src/main/java: handwritten application, domain, persistence, and infrastructure code.
src/main/resources/openapi: the source OpenAPI contract.
src/main/resources/db/migration: versioned Flyway migrations.
src/test/java: unit, web-layer, repository, and integration tests.
docs: source files for the static dashboard and this guide.

Configure the local environment

The defaults are suitable for the repository's local PostgreSQL container:

Variable	Default	Used by
`DB_USERNAME`	`postgres`	Spring Boot and Docker Compose
`DB_PASSWORD`	`postgres`	Spring Boot and Docker Compose
`SPRING_DATASOURCE_URL`	`jdbc:postgresql://localhost:5432/identity_db`	Optional Spring Boot override

Docker Compose reads an optional repository-root .env file. It is ignored by Git and must not contain shared or production credentials.

Run locally with Maven

Start PostgreSQL first, then launch the application in a second terminal:

docker compose up -d db

mvn spring-boot:run

Flyway applies pending migrations during startup and Hibernate validates the resulting schema. The application listens on http://localhost:8080/api.

Verify startup

Wait for the Spring Boot log to report that IdentityServiceApplication has started.
Open local Swagger UI.
Use the documented v1 or v2 endpoints, or import the Postman collection.

Local runtime only: Swagger UI requires the running Spring Boot application. The public GitHub Pages site exposes generated static OpenAPI documentation instead.