Setting Up the Development Environment for Enterprise Spring Boot Microservices

Table of Contents

• 1. Introduction: The Modern Inner Development Loop
• 2. What You Will Learn
• 3. System Prerequisites & Hardware Requirements
• 4. Local Microservices Architecture Blueprint
• 5. Choosing & Tuning the JDK (Java 17 vs. Java 21)
• 6. Build Tool Orchestration: Maven vs. Gradle in Enterprise Monorepos
• 7. Infrastructure Orchestration via Docker Compose
• 8. Deep Dive: Spring Boot 3.x Docker Compose Integration
• 9. IDE Optimization & Hot Swapping (IntelliJ & VS Code)
• 10. Step-by-Step Enterprise Project Initialization
• 11. Environment Parity, Profiles, and Local Secret Management
• 12. Common Dev Environment Pitfalls & Anti-Patterns
• 13. Troubleshooting & Debugging Port Conflicts and Memory Leaks
• 14. Local Observability: Actuator, Prometheus, and Grafana
• 15. Technical Interview Questions & Answers
• 16. Frequently Asked Questions (FAQs)
• 17. Summary & Next Steps

1. Introduction: The Modern Inner Development Loop

In enterprise software engineering, the "Inner Loop" represents the iterative process of writing, compiling, running, and debugging code before committing it to version control. When building distributed systems with Spring Boot, Spring Cloud, and Apache Kafka, the inner loop can rapidly degrade. Developers often face slow build times, port conflicts, configuration drift, and "works on my machine" syndrome due to discrepancies between local environments and production Kubernetes clusters.

Historically, setting up a microservices development environment meant manually installing databases, message brokers, and caching layers directly onto the host operating system. This approach is brittle, non-reproducible, and fails to scale as engineering teams grow.

A modern, enterprise-grade development environment treats local infrastructure as code. By leveraging containerization, advanced JVM ergonomics, and Spring Boot 3.x's native integration with Docker Compose and Testcontainers, we can establish a deterministic, isolated, and highly productive development workspace. This guide provides the blueprint for setting up such an environment from scratch.

2. What You Will Learn

By completing this comprehensive guide, you will master:

• Installing and tuning Java 21 (LTS) with optimal garbage collection and memory flags for local microservice development.
• Configuring an enterprise-grade Maven multi-module structure with optimized caching and dependency management.
• Writing a production-ready docker-compose.yml that orchestrates PostgreSQL, Apache Kafka (KRaft mode), and Redis.
• Utilizing Spring Boot 3.x's Docker Compose integration to automatically discover and wire containerized services without manual profile switching.
• Tuning IntelliJ IDEA and VS Code JVM heap parameters and hot-swapping configurations to achieve sub-second code-reload times.
• Designing a secure local environment that leverages environment variables and prevents secret leakage into git repositories.
• Setting up local observability using Spring Boot Actuator, Prometheus, and Grafana to debug performance issues before deployment.

3. System Prerequisites & Hardware Requirements

Developing distributed systems locally is resource-intensive. To run multiple JVM instances alongside Kafka, databases, and monitoring tools, your workstation must meet or exceed the following specifications:

4. Local Microservices Architecture Blueprint

To ensure fast feedback loops, we isolate the host operating system from the backing services. The Spring Boot application runs directly on the host JVM (for rapid debugging and hot-swapping), while all external dependencies (PostgreSQL, Kafka, Redis) run inside isolated Docker containers.

The diagram below illustrates the network and execution boundary of your local development environment:

+-------------------------------------------------------------------------------------------------+
|                                         HOST MACHINE                                            |
|                                                                                                 |
|  +-----------------------------------+               +---------------------------------------+  |
|  |       IDE (IntelliJ / VS Code)    |               |         Spring Boot Application       |  |
|  |                                   |               |                                       |  |
|  |  * Direct Debugger Attachment     |<------------> |  * Port: 8080                         |  |
|  |  * Hot Swap/Compilation Agent     |  Port: 5005   |  * Virtual Threads Enabled (Java 21)  |  |
|  +-----------------------------------+               +---------------------------------------+  |
|                                                                  |                              |
|                                                                  | Dynamic Configuration        |
|                                                                  | (Auto-discovered by Boot)    |
|                                                                  v                              |
|=================================================================================================|
|                                    DOCKER CONTAINER NETWORK                                     |
|                                                                                                 |
|    +------------------------+    +--------------------------+    +-------------------------+    |
|    |     PostgreSQL DB      |    |       Apache Kafka       |    |       Redis Cache       |    |
|    |                        |    |       (KRaft Mode)       |    |                         |    |
|    |  * Port: 5432          |    |  * Port: 9092            |    |  * Port: 6379           |    |
|    |  * Vol: pg_data        |    |  * Vol: kafka_data       |    |  * Vol: redis_data      |    |
|    +------------------------+    +--------------------------+    +-------------------------+    |
|                                                                                                 |
+-------------------------------------------------------------------------------------------------+
    

By keeping the JVM on the host and databases in Docker, we avoid the overhead of running a full Kubernetes cluster (like Minikube or Kind) locally, while still maintaining identical network and service layers.

5. Choosing & Tuning the JDK (Java 17 vs. Java 21)

For modern Spring Boot 3.x microservices, Java 21 (LTS) is the industry standard. Java 21 introduces Virtual Threads (Project Loom), which fundamentally change how Spring Boot processes concurrent web requests. Instead of dedicating a heavy operating system thread per request (the classic servlet model), Spring Boot 3.x can map millions of concurrent requests to lightweight virtual threads, drastically reducing memory consumption under load.

Additionally, Java 21 introduces the Generational Z Garbage Collector (Generational ZGC). Generational ZGC reduces GC pause times to under a millisecond, which is critical for low-latency distributed systems.

Recommended JDK Distribution

We recommend using Eclipse Temurin (by Adoptium) or Liberica JDK (by BellSoft). Liberica JDK is the default runtime for Spring Cloud and buildpacks, offering excellent cloud-native optimizations.

To manage multiple JDK versions on your workstation without corrupting system paths, use SDKMAN!:

# Install SDKMAN!
curl -s "https://get.sdkman.io" | bash
source "$HOME/.sdkman/bin/sdkman-init.sh"

# Install Java 21 Eclipse Temurin
sdk install java 21.0.2-tem

# Set Java 21 as default
sdk default java 21.0.2-tem
    

JVM Flag Tuning for Local Development

In a production environment, you allocate maximum resources to a single JVM. Locally, you might run 5 to 10 microservices simultaneously. If each JVM claims 2 GB of RAM, your system will quickly swap to disk. We must tune the JVM to minimize its footprint without sacrificing compilation speed.

Add the following JVM global options to your IDE run configurations or your .bashrc/.zshrc:

export JAVA_OPTS="-XX:+UseG1GC \
                  -XX:MaxRAMPercentage=50.0 \
                  -XX:InitialRAMPercentage=25.0 \
                  -XX:TieredStopAtLevel=1 \
                  -Dspring.devtools.restart.enabled=true \
                  -Dspring.backgroundpreinitializer.ignore=true"
    

Why these flags?

• -XX:TieredStopAtLevel=1: Limits the HotSpot dynamic compiler to C1 (Level 1) compilation. This drastically reduces the startup time of your Spring Boot application during development by avoiding heavy C2 optimizations that are only useful for long-running production processes.
• -XX:MaxRAMPercentage=50.0: Ensures that the JVM scales dynamically based on your system's available memory, preventing hard-coded memory allocation failures.
• -Dspring.backgroundpreinitializer.ignore=true: Disables background initialization of certain Spring libraries during startup, saving precious milliseconds on local restarts.

6. Build Tool Orchestration: Maven vs. Gradle in Enterprise Monorepos

Choosing between Maven and Gradle depends on your organization's standards. Maven offers strict structure and predictability, while Gradle provides highly optimized build caches and faster execution times for massive multi-module projects.

For enterprise microservices, a Multi-Module project layout is highly recommended. This allows shared domain libraries, security configurations, and API contracts to reside in the same repository, ensuring strict type-safety across service boundaries.

Production-Grade Maven pom.xml Configuration

Below is an optimized, enterprise-grade root pom.xml. It utilizes the Spring Cloud Bill of Materials (BOM) to guarantee dependency compatibility and configures the Maven Compiler Plugin for Java 21.

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" 
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
    
    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>3.2.4</version>
        <relativePath/> <!-- lookup parent from repository -->
    </parent>

    <groupId>com.enterprise.microservices</groupId>
    <artifactId>microservices-parent</artifactId>
    <version>1.0.0-SNAPSHOT</version>
    <packaging>pom</packaging>
    <name>microservices-parent</name>
    <description>Enterprise Microservices Parent POM</description>

    <properties>
        <java.version>21</java.version>
        <spring-cloud.version>2023.0.0</spring-cloud.version>
        <org.mapstruct.version>1.5.5.Final</org.mapstruct.version>
        <lombok-mapstruct-binding.version>0.2.0</lombok-mapstruct-binding.version>
    </properties>

    <dependencyManagement>
        <dependencies>
            <dependency>
                <groupId>org.springframework.cloud</groupId>
                <artifactId>spring-cloud-dependencies</artifactId>
                <version>${spring-cloud.version}</version>
                <type>pom</type>
                <scope>import</scope>
            </dependency>
        </dependencies>
    </dependencyManagement>

    <dependencies>
        <!-- Global developer dependencies -->
        <dependency>
            <groupId>org.projectlombok</groupId>
            <artifactId>lombok</artifactId>
            <optional>true</optional>
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-configuration-processor</artifactId>
            <optional>true</optional>
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-devtools</artifactId>
            <scope>runtime</scope>
            <optional>true</optional>
        </dependency>
    </dependencies>

    <build>
        <plugins>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-compiler-plugin</artifactId>
                <configuration>
                    <source>${java.version}</source>
                    <target>${java.version}</target>
                    <annotationProcessorPaths>
                        <path>
                            <groupId>org.projectlombok</groupId>
                            <artifactId>lombok</artifactId>
                            <version>${lombok.version}</version>
                        </path>
                        <path>
                            <groupId>org.mapstruct</groupId>
                            <artifactId>mapstruct-processor</artifactId>
                            <version>${org.mapstruct.version}</version>
                        </path>
                        <path>
                            <groupId>org.projectlombok</groupId>
                            <artifactId>lombok-mapstruct-binding</artifactId>
                            <version>${lombok-mapstruct-binding.version}</version>
                        </path>
                    </annotationProcessorPaths>
                </configuration>
            </plugin>
        </plugins>
    </build>
</project>
    

Speeding Up Local Maven Builds

By default, Maven processes projects sequentially. In multi-core systems, this is highly inefficient. You can instruct Maven to run parallel builds using the following command:

# Build using 1 thread per available CPU core
mvn clean install -T 1C -DskipTests
    

Additionally, configure a local dependency proxy (such as Sonatype Nexus or JFrog Artifactory) inside your ~/.m2/settings.xml if your corporate network restricts direct access to Maven Central. This prevents build failures due to external network flakiness.

7. Infrastructure Orchestration via Docker Compose

To build resilient microservices, we must develop against the exact same infrastructure used in production. Mocking databases or using in-memory alternatives (like H2 for SQL or embedded Kafka) is an anti-pattern. Embedded databases do not support enterprise dialect-specific features (such as PostgreSQL JSONB operators or window functions) and hide performance and serialization issues that only manifest in real databases.

The following docker-compose.yml file provisions a high-performance local environment containing:

• PostgreSQL 16: Configured with custom memory limits for local execution.
• Apache Kafka (KRaft Mode): Utilizing Confluent's official image without the overhead of ZooKeeper.
• Redis 7: For distributed caching and session storage.

version: '3.8'

services:
  postgres:
    image: postgres:16-alpine
    container_name: local-postgres
    ports:
      - "5432:5432"
    environment:
      POSTGRES_DB: enterprise_db
      POSTGRES_USER: dev_user
      POSTGRES_PASSWORD: dev_password
    volumes:
      - pg_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U dev_user -d enterprise_db"]
      interval: 5s
      timeout: 5s
      retries: 5

  kafka:
    image: confluentinc/cp-kafka:7.5.0
    container_name: local-kafka
    ports:
      - "9092:9092"
    environment:
      KAFKA_NODE_ID: 1
      KAFKA_LISTENER_SECURITY_PROTOCOL_MAP: 'CONTROLLER:PLAINTEXT,PLAINTEXT:PLAINTEXT,PLAINTEXT_HOST:PLAINTEXT'
      KAFKA_ADVERTISED_LISTENERS: 'PLAINTEXT://kafka:29092,PLAINTEXT_HOST://localhost:9092'
      KAFKA_OFFSETS_TOPIC_REPLICATION_FACTOR: 1
      KAFKA_GROUP_INITIAL_REBALANCE_DELAY_MS: 0
      KAFKA_TRANSACTION_STATE_LOG_MIN_ISR: 1
      KAFKA_TRANSACTION_STATE_LOG_REPLICATION_FACTOR: 1
      KAFKA_PROCESS_ROLES: 'broker,controller'
      KAFKA_CONTROLLER_QUORUM_VOTERS: '1@kafka:29093'
      KAFKA_LISTENERS: 'PLAINTEXT://0.0.0.0:29092,CONTROLLER://0.0.0.0:29093,PLAINTEXT_HOST://0.0.0.0:9092'
      KAFKA_INTER_BROKER_LISTENER_NAME: 'PLAINTEXT'
      KAFKA_CONTROLLER_LISTENER_NAMES: 'CONTROLLER'
      KAFKA_LOG_DIRS: '/tmp/kraft-combined-logs'
      CLUSTER_ID: 'MkU3OEVBNTcwNTJENDM2Qk'
    volumes:
      - kafka_data:/var/lib/kafka/data
    healthcheck:
      test: ["CMD-SHELL", "kafka-topics.sh --bootstrap-server localhost:9092 --list"]
      interval: 10s
      timeout: 5s
      retries: 5

  redis:
    image: redis:7-alpine
    container_name: local-redis
    ports:
      - "6379:6379"
    volumes:
      - redis_data:/data
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 5s
      timeout: 3s
      retries: 5

volumes:
  pg_data:
    driver: local
  kafka_data:
    driver: local
  redis_data:
    driver: local
    

Critical Kafka KRaft Configuration Explained

Notice the KAFKA_ADVERTISED_LISTENERS configuration. This is the single most common source of local connection errors.

• PLAINTEXT://kafka:29092: Used for container-to-container communication inside the Docker network. If you deploy another microservice as a Docker container, it will connect via this port.
• PLAINTEXT_HOST://localhost:9092: Used by your Spring Boot application running directly on your host machine. The broker advertises localhost to the host client, allowing seamless metadata exchanges.

8. Deep Dive: Spring Boot 3.x Docker Compose Integration

One of the most powerful features introduced in Spring Boot 3.1 is the ConnectionDetails abstraction and native integration with Docker Compose. This completely eliminates the need to maintain separate local profiles with hardcoded database credentials and port mappings.

How it Works

When your Spring Boot application starts up in development mode, it searches your project directory for a docker-compose.yml file. If found, it automatically:

1. Runs docker compose up to start the configured containers.
2. Inspects the running containers' dynamic ports and statuses.
3. Generates ConnectionDetails beans behind the scenes, overriding properties like spring.datasource.url, spring.kafka.bootstrap-servers, and spring.data.redis.host automatically.

Implementation Steps

First, add the required dependency to your microservice's pom.xml:

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-docker-compose</artifactId>
    <optional>true</optional>
</dependency>
    

Next, configure the behavior in your application.yml file:

spring:
  docker:
    compose:
      enabled: true
      file: ./docker-compose.yml
      lifecycle-management: start-and-keep-alive
      readiness:
        tcp:
          connect-timeout: 5s
          read-timeout: 5s
    

The lifecycle-management: start-and-keep-alive configuration is critical for developer productivity. It ensures that when you stop your Spring Boot application to make a code change, the database and Kafka containers remain running. This avoids the overhead of restarting heavy containers on every code change, keeping your development loop extremely fast.

9. IDE Optimization & Hot Swapping (IntelliJ & VS Code)

Your IDE is your primary interface. If it is sluggish, your productivity suffers. Out-of-the-box configurations for both IntelliJ IDEA and VS Code are tailored for general-purpose development, not heavy, multi-module Spring Boot environments.

IntelliJ IDEA Configuration Tuning

Locate your IntelliJ VM Options file (Help -> Edit Custom VM Options) and replace it with the following high-performance configuration:

# Increase heap size to prevent GC thrashing on large projects
-Xms2g
-Xmx4g
-XX:ReservedCodeCacheSize=512m

# Use modern G1 Garbage Collector for IDE responsiveness
-XX:+UseG1GC
-XX:SoftRefLRUPolicyMSPerMB=50

# Enable compiler parallelization
-Dcompiler.process.number.of.cores=4
-Dkotlin.incremental.compilation=true
    

Enabling Automatic Compilation & Hot Swap

To achieve instant feedback, you must configure your IDE to compile code changes in the background and hot-swap them into the running JVM.

1. Go to Settings -> Build, Execution, Deployment -> Compiler and check "Build project automatically".
2. Go to Settings -> Advanced Settings and check "Allow auto-make to start even if developed application is currently running".
3. Ensure Spring Boot DevTools is on the classpath. Now, whenever you save a file (Ctrl+S or Cmd+S), IntelliJ compiles the class, and DevTools reloads only the modified classloader, reducing restart times to less than a second.

VS Code Configuration

If you are using VS Code, install the Extension Pack for Java and the Spring Boot Extension Pack. Add the following settings to your global settings.json:

{
    "java.jdt.ls.vmargs": "-XX:+UseG1GC -XX:MaxRAMPercentage=60.0 -Xmx3G",
    "java.autobuild.enabled": true,
    "spring-boot.ls.java.home": "/home/user/.sdkman/candidates/java/current",
    "java.configuration.updateBuildConfiguration": "automatic"
}
    

10. Step-by-Step Enterprise Project Initialization

Let's build a clean, production-ready directory structure that supports domain isolation (Hexagonal / Clean Architecture). We will create a sample service named order-service.

Directory Structure Layout

microservices-root/
│
├── docker-compose.yml
├── pom.xml
│
└── order-service/
    ├── pom.xml
    └── src/
        └── main/
            ├── java/
            │   └── com/
            │       └── enterprise/
            │           └── order/
            │               ├── OrderServiceApplication.java
            │               ├── config/
            │               │   ├── SecurityConfig.java
            │               │   └── ThreadPoolConfig.java
            │               ├── domain/
            │               │   ├── model/
            │               │   └── ports/
            │               └── infrastructure/
            │                   ├── adapters/
            │                   └── messaging/
            │                       └── KafkaOrderProducer.java
            └── resources/
                ├── application.yml
                └── application-local.yml
    

Step 1: Write the Spring Boot Application Entrypoint

This class initializes the context. Notice the @EnableAsync annotation, which we will use to leverage Virtual Threads.

package com.enterprise.order;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.scheduling.annotation.EnableAsync;

@SpringBootApplication
@EnableAsync
public class OrderServiceApplication {
    public static void main(String[] args) {
        SpringApplication.run(OrderServiceApplication.class, args);
    }
}
    

Step 2: Enable Virtual Threads in Configuration

To process HTTP requests and asynchronous tasks using Project Loom's virtual threads, we configure our thread pools. Since Spring Boot 3.2, enabling virtual threads for TomCat and Task Execution is a single property toggle.

package com.enterprise.order.config;

import org.springframework.boot.autoconfigure.task.TaskExecutionAutoConfiguration;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.core.task.AsyncTaskExecutor;
import org.springframework.core.task.support.TaskExecutorAdapter;
import java.util.concurrent.Executors;

@Configuration
public class ThreadPoolConfig {

    @Bean(TaskExecutionAutoConfiguration.APPLICATION_TASK_EXECUTOR_BEAN_NAME)
    public AsyncTaskExecutor asyncTaskExecutor() {
        // Map Spring's async task executor directly to JVM Virtual Threads
        return new TaskExecutorAdapter(Executors.newVirtualThreadPerTaskFactory());
    }
}
    

Step 3: Define the application.yml

Our configuration leverages environment variables with safe fallbacks, ensuring seamless transition between your local machine and Kubernetes.

spring:
  application:
    name: order-service
  
  # Enable Virtual Threads in Spring Boot 3.2+
  threads:
    virtual:
      enabled: true

  datasource:
    url: ${SPRING_DATASOURCE_URL:jdbc:postgresql://localhost:5432/enterprise_db}
    username: ${SPRING_DATASOURCE_USERNAME:dev_user}
    password: ${SPRING_DATASOURCE_PASSWORD:dev_password}
    driver-class-name: org.postgresql.Driver
    hikari:
      maximum-pool-size: 10
      minimum-idle: 2
      idle-timeout: 30000
      pool-name: OrderServiceHikariCP

  kafka:
    bootstrap-servers: ${SPRING_KAFKA_BOOTSTRAP_SERVERS:localhost:9092}
    consumer:
      group-id: order-group
      auto-offset-reset: earliest
      key-deserializer: org.apache.kafka.common.serialization.StringDeserializer
      value-deserializer: org.apache.kafka.common.serialization.StringDeserializer
    producer:
      key-serializer: org.apache.kafka.common.serialization.StringSerializer
      value-serializer: org.apache.kafka.common.serialization.StringSerializer
      acks: all

server:
  port: 8081
  tomcat:
    threads:
      max: 200 # Virtual threads make this highly efficient
    

11. Environment Parity, Profiles, and Local Secret Management

A major security vulnerability in microservice architectures is committing API keys, database passwords, or private keys to source control. Your local environment must enforce strict separation between configuration structure and sensitive values.

The Twelve-Factor App Principle

According to the Twelve-Factor App methodology, configuration must be stored in the environment, not in the code. We achieve this by using Spring placeholders that resolve environment variables at runtime.

Using Local .env Files

Rather than hardcoding credentials in application-local.yml, use a .env file at the root of your project. This file is added to your .gitignore and never committed.

# .env file - DO NOT COMMIT TO GIT
SPRING_DATASOURCE_USERNAME=prod_equivalent_dev_user
SPRING_DATASOURCE_PASSWORD=super_secret_local_password_99!
STRIPE_API_KEY=sk_test_51Nz...
JWT_SIGNING_KEY=404E635266556A586E3272357538782F413F4428472B4B6250645367566B5970
    

To load these variables into your Spring Boot application during local IDE runs, install the EnvFile plugin in IntelliJ, or configure VS Code's launch.json to read the .env file:

{
    "version": "0.2.0",
    "configurations": [
        {
            "type": "java",
            "name": "OrderServiceApplication",
            "request": "launch",
            "mainClass": "com.enterprise.order.OrderServiceApplication",
            "envFile": "${workspaceFolder}/.env"
        }
    ]
}
    

12. Common Dev Environment Pitfalls & Anti-Patterns

Avoid these common mistakes to maintain a highly performant and stable development environment:

• Anti-Pattern: Hardcoded Localhost IP Addresses
  Consequence: If your code contains localhost:5432 directly, it will fail when containerized or run inside a CI/CD pipeline. Always use Spring property placeholders with fallbacks.
• Anti-Pattern: Running Docker Containers Without Health Checks
  Consequence: Your Spring Boot application may start faster than the PostgreSQL container can initialize, resulting in immediate connection failures on startup. Always define explicit healthcheck parameters in your docker-compose.yml.
• Anti-Pattern: Committing the Target Directory or IDE Metadata
  Consequence: Merge conflicts and polluted code repositories. Ensure your global .gitignore includes .idea/, .vscode/, target/, .gradle/, and .env.
• Anti-Pattern: Shared Development Databases
  Consequence: When multiple developers share a single remote development database, schema migrations run by one developer will break the local environment of another. Every developer must run an isolated local database instance via Docker.

13. Troubleshooting & Debugging Port Conflicts and Memory Leaks

When running multiple microservices locally, errors are inevitable. Here is how to diagnose and resolve the most common environmental issues.

Issue 1: Port Already in Use (java.net.BindException: Address already in use)

This occurs when another process is already listening on your microservice's configured port (e.g., 8080 or 5432).

Diagnosis (Linux/macOS):

# Find the Process ID (PID) using port 8080
lsof -i :8080

# Kill the offending process
kill -9 <PID>
    

Diagnosis (Windows PowerShell):

# Find the PID using port 8080
Get-NetTCPConnection -LocalPort 8080 | Format-List

# Kill the process
Stop-Process -Id <PID> -Force
    

Issue 2: Docker Container Fails to Start Due to Port Conflict

If you have a local PostgreSQL service installed directly on your host OS running in the background, your Docker PostgreSQL container will fail to bind to port 5432.

Solution:

Stop the host service or change the external port mapping in your docker-compose.yml:

ports:
  - "5433:5432" # Map host port 5433 to container port 5432
    

Issue 3: Out of Memory Errors (java.lang.OutOfMemoryError: Java heap space)

This occurs when the JVM has exhausted its allocated heap memory.

Solution:

1. Generate a heap dump on OOM to analyze the leak: -XX:+HeapDumpOnOutOfMemoryError -XX:HeapDumpPath=/tmp/dumps/.
2. Analyze the dump using Eclipse Memory Analyzer (MAT) or IntelliJ's built-in profiler.
3. If the memory consumption is legitimate due to processing large datasets, increase the max heap size: -Xmx2g.

14. Local Observability: Actuator, Prometheus, and Grafana

Observability should not be treated as a production-only concern. Enterprise engineering teams monitor applications locally to detect

<dependency>
    <groupId>io.micrometer</groupId>
    <artifactId>micrometer-tracing-bridge-otel</artifactId>
</dependency>

<dependency>
    <groupId>io.opentelemetry</groupId>
    <artifactId>opentelemetry-exporter-zipkin</artifactId>
</dependency>
    

management:
  tracing:
    sampling:
      probability: 1.0

  zipkin:
    tracing:
      endpoint: http://localhost:9411/api/v2/spans
    

zipkin:
  image: openzipkin/zipkin
  container_name: local-zipkin

  ports:
    - "9411:9411"
    

http://localhost:9411
    

logging:
  pattern:
    console: >
      {"timestamp":"%d",
      "level":"%p",
      "service":"${spring.application.name}",
      "trace":"%X{traceId}",
      "span":"%X{spanId}",
      "thread":"%t",
      "logger":"%c",
      "message":"%m"}%n
    

<dependency>
    <groupId>org.testcontainers</groupId>
    <artifactId>junit-jupiter</artifactId>
    <scope>test</scope>
</dependency>

<dependency>
    <groupId>org.testcontainers</groupId>
    <artifactId>postgresql</artifactId>
    <scope>test</scope>
</dependency>
    

@Testcontainers
@SpringBootTest
class OrderServiceIntegrationTest {

    @Container
    static PostgreSQLContainer<?> postgres =
            new PostgreSQLContainer<>("postgres:16");

    @DynamicPropertySource
    static void configureProperties(DynamicPropertyRegistry registry) {

        registry.add(
            "spring.datasource.url",
            postgres::getJdbcUrl
        );

        registry.add(
            "spring.datasource.username",
            postgres::getUsername
        );

        registry.add(
            "spring.datasource.password",
            postgres::getPassword
        );
    }
}
    

In this section, we will configure:

• Spring Boot Actuator
• Micrometer Metrics
• Prometheus
• Grafana

This setup provides real-time visibility into JVM performance, HTTP traffic, thread pools, Kafka consumers, HikariCP connections, and custom business metrics.

Step 1: Add Actuator and Prometheus Dependencies

Add the following dependencies to your pom.xml.

<!-- ========================================= -->
<!-- OBSERVABILITY + MONITORING -->
<!-- ========================================= -->

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-actuator</artifactId>
</dependency>

<dependency>
    <groupId>io.micrometer</groupId>
    <artifactId>micrometer-registry-prometheus</artifactId>
</dependency>
    

Step 2: Configure application.yml

Enable Spring Boot Actuator endpoints and Prometheus metrics export.

# =========================================
# application.yml
# =========================================

management:
  endpoints:
    web:
      exposure:
        include: health,info,metrics,prometheus

  endpoint:
    health:
      show-details: always

  metrics:
    tags:
      application: ${spring.application.name}

  prometheus:
    metrics:
      export:
        enabled: true
    

Step 3: Configure Docker Compose for Monitoring Stack

Extend your existing docker-compose.yml by adding Prometheus and Grafana services.

version: '3.8'

services:

  postgres:
    image: postgres:16-alpine
    container_name: local-postgres

    ports:
      - "5432:5432"

    environment:
      POSTGRES_DB: enterprise_db
      POSTGRES_USER: dev_user
      POSTGRES_PASSWORD: dev_password

    volumes:
      - pg_data:/var/lib/postgresql/data

    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U dev_user -d enterprise_db"]
      interval: 5s
      timeout: 5s
      retries: 5

  kafka:
    image: confluentinc/cp-kafka:7.5.0
    container_name: local-kafka

    ports:
      - "9092:9092"

    environment:
      KAFKA_NODE_ID: 1
      KAFKA_LISTENER_SECURITY_PROTOCOL_MAP: 'CONTROLLER:PLAINTEXT,PLAINTEXT:PLAINTEXT,PLAINTEXT_HOST:PLAINTEXT'
      KAFKA_ADVERTISED_LISTENERS: 'PLAINTEXT://kafka:29092,PLAINTEXT_HOST://localhost:9092'
      KAFKA_OFFSETS_TOPIC_REPLICATION_FACTOR: 1
      KAFKA_GROUP_INITIAL_REBALANCE_DELAY_MS: 0
      KAFKA_TRANSACTION_STATE_LOG_MIN_ISR: 1
      KAFKA_TRANSACTION_STATE_LOG_REPLICATION_FACTOR: 1
      KAFKA_PROCESS_ROLES: 'broker,controller'
      KAFKA_CONTROLLER_QUORUM_VOTERS: '1@kafka:29093'
      KAFKA_LISTENERS: 'PLAINTEXT://0.0.0.0:29092,CONTROLLER://0.0.0.0:29093,PLAINTEXT_HOST://0.0.0.0:9092'
      KAFKA_INTER_BROKER_LISTENER_NAME: 'PLAINTEXT'
      KAFKA_CONTROLLER_LISTENER_NAMES: 'CONTROLLER'
      KAFKA_LOG_DIRS: '/tmp/kraft-combined-logs'
      CLUSTER_ID: 'MkU3OEVBNTcwNTJENDM2Qk'

    volumes:
      - kafka_data:/var/lib/kafka/data

    healthcheck:
      test: ["CMD-SHELL", "kafka-topics.sh --bootstrap-server localhost:9092 --list"]
      interval: 10s
      timeout: 5s
      retries: 5

  redis:
    image: redis:7-alpine
    container_name: local-redis

    ports:
      - "6379:6379"

    volumes:
      - redis_data:/data

    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 5s
      timeout: 3s
      retries: 5

  prometheus:
    image: prom/prometheus:latest
    container_name: local-prometheus

    ports:
      - "9090:9090"

    volumes:
      - ./monitoring/prometheus.yml:/etc/prometheus/prometheus.yml

  grafana:
    image: grafana/grafana:latest
    container_name: local-grafana

    ports:
      - "3000:3000"

    environment:
      GF_SECURITY_ADMIN_USER: admin
      GF_SECURITY_ADMIN_PASSWORD: admin

    volumes:
      - grafana_data:/var/lib/grafana

volumes:
  pg_data:
    driver: local

  kafka_data:
    driver: local

  redis_data:
    driver: local

  grafana_data:
    driver: local
    

Step 4: Create Prometheus Configuration

Create the following file:

monitoring/prometheus.yml
    

Add this configuration:

global:
  scrape_interval: 5s

scrape_configs:

  - job_name: 'order-service'

    metrics_path: '/actuator/prometheus'

    static_configs:
      - targets:
          - 'host.docker.internal:8081'
    

Step 5: Start the Monitoring Stack

Run the following command from the root project directory:

docker compose up -d
    

This starts:

• PostgreSQL
• Kafka
• Redis
• Prometheus
• Grafana

Step 6: Verify Spring Boot Metrics Endpoint

Open the following URL in your browser:

http://localhost:8081/actuator/prometheus
    

You should see raw Prometheus metrics such as:

• JVM memory usage
• HTTP request metrics
• Thread pool statistics
• HikariCP connection pool metrics
• Kafka producer metrics

Step 7: Access Grafana Dashboard

Grafana URL:

http://localhost:3000
    

Default Login Credentials:

Username: admin
Password: admin
    

Step 8: Configure Prometheus as Grafana Datasource

Inside Grafana:

1. Open Grafana
2. Navigate to Connections → Data Sources
3. Click Add data source
4. Select Prometheus

Use the following datasource URL:

http://prometheus:9090
    

Click:

Save & Test
    

Step 9: Import JVM Dashboard

Recommended Grafana Dashboard IDs:

To import:

1. Click "+" in Grafana
2. Import Dashboard
3. Enter Dashboard ID
4. Select Prometheus datasource
5. Click Import

Benefits of Local Observability

With this setup, developers can:

• Detect memory leaks early
• Monitor virtual thread behavior
• Analyze Kafka throughput
• Monitor database pool saturation
• Track HTTP latency
• Debug performance bottlenecks
• Validate scaling characteristics before deployment

This creates production-like visibility directly on the local workstation, dramatically improving debugging efficiency and system reliability.