Java applications

Octopus Deploy comes with a number of steps that allow you to deploy and modify the state of Java applications for popular Java application servers.

In addition, Java packages like jar, war, ear and rar files can be managed as part of the Octopus Deploy library.

Supported application servers

The following application servers are supported by Octopus Deploy:

• Tomcat 7 and above
• Red Hat JBoss EAP 6 and above
• WildFly 10 and above

Deploying Java applications via Octopus

Regardless of which application server you are deploying to, there are a number of common steps that need to be performed.

1. Push a package to Octopus

For a package to be made available to the deployment steps, it first must be added to the Octopus library.

The Octopus library accepts files with the jar, war, ear and rar file extensions.

The package filenames have to adhere to the standard Octopus versioning rules, which are based on the SemVer format.

Valid packages can then be added to the library using the web based interface, or using the CLI tool.

Building SemVer Compatible Artifacts

The most common incompatibility between Maven and SemVer formatting comes from the use of a dash to separate the package name from the version.

For example, by default Maven will build artifacts with names like myapplication-1.0.0-SNAPSHOT.war. To be managed by the built in Octopus library, this filename needs to be in the format myapplication.1.0.0-SNAPSHOT.war.

The easiest way to generate the correct filenames in a Maven build is to set the finalName element to <finalName>${project.name}.${project.version}</finalName>.

The following xml is a snippet from a pom.xml file that defines the finalName option in a SemVer compatible format.

<?xml version="1.0" encoding="UTF-8"?>
<project
xmlns="http://maven.apache.org/POM/4.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
  <build>
    <finalName>${project.name}.${project.version}</finalName>
  </build>
</project>

Gradle builds can define the filename through the war.archiveName property.

The following code is a snippet of a build.gradle file that defines the name of the WAR file in a SemVer compatible format.

apply plugin: 'java'
apply plugin: 'war'

group = 'com.example'
version = '0.0.1-SNAPSHOT'

war.archiveName "${project.name}.${version}.war"

2. Ensure the target meets the minimum requirements

The target machine must have Java 1.8 installed, and the java executable must either be on the path, or the JAVA_HOME environment variable must be set.

Deploying to Tomcat via the Manager

The Deploy to Tomcat via Manager step takes advantage of the Manager application shipped with Tomcat to deploy Java applications. The following steps describe the process of deploying a web application (a WAR package) to Tomcat through Octopus Deploy.

1. Configure Tomcat

Tomcat needs to be configured with a user that Octopus can use to log into the Manager API.

Tomcat users are defined in the $CATALINA_HOME/conf/tomcat-users.xml file. The user that will deploy the applications must be added to the manager-script group.

Here is an example of a $CATALINA_HOME/conf/tomcat-users.xml file that defines a user called tomcat in the manager-script group.

<?xml version='1.0' encoding='utf-8'?>
<tomcat-users>
    <role rolename="manager-script"/>
    <user username="tomcat"
          password="thepassword"
          roles="manager-script"/>
</tomcat-users>

See the Tomcat documentation for more details on the groups used by the manager application.

<multipart-config>
  <max-file-size>262144000</max-file-size>
  <max-request-size>262144000</max-request-size>
  <file-size-threshold>0</file-size-threshold>
</multipart-config>

2. Populate the Tomcat deployment step

The Deploy to Tomcat via Manager step is used to deploy a package from the Octopus library to Tomcat. The following steps can be used to deploy an application to a Tomcat server.

• Select the Package feed and Package ID that references the Java application to be deployed.
• Define the Context path. This can be the root context with a path of /, a simple path like myapplication, or a nested path like myapplication/v1.
• If you want to take advantage of Tomcat’s parallel deployment features, you need to define the populate Deployment Version field. To be effective, these values are required to increase with each deployment . Common values are the Octopus release number, which is defined in the #{Octopus.Release.Number} variable. The package version number can also be used, and is defined in the #{Octopus.Action.Package.NuGetPackageVersion} variable.
• Define the path to the Tomcat Manager. The path is relative to the target machine that is running the step, and includes the manager application context path. In most cases the target machine is also the machine hosting Tomcat, so this URL will typically point to localhost. Common examples of the manager URL are http://localhost:8080/manager.
• Supply the Management User and Management Password of the user was defined using the instructions from Configure Tomcat.
• The Start/Stop the Deployment option allows you to deploy the application in a started or stopped state. Typically you will deploy in a started state.

Deploying to Tomcat via Manager step details

Deploying to WildFly/JBoss EAP

The Deploy to WildFly or Red Hat JBoss EAP step uses the management API to deploy applications and change their state. The following steps describe the process of deploying a web application (a WAR package) to WildFly or JBoss EAP through Octopus Deploy.

1. Configure authentication

You have two options for authenticating with WildFly and JBoss EAP servers.

The easiest solution is to use silent authentication. Silent authentication allows local users to log into the management API without supplying any credentials, and because Octopus typically executes a deployment from the same machine that is hosting the application server, it is treated as a local user.

To take advantage of silent authentication, the user running the Octopus deployment on the target machine (i.e the user assigned to the Tentacle service in Windows or the SSH user in Linux or MacOS) must have access to the auth directory inside the directory defined by the jboss.server.temp.dir variable. By default this directory will be located at $JBOSS_HOME/standalone/tmp/auth or $JBOSS_HOME/domain/tmp/auth.

The second option is to use the application server add-user script to create a new user, and use these credentials in the Octopus deployment steps.

2. Populate the WildFly/JBoss EAP deployment step

The Deploy to WildFly or Red Hat JBoss EAP step is used to deploy a package from the Octopus library to a WildFly or Red Hat JBoss EAP instance.

• Select the Package feed and Package ID that references the Java application to be deployed.
• Optionally set the Deployment Name, which will define the name of the deployment in the WildFly deployment library. For example, deploying a file from the Octopus library with the filename myapplication.0.0.1.war and setting this field to myapplication.war will mean the deployment is listed in WildFly as myapplication.war. If this field is left blank, the original file name will be used by WildFly. For example, deploying a file from the Octopus library with the filename myapplication.0.0.1.war and leaving this field blank will mean the deployment is listed in the application server as myapplication.0.0.1.war.
• Set the Management Host or IP field to the address that the WildFly management interface is listening to. This value is relative to the target machine that is performing the deployment. Since the target machine performing the deployment is typically the same machine hosting the application server, this value will usually be localhost.
• Set the Management Port to the port bound to the WildFly management interface. For WildFly 10+ and JBoss EAP 7+, this will default to 9990. For JBoss EAP 6, this will default to 9999.
• The Management Protocol field defines the protocol to be used when interacting with the management interface. For WildFly 10+ and JBoss EAP 7+, this will default to http-remoting or remote+http (the two are equivalent). For JBoss EAP 6, this will default to remoting.
• If you wish to use silent authentication, and have configured the required permissions for the $JBOSS_HOME/standalone/tmp/auth or $JBOSS_HOME/domain/tmp/auth directory, then the Management User and Management Password fields can be left blank. Alternatively these fields can hold the credentials that were configured via the add-user script.
• If you are deploying to a standalone server, the deployment can be enabled or disabled using the Enable/Disable the Deployment field. This field has no effect when deploying to a domain controller.
• If you are deploying to a domain controller, the server groups that will have the deployment enabled must be specified in the Enabled Server Groups field. Likewise the server groups that will have the deployment disabled must be specified in the Disabled Server Groups. Multiple server groups can be specified separated by a comma. These fields has no effect when deploying to a standalone server.

Defining context paths

There are multiple ways that the context of an application deployed to WildFly and JBoss EAP is defined.

The WEB-INF/jboss-web.xml file inside a war package can define the context path. For example a war package with the following jboss-web.xml file will be deployed to the /myapplication context.

<jboss-web>
    <context-root>myapplication</context-root>
</jboss-web>

If not defined in the jboss-web.xml file, the context of a war file will default to the filename of the deployment. For example, a war file called myapplication.war will be deployed to the context /myapplication.

If the war file has the special name ROOT.war it will be deployed to the root context.

See Setting the context root of a web application for more information.

The context of a web application can also be defined in the application.xml file inside a ear package. For example, package module-web-1.0-SNAPSHOT.war in an ear package with the following application.xml file would de be deployed to the /custom-context-root context.

<?xml version="1.0" encoding="UTF-8"?>
<application xmlns="http://xmlns.jcp.org/xml/ns/javaee" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://xmlns.jcp.org/xml/ns/javaee http://xmlns.jcp.org/xml/ns/javaee/application_7.xsd" version="7">
  <display-name>module-ear</display-name>
  <module>
    <web>
      <web-uri>module-web-1.0-SNAPSHOT.war</web-uri>
      <context-root>/custom-context-root</context-root>
    </web>
  </module>
</application>

The context that an application has been deployed to is shown in the WildFly logs. Look for an entry with the text Registered web context.

2017-09-05 02:57:15,598 INFO  [org.wildfly.extension.undertow] (ServerService Thread Pool -- 77) WFLYUT0021: Registered web context: /custom-context-root

WildFly/JBoss EAP deployment step details

Starting/Stopping Tomcat applications

The Start/Stop App in Tomcat step is used to start or stop applications that have already been deployed to Tomcat. The following steps can be used to start or stop an application deployed to a Tomcat server.

• Define the Context path of the deployed application to start or stop. This can be the root context with a path of /, a simple path like myapplication, or a nested path like myapplication/v1.
• Define the Deployment Version of the deployed application to start or stop. Leave this field blank to modify the state of an unversioned Tomcat deployment.
• Define the path to the Tomcat Manager. The path is relative to the target machine that is running the step. In most cases the target machine is also the machine hosting Tomcat, so this URL will typically point to localhost. Common examples of the manager URL are http://localhost:8080/manager.
• Supply the Management User and Management Password of the user was defined using the instructions from Configure Tomcat.
• The Start/Stop the Deployment option allows you to start or stop the deployed application.

Starting/Stopping Tomcat applications step details

Enabling/Disabling WildFly and EAP applications

The Enable/Disable deployment in WildFly step is used to modify the state of a deployed application. The following steps can be used to enable or disable an application deployed to an application server.

• Define set the Deployment Name of the application to be enabled or disabled.
• Set the Management Host or IP field to the address that the WildFly management interface is listening to. This value is relative to the target machine that is performing the deployment. Since the target machine performing the deployment is typically the same machine hosting WildFly, this value will usually be localhost.
• Set the Management Port to the port bound to the WildFly management interface. For WildFly 10+ and JBoss EAP 7+, this will default to 9990. For JBoss EAP 6, this will default to 9999.
• The Management Protocol field defines the protocol to be used when interacting with the management interface. For WildFly 10+ and JBoss EAP 7+, this will default to http-remoting or remote+http (the two are equivalent). For JBoss EAP 6, this will default to remoting.
• If you wish to use silent authentication, and have configured the required permissions for the $JBOSS_HOME/standalone/tmp/auth or $JBOSS_HOME/domain/tmp/auth directory, then the Management User and Management Password fields can be left blank. Alternatively these fields can hold the credentials that were configured via the add-user script.
• If you are deploying to a standalone server, the deployment can be enabled or disabled using the Enable/Disable the Deployment field. This field has no effect when deploying to a domain controller.
• If you are deploying to a domain controller, the server groups that will have the deployment enabled must be specified in the Enabled Server Groups field. Likewise the server groups that will have the deployment disabled must be specified in the Disabled Server Groups. Multiple server groups can be specified separated by a comma. These fields has no effect when deploying to a standalone server.

Enabling/Disabling WildFly and EAP applications step details

Deploy via package copy

The Deploy Java Archive step is used to copy a Java archive to the target machine’s filesystem. This step is not tied to any particular application server, and can be used to deploy applications to any server that will accept files copied into a deployment directory.

The following steps can be used to deploy an application via a file copy to an application server.

• Select the Package feed and Package ID that references the Java application to be deployed.
• Unselect the Explode option. This means we will be copying a repacked package instead of the extracted contents of the original package.
• Select the Custom Deploy Directory option.
• Set the Deploy Directory field to the location within the application server where deployments are located. For WildFly or JBoss EAP, this will be a directory like $JBOSS_HOME/standalone/deployments, and for Tomcat it will be $CATALINA_HOME/webapps.
• Set the Deployed Package File Name field to a filename that reflects the desired context path.
  • For WildFly or JBoss EAP, the filename will be used for the context. For example, setting Package file name to myapplication.war will result in the application being deployed under the /myapplication context. See Defining Context Paths for more information.
  • For Tomcat the filename takes the form context#subcontext##version.war. For example, setting Package file name to myapplication#v1##10.war will result in the application being deployed under the context myapplication/v1 with a Tomcat version of 10. The version and sub-context are optional, so you could set Package file name to myapplication.war, in which case Tomcat would deploy the application under the /myapplication context with no version information.
• Unselect the Purge option because we don’t want to uninstall any existing applications in the deployment directories.

Deploy Java archive step details

Variable substitution in Java packages

Octopus provides the ability to replace variables in packages during deployment. This is done using a specific syntax implemented by the Octostache library.

The syntax used by Octostache and Java libraries such as Spring do overlap, so care must be taken to ensure that files intended to be used as Octostache templates during deployment don’t interfere with local development.

For example, you may have a application.properties file that defines an environment variable which reflects the environment that the application has been published to.

environment: #{Environment}

This file is expected to be used as an Octostache template during deployment, but when testing locally you will receive an error like Unsatisfied dependency expressed through field 'environment';. This is because during local development the template file has not been processed, and the common syntax between Spring and Octostache means Spring is attempting to resolve the variable Environment, which doesn’t exist.

Spring profiles provide a convenient way to load valid properties files for local development, while leaving environment specific templates for deployments processed by Octopus.

For example, you may create a file called application-dev.properties with the following settings:

environment: Development

Maven can then be instructed to active the dev profile for testing:

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
  <build>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-surefire-plugin</artifactId>
        <configuration>
          <argLine>-Dspring.profiles.active=dev</argLine>
        </configuration>
      </plugin>
    </plugins>
  </build>
</project>

Gradle can do the same:

test {
    systemProperties = [
            "spring.profiles.active": "dev"
    ]
}

Now local testing is done against a valid properties file, while the main application.properties file is used a template during deployment to environments managed by Octopus.

Error messages

The Java deployment steps include a number of unique error codes that may be displayed in the output if there was an error. Please see the error codes and troubleshooting page for more details.

Learn more

• Generate an Octopus guide for Java, Tomcat, and the rest of your CI/CD pipeline.
• Java blog posts
• Webinar: Octopus 101: Deploy Your First Java Application
• Install Tomcat Runbook example.

Help us continuously improve

Please let us know if you have any feedback about this page.

Send feedback

Page updated on Wednesday, October 4, 2023