This document explains various Undertow features that you can use in Quarkus.
1. Serving Static Resources
To serve static resources you must place them in the META-INF/resources
directory of your application. This is because
Quarkus applications are jar files rather than war files, and this location is the standard location for resources in
jar files as defined by the Servlet spec.
2. Configuring the Context path
By default Undertow will serve content from under the root context. If you want to change this you can use the
quarkus.servlet.context-path
config key to set the context path.
3. undertow-handlers.conf
You can make use of the Undertow predicate language using an undertow-handlers.conf
file. This file should be placed
in the META-INF
directory of your application jar. This file contains handlers defined using the
Undertow predicate language.
4. web.xml
If you are using a web.xml
file as your configuration file, you can place it in the src/main/resources/META-INF
directory.
5. Supporting secure connections with SSL
In order to have Undertow support secure connections, you must either provide a certificate and associated key file, or supply a keystore.
In both cases, a password must be provided. See the designated paragraph for a detailed description of how to provide it.
To enable SSL support with native executables, please refer to our Using SSL With Native Executables guide. |
5.1. Providing a certificate and key file
If the certificate has not been loaded into a keystore, it can be provided directly using the properties listed below. Quarkus will first try to load the given files as resources, and uses the filesystem as a fallback. The certificate / key pair will be loaded into a newly created keystore on startup.
Your application.properties
would then look like this:
quarkus.http.ssl.certificate.file=/path/to/certificate
quarkus.http.ssl.certificate.key-file=/path/to/key
5.2. Providing a keystore
An alternate solution is to directly provide a keystore which already contains a default entry with a certificate You will need to at least provide the file and a password.
As with the certificate/key file combination, Quarkus will first try to resolve the given path as a resource, before attempting to read it from the filesystem.
Add the following property to your application.properties
:
quarkus.http.ssl.certificate.key-store-file=/path/to/keystore
As an optional hint, the type of keystore can be provided as one of the options listed. If the type is not provided, Quarkus will try to deduce it from the file extensions, defaulting to type JKS.
quarkus.http.ssl.certificate.key-store-file-type=[one of JKS, JCEKS, P12, PKCS12, PFX]
5.3. Setting the password
In both aforementioned scenarios, a password needs to be provided to create/load the keystore with.
The password can be set in your application.properties
(in plain-text) using the following property:
quarkus.http.ssl.certificate.key-store-password=your-password
However, instead of providing the password as plain-text in the configuration file (which is considered bad practice), it can instead be supplied (using MicroProfile config)
as the environment variable QUARKUS_HTTP_SSL_CERTIFICATE_KEY_STORE_PASSWORD
.
This will also work in tandem with Kubernetes secrets.
Note: in order to remain compatible with earlier versions of Quarkus (before 0.16) the default password is set to "password". It is therefore not a mandatory parameter!
6. CORS filter
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.
Quarkus comes with a CORS filter which implements the javax.servlet.Filter
interface and intercepts all incoming HTTP
requests. It can be enabled in the Quarkus configuration file, src/main/resources/application.properties
:
quarkus.http.cors=true
If the filter is enabled and an HTTP request is identified as cross-origin, the CORS policy and headers defined using the following properties will be applied before passing the request on to its actual target (servlet, JAX-RS resource, etc.):
Property Name | Default | Description |
---|---|---|
|
The comma-separated list of origins allowed for CORS. The filter allows any origin if this is not set. |
|
|
The comma-separated list of HTTP methods allowed for CORS. The filter allows any method if this is not set. |
|
|
The comma-separated list of HTTP headers allowed for CORS. The filter allows any header if this is not set. |
|
|
The comma-separated list of HTTP headers exposed in CORS. |
|
|
The duration (see note below) indicating how long the results of a pre-flight request can be cached.
This value will be returned in a |
The format for durations uses the standard You can also provide duration values starting with a number.
In this case, if the value consists only of a number, the converter treats the value as seconds.
Otherwise, |
Here’s what a full CORS filter configuration could look like:
quarkus.http.cors=true
quarkus.http.cors.origins=http://foo.com,http://www.bar.io
quarkus.http.cors.methods=GET,PUT,POST
quarkus.http.cors.headers=X-Custom
quarkus.http.cors.exposed-headers=Content-Disposition
quarkus.http.cors.access-control-max-age=24H
If you want to use the |
7. Http Limits Configuration
The following properties are supported.
Property Name | Default | Description |
---|---|---|
|
|
The maximum size of request body. |
|
|
The maximum length of all headers. |
The following config options would recognize strings in this format (shown as a regular expression):
|