Getting started with WildFly 8

This is Chapter one sample from WildFly8 Administration guide. Enjoy it!

Chapter 1: Installation

In this chapter we will move our first steps with the new release of the application server by learning the following topics:

  • A brief introduction to the changes and enhancements introduced in WildFly 8
  • How to install and verify the installation of the application server
  • How to create a management user which will be in charge to handle server administration
  • Installing the application server as a service using Windows or Linux environment

What is new in WildFly 8?

The new release of the application server contains several enhancements over the AS7/EAP6 baseline both in terms of Administration and in terms of development API. Let’s see a drill down of the changes you are going to experience:

Java SE 7 baseline

The first upgrade we will mention is the new Java SE baseline: as a matter of fact the new release of the application server has been built using a Java SE 7 and thus requires that you have a matching Java 7 installation on your machine. Java 7 provides improvements in many areas such as the Java language, Input/Output libraries and Garbage collector policies. For full details about these enhancements visit the Oracle official release notes page at: http://www.oracle.com/technetwork/java/javase/jdk7-relnotes-418459.html

Administration changes

The new application server greatly improves the administration areas by providing the following features:

  • Fine Grained Administration Control: before WildFly 8, administrative users were not associated with a particular role, in other words, once created a Management user then you are entitled to perform any change to the server configuration like a classic super user. Now you can associate each Management user with one role and even configure constraints which allow you to tweak the behavior of roles.
  • New Web Server: WildFly 8 has switched to a different Web Server implementation named Undertow which is an embeddable Web server providing both blocking and non-blocking API’s based on NIO. Besides the API enhancements, the Undertow Web server can provide better flexibility thanks to its composition based architecture that allows you to build a Web server by combining small single purpose handlers. More details about the Undertow Web server are contained in chapter 5 of this book.
  • Richer Management Interfaces: WildFly 8 can use a richer set of management commands which have been added to the Command Line Interface such as the ability to patch the module baseline, thus avoiding costly server installations in order to solve some issues. Also the Web Administration Console has been greatly improved allowing a complete management of the application server subsystem along with a comprehensive set of performance indicators.
  • Simplified socket management: The new release of the application server uses a reduced number of ports, multiplexing invocations over the HTTP channel; as a consequence, administrators and your security staff will spend less time in setting up firewall policies.

Besides this, take in consideration that in the Final release of WildFly 8 the new public API classes will have the org.wildfly package whereas existing ones will continue to have what they had (like org.jboss.*).

New Java EE 7 API

The last area of improvement is in the Java Enterprise API which now fully supports Java EE 7. Some of the major enhancements included in the application server include:

  • WebSocket 1.0: Before the advent of HTML 5, the traditional request-response model used in HTTP meant that the client requested resources and the server provided responses. Therefore, unless you are continuously polling the server, there is no way to way to provide dynamic changes to your Web pages. The WebSocket protocol addresses these limitations by providing a full-duplex communication channel between the client and the server without any latency problem. Combined with other client technologies, such as JavaScript and HTML5, WebSocket enables web applications to deliver a richer user experience.
  • Java API for JSON Processing 1.0 (JSON-P): This API elevates the capabilities of JSON based applications by defining new API to parse, generate, transform and query JSON documents. Therefore you will be able to build a JSON object model (just like you did with DOM for XML based applications) and consume them in a streaming fashion (as you did with XML using StAX).
  • Batch Application API 1.0: this API has been designed to standardize batch processing for Java applications. You can think of it as a replacement for your older, bulk, long running procedures that were managed by shell scripting or dated languages such as COBOL. The new Batch API provides a rich programming model oriented to batch scripting which allows defining, partition and forking the execution of jobs.
  • Concurrency Utilities for Java EE 1.0:  this API is an extension to the Java SE Concurrency Utility (JSR-166) which aims to provide a simple and standard API for using Concurrency from Java Enterprise components preserving the container integrity. This API can be used along with asynchronous processing APIs in Servlets or for creating custom executors in advanced use cases.
  • Other API enhancements: besides the additions mentioned so far, there are further enhancements in existing areas such the JAX-RS 2.0, which now includes a Client API for async processing, a matching Server side asynchronous HTTP response and the addition of Filter and Interceptors for proxying REST communications. Another area of improvement is the JMS 2.0 API which now delivers a JMSContext resource as a wrapper for JMS Connection, Session and Message Producer objects plus several enhancements such as the simplified ConnectionFactory injection (which has finally a platform default) or the inclusion of delayed delivery and async send. Other minor improvements are spread across the entire API (e.g. EJB 3.2, Servlet 3.1, EL 3.0, CDI 1.1 etc.). If you want to learn more details about it please consult the official Java EE 7 tutorial at: http://docs.oracle.com/javaee/7/tutorial/doc/

Installing WildFly 8

The pre-requisite to the Application Server installation is that you have available a JDK 1.7 on your machine. Once installed the JDK, you have to set the JAVA_HOME environment variable accordingly. See the following frame if you don’t know how to do it:

Windows users: Right click on the My Computer icon on your desktop and select properties. Then select the Advanced Tab contained in the Environment Variables button.

Under System Variable, click New. Enter the variable name as JAVA_HOME and value the Java install path.  Click OK and Click Apply Changes.

Linux users: Enter in your .profile / .bash_profile script the following (substitute with the actual JDK installation path):

export JAVA_HOME=/usr/java/jdk1.7.0_45

Done with JDK installation, let’s move to the application server. WildFly 8 can be downloaded from http://www.wildfly.org by following the Downloads link in the home page which will take you to the following screen:

wildfly 8 book guide jboss bookOnce downloaded, extract the archive to a folder and you are done with the installation.

unzip wildfly-8.0.0.CR1.zip
 wildfly 8 book guide jboss book

Linux users should be aware that running WildFly as the root user could lead to security breaches; therefore if you installed the application server in a folder owned by root (e.g. /usr/share), change its ownership so that it can be executed by another user without super-user privileges. 

You can optionally set the JBOSS_HOME environment variable to the location where WildFly is installed. This will enable starting the application server which is located on a different path of your file system.  For example Linux users:

export JBOSS_HOME=/usr/share/wildfly-8.0.0.CR1

A look into the application server file system

Once unzipped, the application server will create the following file structure on your file system:

wildfly 8 book guide jboss book 

As you can see, the WildFly file system is divided into two main parts: the first one which is pertinent to a standalone server mode and the other which is dedicated to domain server mode. Common to both server modes is the modules directory which is the heart of the application server.

And here’s some detail about the application server folders:

  • appclient: contains configuration files, deployment content, and writable areas used by the application client container run from this installation.
  • bin: contains start up scripts, startup configuration files and various command line utilities like vault.sh, add-user.sh. Inside the client subfolder, you can find a client jar for use by non-maven based clients. The other folders (service, init.d) are used respectively to install WildFly as a Service on Windows and Linux machines.
  • docs/schema:             contains the XML schema definition files 
  • docs/examples/config: contains some sample standalone configurations (such as standalone-minimalistic.xml).
  • domain: contains domain configuration files, server data and writable areas used by the domain mode processes.
  • modules: contains all the modules installed on the application server.
  • standalone: contains configuration files, deployment content, and writable areas used by the single standalone server run from this installation.
  • welcome-content: contains content related to the default (ROOT) web application.

Starting WildFly 8

The application server ships with two server modes: standalone and domain mode. The difference between the two modes is not about the functionalities available but is related to the management of the application server: in particular, domain is used when you run several instances of WildFly and you want a single point where you can manage servers and their configuration (see chapter 2 for more information about the different server modes).

In order to start WildFly using the default configuration in "standalone" mode, change directory to $JBOSS_HOME/bin and issue:

./standalone.sh

To start the application server using the default configuration in "domain" mode, change directory to $JBOSS_HOME /bin.

./domain.sh

In the server console, you should find something like this, at the end of startup process:

22:51:41,490 INFO  [org.jboss.as] (Controller Boot Thread) JBAS015961: Http management interface listening on http://127.0.0.1:9990/management

22:51:41,494 INFO  [org.jboss.as] (Controller Boot Thread) JBAS015951: Admin console listening on http://127.0.0.1:9990

22:51:41,495 INFO  [org.jboss.as] (Controller Boot Thread) JBAS015874: WildFly 8.0.0.CR1 "WildFly" started in 44700ms - Started 182 of 219 services (62 services are lazy, passive or on-demand)

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 following address: http://localhost:8080

wildfly 8 book guide jboss book 

Application server bootstrap configuration

If you had a quick look in the bin folder of your server installation you should have discovered a large amount of shell scripts which serve to different purposes. In particular a couple of them named standalone.conf and domain.conf (standalone.conf.bat and domain.conf.bat for Windows users) are executed on server boot in standalone mode and domain mode. These script files can be used for a variety of purposes such as setting JVM settings of the standalone server or of the domain controller. Another possible use of this file is setting the application server’s home directory.

Setting the JBOSS_HOME configuration variable is not a mandatory step. By defining it in your bootstrap file (or in your user's profile), you are specifying the folder where WildFly distribution is located. The impact on your administration is that you can use the standalone/domain startup script from a different location than the server distribution. The reverse side of the coin is that this can lead to confusion your server administrator especially if you have this variable buried in one of the many Linux configuration files. For this reason we would rather discourage the usage of this environment variable.

Your first task: create an user to manage WildFly

If you want to manage the application server configuration using its management instruments you need to create a management user.

In order to create a new user, just execute the add-user.sh/add-user.bat which is located in the bin folder of the application server’s home. Here’s a transcript of the creation of a management user:

What type of user do you wish to add?

 a) Management User (mgmt-users.properties)

 b) Application User (application-users.properties)

(a): a

Enter the details of the new user to add.

Using realm 'ManagementRealm' as discovered from the existing property files.

Username : wildflyadmin

Password requirements are listed below. To modify these restrictions edit the add-user.properties configuration file.

. . . .

Password :

Re-enter Password :

What groups do you want this user to belong to? (Please enter a comma separated

list, or leave blank for none)[  ]:

About to add user 'wildflyadmin' for realm 'ManagementRealm'

Is this correct yes/no? yes

Added user 'wildflyadmin' to file 'C:\jboss\wildfly-8.0.0.CR1\standalone\configuration\mgmt-users.properties'

. . . .

Is this new user going to be used for one AS process to connect to another AS process?

e.g. for a slave host controller connecting to the master or for a Remoting connection for server to server EJB calls.

yes/no? yes

To represent the user add the following to the server-identities definition <secret value="RXJpY3Nzb24xIQ==" />

In the above example we have created a management user named “wildflyadmin” which belongs to the ManagementRealm and is not part of any group of users (See Chapter 12 which is about Security for more information about it). Also, mind to answer the last question with yes or y to indicate that the user will be used to connect to the domain controller from the host controller. The generated secret value is the Base64-encoded password of the new created user and we will use it when setting up a Domain of application servers.

Since WildFly 8 there is a stricter control over the password you choose for your users. If you want to loosen or strengthen the password checks you can edit the add-user.properties file which is contained in the bin folder as well.

 wildfly 8 book guide jboss book

The user that we have just created will grant us access both for the application server in Standalone mode and for the Domain mode.

Creating an user in non-interactive mode

You can also create users using non-interactive mode. In the following example we are adding a management (-m flag) user by issuing:

add-user.bat -m -u administrator1 -p password1!

If you need adding an application user, you need to include as well the -a flag as in the following example, where we are setting as well a group to which the user belongs (See the Chapter 12 for more information about User groups):

add-user.bat -a -u applicationuser1 -p password1! -g guest

Bear in mind that as side effect the user credentials will be visible in the OS process table, if you are using a Linux/Unix machine.

Stopping WildFly

The simplest way to stop the application server is by sending an interrupt signal with Ctrl+C to the server console. Linux/Unix users might as well have a look at the process table with the “ps” command and issue a “kill” to stop the application server.

On the other hand, the recommended approach is to use the Command Line Interface (CLI) interface to issue an immediate shutdown command. The CLI interface can be started from the $JBOSS_HOME/bin folder of your installation:

./jboss-cli.sh

Windows user will start the CLI using the equivalent batch file:

jboss-cli.bat

Once there, issue the connect command:

[disconnected /] connect

Connected to localhost:9990

Now issue the shutdown command that will stop the application server:

[localhost:9990 /] shutdown

If you want to issue a command like shutdown in no-interactive mode, you can use as well the following syntax:

jboss-cli.bat -c --command=shutdown
 wildfly 8 book guide jboss book

As we said for the add-user script using the non-interactive mode is discouraged for application servers running in production as it shows the user credentials in the process table. Consider using it for learning/development purposes.

Stopping WildFly running on a remote host

If you are connecting to a remote WildFly instance, then a password will be requested when you issue the CLI command:

[disconnected /] connect 192.168.10.1

Username: wildflyadmin

Password:

Connected to 192.168.10.1:9990

Once connected, we will issue the shutdown command just like we did from the local host:

[192.168.10.1:9990 /] shutdown

Installing WildFly as Service

WildFly can be as well installed as a service and allowed to be started at boot time. In order to do that, you need to use some script files which are contained within the server. The next two sections (one for Linux users and one for Windows users) discuss about it:

Linux users

In order to start the application server as service using a Linux distribution you can use the scripts which are located under the JBOSS_HOME/bin/init.d folder. If you look into this folder, you will find the following files:

  • wildfly-init-redhat.sh : this file needs to be used for Red Hat Enterprise-like Linux distributions (e.g. RHEL, Centos)
  • wildfly-init-debian.sh: this file needs to be used for Debian-like Linux distributions (e.g. Debian, Ubuntu)
  • wildfly.conf: this file contains the configuration used by the above init files

As first step, copy the shell script which is required by your Linux distribution into the /etc/init.d folder. For example, if we were to install WildFly as a service on RHEL:

[root@dev2 init.d]# cp wildfly-init-redhat.sh /etc/init.d/wildfly

Now we will copy as well the wildfly.conf configuration file in the location where the startup script expects it:

[root@dev2 init.d]# mkdir –p /etc/default

[root@dev2 init.d]# cp wildfly.conf /etc/default

Within the wildfly.conf file adjust the settings in order to fit your installation:

JAVA_HOME=/usr/java/jdk1.7.0_21

# Location of WildFly
JBOSS_HOME=/usr/share/wildfly.8.0.0.Final

# The username who should own the process.
JBOSS_USER=wildfly

# The mode WildFly should start, standalone or domain
JBOSS_MODE=standalone

# Configuration for standalone mode
JBOSS_CONFIG=standalone.xml

Next, we will use the chkconfig command to install the EAP as a service: the first command will add the wildfly shell script to the chkconfig list:

[root@dev2 init.d]# chkconfig --add wildfly 

The second one, sets the boot levels where the service will be started:

[root@dev2 init.d]# chkconfig --level 2345 wildfly  on

In order to test that the service starts correctly issue:

service wildfly  start

And here's the corresponding service stopping:

service wildfly  stop

Windows users

Installing WildFly 8 as a service on Windows is much simpler than the older AS7/EAP6 counterpart. As a matter of fact it’s not necessary to install any third party native library because WildFly 8 already ships with all you need. So move to the JBOSS_HOME/bin/service folder.

If you want to install WildFly 8 as a service in standalone mode simple issue:

service install

Now you can use the Windows Services tab in order to manage the service start/stop

As an alternative you can use the service command to perform basic service management (start/stop/restart). Example:

service restart

Installing WildFly 8 in domain mode requires that you specify some additional settings such as the Domain controller (default 127.0.0.1 on port 9990) and the host name we are going to start (default “master”).

service install /controller localhost:9990 /host master

The concept of Domain controller deserves some additional explanations; luckily you don’t need to wait so long for it, as next chapter discusses in detail about the server configuration (standalone mode and domain mode).

Francesco Google+