# Quarkus

A Quarkus 3 REST API starter in Java 17, built with the Maven wrapper, for Java developers who want Quarkus REST, CDI and dev-mode live reload set up. It packages as a single uber-jar and includes REST Assured tests plus an integration test against the packaged jar.

- Framework: Quarkus (Java)
- Category: Starters / REST APIs
- Creates: a server app
- Plan: Free
- Price: Free
- Author: Light Cloud
- Page: https://templates.light-cloud.com/starters/rest-apis/quarkus-api-starter
- Updated: 2026-11-21

## Features

- Quarkus 3.38 with Quarkus REST (Jakarta REST), Jackson and ArC for CDI
- GET / returns JSON with the service name, "status": "ok" and the endpoint list; GET /hello returns plain text
- The /hello text comes from greeting.message, which reads GREETING_MESSAGE from the environment
- ./mvnw quarkus:dev reloads on every change and serves the Dev UI at /q/dev-ui
- Packaged as an uber-jar, target/*-runner.jar, so one file holds the app and its dependencies
- @QuarkusTest tests with REST Assured, and GreetingResourceIT reruns them against the jar with -DskipITs=false
- Listens on 0.0.0.0 and the port in PORT, with 8080 as the fallback
- Quarkus-generated JVM and native Dockerfiles in src/main/docker for building a native executable

## What you need

- Free plan: it runs as a server app, and the Free plan includes 3 server apps
- To run it locally: a JDK for Java 17 or newer (the Maven wrapper downloads Maven)
- No API keys: it starts with nothing to configure
- Optional: GREETING_MESSAGE to change the text GET /hello returns

## About

Resources are grouped by feature (greeting/ and root/) and get their services through constructor injection, with configuration injected by @ConfigProperty, so the pattern to copy is GreetingResource plus GreetingService. Quarkus does its wiring at build time, which keeps start-up short, and the uber-jar setting in application.properties means a deploy only has to pick up one jar. Light Cloud builds that jar with Maven and runs it as a container on PORT, and each push to your copy redeploys.

## Questions

### How do I add a new REST endpoint in Quarkus?

Add a class annotated with @Path("/your-path") and a method with @GET or @POST that returns a record; quarkus-rest-jackson writes it as JSON. Quarkus finds the class at build time, so there is nothing to register.

### How do I set Quarkus config from environment variables?

Reference the variable in application.properties with a default, as in greeting.message=${GREETING_MESSAGE:Hello from Quarkus REST}. Quarkus also reads a .env file in the project folder for local runs.

### Why does this Quarkus starter build an uber-jar instead of a fast-jar?

The default fast-jar writes target/quarkus-app/ with loose dependencies, while an uber-jar is one file that is simpler to copy into a container or onto a server. Switch quarkus.package.jar.type back to fast-jar if you want to use Dockerfile.jvm.

### How do I add Swagger UI to a Quarkus API?

Run ./mvnw quarkus:add-extension -Dextensions=smallrye-openapi. Quarkus then serves the schema at /q/openapi and Swagger UI at /q/swagger-ui in dev mode.

### Can I deploy this Quarkus app without Light Cloud?

Yes. Run ./mvnw clean package and start java -jar target/*-runner.jar on any host with Java 17, or build a native executable with ./mvnw package -Dnative and use the Dockerfiles in src/main/docker.
