GraalVM Native Microservice

A cloud-native Spring Boot microservice compiled to a native executable with GraalVM Native Image. Sub-second startup, low memory footprint, and one-command run with Docker Compose.

Features • Quick Start • API • Architecture

---

✨ Features

Feature	Description
Native executable	Compiled ahead-of-time with GraalVM Native Image — no JVM warm-up, instant startup (~0.1s).
Low memory	Single Linux binary; typical RSS far below a traditional JVM process.
Spring Boot 3	Modern stack: Spring Web, Actuator (health, info); Java 21.
REST API	Simple /api/hello endpoint; easy to extend.
Docker-first	Multi-stage Dockerfile: build native in GraalVM image, run in minimal Debian slim.
One-command run	docker compose up --build builds and runs the service.
Tests	@WebMvcTest for the controller; ./gradlew test before every build.

---

🏗 Architecture

flowchart LR
    subgraph Build
        A[Source + Gradle] --> B[GraalVM Native Image]
        B --> C[Linux binary]
    end
    subgraph Run
        C --> D[Debian slim container]
        D --> E[:8080]
    end
    subgraph Clients
        F[curl / browser]
    end
    E --> F

Loading

• Build stage: GraalVM native-image-community:21 runs ./gradlew nativeCompile and produces a single executable.
• Run stage: Only the binary is copied into debian:bookworm-slim; no JDK in the final image.
• Result: Small, fast container ideal for serverless, Kubernetes, or edge.

---

🚀 Quick Start

Prerequisites

• JDK 21 (for local run and tests)
• GraalVM 21 with native-image (for local native build; e.g. sdk install java 21-graalce then sdk use java 21-graalce)
• Docker and Docker Compose (for containerized build and run)

Option 1: Run with Docker (recommended)

Build and run in one command:

git clone https://github.com/NullPoint3rDev/graalvm-native-microservice.git
cd graalvm-native-microservice
docker compose up --build

• API: http://localhost:8080/api/hello
• Health: http://localhost:8080/actuator/health

First build may take several minutes (GraalVM image download + native compile). Later builds reuse layers.

Option 2: Run on JVM (local)

./gradlew bootRun

Then open http://localhost:8080/api/hello and http://localhost:8080/actuator/health.

Option 3: Build and run native locally

Ensure GraalVM 21 is active (sdk use java 21-graalce or set JAVA_HOME), then:

./gradlew nativeCompile
./build/native/nativeCompile/graalvm-native-microservice

Startup is typically under 0.1 seconds.

---

📡 API

Method	Path	Description
GET	/api/hello	Returns a plain-text greeting.
GET	/actuator/health	Health check (e.g. for Docker/Kubernetes).
GET	/actuator/info	Application info.

Example:

curl http://localhost:8080/api/hello
# Hello from native!

---

📁 Project structure

graalvm-native-microservice/
├── src/main/java/.../nativeapp/
│   ├── NativeMicroserviceApplication.java   # Spring Boot entry point
│   └── controller/
│       └── NativeAppController.java         # GET /api/hello
├── src/main/resources/
│   └── application.yml
├── src/test/.../controller/
│   └── NativeAppControllerTest.java        # MockMvc test
├── build.gradle.kts                        # Spring Boot + GraalVM native plugin
├── Dockerfile                              # Multi-stage: GraalVM build → Debian run
├── docker-compose.yml
├── LICENSE
└── README.md

---

🔧 Configuration

Property	Default	Description
server.port	8080	HTTP port.
spring.application.name	graalvm-native-microservice	Application name.

Override via environment variables or application.yml as needed.

---

📜 License

This project is licensed under the MIT License — see the LICENSE file for details.

---

Star the repo if you find it useful.