Skip to content

b1krams/ms

BranchesTags

Repository files navigation

Spring Boot Microservices Template

A production-ready microservices architecture built with Spring Boot 3.5, Spring Cloud 2025.0.0, and GraalVM native image support.

🏗️ Architecture

This project implements a microservices architecture with API gateway and multiple business services:

┌─────────────────────────────────────────────────────────────┐
│                      API Gateway (8080)                      │
│                     traefik                                 │
└──────────────┬──────────────────────────────────────────────┘
               │
               ├──────────────┬──────────────┬─────────────┐
               │              │              │             │
       ┌───────▼────────┐ ┌──▼───────────┐ ┌▼──────────┐ ┌▼────────────┐
       │ user-service   │ │product-service│ │order-service│ │   ...more   │
       │   (8081)       │ │   (8082)      │ │   (8083)   │ │  services   │
       └────────────────┘ └───────────────┘ └────────────┘ └─────────────┘

Services

  • gateway-server (8080): API Gateway with routing and load balancing
  • user-service (8081): User management service
  • product-service (8082): Product catalog service
  • order-service (8083): Order processing service with circuit breaker

Note

This template does not include a config-server. Services use environment variables and embedded configuration files for simplicity.

📦 Project Structure

.
├── .github/
│   └── workflows/
│       └── native-build.yml       # CI/CD for native image builds
├── gateway-server/                # API Gateway
├── user-service/                  # User management
├── product-service/               # Product catalog
├── order-service/                 # Order processing
├── k8s/                          # Kubernetes manifests
│   ├── namespace.yaml
│   ├── gateway-server.yaml
│   ├── user-service.yaml
│   ├── product-service.yaml
│   └── order-service.yaml
├── tests/                        # Test suites
│   ├── functional-tests/         # Postman collections
│   └── performance-tests/        # JMeter tests
├── Containerfile                 # Generic native image build
├── pom.xml                       # Parent POM with native profile
├── Makefile                      # Build automation
├── run-all.sh                    # Start all services locally
├── stop-all.sh                   # Stop all services
└── populate_data.py              # Test data population

🚀 Quick Start

Prerequisites

  • Java 21 (Temurin or similar)
  • Maven 3.9+
  • Buildah (for native image builds)
  • k0s (for Kubernetes deployment)
  • GraalVM (optional, for local native builds)

Local Development

Option 1: Run all services with Maven

# Start all services with local profile
./run-all.sh

# Stop all services
./stop-all.sh

Option 2: Run individual services

# Build all services
mvn clean package -DskipTests

# Start all services
cd user-service && mvn spring-boot:run &
cd product-service && mvn spring-boot:run &
cd order-service && mvn spring-boot:run &
cd gateway-server && mvn spring-boot:run &

Option 3: Using Makefile

make build          # Build all services (Maven)
make deploy         # Deploy to k0s (local images)
make deploy-remote  # Deploy to k0s (remote images from ghcr.io)
make pull-images    # Pre-pull remote images
make update-images  # Update running deployments
make undeploy       # Remove from k0s
make logs           # View logs (default: gateway-server)
make status         # Check pod status
make k8s-status     # Detailed k8s status

Access Services

🔨 Building Native Images

This project supports GraalVM native image compilation for faster startup and lower memory footprint.

Using GitHub Actions (Recommended)

The project includes automated CI/CD for native image builds:

  • Workflow: .github/workflows/native-build.yml
  • Triggers: Push to main or pull requests
  • Output: Native images pushed to ghcr.io
  • Build time: ~5-10 minutes per service

Local Native Build

Build with Maven native profile:

# Build native executable for a specific service
mvn -Pnative native:compile -pl user-service -DskipTests

# Run the native executable
./user-service/target/user-service

Native Image Benefits

  • Startup Time: ~0.1s vs ~3-5s (JVM)
  • Memory Usage: ~50-100MB vs ~200-400MB (JVM)
  • Image Size: ~100-150MB vs ~300-500MB (JVM)

⚡ Build Performance Improvements

  • Parallel Maven Builds: Uses Maven's parallel build mode (-T 1C) for faster multi-service compilation
  • CI Pipeline Caching: GitHub Actions caches Maven dependencies and Docker layers for faster builds
  • Buildah Support: Rootless container builds with efficient layer caching
  • Incremental Builds: Only rebuilds changed services in multi-module setup

🧪 Testing

Populate Test Data

python3 populate_data.py

Run Functional Tests (Postman)

make postman-test

Run Performance Tests (JMeter)

make perf-test

Run Tests in Kubernetes

Performance Tests (JMeter):

# 1. Create ConfigMap with test plan and data
k0s kubectl create configmap jmeter-tests -n ms \
  --from-file=tests/performance-tests/test-plan.jmx \
  --from-file=tests/performance-tests/data/

# 2. Run the Job
k0s kubectl apply -f k8s/jmeter-job.yaml

# 3. View logs/results
k0s kubectl logs -n ms job/jmeter-test -f

# Cleanup (to run again)
k0s kubectl delete job jmeter-test -n ms
k0s kubectl delete configmap jmeter-tests -n ms

Functional Tests (Newman):

# 1. Create ConfigMap with collection and environment
k0s kubectl create configmap newman-tests -n ms \
  --from-file=tests/functional-tests/api-tests.postman_collection.json \
  --from-file=tests/functional-tests/api-environment.postman_environment.json

# 2. Run the Job
k0s kubectl apply -f k8s/newman-job.yaml

# 3. View logs/results
k0s kubectl logs -n ms job/newman-test

# Cleanup (to run again)
k0s kubectl delete job newman-test -n ms
k0s kubectl delete configmap newman-tests -n ms

☸️ Kubernetes Deployment (k0s)

Deploy Using Prebuilt Images (Recommended)

The easiest way to deploy is using prebuilt native images from GitHub Container Registry:

# Deploy using remote images from ghcr.io/bikram054/ms
make deploy-remote

This will:

  • Pull native images from ghcr.io/bikram054/ms
  • Deploy all microservices to k0s
  • Wait for all pods to be ready
  • Display service endpoints

Available commands:

make deploy-remote    # Deploy using remote images
make pull-images      # Pre-pull all images to k0s nodes
make update-images    # Update deployments with latest images
make status           # Check pod status
make logs             # View logs (default: gateway-server)
make undeploy         # Remove all services

Deploy Using Local Images

If you've built images locally:

# Deploy to k0s
make deploy

Manual deployment:

# Create namespace and deploy
sudo k0s kubectl apply -f k8s/namespace.yaml
sudo k0s kubectl apply -f k8s/

# Verify deployment
sudo k0s kubectl logs -n ms -l app=gateway-server -f

Resource Requirements

Native Images (Recommended):

resources:
  requests:
    memory: "128Mi"
    cpu: "100m"
  limits:
    memory: "256Mi"
    cpu: "300m"

JVM Images:

resources:
  requests:
    memory: "256Mi"
    cpu: "200m"
  limits:
    memory: "512Mi"
    cpu: "500m"

🔧 Configuration

Profiles

  • default: Local development with H2 database
  • prod: Production configuration (used in native builds)

Environment Variables

# Spring profiles
SPRING_PROFILES_ACTIVE=prod

📊 Monitoring

Health Checks

# Check service health
curl http://localhost:8080/actuator/health

Kubernetes Monitoring (k0s)

# Quick status
make status

# Detailed status
make k8s-status

# View all services
sudo k0s kubectl get all -n ms

# Check pod status
sudo k0s kubectl describe pod <pod-name> -n ms

# View logs
make logs SERVICE=gateway-server

# Resource usage
sudo k0s kubectl get pods -n ms

🐛 Troubleshooting

Image Pull Errors

Issue: ImagePullBackOff or ErrImagePull

# Check pod events
sudo k0s kubectl describe pod <pod-name> -n ms

# Verify image exists
docker pull ghcr.io/bikram054/ms/gateway-server:latest

# For private registries, ensure image pull secret is created
./setup-image-pull-secret.sh

Issue: Images not updating

# Force pull latest images
make update-images

# Or manually restart deployments
sudo k0s kubectl rollout restart deployment --all -n ms

Native Image Build Failures

Issue: Missing reflection configuration

# Add to native-image.properties or use @RegisterReflectionForBinding

Issue: Out of memory during build

# Increase Docker memory limit to 8GB+

Pod CrashLoopBackOff

# Check events
sudo k0s kubectl describe pod <pod-name> -n ms

# View logs
sudo k0s kubectl logs <pod-name> -n ms --previous

# Common fixes:
# 1. Increase initialDelaySeconds in liveness probe
# 2. Verify image pull secrets (if using private registry)

🤝 Contributing

  1. Fork the repository
  2. Create a feature branch (git checkout -b feature/amazing-feature)
  3. Commit your changes (git commit -m 'Add amazing feature')
  4. Push to the branch (git push origin feature/amazing-feature)
  5. Open a Pull Request

📝 License

This project is licensed under the MIT License.

🔗 Related Resources

Built with ❤️ using Spring Boot and GraalVM

About

No description, website, or topics provided.

Resources

Readme
Activity

Stars

1 star

Watchers

1 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages