xDev Asia

Install Quarkus CLI and JDK 21+, create project, Dev Mode live reload, Dev UI dashboard, Dev Services, Continuous Testing.

Quarkus Microservices: From Basics to Production

Part 1: Quarkus Platform & Project Setup

xdev.asia

Introduction

One of Quarkus's greatest strengths is Developer Experience (DX). With Dev Mode, you change code → save → results immediately. Dev Services automatically starts PostgreSQL, Kafka, Keycloak without any configuration. Dev UI gives you an intuitive dashboard to manage extensions. Continuous Testing runs tests automatically every time the code changes.

Environment settings

JDK 21+

# SDKMAN (khuyến nghị)
sdk install java 21.0.4-tem

# Hoặc download từ Adoptium
# https://adoptium.net/

# Verify
java --version
# openjdk 21.0.4 2024-07-16 LTS

Quarkus CLI

# macOS (Homebrew)
brew install quarkusio/tap/quarkus

# Linux / macOS (SDKMAN)
sdk install quarkus

# Linux (JBang)
curl -Ls https://sh.jbang.dev | bash -s - trust add https://repo1.maven.org/maven2/io/quarkus/quarkus-cli/
curl -Ls https://sh.jbang.dev | bash -s - app install --fresh --force quarkus@quarkusio

# Verify
quarkus version
# 3.34.x

Docker (for Dev Services)

# Docker Desktop hoặc Podman
docker --version
# Docker version 27.x

# Quarkus hỗ trợ cả Podman
podman --version

Create the first Project

Quarkus CLI

quarkus create app com.xdev.ecommerce:product-service \
  --extension='rest-jackson,hibernate-orm-panache,jdbc-postgresql,flyway,smallrye-health,openapi' \
  --java=21 \
  --wrapper

cd product-service

Project structure

product-service/
├── mvnw                          # Maven wrapper
├── pom.xml                       # Dependencies & plugins
├── src/
│   ├── main/
│   │   ├── docker/               # Dockerfiles (JVM, Native, Legacy)
│   │   │   ├── Dockerfile.jvm
│   │   │   ├── Dockerfile.native
│   │   │   └── Dockerfile.native-micro
│   │   ├── java/com/xdev/ecommerce/
│   │   │   └── GreetingResource.java
│   │   └── resources/
│   │       ├── application.properties  # Configuration
│   │       └── META-INF/
│   │           └── resources/          # Static files (index.html)
│   └── test/
│       └── java/com/xdev/ecommerce/
│           ├── GreetingResourceTest.java
│           └── GreetingResourceIT.java   # Integration test (native)
└── .mvn/                         # Maven wrapper config

pom.xml — Quarkus BOM

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>io.quarkus.platform</groupId>
            <artifactId>quarkus-bom</artifactId>
            <version>3.34.2</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

<dependencies>
    <dependency>
        <groupId>io.quarkus</groupId>
        <artifactId>quarkus-rest-jackson</artifactId>
    </dependency>
    <dependency>
        <groupId>io.quarkus</groupId>
        <artifactId>quarkus-hibernate-orm-panache</artifactId>
    </dependency>
    <dependency>
        <groupId>io.quarkus</groupId>
        <artifactId>quarkus-jdbc-postgresql</artifactId>
    </dependency>
    <!-- ... -->
</dependencies>

Dev Mode — Live Coding

quarkus dev
# hoặc
./mvnw quarkus:dev

How does Hot Reload work?

┌─────────────────────────────────────────────┐
│  Developer thay đổi code → Save file        │
│              │                               │
│              ▼                               │
│  Quarkus detect file change                  │
│              │                               │
│              ▼                               │
│  Re-compile class đã thay đổi (incremental) │
│              │                               │
│              ▼                               │
│  Re-deploy application (trong cùng JVM)      │
│              │                               │
│              ▼                               │
│  Next HTTP request nhận code mới (~200ms)    │
└─────────────────────────────────────────────┘

Differences compared to Spring DevTools:

Do not restart JVM — only reload the changed class
Supports changing dependencies (add new extensions without restarting)
configuration changes are also reloaded immediately

Dev Mode commands

While Dev Mode is running, press the keys:

Press [h] for more options>

[r] - Re-run all tests
[o] - Toggle test output
[s] - Force restart
[w] - Open Dev UI in browser
[d] - Disable/Enable live reload
[h] - Show this help
[q] - Quit

Dev Services — Zero-Config Infrastructure

Dev Services is the killer feature of Quarkus. When you add extensions that need external services (database, message broker, auth server), Quarkus automatically starts the container with Testcontainers.

How it works

┌─────────────────────────────────────────────┐
│  quarkus dev                                 │
│              │                               │
│              ▼                               │
│  Detect jdbc-postgresql extension            │
│  → No datasource URL configured             │
│  → Auto-start PostgreSQL container           │
│              │                               │
│  Detect quarkus-oidc extension               │
│  → No OIDC server configured                │
│  → Auto-start Keycloak container             │
│              │                               │
│  Detect kafka extension                      │
│  → No bootstrap servers configured           │
│  → Auto-start Kafka container (Redpanda)     │
│              │                               │
│  Inject connection URLs automatically        │
└─────────────────────────────────────────────┘

application.properties (Dev Mode)

# KHÔNG cần cấu hình gì cho dev mode!
# Dev Services tự start PostgreSQL, Keycloak, Kafka

# Chỉ cần config cho production
%prod.quarkus.datasource.db-kind=postgresql
%prod.quarkus.datasource.jdbc.url=jdbc:postgresql://db:5432/products
%prod.quarkus.datasource.username=${DB_USER}
%prod.quarkus.datasource.password=${DB_PASS}

Dev Services for PostgreSQL

# Tùy chỉnh Dev Services (tùy chọn)
quarkus.datasource.devservices.image-name=postgres:16
quarkus.datasource.devservices.port=5433
quarkus.datasource.devservices.db-name=product_db
quarkus.datasource.devservices.volumes."/path/to/init.sql"=/docker-entrypoint-initdb.d/init.sql

Dev Services for Keycloak

# Auto-start Keycloak 26.x
quarkus.oidc.devservices.realm-path=dev-realm.json
quarkus.oidc.devservices.port=8180
quarkus.oidc.devservices.roles.alice=admin,user
quarkus.oidc.devservices.roles.bob=user

Dev UI — Development Dashboard

Access http://localhost:8080/q/dev-ui when Dev Mode is running:

Dev UI features

Tabs	Function
Extensions	List of installed extensions, link to docs
Configuration	View/edit all config properties real-time
Endpoints	List all REST endpoints
Dev Services	Container status running
Swagger UI	Test API directly
Hibernate ORM	View entities, run HQL/SQL queries
SmallRye Health	Check health status
Continuous Testing	Real-time test results

Continuous Testing

Quarkus runs tests automatically every time the code changes:

# Bật Continuous Testing trong Dev Mode
# Nhấn [r] để chạy tất cả tests

# Hoặc configure trong application.properties
quarkus.test.continuous-testing=enabled
# enabled | paused | disabled

Test lifecycle

┌──────────────────────────────────────────┐
│  Code change detected                     │
│          │                                │
│          ▼                                │
│  Identify affected tests                  │
│          │                                │
│          ▼                                │
│  Run ONLY affected tests (smart filter)   │
│          │                                │
│          ▼                                │
│  Display results in terminal              │
│  ✅ 5 passed | ❌ 1 failed | ⏭️ 3 skipped │
└──────────────────────────────────────────┘

Multi-Module Project structure

For the microservices system, we use multi-module Maven project:

ecommerce-platform/
├── pom.xml                     # Parent POM
├── common/                     # Shared DTOs, utils
│   ├── pom.xml
│   └── src/
├── product-service/            # Microservice 1
│   ├── pom.xml
│   └── src/
├── order-service/              # Microservice 2
│   ├── pom.xml
│   └── src/
├── payment-service/            # Microservice 3
│   ├── pom.xml
│   └── src/
├── notification-service/       # Microservice 4
│   ├── pom.xml
│   └── src/
└── docker-compose.yml          # Local environment

Parent POM

<project>
    <groupId>com.xdev.ecommerce</groupId>
    <artifactId>ecommerce-platform</artifactId>
    <version>1.0.0-SNAPSHOT</version>
    <packaging>pom</packaging>

    <modules>
        <module>common</module>
        <module>product-service</module>
        <module>order-service</module>
        <module>payment-service</module>
        <module>notification-service</module>
    </modules>

    <properties>
        <quarkus.platform.version>3.34.2</quarkus.platform.version>
        <java.version>21</java.version>
        <maven.compiler.source>${java.version}</maven.compiler.source>
        <maven.compiler.target>${java.version}</maven.compiler.target>
    </properties>

    <dependencyManagement>
        <dependencies>
            <dependency>
                <groupId>io.quarkus.platform</groupId>
                <artifactId>quarkus-bom</artifactId>
                <version>${quarkus.platform.version}</version>
                <type>pom</type>
                <scope>import</scope>
            </dependency>
        </dependencies>
    </dependencyManagement>
</project>

Exercises

Install JDK 21, Quarkus CLI and Docker on local machine
Create project product-service with extensions: rest-jackson, hibernate-orm-panache, jdbc-postgresql, flyway, smallrye-health
Run quarkus dev and observe Dev Services automatically start the PostgreSQL container
Access Dev UI at /q/dev-ui — explore tabs
Write a new endpoint, save the file and test whether the live reload works
Create a multi-module project structure for E-Commerce Platform

Summary

Quarkus CLI create projects quickly with quarkus create app
Dev Mode live reload without restarting the JVM
Dev Services automatically starts PostgreSQL, Kafka, Keycloak — zero config
Dev UI dashboard manages extensions, endpoints, real-time configuration
Continuous Testing runs tests automatically when code changes
Multi-module project suitable for microservices systems

Next article: Build professional RESTful APIs with Quarkus REST.

Lesson 2: Creating Quarkus Project — CLI, Dev Mode, Dev UI & Live Coding

Introduction

Environment settings

JDK 21+

Quarkus CLI

Docker (for Dev Services)

Create the first Project

Quarkus CLI

Project structure

pom.xml — Quarkus BOM

Dev Mode — Live Coding

How does Hot Reload work?

Dev Mode commands

Dev Services — Zero-Config Infrastructure

How it works

application.properties (Dev Mode)

Dev Services for PostgreSQL

Dev Services for Keycloak

Dev UI — Development Dashboard

Dev UI features

Continuous Testing

Test lifecycle

Multi-Module Project structure

Parent POM

Exercises

Summary