Spring Boot Microservice

byAditi Patil -
0

 

Beginners Tutorial For Learning Spring Boot Microservice with

Docker  |  Kubernetes  |  Jenkins CI/CD  |  Swagger

Windows 10/11  |  Eclipse IDE  |  Java 21  |  MySQL

 

Tech Stack Overview

 

Layer

Technology

Version

Framework

Spring Boot

3.2.0

Language

Java

17 or 21

Database

MySQL

8.0

ORM

Spring Data JPA / Hibernate

Latest

API Docs

Swagger / OpenAPI

3.0

Container

Docker Desktop

Latest

Orchestration

Kubernetes (kubectl)

Latest

CI/CD

Jenkins

Latest

IDE

Eclipse IDE

2023+

Build Tool

Maven

3.9.x

 

 

Section 1: Install Prerequisites on Windows

 

1.1  Install Java 21

The project uses Java 17 minimum. Java 21 (LTS) is recommended and fully compatible.

 

1.    Go to https://adoptium.net

2.    Select: Version = Java 21 (LTS), OS = Windows, Arch = x64, Package = JDK

3.    Download the .msi installer and run it

4.    On the Custom Setup screen, enable all three options:

◦       Set JAVA_HOME variable

◦       Add to PATH

◦       Associate .jar files

5.    Verify installation — open Command Prompt and type:

 

java -version

javac -version

echo %JAVA_HOME%

 

Expected output:

openjdk version "21.0.9" 2025-10-21 LTS

OpenJDK Runtime Environment Zulu21.46+19-CA

javac 21.0.9

C:\Program Files\Eclipse Adoptium\jdk-21...

 

Note  Spring Boot 3.x requires minimum Java 17. It will NOT run on Java 8 or Java 11.

 

1.2  Install Maven

6.    Go to https://maven.apache.org/download.cgi

7.    Download Binary zip archive (e.g. apache-maven-3.9.x-bin.zip)

8.    Extract to C:\maven

9.    Add Environment Variables — press Windows + S, search Environment Variables:

◦       New System Variable: MAVEN_HOME = C:\maven

◦       Edit Path variable → Add: %MAVEN_HOME%\bin

10.  Open a new Command Prompt and verify:

mvn -version

Expected: Apache Maven 3.9.x ... Java version: 21

 

1.3  Enable WSL 2 (Required for Docker)

WSL 2 (Windows Subsystem for Linux) is required for Docker Desktop to run on Windows.

 

Check if WSL is already installed:

wsl --version

If you see WSL version 2.x — WSL is already installed. Skip to section 1.4.

 

Check via Windows Features (GUI method):

11.  Press Windows + R, type optionalfeatures, press Enter

12.  Look for these two items and ensure both are checked:

◦       Windows Subsystem for Linux

◦       Virtual Machine Platform

13.  If unchecked, check them and click OK, then restart PC

 

Install WSL 2 via PowerShell (if not installed):

Open PowerShell as Administrator and run each command:

# Step 1 - Enable WSL

wsl --install

 

# Step 2 - Set WSL 2 as default

wsl --set-default-version 2

 

# Step 3 - Restart PC

Restart-Computer

 

# Step 4 - Verify after restart

wsl --list --verbose

 

Verify WSL version output:

  NAME      STATE    VERSION

* Ubuntu    Running  2        <- Version 2 = WSL 2 active

 

 Note  WSL 2 requires Virtualization to be enabled in your PC BIOS. Check Task Manager > Performance > CPU > Virtualization: Enabled.

 

1.4  Install Docker Desktop

14.  Go to https://www.docker.com/products/docker-desktop

15.  Download Docker Desktop for Windows

16.  Run the installer — during setup, ensure Use WSL 2 based engine is checked

17.  After install, open Docker Desktop and wait for Engine Running status at bottom left

18.  Enable WSL 2 Integration in Docker Desktop:

◦       Click Settings (gear icon, top right)

◦       Go to General tab — check Use the WSL 2 based engine

◦       Go to Resources > WSL Integration — enable your distro (Ubuntu)

◦       Click Apply and Restart

19.  Verify Docker is working:

docker --version

docker-compose --version

docker ps

 

Tip  Docker Desktop must be running (Engine Running) before you can start MySQL or run docker commands.

 

1.5  Install Git

20.  Go to https://git-scm.com/download/win

21.  Download and run the installer with default settings

22.  Verify:

git --version

 

1.6  Install Eclipse IDE

23.  Go to https://www.eclipse.org/downloads

24.  Click Download x86_64 and run the installer

25.  Select Eclipse IDE for Enterprise Java and Web Developers

26.  Choose install location and click Install, then Launch

 

Install Spring Tools 4 Plugin:

27.  Open Eclipse

28.  Go to Help > Eclipse Marketplace

29.  Search: Spring Tools

30.  Find Spring Tools 4 and click Install

31.  Accept license > Finish > Restart Eclipse when prompted

 

Install Lombok Plugin:

Lombok is required for @Builder, @Data, @Getter annotations used in the project.

32.  Go to https://projectlombok.org/download and download lombok.jar

33.  Open Command Prompt where lombok.jar was downloaded:

java -jar lombok.jar

34.  The Lombok installer window opens — Eclipse should be auto-detected

35.  Click Install / Update

36.  If Eclipse is not detected, click Specify Location and browse to eclipse.exe

37.  Click Quit Installer and restart Eclipse

38.  Verify: Help > About Eclipse — you should see Lombok vX.X installed at the bottom

 

 

Section 2: Project Setup in Eclipse

 

2.1  Extract and Import Project

39.  Extract employee-service.zip to C:\Projects\employee-service

40.  Open Eclipse

41.  Go to File > Import

42.  Select Maven > Existing Maven Projects > click Next

43.  Click Browse and navigate to C:\Projects\employee-service

44.  You will see pom.xml checked in the list

45.  Click Finish

46.  Wait for Maven to download all dependencies (watch progress bar at bottom right)

 

Tip  If you see red errors after import, right-click the project > Maven > Update Project (Alt+F5) and check Force Update.

 

2.2  Set Java 21 in Eclipse

47.  Go to Window > Preferences

48.  Navigate to Java > Installed JREs

49.  Click Add > Standard VM > Next

50.  Click Directory and browse to your Java 21 installation:

C:\Program Files\Eclipse Adoptium\jdk-21.x.x.x-hotspot

51.  Eclipse auto-fills the JRE name and libraries

52.  Click Finish

53.  Check the checkbox next to your JDK 21 entry to make it default

54.  Click Apply and Close

 

Set Compiler Level to 21:

55.  Go to Window > Preferences > Java > Compiler

56.  Set Compiler compliance level to 21

57.  Click Apply and Close

 

Update pom.xml for Java 21:

Open pom.xml in your project and update the properties section:

<properties>

    <java.version>21</java.version>

    <maven.compiler.source>21</maven.compiler.source>

    <maven.compiler.target>21</maven.compiler.target>

</properties>

After saving pom.xml, right-click project > Maven > Update Project > OK.

 

2.3  Configure Run Settings (Environment Variables)

The Spring Boot app reads database connection details from environment variables. These must be set before running.

 

First Run — Register the App:

58.  In Project Explorer, expand: src/main/java > com.company.employee

59.  Right-click EmployeeServiceApplication.java

60.  Click Run As > Java Application

61.  The app will try to run and may fail (MySQL not started yet) — that is OK

62.  This step registers the app in Run Configurations

 

Set Environment Variables:

63.  Right-click project > Run As > Run Configurations

64.  Expand Java Application in the left panel

65.  Click EmployeeServiceApplication

66.  Click the Environment tab

67.  Click New and add each variable one by one:

 

Variable Name

Value

ENVIRONMENT

dev

DB_HOST

localhost

DB_PORT

3306

DB_NAME

employeedb

DB_USER

empuser

DB_PASS

emppassword

 

68.  Click Apply

 

Note  Do NOT click Run yet. Start MySQL first (Section 3) before running the app.

 

 

Section 3: Start MySQL Database

 

3.1  Start Docker Desktop

69.  Open Docker Desktop from Start menu

70.  Wait until you see Engine Running at the bottom left

71.  This must be running before any docker command will work

 

3.2  Start MySQL Container

Open Command Prompt and run this command (all one command — use ^ to continue on next line):

docker run -d --name employee-mysql ^

  -e MYSQL_ROOT_PASSWORD=rootpassword ^

  -e MYSQL_DATABASE=employeedb ^

  -e MYSQL_USER=empuser ^

  -e MYSQL_PASSWORD=emppassword ^

  -p 3306:3306 ^

  mysql:8.0

 

Verify MySQL is Running:

docker ps

Expected output:

CONTAINER ID   IMAGE       STATUS          PORTS

abc123         mysql:8.0   Up 30 seconds   0.0.0.0:3306->3306/tcp

 

Wait for MySQL to be Fully Ready:

MySQL takes 20-30 seconds to fully start. Check logs:

docker logs employee-mysql

Look for this line at the bottom before proceeding:

ready for connections. Version: '8.0.x'

 

Note  If you see: Error response: Conflict. The container name employee-mysql is already in use — run: docker stop employee-mysql && docker rm employee-mysql — then re-run the docker run command above.

 

 

Section 4: Run the Spring Boot Application

 

4.1  Run from Eclipse

Option A — Using Spring Boot Dashboard (Recommended):

72.  Go to Window > Show View > Other

73.  Search Boot Dashboard and open it

74.  You will see employee-service listed

75.  Click the Play (▶) button to start

 

Option B — Direct Run:

76.  Open EmployeeServiceApplication.java

77.  Right-click > Run As > Spring Boot App

 

Confirm App Started Successfully:

Look for these lines in the Eclipse Console tab at the bottom:

Tomcat started on port(s): 8080 (http)

Started EmployeeServiceApplication in 4.2 seconds

 

Tip  If you see CommunicationsException or Connection refused — MySQL is not running. Go back to Section 3 and start MySQL first.

 

4.2  Verify Everything is Running

URL

What it Shows

http://localhost:8080/actuator/health

Should return {"status":"UP"}

http://localhost:8080/swagger-ui.html

Interactive API documentation

http://localhost:8080/api/v1/employees

Employee API endpoint (GET all)

 

 

Section 5: Understanding the Architecture

 

5.1  Where is Everything Running?

Component

Where Running

Port

How Started

Spring Boot App

Your Windows PC (via Eclipse)

8080

Run As > Spring Boot App

Apache Tomcat

Embedded inside Spring Boot

8080

Auto-starts with Spring Boot

MySQL Database

Docker Container

3306

docker run mysql:8.0

Swagger UI

Served by Spring Boot

8080

Auto-available when app runs

 

Your Spring Boot app runs directly on your Windows PC using Java 21. It connects to MySQL which runs inside Docker. The built-in Tomcat web server handles all HTTP requests automatically — no separate web server installation needed.

 

5.2  What is the Embedded Web Server?

Spring Boot includes Apache Tomcat as a built-in web server. You do not need to install Tomcat separately.

 

It is included automatically through this dependency in pom.xml:

<dependency>

    <groupId>org.springframework.boot</groupId>

    <artifactId>spring-boot-starter-web</artifactId>

    <!-- This includes Tomcat web server automatically -->

</dependency>

 

When a request arrives at http://localhost:8080:

78.  Tomcat (port 8080) receives the HTTP request

79.  Routes it to the correct Controller method

80.  Controller calls Service > Repository > MySQL

81.  Data returns as JSON response via Tomcat

 

5.3  Understanding Docker Concepts

Docker Concept

Real World Analogy

In This Project

Image

Recipe / Blueprint

mysql:8.0 downloaded from Docker Hub

Container

Actual running instance

employee-mysql running on port 3306

Volume

Fridge that saves leftovers

Saves MySQL data when container restarts

Port (3306:3306)

Door number

Maps container port to your Windows port

Docker Desktop

The kitchen

Manages all containers and images

 

 

Section 6: API Endpoints

 

6.1  Available Endpoints

Method

URL

Description

POST

/api/v1/employees

Create a new employee

GET

/api/v1/employees

Get all employees

GET

/api/v1/employees/{id}

Get employee by ID

PUT

/api/v1/employees/{id}

Update employee by ID

DELETE

/api/v1/employees/{id}

Delete employee by ID

GET

/api/v1/employees/department/{dept}

Get employees by department

GET

/actuator/health

Health check (UP/DOWN status)

GET

/swagger-ui.html

Interactive Swagger UI

 

6.2  Test with Postman

Download Postman from https://www.postman.com/downloads

 

Sample JSON body for POST / PUT requests:

{

  "firstName": "John",

  "lastName": "Doe",

  "email": "john.doe@company.com",

  "department": "Engineering",

  "designation": "Developer",

  "salary": 75000

}

 

Sample Successful Response:

{

  "success": true,

  "message": "Employee created successfully",

  "data": {

    "id": 1,

    "firstName": "John",

    "lastName": "Doe",

    "email": "john.doe@company.com",

    "department": "Engineering",

    "designation": "Developer",

    "salary": 75000.0

  },

  "timestamp": "2026-03-28T15:40:00"

}

 

 

Section 7: Run Everything with Docker Compose

 

Docker Compose runs both the Spring Boot app AND MySQL together inside Docker — no need for Eclipse to keep running.

 

82.  Open Command Prompt and navigate to your project folder:

cd C:\Projects\employee-service

83.  Build and start all services:

docker-compose up --build




84.  Wait for both containers to start. You will see:

employee-service  | Started EmployeeServiceApplication in 4.2 seconds

mysql             | ready for connections

85.  Access the app in your browser:

Swagger UI   -> http://localhost:8080/swagger-ui.html

Health Check -> http://localhost:8080/actuator/health

86.  To stop everything:

docker-compose down

 

Tip  Use docker-compose up --build when you make code changes (rebuilds the image). Use docker-compose up (without --build) to start without rebuilding.

 


     


Section 8: Deploy to Kubernetes

 

8.1  Enable Kubernetes in Docker Desktop

87.  Open Docker Desktop

88.  Go to Settings > Kubernetes

89.  Check Enable Kubernetes

90.  Click Apply and Restart

91.  Wait for Kubernetes to start (green dot next to Kubernetes in bottom left)

92.  Verify:

kubectl version

kubectl get nodes

 

8.2  Deploy to Kubernetes

93.  Open Command Prompt in your project folder:

cd C:\Projects\employee-service

94.  Apply all Kubernetes config files in order:

kubectl apply -f k8s/namespace.yml

kubectl apply -f k8s/secret.yml

kubectl apply -f k8s/configmap.yml

kubectl apply -f k8s/mysql-deployment.yml

kubectl apply -f k8s/employee-deployment.yml

kubectl apply -f k8s/ingress.yml

95.  Check pods are running:

kubectl get pods -n employee-ns

96.  Check services:

kubectl get svc -n employee-ns

97.  View logs:

kubectl logs -f deployment/employee-deployment -n employee-ns

 

8.3  Kubernetes Files Explained

File

Purpose

namespace.yml

Creates isolated employee-ns namespace

secret.yml

Stores encrypted DB credentials (base64)

configmap.yml

Stores environment variables (ENVIRONMENT, DB_HOST etc.)

mysql-deployment.yml

Deploys MySQL pod + PersistentVolume + Service

employee-deployment.yml

Deploys Spring Boot app with 2 replicas + LoadBalancer + HPA

ingress.yml

Exposes app externally via domain name

 

 

Section 9: Jenkins CI/CD Pipeline

 

9.1  What the Jenkins Pipeline Does

The Jenkinsfile defines a full automated pipeline triggered when code is pushed to Git:

 

Stage

What Happens

Checkout

Pulls selected branch from GitHub

Build

Compiles Java code using Maven

Test

Runs JUnit tests, generates coverage report

Code Quality

Scans code with SonarQube

Package

Creates executable JAR file

Docker Build

Builds Docker image with your JAR

Docker Push

Pushes image to DockerHub

Deploy to K8s

Applies Kubernetes configs and rolls out new version

Health Check

Verifies pods are running successfully

 

9.2  Build with Parameters (Jenkins UI)

When you open your Jenkins job and click Build with Parameters, you will see this form:

 

Parameter

Type

Options / Example

BRANCH_NAME

Git Branch dropdown

main, develop, feature/xyz

ENVIRONMENT

Choice dropdown

dev, staging, prod

VERSION

Text input

1.0.0, 1.0.1, 2.0.0

SERVICE_NAME

Choice dropdown

employee-service

 

98.  Open your company Jenkins URL in browser

99.  Find your job (e.g. employee-service-pipeline)

100.               Click Build with Parameters in the left panel

101.               Select Branch, Environment, Version, Service Name

102.               Click Build

103.               Click the build number in Build History to monitor

104.               Click Console Output to see live logs

 

9.3  Jenkins Credentials Required

Ask your DevOps team to add these credentials in Jenkins > Manage Jenkins > Credentials:

 

Credential ID

Type

Purpose

github-credentials

Username + Password/Token

Pull code from GitHub

dockerhub-credentials

Username + Password

Push Docker image to DockerHub

kubeconfig-credentials

Secret File

Deploy to Kubernetes cluster

 

 

Section 10: Troubleshooting Common Errors

 

Error

Cause

Fix

CommunicationsException / Connection refused

MySQL not running

Start Docker Desktop then run: docker run mysql:8.0 (Section 3)

The method builder() is undefined

Lombok plugin missing

Install Lombok: java -jar lombok.jar (Section 1.6)

Cannot find symbol / Red errors in Eclipse

Maven dependencies not downloaded

Right-click project > Maven > Update Project (Alt+F5)

Port 8080 already in use

Another app using 8080

Change server.port=9090 in application.yml

Port 3306 already in use

Local MySQL running

Run: net stop MySQL in Command Prompt

wsl not recognized

WSL not installed

Run: wsl --install in PowerShell as Admin (Section 1.3)

Docker Desktop won't start

Virtualization disabled

Enable Intel VT-x or AMD-V in BIOS settings

Container name already in use

Old container exists

Run: docker stop employee-mysql && docker rm employee-mysql

EmployeeServiceApplication not in Run Configs

App never run before

Right-click the .java file > Run As > Java Application first

spring.profiles.active not working

ENVIRONMENT var not set

Add ENVIRONMENT=dev in Eclipse Run Configuration > Environment tab

 

 

Section 11: Quick Reference Cheat Sheet

 

Eclipse Shortcuts

Shortcut

Action

Ctrl + Shift + T

Find any Java class

Ctrl + Shift + R

Find any file

Ctrl + Shift + O

Organize imports (fix import errors)

Alt + Shift + R

Rename variable or method

Ctrl + /

Comment or uncomment line

F3

Go to declaration (jump to method/class)

Ctrl + F11

Run last configuration

Alt + F5

Maven Update Project

 

Docker Quick Commands

# See running containers

docker ps

 

# See all containers (including stopped)

docker ps -a

 

# Start existing MySQL container

docker start employee-mysql

 

# Stop MySQL container

docker stop employee-mysql

 

# View MySQL logs

docker logs employee-mysql

 

# Remove container

docker rm employee-mysql

 

# Run all services with Docker Compose

docker-compose up --build

 

# Stop Docker Compose services

docker-compose down

 

Useful URLs When App is Running

URL

Purpose

http://localhost:8080/swagger-ui.html

Interactive API Documentation

http://localhost:8080/actuator/health

App Health Status

http://localhost:8080/actuator/info

App Info

http://localhost:8080/api/v1/employees

Employee API (GET all)

 

 


 

Spring Boot Microservice Guide  |  Java 21  |  Docker  |  Kubernetes  |  Jenkins

Post a Comment

Previous Post Next Post