The local development stack for Auth Service is designed to mirror a realistic runtime environment without needing any external services. Docker Compose brings up three backing services — a PostgreSQL 15 database, a MailHog SMTP capture server, and a Redpanda Kafka-compatible broker — so that you can start the Spring Boot application with a single Maven command and have a fully functional authentication service running on your machine within minutes.Documentation Index
Fetch the complete documentation index at: https://mintlify.com/ricardomb-tech/auth-service/llms.txt
Use this file to discover all available pages before exploring further.
Prerequisites
Before you begin, make sure the following tools are installed:- Java 21 (Eclipse Temurin recommended — the same distribution used in CI)
- Maven 3.9+, or use the included
./mvnwwrapper (no separate Maven installation needed) - Docker and Docker Compose (Docker Desktop on macOS/Windows, or Docker Engine + Compose plugin on Linux)
Setup Steps
Create your local environment file
Copy the provided example and populate the required secrets. The only value you must change before starting is Generate a secure, random 256-bit JWT secret:Open Leave
JWT_SECRET_CURRENT — everything else has working dev defaults..env and replace the placeholder value:JWT_SECRET_PREVIOUS empty for a fresh local setup. You can optionally fill in GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET, GITHUB_CLIENT_ID, and GITHUB_CLIENT_SECRET if you want to test the OAuth2 social login flows locally — the service starts without them but those endpoints will not work.Start the backing services with Docker Compose
healthy or running.Start Auth Service with the dev profile
dev profile (application-dev.properties) supplies default database connection values that match the Docker Compose service, so no additional configuration is needed for a first run. Flyway will automatically apply all pending migrations on startup and log each applied version.Verify the service is running
Spring Boot logs A healthy response looks like:
Started AuthServiceApplication when the service is ready. You can also probe the actuator health endpoint (enabled on the default port in local development):The actuator endpoints are configured with
management.endpoints.web.exposure.include=none by default — health is accessible in the dev profile but no other endpoints are exposed publicly. Management port configuration for Kubernetes liveness/readiness probes is planned as part of Epic 5.What Docker Compose Starts
Thedocker-compose.yml defines three services that back the local development environment:
| Service | Ports | Purpose |
|---|---|---|
postgres | 5432 | PostgreSQL 15 database. Flyway creates and migrates the schema on first boot. Data is persisted to the named volume auth-service-postgres-data. |
mailhog | 1025 (SMTP), 8025 (Web UI) | Catches all outbound email sent by the service (verification links, password-reset links) and displays them in a browser UI. No emails are actually delivered. |
redpanda | 9092 | Kafka-compatible message broker. Provisioned now so the docker-compose.yml does not need changes when Epic 6 (Transactional Outbox) lands. Not consumed by the service yet. |
pg_isready) that retries up to 10 times at 5-second intervals, so dependent services wait for a genuinely ready database before starting.
The interactive API documentation is available at http://localhost:8080/swagger-ui.html once the service is running. All endpoints are listed there with their request/response schemas and can be called directly from the browser.
Open http://localhost:8025 in your browser to access the MailHog web UI. Every verification email and password-reset email sent during local development appears here — no real inbox needed. The SMTP port
1025 maps to the MAIL_HOST=localhost / MAIL_PORT=1025 values in .env.example.