NOTE - this is the WildFly deployment guide. Information on installing and tuning WildFly is found in the WildFly Installation and Tuning User Guide.
WildFly is the continuation of the open source JBoss Application Server (JBoss AS) project. The project was renamed by Red Hat in order to differentiate the open source JBoss AS project from the commercial Red Hat JBoss Middleware project. More information about WildFly can be found here - What Is WildFly?
One of the main advantages of WildFly is the Undertow web server. Undertow was built to be fast, lightweight, and scalable to over a million connections. If you are deploying a high performance, single purpose application, Undertow is the best choice. More information about Undertow can be found here - Undertow Web Server.
There are two operating modes for WildFly deployment: as a Standalone server, and as a Managed Domain
Standalone server: a Standalone server is a single instance of WildFly running as an independent process. The eApps default operating mode for WildFly deployment is a Standalone server.
Managed Domain: a Managed Domain is a collection of WildFly server instances managed from a single control point. Managed domains can span multiple physical or virtual servers. This is an advanced configuration. More information about setting up a Managed Domain can be found here - WildFly Managed Domains.
More information about WildFly Operating Modes can be found here - WildFly Operating Modes.
The default deployment approach for WildFly at eApps is to have Apache as the front-end for WildFly and to use either mod_jk or mod_proxy_ajp to pass requests from the Apache web server to WildFly. This allows the Apache web server to serve static content and applications that require Apache (PHP or HTML applications), and the Undertow web server that is built-in to WildFly to serve JSPs and Servlets.
If you do not need to serve PHP or HTML applications and want to maximize the performance of your WildFly server you can turn off and disable the Apache web server. This will allow you to configure the Virtual Server to pass all requests directly to the Undertow web server included with WildFly.
This User Guide explains how to configure WildFly to serve applications in Standalone server mode either with or without Apache, and also how to upload and deploy your WAR file using the WildFly Administration Console.
 |
This user guide uses WildFlyX or wildflyX to refer to WildFly versions. Please make sure to substitute your version of WildFly (wildfly8/WildFly 8, wildfly9/WildFly 9, or wildfly10/WildFly 10 where applicable). |
----- With Apache -----
WildFly Deployment in Standalone Mode with Apache
mod_jk and mod_proxy_ajp Deployment
Deployment examples using WildFly in Standalone mode with Apache
Deployment example with WildFly serving JSP and Servlet using a WAR file from the domain directory, Apache serving all other content
Deployment example with WildFly serving JSP and Servlet using a WAR file from a subdirectory, Apache serving all other content
----- Without Apache -----
WildFly Deployment in Standalone Mode without Apache
Stopping Apache and Configuring the Port Redirect
Configure ISPmanager 4 to run on its own web server and port
Deployment examples using WildFly in Standalone mode without Apache
Deployment example with WildFly serving JSP and Servlets using a WAR file from the domain directory
Deployment example with WildFly serving JSP and Servlets using a WAR file from a subdirectory
----- Completing Your Deployment using the WildFly Admin Console -----
Deploying your application using the WildFly Administration Console
Upload your WAR file
Create the Virtual Host
Enable your WAR file
Using mod_jk or mod_proxy_ajp you can have the Apache web server as a front-end to WildFly. This is the most common usage at eApps, because it allows you to serve applications that require Apache along with your Java application being served by WildFly.
Both mod_jk and mod_proxy_ajp work by using directives to send requests to the Apache web server to files or applications as specified by the directive. For example, this allows you to pass all requests for .php files to Apache, and all requests for .jsp files to WildFly.
mod_jk – this is the most common way of configuring WildFly and Apache. mod_jk is older and a bit more robust than the newer mod_proxy_ajp. With mod_jk you specify directives that tell Apache whether to pass the request on to WildFly, or if Apache will handle the request itself. mod_jk is installed as part of the CentOS WildFly (ISPmanager CP) template.
mod_proxy_ajp – similar to using mod_jk, in that you have to specify directives to forward requests from Apache to WildFly. mod_proxy_ajp is built into the Apache web server starting with version 2.2.
Both mod_jk and mod_proxy_ajp work in a very similar manner. If you have a preferred approach, use that. If you do not have a preferred approach, use mod_jk.
There are two ways to deploy applications using WildFly in Standalone mode with Apache:
Deployment with WildFly serving JSP and Servlets using a WAR file from the domain directory, Apache serving all other content using mod_jk or mod_proxy_ajp
Deployment with WildFly serving JSP and Servlets using a WAR file from a subdirectory, Apache service all other content using mod_jk or mod_proxy_ajp
This deployment example assumes you have a WAR file called mywebapp.war, using a Virtual Host of eapps-example.com.
For this deployment approach to work, you will need to add the following in your WEB-INF/jboss-web.xml file:
<jboss-web>
<context-root>/</context-root>
<virtual-host>eapps-example.com</virtual-host>
</jboss-web>
To serve eapps-example.com using mod_jk, add the following directive to the VirtualHost block for the website. The mod_jk directives in this example will serve all applications provided by eApps but forward all other requests to WildFly.
You can all the directives to the VirtualHost block from the Control Panel or from the command line.
Using a Control Panel
ISPmanager 4 - go to Domains > WWW Domains and select the domain where you want to add the mod_jk directives. Click on Config, and then add your mod_jk directives near the end of the file, just above the closing </VirtualHost> tag. More information about managing WWW Domains in ISPmanager 4 can be found here - Managing WWW Domains
ISPmanager 5 - go to Domains > Web-domains and select the domain where you want to add the no_jk directives. Click on Config, and then add your mod_jk directives near the end of the file, just above the closing </VirtualHost> tag. More information about managing Web-domains in ISPmanager 5 can be found here - Managing Web-domains
Information on how to tell which version of ISPmanager you are using can be found here - ISPmanager versions
JkMount /* ajp13
# Directives to enable Apache to continue serving applications dependent on it.
SetEnvIf Request_URI "/webmail" no-jk
SetEnvIf Request_URI "/awstats" no-jk
SetEnvIf Request_URI "/myadmin" no-jk
SetEnvIf Request_URI "/pgadmin" no-jk
SetEnvIf Request_URI "/cgi-bin" no-jk
SetEnvIf Request_URI "/joomla" no-jk
SetEnvIf Request_URI "/wordpress" no-jk
SetEnvIf Request_URI "/drupal" no-jk
SetEnvIf Request_URI "/mailman" no-jk
Depending on the applications you have installed, you may need different (or additional or fewer) no-jk settings.
If you are using ISPmanager 4, make a note of these three "no-jk" directives:
SetEnvIf Request_URI "/manager/ispmgr*" no-jk
SetEnvIf Request_URI "/manimg*" no-jk
SetEnvIf Request_URI "/mancgi*" no-jk
These are the directives that allow the ISPmanager 4 Control Panel to still be available, even if everything else is being forwarded to WildFly. These must be included if you still want to use ISPmanager 4.
Once you have added the settings, click Ok to restart Apache.
Using the command line
You can also add the directives to the VirtualHost block for the website in the httpd.conf file, and then restart Apache.
To serve eapps-example.com using mod_proxy_ajp, add the following directive to the VirtualHost block for the website. The mod_proxy_ajp directives in this example will serve all applications provided by eApps but forward all other requests to WildFly.
You can all the directives to the VirtualHost block from the Control Panel or from the command line.
Using a Control Panel
ISPmanager 4 - go to Domains > WWW Domains and select the domain where you want to add the mod_proxy_ajp directives. Click on Config, and then add your mod_proxy_ajp directives near the end of the file, just above the closing </VirtualHost> tag. More information about managing WWW Domains in ISPmanager 4 can be found here - Managing WWW Domains
ISPmanager 5 - go to Domains > Web-domains and select the domain where you want to add the mod_proxy_ajp directives. Click on Config, and then add your mod_proxy_ajp directives near the end of the file, just above the closing </VirtualHost> tag. More information about managing Web-domains in ISPmanager 5 can be found here - Managing Web-domains
Information on how to tell which version of ISPmanager you are using can be found here - ISPmanager versions
# Directives for your application
ProxyPass / ajp://localhost:8009/
ProxyPassReverse / ajp://localhost:8009/
# Directives for eApps applications dependent on Apache
ProxyPass /webmail !
ProxyPass /joomla !
ProxyPass /awstats !
ProxyPass /myadmin !
ProxyPass /cgi-bin !
ProxyPass /pgadmin !
Depending on the applications you have installed, you may need different (or additional or fewer) ProxyPass settings.
If you are using ISPmanager 4, make a note of these three "mod_proxy_ajp" directives:
ProxyPass /manager/ispmgr !
ProxyPass /manimg !
ProxyPass /mancgi !
These are the directives that allow the ISPmanager 4 Control Panel to still be available, even if everything else is being forwarded to WildFly. These must be included if you still want to use ISPmanager 4.
Once you have added the settings, click Ok to restart Apache.
Using the command line
You can also add the directive to the VirtualHost block for the website in the httpd.conf file, and then restart Apache.
This deployment example assumes you have a WAR file called mywebapp.war, using a Virtual Host of eapps-example.com.
For this deployment approach to work, you will need to add the following in your WEB-INF/jboss-web.xml file:
<jboss-web>
<context-root>/mywebapp</context-root>
<virtual-host>eapps-example.com</virtual-host>
</jboss-web>
To serve eapps-example.com/mywebapp using mod_jk, add the following directive to the VirtualHost block for the website. The mod_jk directives in this example will serve all applications provided by eApps but forward all other requests to WildFly.
You can all the directives to the VirtualHost block from the Control Panel or from the command line.
Using a Control Panel
ISPmanager 4 - go to Domains > WWW Domains and select the domain where you want to add the mod_jk directives. Click on Config, and then add your mod_jk directives near the end of the file, just above the closing </VirtualHost> tag. More information about managing WWW Domains in ISPmanager 4 can be found here - Managing WWW Domains
ISPmanager 5 - go to Domains > Web-domains and select the domain where you want to add the no_jk directives. Click on Config, and then add your mod_jk directives near the end of the file, just above the closing </VirtualHost> tag. More information about managing Web-domains in ISPmanager 5 can be found here - Managing Web-domains
Information on how to tell which version of ISPmanager you are using can be found here - ISPmanager versions
JkMount /mywebapp* ajp13
This directive passes all requests for /mywebapp to WildFly, and allows Apache to serve all other content.
Once you have added the settings, click Ok to restart Apache.
Using the command line
You can also add the directive to the VirtualHost block for the website in the httpd.conf file, and then restart Apache.
To serve eapps-example.com/mywebapp using mod_proxy_ajp, add the following directive to the VirtualHost block for the website. The mod_proxy_ajp directives in this example will serve all applications provided by eApps but forward all other requests to WildFly.
You can all the directives to the VirtualHost block from the Control Panel or from the command line.
Using a Control Panel
ISPmanager 4 - go to Domains > WWW Domains and select the domain where you want to add the mod_proxy_ajp directives. Click on Config, and then add your mod_proxy_ajp directives near the end of the file, just above the closing </VirtualHost> tag. More information about managing WWW Domains in ISPmanager 4 can be found here - Managing WWW Domains
ISPmanager 5 - go to Domains > Web-domains and select the domain where you want to add the mod_proxy_ajp directives. Click on Config, and then add your mod_proxy_ajp directives near the end of the file, just above the closing </VirtualHost> tag. More information about managing Web-domains in ISPmanager 5 can be found here - Managing Web-domains
Information on how to tell which version of ISPmanager you are using can be found here - ISPmanager versions
ProxyPass /mywebapp ajp://localhost:8009/mywebapp
Once you have added the settings, click Ok to restart Apache.
Using the command line
You can also add the directive to the VirtualHost block for the website in the httpd.conf file, and then restart Apache.
This directive passes all requests for /mywebapp to WildFly, and allows Apache to serve all other content.
If you do not need to use Apache, you can run WildFly directly from the built-in Undertow web server. This approach is often used when the Virtual Server will do nothing but serve the production Java application - there will be no other applications such as WordPress or Webmail available.
In order to run WildFly in Standalone mode without Apache, you will need to disable the Apache web server, and then redirect traffic from the port Apache listens on to the port used by WildFly. If you still wish to use the ISPmanager 4 Control Panel, you can configure it to run using its own web server and port. The ISPmanager 5 Control Panel needs no additional configuration - it is set up to run using its own web server and port by default.
Using the WildFly Administration Console, you can deploy your WAR file and set up your WildFly Virtual Host. Then you can set up your application deployment approach depending on how you have configured your WEB-INF/jboss-web.xml file.
See the section of this User Guide titled Deploying your application using the WildFly 8 Administration Console for more information on deploying your WAR files. How to disable Apache, set up ISPmanager to run using its own web server, and set up your jboss-web.xml file for you application deployment approach is covered below.
WildFly cannot run on port 80 because root privileges are required. Since WildFly does not have the ability to start as root, bind to port 80, then switch back to a user without administrative privileges it would have to run as root. This creates a security issue for your system.
To use WildFly in Standalone mode without Apache, you will need to add a file to the /etc/xinted.d directory that will keep WildFly running on port 8080, and have any requests to port 80 redirected to WildFly.
All of this must be done from the command line of the Virtual Server, as the root user. See the SSH User Guide for more information if needed.
To stop Apache, you need to stop the httpd service. Once the httpd service is stopped, you will need to prevent it from starting again at the next Virtual Server reboot.
For CentOS 6, use the service httpd stop command to stop the service, and the chkconfig httpd off command to prevent it from starting again.
[root@eapps-example ~]# service httpd stop
[root@eapps-example ~]# chkconfig httpd off
For CentOS 7, use the systemctl stop httpd command to stop the service, and the systemctl disable httpd command to prevent it from starting again.
[root@eapps-example ~]# systemctl stop httpd
[root@eapps-example ~]# systemctl disable httpd
To set up the redirect so that requests on port 80 are redirected to port 8080, change directories to /etc/xinetd.d, and create the wildfly file:
[root@eapps-example ]# cd /etc/xinetd.d
[root@eapps-example xinetd.d]# vim wildfly
Using a text editor (this example uses the vim editor), add these lines to the wildfly file:
# Redirects any requests on port 80
# to port 8080 (where WildFly is listening)
service http
{
socket_type = stream
user = root
wait = no
redirect = localhost 8080
disable = no
}
Save and exit the file, and then restart the xinetd service.
For CentOS 6, use the service xinetd restart command:
[root@eapps-example ~]# service xinetd restart
For CentOS 7, use the systemctl restart xinetd command:
[root@eapps-example ~]# systemctl restart xinetd
ISPmanager 4 uses the Apache web server and runs on port 80 by default. If you will want to use the ISPmanager 4 Control Panel while running WildFly without Apache you will need to make the following changes. Note that ISPmanager 5 is already set up to run with its own web server by default - no changes are needed for ISPmanager 5.
Information on how to tell which version of ISPmanager you are using can be found here - ISPmanager versions
|
This will break the ability to access ISPmanager 4 from the Customer Portal for this Virtual Server. All access to ISPmanager 4 will have to be done using a direct URL - https://IP_ADDRESS:1500 (note the https), where IP_ADDRESS is the main IP address of the Virtual Server |
To start ISPmanager 4 running using its own web server and port, run the following command as the root user: /usr/local/ispmgr/sbin/ihttpd IP_ADDRESS 1500 where IP_ADDRESS is the main IP address for your Virtual Server.
[root@eapps-example ~]# /usr/local/ispmgr/sbin/ihttpd IP_ADDRESS 1500
To make sure that ISPmanager 4 starts at system boot, you will also need to either add or edit a line in /etc/rc.local. Depending on the age of your Virtual Server, your rc.local file may contain the following lines:
/var/lock/subsys/local
# /usr/local/ispmgr/sbin/ihttpd 69.89.2.169 1500
Uncomment the /usr/local/ispmgr/sbin/ihttpd 69.89.2.169 1500 line, and change the IP address to match the main IP address of the Virtual Server. Save and exit the file.
If your rc.local file does not already contain the /usr/local/ispmgr/sbin/ihttpd 69.89.2.169 1500 line, add that line to the file, and make sure to use the main IP address of your Virtual Server. Save and exit the file.
The file should look like this when you are done. Remember to substitute the main IP address of the Virtual Server for IP_ADDRESS.
/var/lock/subsys/local
/usr/local/ispmgr/sbin/ihttpd IP_ADDRESS 1500
When the Virtual Server is rebooted, this will make sure that ISPmanager 4 is available at the direct URL of https://IP_ADDRESS:1500 (note the https).
There are two ways to deploy applications using WildFly in Standalone mode without Apache:
Deployment with WildFly serving JSP and Servlets using a WAR file from the domain directory
Deployment with WildFly serving JSP and Servlets using a WAR file from a subdirectory
This deployment example assumes you have a WAR file called mywebapp.war, using a Virtual Host of eapps-example.com.
For this deployment approach to work, you will need to add the following in your WEB-INF/jboss-web.xml file:
<jboss-web>
<context-root>/</context-root>
<virtual-host>eapps-example.com</virtual-host>
</jboss-web>
This deployment example assumes you have a WAR file called mywebapp.war, using a Virtual Host of eapps-example.com.
For this deployment approach to work, you will need to add the following in your WEB-INF/jboss-web.xml file:
<jboss-web>
<context-root>/mywebapp</context-root>
<virtual-host>eapps-example.com</virtual-host>
</jboss-web>
To deploy your application from the WildFly Administration Console, you will need to do the following:
Log in to the WildFly Administration Console to upload your WAR file. To access the Administration Console, go to http://eapps-example.com:9990 (substitute your domain name or IP address for eapps-example.com).
The User Name and Password for the Administration Console is located in a file on the Virtual Server - /opt/wildflyX/.mgmtsecret.
Once you are logged in to the WildFly Administration Console, click on the Deployments menu at the top of the screen.
In the Deployments screen, click on Add. This opens the Create Deployment dialog, on the Deployment Selection screen.
Click on Choose File, and browse on your local computer to the location of your WAR file. Select it, and click Open. This will show the name of your WAR file in place of No File Chosen. Click Next.
This takes you to the Verify Deployment Names screen, where you see the Name and Runtime Name of your WAR file.
DO NOT CLICK ENABLE. Click on Save. This takes you back to the Deployments screen, showing your WAR file as Deployed, but not Enabled.
|
The Virtual Host created from the Administration Console for WildFly is NOT the same as a Virtual Host created for the Apache Web server. If you are using a mod_jk or mod_proxy_ajp deployment you will still need to create the Virtual Host for the domain in Apache along with the Virtual Host in WildFly. |
After you have uploaded and deployed your WAR file, you will need to create the Virtual Host in the WildFly Administration Console. To do this, click on the Configuration tab, and go to Subsystems > Web > HTTP.
In the middle of the screen, under Option, click on View. This takes you to the HTTP Listener screen. On this screen, click on Hosts. This takes you to the Host Setting screen.
Click on Add. This takes you to the Create HOST dialog.
Once you have entered the information, click Save. This adds the Virtual Host to WildFly.
After you have added the Virtual Host to WildFly, you can enable the WAR file. Click on Deployments, and then click on the name of the WAR file to highlight it (this will put a small blue triangle to the left of the file name). Click En/Disable to enable the deployment. You will need to confirm that you want to enable the application. Once you have done this, your deployment will be enabled.
At this point your application is enabled and available. Test by going to the URL defined in your deployment method.
