Getting Started

This guide will help you get up and running with the benchmarks in just a few minutes. We'll walk through running your first framework and understanding the results.

Prerequisites

Before you begin, ensure you have the following installed:

Required

Java: 19-21 (Eclipse Temurin or OpenJDK)

# Check Java version
java -version

# Should show: openjdk version "21.x.x" or similar

Docker: For containerized deployments

# Check Docker
docker --version
docker compose version

Optional (for benchmarking)

wrk: HTTP benchmarking tool

# Install on Ubuntu/Debian
sudo apt install wrk

# Install on macOS
brew install wrk

Build Tools: Maven 3.9+ or Gradle 8+ (optional, Docker builds included)
```
# Check Maven
mvn --version
```

Quick Start (2 Minutes)

1. Clone the Repository

# Clone repository
git clone https://github.com/your-org/java-framework-showdown.git
cd java-framework-showdown

2. Run the Fastest Framework (Undertow)

# Navigate to Undertow
cd undertow-baseline

# Start with Docker Compose
docker compose up -d

# Wait 10 seconds for startup, then test
curl http://localhost:8088/health

Expected Output:

{"status":"UP"}

That's it! You've just run the fastest framework from our benchmarks (37,808 req/s in our tests).

3. Quick Benchmark

# Run a quick performance test (if wrk installed)
wrk -t2 -c10 -d10s http://localhost:8088/health

# Expected: ~35k-38k requests/second

4. Cleanup

# Stop the container
docker compose down

Try Different Frameworks

Undertow (Fastest - 37,808 req/s)

cd undertow-baseline
docker compose up -d
curl http://localhost:8088/health
docker compose down

Why choose: Maximum performance, lowest latency

Armeria (Feature-Rich - 35,810 req/s)

cd armeria-rest
docker compose up -d
curl http://localhost:8085/health
docker compose down

Why choose: Async RPC/REST, circuit breakers, distributed tracing

Micronaut (Cloud-Native - 28,130 req/s)

cd micronaut-rest
docker compose up -d
curl http://localhost:8082/health
docker compose down

Why choose: Lowest memory (130 MB), best cloud cost efficiency

Quarkus (Kubernetes-Native - 26,608 req/s)

cd quarkus-rest
docker compose up -d
curl http://localhost:8083/health
docker compose down

Why choose: Live reload, native compilation (<100ms startup)

Javalin (Best Developer Experience - 19,853 req/s)

cd javalin-rest
docker compose up -d
curl http://localhost:8087/health
docker compose down

Why choose: Simple API, fastest time to market

Running Performance Tests

Test All Frameworks

cd performance-tests

# Run comprehensive benchmarks on all frameworks
./run-all-tests.sh

# This will:
# 1. Start each framework one by one
# 2. Run wrk benchmarks (low, medium, high concurrency)
# 3. Collect results in results/ directory
# 4. Generate comparison report

# View results
cat results/comparison-report.txt

Test Individual Framework

cd performance-tests

# Test specific framework
./test-app.sh undertow-baseline 8088

# Arguments: <app-name> <port>

Analyze Results

# Generate detailed analysis
./analyze-results.sh

# Clean up all test results
./cleanup.sh

Exploring the Frameworks

1. Check Out the Code

Each framework directory contains:

framework-name/
├── src/                  # Source code
├── pom.xml              # Maven configuration (or build.gradle)
├── docker-compose.yml   # Docker deployment
├── Dockerfile           # Multi-stage build
└── README.md            # Framework-specific docs

Example: Explore Undertow

cd undertow-baseline
cat src/main/java/com/example/UndertowServer.java

2. Build from Source

# Navigate to any framework
cd undertow-baseline

# Build with Maven
mvn clean package

# Run the JAR
java -jar target/*.jar

# Test in another terminal
curl http://localhost:8088/health

3. Inspect Docker Images

# Build image
docker build -t undertow-test .

# Check image size
docker images undertow-test

# Run container
docker run -p 8088:8088 undertow-test

Understanding the Results

What to Look For

When comparing frameworks, consider:

Throughput (req/s): Higher is better
- Top tier: 35k+ (Undertow, Armeria)
- Production: 26-30k (Light4J, Micronaut, Vert.x, Quarkus)
- Solid: 18-24k (Helidon, Javalin, Netty)
Latency (milliseconds): Lower is better
- Excellent: <500μs (Undertow, Armeria)
- Good: <1ms (Light4J, Vert.x, Micronaut, Quarkus)
- Acceptable: <2ms (All frameworks at low concurrency)
Memory (MB): Lower is better (cloud cost)
- Most efficient: Micronaut (130 MB), Quarkus (140 MB)
- Standard: 165-210 MB (most frameworks)
- Higher: Vert.x (240 MB) - offset by reactive performance
JAR Size (MB): Smaller is better (CI/CD speed)
- Tiny: ActiveJ (5.3 MB), Undertow (7.1 MB)
- Small: 8-12 MB (most frameworks)
- Large: Armeria (28 MB) - includes gRPC, HTTP/2

Reading Benchmark Output

wrk -t4 -c100 -d30s http://localhost:8088/health

Sample Output:

Running 30s test @ http://localhost:8088/health
  4 threads and 100 connections
  Thread Stats   Avg      Stdev     Max   +/- Stdev
    Latency     3.10ms    1.52ms  28.44ms   89.67%
    Req/Sec     9.45k     1.23k   12.34k    71.25%
  1134240 requests in 30.00s, 102.34MB read
Requests/sec:  37808.00
Transfer/sec:      3.41MB

Key Metrics:

Requests/sec: 37,808 (throughput)
Latency Avg: 3.10ms (p50 latency)
Latency Max: 28.44ms (p100 latency)
Throughput/Thread: ~9,450 req/s

Next Steps

For Developers

Explore Framework Details
- Read Frameworks Guide for detailed info on all 11 frameworks
Study Code Examples
- Check Code Examples for copy-paste snippets
Dive into Implementation
- Browse source code in each framework directory
- Understand database integration, error handling, health checks

For Architects & Decision Makers

Compare Performance
- Review Benchmarks for detailed performance analysis
Make a Decision
- Use Decision Guide to choose the right framework
Calculate ROI
- See Migration Guides for effort estimates and cost savings

For DevOps Engineers

Deploy to Kubernetes
- Explore k8s/ for production-ready manifests
Set Up Monitoring
- Check observability/ for Prometheus, Grafana, Jaeger setup
Read Deployment Guide
- See Deployment Guide for Docker, K8s, cloud platforms

Troubleshooting

Port Already in Use

Problem: Error: bind: address already in use

Solution:

# Find process using port
lsof -i :8088

# Kill process
kill -9 <PID>

# Or use different port
docker run -p 9000:8088 framework-image

Docker Compose Issues

Problem: docker compose: command not found

Solution:

# Use older syntax
docker-compose up -d

# Or install docker compose plugin
sudo apt install docker-compose-plugin

Out of Memory

Problem: Container crashes with OOM error

Solution:

# Increase Docker memory limit (Docker Desktop)
# Settings → Resources → Memory → 4GB+

# Or set Java heap size
docker run -e JAVA_OPTS="-Xmx512m" framework-image

Slow Build Times

Problem: Maven builds taking too long

Solution:

# Use Docker multi-stage builds (pre-configured)
docker build -t framework .

# Or skip tests
mvn clean package -DskipTests

wrk Not Available

Problem: wrk: command not found

Solution:

# Ubuntu/Debian
sudo apt update && sudo apt install wrk

# macOS
brew install wrk

# Or build from source
git clone https://github.com/wg/wrk.git
cd wrk && make
sudo cp wrk /usr/local/bin/

Common Questions

Q: Which framework should I start with?

A: Depends on your goal:

Maximum performance: Undertow
Cloud-native: Micronaut or Quarkus
Easy to learn: Javalin
Reactive: Vert.x
Production-ready: Light4J or Armeria

Q: Can I use these in production?

A: Absolutely! Frameworks used in production:

Undertow: Powers WildFly, used by Fortune 500
Armeria: Handles billions of requests/day at Line
Quarkus: Used by Red Hat customers globally
Micronaut: Deployed at major enterprises
Light4J: Proven in financial services

Q: How do I migrate from Spring Boot?

A: See Migration Guides:

Spring Boot → Micronaut: 1-2 days, 90% similar
Spring Boot → Quarkus: 2-3 days, 85% similar
Both guides include code comparisons and examples

Q: Are these benchmarks realistic?

A: Yes, because:

✅ Tested on identical hardware
✅ Real-world endpoints (/health, database queries)
✅ Controlled environment (Docker)
✅ Multiple concurrency levels
✅ Reproducible (run tests yourself!)

Q: Can I contribute?

A: Absolutely! See Contributing Guide for:

Adding new frameworks
Improving benchmarks
Fixing bugs
Enhancing documentation

Quick Reference

Framework Ports

Framework	Port
Vert.x	8081
Micronaut	8082
Quarkus	8083
Light4J	8084
Armeria	8085
Helidon	8086
Javalin	8087
Undertow	8088
Netty	8089
ActiveJ	8090

Essential Commands

# Start framework
docker compose up -d

# View logs
docker compose logs -f

# Test health endpoint
curl http://localhost:<PORT>/health

# Stop framework
docker compose down

# Run benchmark
wrk -t4 -c100 -d30s http://localhost:<PORT>/health

# Build from source
mvn clean package

# Run JAR
java -jar target/*.jar

Resources

Documentation

Frameworks Guide - All 11 frameworks in detail
Benchmarks - Performance analysis with charts
Decision Guide - Choose the right framework
Deployment - Production deployment guides

Advanced Topics

GraalVM Native - Native compilation (100x faster startup)
Memory Analysis - Memory usage deep dive
Migration Guides - Step-by-step migrations

Production Resources

Kubernetes Manifests - Production K8s configs
Observability Stack - Prometheus, Grafana, Jaeger
Performance Tests - Benchmark methodology

Need Help?

💬 Discussions: GitHub Discussions
🐛 Issues: Report bugs or request features
📧 Contact: For business inquiries or collaborations

Last Updated: August 25, 2026

FilesExpand file tree

GETTING_STARTED.md

Latest commit

History

GETTING_STARTED.md

File metadata and controls

Getting Started

Prerequisites

Required

Optional (for benchmarking)

Quick Start (2 Minutes)

1. Clone the Repository

2. Run the Fastest Framework (Undertow)

3. Quick Benchmark

4. Cleanup

Try Different Frameworks

Undertow (Fastest - 37,808 req/s)

Armeria (Feature-Rich - 35,810 req/s)

Micronaut (Cloud-Native - 28,130 req/s)

Quarkus (Kubernetes-Native - 26,608 req/s)

Javalin (Best Developer Experience - 19,853 req/s)

Running Performance Tests

Test All Frameworks

Test Individual Framework

Analyze Results

Exploring the Frameworks

1. Check Out the Code

2. Build from Source

3. Inspect Docker Images

Understanding the Results

What to Look For

Reading Benchmark Output

Next Steps

For Developers

For Architects & Decision Makers

For DevOps Engineers

Troubleshooting

Port Already in Use

Docker Compose Issues

Out of Memory

Slow Build Times

wrk Not Available

Common Questions

Q: Which framework should I start with?

Q: Can I use these in production?

Q: How do I migrate from Spring Boot?

Q: Are these benchmarks realistic?

Q: Can I contribute?

Quick Reference

Framework Ports

Essential Commands

Resources

Documentation

Advanced Topics

Production Resources

Need Help?