How to serve static content in WildFly applications?

This article presents different ways of including static content (such as image or css files) in Web applications running on top of WildFly application server.

Web application structure

In general terms, a Web application which uses Maven as builder, includes both static and dynamic content within the webapp folder. Example:

├── pom.xml
└── src
    └── main
        ├── resources
        └── webapp
            ├── index.html
            └── WEB-INF
                └── web.xml

In order to keep apart dynamic content from static content, many administrators use Apache server as a Front-end Server. Within Apache’s httpd conf, you would typically configure a Virtual Host with an Alias to the directory where you are keeping your static content. Example:

<VirtualHost *:80>
DocumentRoot /var/www/
Alias /images "/var/www/img/"  
    <Directory "/var/www/img">  
    Options +Indexes  
    AllowOverride None  
    Order allow,deny  
    Allow from all  

You can however use Undertow’s handlers to serve static content of your Web application, which is available in an external directory of file system. Let’s see how to do it.

Using Undertow to serve static content from an external directory

Firstly, we will assume that the static content is available in the external folder “/home/francesco/Pictures”.

Next, start the CLI and run the following commands:



With the first command, we have created an Handler which points to the external folder with static content. Please note that you can also enable directory listing through the property “directory-listing”.

Next, we have added the Handler to the default Undertow server and bound it to the location “/static”.

Therefore, if you request the http://localhost:8080/static path, you will be able to see the directory listing for the external folder:

Here is the server configuration after our updates:

<subsystem xmlns="urn:jboss:domain:undertow:12.0" default-server="default-server" default-virtual-host="default-host" default-servlet-container="default" default-security-domain="other" statistics-enabled="${wildfly.undertow.statistics-enabled:${wildfly.statistics-enabled:false}}">
    <buffer-cache name="default"/>
    <server name="default-server">
        <http-listener name="default" socket-binding="http" redirect-socket="https" enable-http2="true"/>
        <https-listener name="https" socket-binding="https" ssl-context="applicationSSC" enable-http2="true"/>
        <host name="default-host" alias="localhost">
            <location name="/" handler="welcome-content"/>
            <location name="/static" handler="images"/>
            <http-invoker http-authentication-factory="application-http-authentication"/>
    <servlet-container name="default">
        <file name="welcome-content" path="${jboss.home.dir}/welcome-content"/>
        <file name="images" path="/home/francesco/Pictures" directory-listing="true"/>
        <application-security-domain name="other" security-domain="ApplicationDomain"/>

Configuring static resources at application level

In the above example, we have defined an Handler that you can use for any Web application running on Undertow. If you want a more fine-grained approach, you can bundle your application with a jboss-web.xml file. Within this file, we will use the overlay element to to define separate context-roots for your Web application.


<jboss-web xmlns=""

If you want to learn more about using the deployment overlay feature check this article: How to add a web fragment to all applications deployed on WildFly

How to use CSS in Web applications running on WildFly

Finally, in the last part of this article we will learn how to link a CSS to a Web page which is part of a Web application

The first step, is to include a link to the CSS in the HTML (or .xhtml) page:

	<link rel="stylesheet" type="text/css" href="resources/css/style.css" />

Next, place the css file in the href location starting from the webapp virtual folder of Maven. For example:

$ tree webapp
├── index.xhtml
├── resources
│   └── css
│       └── style.css
    └── web.xml

Then, you will be able to display the style.css page from within your index.html.


In this article we have discussed several strategies to serve static content (such as images or CSS) from an external directory of your file system.