WildFly Configuration, Deployment, and Administration

WildFly is written in Java; therefore it needs a Java Virtual Machine (JVM) in which to run, along with the standard edition Java libraries. So, before we can get started setting up or learning about WildFly, we first need to install the Java Development Kit (JDK).

To use WildFly, you will need at least Java SE 7 or above. Although there is no plan to use Java 8 language changes within the WildFly 8.x source code, WildFly is compiled against Java 8. It is recommended that you use the latest version of Java SE 8 to run WildFly.

So, let's move to the Oracle download page, http://www.oracle.com/technetwork/java/javase/downloads/index.html, which now hosts all JDK downloads, as shown in the following screenshot:

This will take you to the download page for the latest JDK. At the time of writing, this was Java 8 update 5. You will need to accept the license agreement before downloading the JDK. Choose to download the latest version of Java for your operating system. Have a look at the following screenshot:

The download will take a few minutes depending how fast your network is.

tar -xzvf jdk-8u5-linux-x64.tar.gz

export JAVA_HOME=/installDir/jdk1.8.0_05
export PATH=$JAVA_HOME/bin:$PATH

The WildFly application server can be downloaded for free from the WildFly site, http://www.wildfly.org/downloads/. Have a look at the following screenshot:

You will notice that there is an option to download a minimalistic core distribution. This is aimed at developers who want to build their own application runtime using the WildFly 8 architecture.

Choose to download the full Java EE7 distribution. Like JBoss AS 7, WildFly does not come with an installer. It is simply a matter of extracting the compressed archive to a location of your choosing.

Linux users can extract the file using the tar or unzip command (depending on the type of compressed file you downloaded):

tar -xzvf wildfly-8.1.0.Final.tar.gz
unzip wildfly-8.1.0.Final.zip

For those of you using Windows, you can use WinZip or WinRAR, taking care to choose a folder that does not contain empty spaces.

After installing WildFly, it is wise to perform a simple startup test to validate that there are no problems with your Java configuration. To test your installation, move to the bin directory of your WildFly install and issue the following command:

The following screenshot shows a sample WildFly 8 startup console:

The preceding command starts up a WildFly standalone instance that's equivalent to starting the application server with the run.sh script used by releases prior to JBoss AS 7. The run.sh file remains in the WildFly bin directory but is merely a placeholder and will not start the application server.

Notice how fast the application server starts. This is due to the modular architecture of WildFly. Essential services are started concurrently on boot-up, and non-critical services are started only when needed, resulting in an exceptionally fast startup. Local caching means that the server will start even quicker second time round!

If you need to customize the startup properties of your application server, then you need to open and modify the standalone.conf file (or standalone.conf.bat for Windows users). This file contains the memory requirements of WildFly. The following is the Linux core section of it:

if [ "x$JAVA_OPTS" = "x" ]; then
   JAVA_OPTS="-Xms64m -Xmx512m -XX:MaxPermSize=256m -Djava.net.preferIPv4Stack=true"
   JAVA_OPTS="$JAVA_OPTS -Djboss.modules.system.pkgs=$JBOSS_MODULES_SYSTEM_PKGS -Djava.awt.headless=true"
fi

By default, the application server starts with a minimum heap space memory requirement of 64 MB and a maximum requirement of 512 MB. This will be just enough to get started; however, if you need to run a core Java EE application on it, you will likely require a minimum of 1 GB of heap space. More realistically, you will need 2 GB or more depending on your application type. Generally speaking, 32-bit machines cannot execute a process whose space exceeds 4 GB; however, on 64-bit machines, there's essentially no limit to process the size.

You can verify that the server is reachable from the network by simply pointing your browser to the application server's welcome page, which is reachable by default at the well-known address: http://localhost:8080. Have a look at the following screenshot:

Connecting to the server with the command-line interface

If you have been using releases of the application server prior to JBoss AS 7, you might have heard about the twiddle command-line utility that queries the MBeans installed on the application server. This utility was replaced in JBoss AS 7 and is still used in WildFly. Its replacement is a more sophisticated interface named the command-line interface (CLI), which can be found in the JBOSS_HOME/bin folder.

Tip

References to JBOSS_HOME

Although the community version of JBoss AS has been renamed to WildFly, you will see that the properties in the startup scripts continue to use the property, JBOSS_HOME, to reference the install directory of WildFly. For this reason, we will continue to use JBOSS_HOME when referring to the root install of WildFly.

Just launch the jboss-cli.sh script (or jboss-cli.bat for Windows users), and you will be able to manage the application server via a shell interface, as shown in the following screenshot. Bear in mind that the server needs to be running in order to connect via the CLI.

Once you are in the shell session, if you are unsure of what commands can be issued, you can simply press the Tab button to display all possible commands. If your command is partly typed, and there is only one possible matching command, your command will be autocompleted. Those of you who use Linux will be used to this type of command-line assistance.

In the preceding screenshot, we have just connected to the server using the connect command, which, by default, uses the loopback server address and plugs into port number 9990.

Note

The CLI is discussed in depth in Chapter 7, Using the Management Interfaces, which is all about the server-management interfaces. We will have an initial taste of its basic functionalities in the following sections, to get you accustomed to this powerful tool.

Probably the easiest way to stop WildFly is to send an interrupt signal using Ctrl + C. This should be done in the same console window in which you issued the startup command, that is, where the server is running.

However, if your WildFly process was launched in the background or is running on another machine (see in the following sections), then you can use the CLI interface to issue an immediate shutdown command as follows:

[disconnected /] connect
[standalone@localhost:9990 /] shutdown
[disconnected /]

jboss-cli.sh --connect command=:shutdown       # Unix / Linux
jboss-cli.bat --connect command=:shutdown      # Windows

[disconnected /] connect 192.168.1.10

[192.168.1.10:9990 /] shutdown

The CLI contains a lot of useful commands. One of the most helpful options is the ability to reload all or part of the server configuration using the reload command.

When issued on the root node path of the server, WildFly reloads all the services configuration, as shown in the following command:

[disconnected /] connect

[standalone@localhost:9990 /] reload

Although the main focus of this book is the administration of the WildFly application server, we are also concerned with application packaging and deployment. For this reason, we will sometimes add examples that require a development environment to be installed on your machine.

The development environment used in this book is Eclipse. Eclipse is known by developers worldwide and contains a huge set of plugins, building on its core functionality. If you are comfortable with another IDE, then feel free to use it, but this book will demonstrate Eclipse only. At the time of writing this, only Eclipse and NetBeans have plugins for WildFly.

So let's move to the Eclipse download page, located at http://www.eclipse.org/downloads.

From this page, download the latest Enterprise edition. The compressed package contains all the Java EE plugins already installed and requires about 248 MB of disk space. Have a look at the following screenshot:

Once you have downloaded Eclipse, unzip it to a folder of your choice. The extracted folder will be called eclipse. To start Eclipse, navigate to the eclipse folder and run:

$ ./eclipse

Windows users can simply double-click on the executable file contained in the eclipse folder (the one with the big, blue, round eclipse icon).

The bin folder is where you will find all your startup scripts, such as standalone.sh and domain.sh. In addition to the startup scripts, you can find standalone.conf, which can be used to customize WildFly's bootstrap process.

As you saw earlier, the bin folder also includes the jboss-cli.sh script (jboss-cli.bin for Windows users), which starts the interactive CLI. You will also find various other useful scripts, such as add-user.sh and vault.sh. This folder also contains the web services utility scripts (wsconsume.sh and wsprovide.sh) used to generate the web services definition language and the corresponding Java interfaces.

There are several subfolders within the bin directory. The service folder and the init.d folder contain programs that allow you to install WildFly as service on Windows and Linux, respectively.

The docs folder contains two subfolders, examples and schema. The schema folder contains all the .xsd schema definition files used by the configuration as schema.

The examples folder contains numerous configuration examples, from a minimalistic standalone example to an ec2 HA example (HA meaning high availability, and ec2 referring to Amazon Elastic Compute Cloud).

The next folder is the domain folder, which contains the domain structure split across a set of folders:

If you are running the application server in standalone mode, this is the part of the filesystem you will be interested in. Its structure is quite similar to the domain folder with the notable exception of a deployment folder. Let's proceed with order. Just below the standalone folder, you will find the following set of subdirectories:

The content and use of these subdirectories is explained as follows:

The welcome-content folder contains the default page, which is loaded when you browse to the root of your application server (http://localhost:8080). In terms of web server configuration, this is the Web root context.

Beneath the modules folder, you will find the application server's set of libraries, which are a part of the server distribution.

Historically, JBoss AS releases used to manage their set of libraries in different ways. Let's recap to bring about some order. Earlier, Release 4.x was used to define the core server libraries into the JBOSS_HOME/server libraries. Thereafter, each server definition had its specific library in the server/<servername>/lib folder.

This approach was pretty simple, however, it led to a useless proliferation of libraries that were replicated in the default/all server distribution.

Releases 5.x and 6.x had the concept of the common/lib folder, which was the main repository for all modules that were common to all server definitions. Each server distribution still contained a server/<servername>/lib path for the libraries that were specific to that server definition. Unchanged from the earlier release was the repository for core server modules comprised by JBOSS_HOME/server.

JBoss AS 7 followed a more modular approach improving over all the earlier approaches. This modular approach remains unchanged in WildFly. The server bootstrap library, jboss-modules.jar, can be found in the root of the application server. This single archive is all you need to bootstrap WildFly's application server kernel.

The main system modules are located in the system/layers/base folder under the modules folder. This has changed slightly in WildFly as, in JBoss AS 7, all modules were defined directly in the modules folder.

The following table outlines the diverse approaches used across different server releases:

Listing all the modules will take up too much space, however, the module repository layout is often the same as the module name. For example, the org.jboss.as.ejb3 module can be found in the org/jboss/as/ejb3 subfolder of the modules folder. This approach to organizing the modules certainly makes sense, and if you are used to a maven repository layout structure, you will have no problem getting your head around it.

In the last section of this chapter, we will see how modules are actually loaded by the application server.

WildFly's kernel was redesigned in JBoss AS 7. Understanding the details of the modular kernel will help you understand concepts introduced later in the book. The kernel is based on two main projects, as follows:

The following diagram depicts the basic architecture of WildFly's server kernel:

With this information, we can now progress to the loading of server modules.

Learning more about JBoss modules is essential if you want to understand the server configuration discussed in the next few chapters. At its heart, a module is really just a wrapper for a JAR file but treated by the application container as a module. The reason for this is class loading and dependency management, as each module can be treated as a pluggable unit, as depicted by the next diagram. WildFly has two different types of modules; the only difference between them is the way they are packaged:

Have a look at the following screenshot:

Using a static module is the simplest way to load a module, and it's used as the default module when starting up the application server. Static modules are defined within the JBOSS_HOME/modules/system/layers/base directory. Each module has a configuration file called module.xml. The following example shows the contents of the javax.batch.api module.xml file:

<module xmlns="urn:jboss:module:1.3" name="javax.batch.api">
    <resources>
        <resource-root path="jboss-batch-api_1.0_spec-1.0.0.Final.jar"/>
    </resources>
    <dependencies>
        <module name="javax.api"/>
        <module name="javax.enterprise.api"/>
    </dependencies>    
</module>

As you can see, a module definition contains two main elements, the resources defined in the module (and their path) and the module's dependencies. In this example, the main resource is jboss-batch-api_1.0_spec-1.0.0.Final.jar, contained in the same folder as the module.xml file. It has dependencies on two other modules, javax.api and javax.enterprise.api.

A module which is defined with a main-class element is said to be executable. In other words, the module name can be listed on the command line, and the standard static main(String[]) method in the named module's main-class will be loaded and executed.

The other way to approach the module repository is by using dynamic modules. This can be achieved in two ways, as follows:

We will cover this in more detail in Chapter 6, Application Structure and Deployment, in which we explain class loading.