Configuring WildFly to run inside Docker
Containerising an older version of Wildfly to allow us to go faster
WildFly is the open source Java Application Server (AS) that grew out of JBoss. There are many other AS platforms out there including Glassfish, Apache Tomcat and Oracle's Web Application server.
At my current role at MyTutor we had part of our system running on Wildfly in a baremetal VM. The old school way of deploying to these AS services starts with building a WAR (Web ARchive Java application).
This is then uploaded or deployed automatically to Wildfly which executes the Java app. Which can then be accessed via Wildfly's servlet container.
The version of Wildfly we were using was quite old and we were limited with upgrading it without breaking our Java application. So as a quick win we decided to containerise Wildfly to allow us to easily scale up and deploy the Java application anywhere without having to curate a virtual machine and configure and maintain it by hand.
This post covers WildFly 11 (11.0.0.Final), which runs on Java 8 in the official image.
Running it in Docker
To get a server running straight away:
docker run -p 8080:8080 -p 9990:9990 -it jboss/wildfly:11.0.0.Final /opt/jboss/wildfly/bin/standalone.sh -b 0.0.0.0 -bmanagement 0.0.0.0
This pulls the WildFly 11 image from Docker Hub and starts it in standalone mode. Two ports are published to the host:
8080for HTTP (your applications)9990for the management console and the HTTP management API
By default WildFly binds to 127.0.0.1, which inside a container means only the container can reach it. -b 0.0.0.0 binds the public interface to all addresses, so a browser on the host can reach port 8080. The image's default command already passes that flag. -bmanagement 0.0.0.0 does the same for the management interface on 9990, and it's the reason for overriding the command here.
Browse to http://localhost:9990 and you get an error page instead of the console. WildFly ships without any management users. That's the first reason to move on from the one-liner.
A Dockerfile
FROM jboss/wildfly:11.0.0.Final
RUN /opt/jboss/wildfly/bin/add-user.sh admin Admin#2021 --silent
CMD ["/opt/jboss/wildfly/bin/standalone.sh", "-b", "0.0.0.0", "-bmanagement", "0.0.0.0"]
add-user.sh adds a user to the ManagementRealm (stored in mgmt-users.properties), and --silent stops it prompting for input. Build and run the image, log in at http://localhost:9990 and the console appears.
A password baked into an image layer can be read by anyone who can pull the image (docker history will show it). That's fine for a local development box and nowhere else.
The tag is pinned to 11.0.0.Final. Leave it off and Docker pulls latest, which is a newer WildFly than the one this post describes.
Deploying an application
WildFly runs a deployment scanner over standalone/deployments. Put a WAR in that directory and it deploys within a few seconds; replace it and it redeploys.
To bake the application into the image, add one line to the Dockerfile:
COPY target/my-app.war /opt/jboss/wildfly/standalone/deployments/
For local development a mounted volume is more convenient, since you can rebuild the WAR without rebuilding the image. That's where Docker Compose comes in.
docker-compose.yml
version: '3'
services:
wildfly:
build: .
ports:
- "8080:8080"
- "9990:9990"
volumes:
- ./deployments:/opt/jboss/wildfly/standalone/deployments
Start it with docker-compose up --build, then copy your WAR into ./deployments on the host.
The scanner writes marker files next to each archive (my-app.war.deployed on success, my-app.war.failed with the error otherwise). They show up in the host directory too, so add deployments/ to .gitignore. The .failed file is the first place to look when nothing appears on port 8080.
On Linux, check file ownership. The container runs as the jboss user (UID 1000), and if it can't write to the mounted directory the scanner can't write its marker files either. Docker for Mac handles this for you.
Changing the server configuration
Sooner or later standalone.xml needs changing: a datasource, a log level, a system property. You can edit the XML by hand and copy it into the image, but a hand-edited copy is easy to break and hard to review.
The better option is a CLI script, run against an embedded server while the image builds. Create config.cli:
embed-server --server-config=standalone.xml --std-out=echo
/system-property=app.environment:add(value=local)
/subsystem=logging/logger=com.example:add(level=DEBUG)
stop-embedded-server
Then run it from the Dockerfile:
COPY config.cli /tmp/config.cli
RUN /opt/jboss/wildfly/bin/jboss-cli.sh --file=/tmp/config.cli \
&& rm -rf /opt/jboss/wildfly/standalone/configuration/standalone_xml_history/current
embed-server starts WildFly inside the CLI process without opening any network ports, so it works during docker build. The commands are the same ones you would type into a live CLI session. That makes it easy to try them against a running container first and copy them into the script once they work:
docker-compose exec wildfly /opt/jboss/wildfly/bin/jboss-cli.sh --connect
The rm -rf removes the history directory the embedded server leaves behind. Without it, the server can fail on first boot when it tries to rename that directory (a known quirk of how Docker's layered filesystem handles directory renames).
Datasources take more work, because the JDBC driver has to be installed as a module or deployment first. That's a post of its own.
Remote debugging
standalone.sh takes a --debug flag, which starts the JVM with a debug agent on port 8787. Override the command in docker-compose.yml and publish the port:
version: '3'
services:
wildfly:
build: .
command: /opt/jboss/wildfly/bin/standalone.sh -b 0.0.0.0 -bmanagement 0.0.0.0 --debug
ports:
- "8080:8080"
- "9990:9990"
- "8787:8787"
volumes:
- ./deployments:/opt/jboss/wildfly/standalone/deployments
Then point your IDE's remote debugger at localhost:8787. On Java 8 the agent listens on every interface when given a bare port number, so nothing else is needed for the host to reach it.
Conclusion
Everything here is pinned to 11.0.0.Final, so the server won't change underneath you. Moving to a newer WildFly is a one-line change to the FROM tag, followed by finding out which lines of config.cli the new version no longer accepts.
Further reading
- Enable WildFly remote access (bgasparotto)
- How to Set Up a WildFly Server (Baeldung)
- WildFly Administration Remote Access (Baeldung)