How to change Quarkus default HTTP Port?

Quarkus 3.x uses high-performance non-blocking HTTP capabilities powered by Eclipse Vert.x and RESTEasy Reactive by default. When you build RESTful web services in modern Quarkus applications, you rely on the Jakarta RESTful Web Services API (jakarta.ws.rs.*) rather than legacy Java EE (javax.ws.rs.*) or Servlet/Undertow dependencies.

In this hands-on tutorial, we will explore the most common configuration options for tuning the embedded HTTP layer in Quarkus 3.x.

First of all, let’s specify how you can set configuration parameters in Quarkus. You have two primary options:

• Pass parameters on the Command Line or system properties using -D
• Include parameters in the src/main/resources/application.properties file

Configuring HTTP Port

The most basic setting is the default HTTP Port (which defaults to 8080). You can override it in your application.properties file:

quarkus.http.port=9080

If you want to use a different port depending on your active profile (e.g., Development vs Production), you can prefix the profile name. For example:

quarkus.http.port=8080
%dev.quarkus.http.port=8180

Finally, you can also pass the property at runtime when starting the application runner:

java -Dquarkus.http.port=8180 -jar target/quarkus-app/quarkus-run.jar

The equivalent option is also available when launching a native executable:

./target/acme-1.0.0-SNAPSHOT-runner -Dquarkus.http.port=8180

Configuring Host name

Next, here is how you can configure the bound host interface in application.properties (the default binding is 0.0.0.0):

quarkus.http.host=acme.com

Configuring HTTPS Port

In order to configure the secure port used for TLS/HTTPS connections, use the following property:

quarkus.http.ssl-port=8443

Configuring HTTP Test Port

Quarkus automated tests run on port 8081 by default to avoid port conflicts with running instances. You can configure the port used during testing with quarkus.http.test-port:

quarkus.http.test-port=8088

Configuring the Root Context Path

Another common requirement is configuring the application's root path. In Quarkus 3.x (using RESTEasy Reactive and Vert.x), the primary setting for the root context path is quarkus.http.root-path (which defaults to /):

quarkus.http.root-path=/webcontext

Note: If you explicitly use traditional Jakarta Servlet extensions (e.g., Undertow Servlet), you can also set quarkus.servlet.context-path=/webcontext. However, for standard RESTEasy Reactive endpoints, quarkus.http.root-path is the recommended property.

Configuring CORS

Cross-origin resource sharing (CORS) is a mechanism that allows restricted resources on a web page to be requested from another domain outside the domain from which the first resource was served. In Quarkus 3.x, CORS support is handled directly at the Vert.x HTTP reactive layer.

To enable CORS, set quarkus.http.cors=true. You can fine-tune your policy with specific origins, HTTP methods, and allowed headers directly in application.properties:

quarkus.http.cors=true
quarkus.http.cors.origins=http://foo.com,http://www.acme.com
quarkus.http.cors.methods=GET,PUT,POST,DELETE
quarkus.http.cors.headers=X-Custom
quarkus.http.cors.exposed-headers=Content-Disposition

Configuring IO Threads and Reactive Event Loops

Quarkus leverages Vert.x event loops to handle non-blocking IO operations efficiently. The number of IO threads is calculated automatically based on available CPU cores, but you can explicitly override it if needed:

quarkus.http.io-threads=5

Configuring HTTPS with Quarkus 3.x

You can configure secure TLS connections either using PEM certificates or a standard PKCS12 / JKS KeyStore. Let's see how to configure a KeyStore. First, generate a self-signed key store:

keytool -genkeypair -storetype PKCS12 -keyalg RSA -alias demo -keystore keystore.p12 -storepass mypassword -validity 365 -keysize 2048

Then, provide the key store path and password in your application.properties file:

quarkus.http.ssl.certificate.key-store-file=keystore.p12
quarkus.http.ssl.certificate.key-store-password=mypassword
quarkus.http.ssl-port=8443

Frequently Asked Questions (FAQs)

1. Can I change the Quarkus HTTP port using Environment Variables?

Yes! Quarkus maps configuration properties to environment variables automatically. To override quarkus.http.port, set the environment variable QUARKUS_HTTP_PORT=9090 before starting your application or container.

2. What is the difference between quarkus.http.root-path and quarkus.servlet.context-path in Quarkus 3.x?

In Quarkus 3.x, quarkus.http.root-path configures the root path for all HTTP endpoints (including RESTEasy Reactive, Reactive Routes, and Management endpoints). quarkus.servlet.context-path only applies if you explicitly include the Jakarta Servlet extension.

3. How does RESTEasy Reactive affect HTTP server performance?

RESTEasy Reactive is integrated directly into the Vert.x HTTP engine at build time. It eliminates traditional reflection and runtime Servlet overhead, executing reactive pipelines (using SmallRye Mutiny) directly on Vert.x IO event loops for maximum throughput.