Building a Wildfly Cluster Using Docker

Hi there!

Using Docker to deal with some daily challenges could be a funny and also rewarding stuff. Sometimes I got amazed on how somethings are easily handled using containers.

My last challenge was building a Wildfly cluster using Docker.

Why Wildfly? Because I like it. Why Docker? Because I love it.


If you are anxious and wanna go straight to the point, here is the link where you can clone and run the example by yourself:

If you wanna understand what the heck I did there, let’s go!

Domain x Standalone

I was tempted to go with a Domain cluster for reasons that I just can’t remember. After got my head knocked for a couple of hours I discovered that a domain cluster cannot be used in the way that I would like to.

Why? Because when you use Wildfly in Domain mode you don’t have a deployment scanner. It means that you have to do your deployment with it’s UI or thru a CLI.

Well none of them were ok to me, because I was trying to build a Docker Appliance. What is a Docker Appliance?

Docker Appliance is a Docker image customized for your own needs specially when you use it to distribute your own application

This quote was said by me… right here, right now…

My intention here is to build a Docker Wildfly image with an application so it can be automatically deployed when a new container is built from that appliance.

The only option for me is the Standalone mode. So let’s get rid of Domain mode for now.

Docker Network

This was the last thing I fixed in order to make the things work, but as I am cool with you I’ll talk about it as first step.

Having a network well defined for your containers will be key for the configurations that I’ll show bellow, so let’s build it:

docker network create \
 --driver=bridge \
 --subnet= \
 --ip-range= \
 --gateway= \

You can use whichever subnet, range and gateway that you want. Just do it properly.

Ah… “wildnetwork” is the name of the network that is being created. Yeah, baby… it’s a wild wild world…


If you go to the “${WILDFLY_HOME}\standalone\configuration” folder you will find these files:


The default is the “standalone.xml”. If you want to use some cool Wildfly features you can use the other files. For this example we will use the “standalone-ha.xml” (when we run the containers).

We had to customize this file for each container. As we are using three containers for this example, we did three versions of this file (you’ll see it in the Dockerfile bellow).

You need to open the file, find the “interfaces” node and do something like this:

<interface name="management">
<inet-address value="${}"/>
<interface name="public">
<inet-address value="${jboss.bind.address:}"/>
<interface name="private">
<inet-address value="${jboss.bind.address.private:}"/>

Of course use the right IP…


You will build your appliance with a Dockerfile. For this example, my Dockerfile is just like this:

FROM jboss/wildfly

# Environment variable with default value
ARG APP_FILE=appfile.war

# Add your application to the deployment folder
ADD ${APP_FILE} /opt/jboss/wildfly/standalone/deployments/${APP_FILE}

# Add standalone-ha.xml - set your own network settings
ADD standalone-ha-1.xml /opt/jboss/wildfly/standalone/configuration/standalone-ha-1.xml
ADD standalone-ha-2.xml /opt/jboss/wildfly/standalone/configuration/standalone-ha-2.xml
ADD standalone-ha-3.xml /opt/jboss/wildfly/standalone/configuration/standalone-ha-3.xml

# Add user for adminstration purpose
RUN /opt/jboss/wildfly/bin/ admin admin123 --silent


  • “FROM” will get a pre-built image from Docker Hub (or locally if you have already used it before);
  • “ARG” is a environment variable. I use it to pass the application file as an argument and make my Dockerfile more flexible and reusable;
  • “ADD” will add the application to the deployment folder, and any other file that I want (as the standalone*.xml)
  • “RUN” line will create a “admin” user with “admin123” password. This can be useful if you want to log into the administration UI.

Now I am ready to build the appliance and run the containers.

Image (Appliance) and Containers

Now we can build our customized image (appliance):

docker build -t wildfly-cluster --build-arg APP_FILE=apptest.war .

So this single line command will build a image (appliance) called “wildfly-cluster” deploying the “apptest.war”. Don’t forget the dot at the end, this means that there is a Dockerfile at the current folder.

Ah… the “apptest.war” must be at the current folder too.

Image built. Let’s run the containers and put some fire at the… oh, forget it:

docker run -d --name wild1 -h wild1 -p 8080:8080 -p 9990:9990 --network=wildnetwork --ip wildfly-cluster /opt/jboss/wildfly/bin/ -c standalone-ha-1.xml -u
docker run -d --name wild2 -h wild2 -p 8081:8080 -p 9991:9990 --network=wildnetwork --ip wildfly-cluster /opt/jboss/wildfly/bin/ -c standalone-ha-2.xml -u
docker run -d --name wild3 -h wild3 -p 8082:8080 -p 9992:9990 --network=wildnetwork --ip wildfly-cluster /opt/jboss/wildfly/bin/ -c standalone-ha-3.xml -u

Lot of things happening:

  • “-d” will detach the console from the terminal so you won’t see the log messing your screen;
  • “–name” will name the container (wild1, wild2, wild3)
  • “-h” will name the host
  • “-p” will expose the ports that I want/need and give alias to them
  • “–network” will specify the Docker network that I want to use
  • “–ip” will define the IP. This is VERY VERY important in order to make the cluster works
  • “wildfly-cluster” is the image used (our appliance)
  • “/opt/jboss…/” is the script used to start the Wildfly in the container
  • “-c standalone-ha-1.xml” will specify the configuration file for this container (details above in the Standalone.xml section);
  • “-u” is specifying the IP used for the multicast

Finally we put them all together and happy with a load balancer:

docker run -d --name wild-balancer -p 80:80 \
  --link wild1:wild1 \
  --link wild2:wild2 \
  --link wild3:wild3 \
  --env-file ./env.list \
  --network=wildnetwork \
  --ip jasonwyatt/nginx-loadbalancer

The “–env-file” argument is passing a file that has some important environment variables for the load balancer. Clone the repository to see the details.

If you came until here you probably wanna see if it works! Just open your browser and go to the link:


You should see a result like this:

Note that while we are refreshing the page the IP and Hostname changes, but the Session ID does not. It means that the cluster is working and it is caching the session between the nodes.

If the session changes, something gone bad… 😦

Like it? Leave a comment! Didn’t like it? Also leave a comment and let’s talk about it! 😉


P.S.: I should also say that some links helped me to write this post:


Author: Elder Moraes

Helping server side developers to create and deliver secure, available and fast server side applications, so they can work on great projects.

5 thoughts on “Building a Wildfly Cluster Using Docker”

  1. Ola Elder parabens pelo post, mas eu fiquei com uma duvida rodando os comandos eu tive o seguinte erro
    docker: Error response from daemon: No such network: wildnetwork.
    comando que dodei:
    sudo docker run -d –name wild2 -h wild2 -p 8081:8080 -p 9991:9990 –network=wildnetwork –ip wildfly-cluster /opt/jboss/wildfly/bin/ -c standalone-ha-2.xml -u

    sera que vc poderia ma ajudar por favor? estou tentando montar um cluster com wildfly.


  2. Hi Elder

    great description – thank you very much.

    I used it but changed the way you handle the standalone-ha.xml in that way, that I let the file as per default but added the IP address to the Wildfly Docker container by using


    ENV IPADDRESS=$(ifconfig | grep -A 1 ‘eth0’ | tail -1 | cut -d ‘:’ -f 2 | cut -d ‘ ‘ -f 1)

    then I started the wildly simply with -c standalone-ha.xml -Djboss.bind.address=${IPADDRESS}${IPADDRESS} -Djboss.bind.address.private=${IPADDRESS} -u ${MCASTADDRESS}

    Both included in the Dockerfile of the Wildfly.

    The result is, that you do not need to pre create standalone-ha.xml files and you can start more than three instances without poroblems by using the “-ip” tag in ‘docker run’.

    Second effect is the environment variable “MCASTADDRESS”. I have defined a default in the Dockerfile (see above) but can handle and change it on runtime by using it as a “–env MCASTADDRESS=XXX.XXX.XXX.XXX” parameter.

    Both helped me a lot to become more efficient and I can generally use such a container.

    Hope to find more or your great tips!!


  3. Well Elder Moraes, creating a wildfly domain cluster with load balancing is very simple now. With wildfly running in Domain mode, You just have to create back-end servers under a group having full-ha and full-ha-sockets, then single server under a group having load-balancer profile and load-balancer-sockets. Then accessing web application through the load balancer server you will see that load balancer server directs requests to the back-end servers


  4. Hi Elder, I tried something like you explained, the difference is that we are using docker swarm, and when the wildfly containers are deployed in different worker nodes, they aren’t able to see each other, and the cluster can’t be created.

    When we run on a single machine (our laptops), the cluster goes up normally.

    Any idea? My guess is that docker swarm doesn’t allow multicast across nodes.


Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google+ photo

You are commenting using your Google+ account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )


Connecting to %s