This guide goes through each step to demonstrate how to deploy Java packages, a WAR file here, from Octopus Deploy to your Tomcat server.
Octopus Deploy has a large collection of useful steps (both included and community provided) that can be used to deploy packages to a variety of different destinations and via different methods.
Fortunately, these same deployment steps can be used to deploy Java packages to Java web servers running in Linux out of the box.
There are some caveats, which I will call out. The Octopus Deploy team is actively investigating how to improve support for Java, so expect to see improvements for Java developers in coming releases.
The following steps provide an example of the process that can be implemented with Octopus Deploy to deploy a WAR file to a Tomcat server running in Linux.
First, I am going to assume that you have a Maven project building a WAR file handy. If not, there is a small demo application at https: //github.com/OctopusDeploy/ThymeleafSpringDemo that will be used for this example.
This project uses the Maven wrapper, so all Maven commands are passed through the mvnw script. This script will download and install the appropriate version of Maven for you if it is not already locally available, and then pass the arguments to the mvn executable.
To build the WAR file, run the command:
This will result in the file demo## .war (e.g. demo##201705290808.war) being created in the target directory.
The timestamp component of the WAR file is used by the Tomcat parallel deployment feature. It allows Tomcat to drain connections to old versions of the web application, while directing new traffic to the latest version.
This is where some of the conventions required by Octopus Deploy differs from those typically used by Java.
To upload a package to Octopus Deploy, it must follow a number of versioning rules. In practice, this means creating a ZIP or tar.gz archive with a file name like demo.0.0.1.zip .
In Java, versioning is mostly done by way of Maven. Additionally, the WAR file created above embeds a timestamp version into the WAR file name itself, which is recognized by Tomcat. Octopus Deploy, on the other hand, uses SemVer. All these versioning schemes are mostly incompatible, and the built-in repository currently does not support WAR files, which means we can’t upload the WAR file as-is.
The solution is to pack the WAR file into an appropriately named ZIP file, which can then be uploaded to Octopus Deploy. This “WAR in a ZIP” package allows us to have the WAR file managed by Octopus Deploy, but it does have some drawbacks, which I will mention later.
To package up the WAR file, use the Octopus Deploy CLI tool. The CLI tool is a. NET Core application that exposes a number of common operations that can be performed in Octopus Deploy, along with some handy features like creating ZIP archives with the correct naming conventions.
If you are not familiar with. NET Core, for the purposes of this blog post, it is enough to know that it allows. NET applications to be run across operating systems, including Linux. The Octopus Deploy CLI tool is a self-contained package that includes the. NET Core runtime, and so when you download the version for your Linux distribution, you get (almost) everything you need to run the CLI.
You may need to install a few additional dependencies to run the CLI tool from Linux environments installed using “minimal” installation options. The documentation at the Get Started with. NET Core page lists the packages required for various Linux distributions.
To create the package, run the command:
This will create the file Demo.1.0.0.zip, which contains the WAR file.
Using the CLI tool is not required for creating the ZIP file. Any ZIP tool will do. However, the tools provided by Octopus Deploy are designed to yield high size reductions based on the actual content of your packaged files. See Delta compression for package transfers for more information.
To push the package, use the push command:
You can find information on API keys at How to create an API key .
This adds the package to the Octopus Deploy built-in package repository so it can be used in deployments. See Package repositories for more information.
In Octopus, an environment is a group of machines that you will deploy to at the same time; common examples of environments are Test, Acceptance, Staging, or Production. The Getting Started documentation details the process of creating a new environment in Octopus Deploy.
Deployment targets represent the servers, machines and cloud services where your application and services will be deployed. The Getting Started documentation details the process of creating a new deployment target in Octopus Deploy.
In this example, we’ ll create a deployment target to represent the Tomcat server running on a Linux host. Almost all Linux servers run SSH as a means of remote administration, and Octopus Deploy supports SSH natively, so this is the means of communication that we will use to deploy the WAR file.
Octopus uses a component called Calamari as the engine to execute deployments on deployment targets. Calamari currently requires Mono as a dependency to provide a. NET environment to operate on Linux. You will need to install Mono onto the Tomcat server to allow the Calamari to run. In the future, this will be simplified to use. NET Core without needing an additional dependency.
This can be confusing to people new to Octopus so I’ll review this. You just need to know that:
One thing to keep in mind with SSH deployment targets is that the user that makes the SSH connection needs to have permissions to deploy to the Tomcat webapps directory. Later on, we’ ll define some deployment steps that will copy the WAR file from the package that was uploaded earlier into the webapps directory, and this step will fail if the SSH user does not have the correct permissions to copy files into this location.
It is possible to deploy to a Linux server from Octopus Deploy without installing Mono. This is handy, but the tradeoff is that you lose a lot of the power that Calamari provides in executing deployments. See Trying Raw Octopus for more information.
Projects define a set of deployment steps that you want Octopus to perform, and their configuration variables. The Getting Started documentation details the process of creating a new deployment target in Octopus Deploy.
Inside the project, we need to open the Process section and add the Deploy a package step.
The Deploy a package step provides a way for us to take a package and extract it to the desired location on the deployment targets. In our case, we are taking the ZIP package and extracting the WAR file to the Tomcat webapps directory.
The Configuration Variables and Configuration transforms sections provide a lot of power that unfortunately we can’ t use while deploying a Java application. These options assume that certain XML files are available directly inside the package. This is not the case when the package contains a WAR file, and any configuration files contained in the WAR file are not available to be modified during deployment.
