Local Development Setup Guide for Digital Money House

Digital Money House is a Java 21 Spring Boot microservices backend that orchestrates authentication, user management, and account operations behind a single API Gateway. The fastest way to run the full stack locally is with Docker Compose, which handles building all service images, wiring up MySQL, RabbitMQ, and Eureka, and exposing each service on its designated port — no manual database setup or service registration required.

Prerequisites

Before you begin, make sure the following are installed and available on your machine:

Requirement	Minimum version	Notes
Docker	24+	Required to build and run all service containers
Docker Compose	v2 (bundled with Docker Desktop)	Uses the `docker compose` or `docker-compose` CLI
Git	Any recent version	For cloning the repository
Java 21	21 (OpenJDK)	Optional — only needed if running services outside Docker
Available RAM	4 GB minimum	All eight containers combined use up to ~5.5 GB

On macOS and Windows, Docker Desktop ships with Docker Compose v2 out of the box. On Linux, install the docker-compose-plugin package alongside Docker Engine.

Step-by-step setup

Clone the repository

Clone the backend repository and change into the project directory:

git clone https://github.com/Gianluca-X/DigitalMoney.git
cd DigitalMoney

Create the .env file

Docker Compose reads credentials and connection strings from a .env file in the repository root. Copy the template below into a new file called .env and update the passwords before proceeding.

# MySQL root credentials
MYSQL_ROOT_PASSWORD=root
MYSQL_PASSWORD=nerea

# Auth Service DB
AUTH_DB_URL=jdbc:mysql://mysql:3306/auth_service_db
AUTH_DB_USERNAME=auth_service_user
AUTH_DB_DATABASE=auth_service_db

# User Service DB
USER_DB_URL=jdbc:mysql://mysql:3306/user_service_db
USER_DB_USERNAME=user_service_user
USER_DB_DATABASE=user_service_db

# Account Service DB
ACCOUNT_DB_URL=jdbc:mysql://mysql:3306/account_service_db
ACCOUNT_DB_USERNAME=account_service_user
ACCOUNT_DB_DATABASE=account_service_db

# Eureka
EUREKA_CLIENT_SERVICEURL_DEFAULTZONE=http://eureka-server:8761/eureka/

# Spring Profiles
SPRING_PROFILES_ACTIVE=dev

# JWT
JWT_SECRET=mySuperUltraSecretKeyForJWTGeneration123456!

The values above match the defaults in the sample .env committed to the repository. Change MYSQL_ROOT_PASSWORD and JWT_SECRET to unique secrets before starting the stack — even for local development, using the defaults is a security risk if the ports are ever exposed.

Note that the JDBC URLs use mysql (the Docker service hostname) rather than localhost. Docker Compose resolves inter-container hostnames on the shared back_network bridge network.

Start MySQL and Eureka first

The application services all depend on MySQL being healthy before they start. Bring up MySQL and Eureka Server in detached mode so that their health checks complete before the rest of the stack starts:

docker-compose up mysql eureka-server -d

Wait until you see MySQL report ready for connections in the logs:

docker-compose logs -f mysql

The MySQL healthcheck polls mysqladmin ping every 30 seconds with up to 5 retries. Once the container is healthy, the dependent services will be allowed to start. The init.sql file at the repository root is automatically executed on first run, creating the three service databases and their dedicated users.

Start all remaining services

With MySQL healthy, start the full stack:

docker-compose up

To run everything in the background instead:

docker-compose up -d

Docker Compose will build each service image from source (this takes a few minutes on first run), then start them in dependency order. You can monitor startup progress with:

docker-compose logs -f

Verify all services are running

Once the stack is up, confirm that every service has registered successfully.Eureka Dashboard — open in your browser to see all registered service instances:

http://localhost:8761

You should see AUTH-SERVICE, USER-SERVICE, ACCOUNTS-SERVICE, and GATEWAY-SERVICE listed as UP.Gateway health endpoint — confirms the gateway is live and can route requests:

curl http://localhost:8085/actuator/health

Expected response:

{ "status": "UP" }

RabbitMQ Management UI — for inspecting message queues:

http://localhost:15672

Service startup order

Docker Compose respects the depends_on conditions declared in docker-compose.yml. The effective startup sequence is:

MySQL ──► RabbitMQ
    │
    └──► Eureka Server
              │
              ├──► Auth Service
              │
              └──► Config Server
                        │
              ┌─────────┴─────────┐
              │                   │
         User Service       Accounts Service
              │                   │
              └─────────┬────────►Gateway

Services that depend on mysql with condition: service_healthy will not start until the MySQL healthcheck passes. Services that depend on eureka-server and config-server use condition: service_started, meaning they start as soon as those containers are running — Spring Cloud’s retry logic handles any brief unavailability during initial registration.

Accessing services after startup

Service	URL	Notes
API Gateway	`http://localhost:8085`	Entry point for all client requests
Eureka Server	`http://localhost:8761`	Service registry dashboard
Config Server	`http://localhost:8888`	Spring Cloud Config endpoint
Auth Service	`http://localhost:8082`	Direct access (normally via Gateway)
User Service	`http://localhost:8087`	Direct access (normally via Gateway)
Accounts Service	`http://localhost:8084`	Direct access (normally via Gateway)
RabbitMQ UI	`http://localhost:15672`	Management console (`guest`/`guest`)
MySQL	`localhost:3308`	Mapped from container port 3306

The Gateway routes /auth/** to the Auth Service, /users/** to the User Service, and /accounts/** to the Accounts Service. For day-to-day API testing, send all requests through http://localhost:8085 rather than hitting individual service ports.

Troubleshooting

Services not registering with Eureka

If one or more services are missing from the Eureka dashboard at http://localhost:8761, check the following:

Eureka is fully started — the dependent services use condition: service_started, which only waits for the container process to begin, not for Eureka to finish booting. Give the server 30–60 seconds, then check again.
EUREKA_CLIENT_SERVICEURL_DEFAULTZONE is set correctly — the value in your .env file must use the Docker service hostname eureka-server, not localhost:
```
EUREKA_CLIENT_SERVICEURL_DEFAULTZONE=http://eureka-server:8761/eureka/
```
Inspect service logs for Cannot execute request on any known server errors:
```
docker-compose logs -f auth-service
```
Spring Cloud will retry registration automatically, but if the hostname is wrong the service will never register.
Network connectivity — all services must be on the shared back_network. If you edited docker-compose.yml, confirm no service is missing the networks: - back_network entry.

Database connection refused

If a service logs Communications link failure or Connection refused on startup, MySQL may not be fully healthy yet.

Check MySQL health status:
```
docker inspect --format='{{json .State.Health}}' mysql
```
Wait until Status is "healthy" before the application services start.
Verify init.sql ran successfully — the script creates all three databases and their users. If MySQL data is already present from a previous run and the script did not re-execute, the databases should already exist. To force a clean reinitialisation, remove the named volume:
```
docker-compose down -v
docker-compose up mysql -d
```
Confirm JDBC URLs use container hostnames — datasource URLs must reference mysql (the service name), not localhost:
```
AUTH_DB_URL=jdbc:mysql://mysql:3306/auth_service_db
```
Port conflict on 3308 — MySQL is mapped to host port 3308 (not the default 3306) to avoid conflicts with a locally installed MySQL instance. If port 3308 is already in use, update the ports mapping in docker-compose.yml.

JWT validation failing

If requests through the Gateway return 401 Unauthorized even with a valid token, the JWT secret is likely out of sync across services.

All three services must share the same secret — auth-service, accounts-service, and gateway each read JWT_SECRET from the environment. Confirm the variable is set identically in .env:
```
JWT_SECRET=mySuperUltraSecretKeyForJWTGeneration123456!
```
Secret length — the HS256 algorithm requires a secret of at least 256 bits (32 characters). Shorter secrets will cause key initialisation failures at startup.
Inspect the Gateway logs for token parsing errors:
```
docker-compose logs -f gateway
```
Look for SignatureException or MalformedJwtException messages.
Token expiry — the Auth Service issues tokens with a 24-hour expiry (86400000 ms). If the system clock on your Docker host is incorrect, tokens may appear expired immediately. Verify with:
```
docker run --rm alpine date
```

Get Started

Services

Deployment

Security & Reliability

Local Development Setup Guide for Digital Money House

Prerequisites

Step-by-step setup

Service startup order

Accessing services after startup

Troubleshooting

Build docs developers (and LLMs) love

Get Started

Services

Deployment

Security & Reliability

Documentation Index

​Prerequisites

​Step-by-step setup

​Service startup order

​Accessing services after startup

​Troubleshooting

Build docs developers (and LLMs) love

Prerequisites

Step-by-step setup

Service startup order

Accessing services after startup

Troubleshooting