The EC-Tomcat plugin allows users to interact with the Tomcat server and perform tasks such as Server Administration (Start/Shutdown of a Server), Application Deployment (Deploy or Undeploy), Resource Management (Adding or Removing JMS Resources or Data Sources) etc. Apache Tomcat, also referred to as Jakarta Tomcat or Tomcat, is an open source servlet container developed by the Apache Software Foundation (ASF). Tomcat implements the Java Servlet and the JavaServer Pages (JSP) specifications from the Oracle Corporation. It also provides a pure Java HTTP web server environment for Java code to run.
For more information about Apache Tomcat, go to the Apache Tomcat site.
Plugin version 3.0.0
Revised on October 18, 2022
EC-Tomcat operations mode
The EC-Tomcat plugin supports two different approaches for interacting with Tomcat that pertain to Application Deployment and Application Management. Refer to the configuration section to determine any special setup required for each kind of interaction.
It can perform a variety of operations without calling any HTTP endpoints and instead using the metadata provided in the application’s context XML file in the file system. The following procedures use this approach:
-
DeployApplication
-
UndeployApplication
-
AddDatasource
-
RemoveDataSource
-
CreateOrUpdateJMSConnectionFactory
-
CreateOrUpdateJMSQueue
-
CreateOrUpdateJMSTopic
-
CreateOrUpdateMailSession
-
DeleteResource
It can also perform a variety of operations that use the Tomcat Manager. The following procedures use this approach:
-
DeployApp
-
UndeployApp
-
StartApp
-
StopApp
-
ReloadApp
-
RunTomcatManager
Supported Versions
All procedures have been tested with the following versions of Tomcat:
-
8.5.81
-
9.0.65
Plugin configurations
Plugin configurations are sets of parameters that can be applied across some, or all, of the plugin procedures. They can reduce the repetition of common values, create predefined parameter sets, and securely store credentials. Each configuration is given a unique name that is entered in the designated parameter for the plugin procedures that use them.
Creating plugin configurations
To create plugin configurations in CloudBees CD/RO, complete the following steps:
-
Navigate to
. -
Select Add plugin configuration to create a new configuration.
-
In the New Configuration window, specify a Name for the configuration.
-
Select the Project that the configuration belongs to.
-
Optionally, add a Description for the configuration.
-
Select the appropriate Plugin for the configuration.
-
Configure the parameters per the descriptions below.
Configuration procedure parameters
Parameter | Description |
---|---|
config |
Configuration Name |
Tomcat Home |
Absolute path to Tomcat Installation Home (aka Catalina Home) directory. (For example /opt/tomcat, etc.) |
Tomcat URL |
URL of Tomcat Server (must include protocol, server and port). |
Debug level |
This option sets the debug level for logs. If Info is selected, only a summary is displayed. If Debug is selected, debug information is displayed. If Trace is selected, all requests and responses are displayed. |
Plugin procedures
For all parameter descriptions in this section, required parameters are shown in *bold italics*. |
For all procedures where a .war file path is required, the .war file must be accessible by Tomcat locally or on a network share. |
StartServer
Starts a Tomcat Server.
StartServer parameters
Parameter | Description |
---|---|
Configuration name |
The unique name for the configuration. |
Catalina Path: |
Provide the absolute path to Catalina’s home to locate the catalina.sh needed to start or stop the application servers. i.e: '/opt/tomcat/'. |
Startup Script Path: |
Provide the absolute path to the startup server script. Include filename and extension. i.e: '/opt/tomcat/bin/startup.sh'. |
ShutdownServer
Shutdown a Tomcat Server.
ShutdownServer parameters
Parameter | Description |
---|---|
Catalina Path: |
Provide the absolute path to Catalina’s home to locate the catalina.sh needed to start or stop the application servers. i.e: '/opt/tomcat/'. (Required) |
Shutdown Script Path: |
Provide the absolute path to the shutdown server script. Include filename and extension. i.e: '/opt/tomcat/bin/shutdown.sh'. (Required) |
DeployApp
Deploy an application into a Tomcat Server
DeployApp parameters
Parameter | Description |
---|---|
Configuration name |
The unique name for the configuration. |
Context Configuration Path: |
Provide the context configuration file path. |
Context Path: |
Context Path to use. In one sentence, the context path is the name after slash, by which your application is accessible. |
Update Application: |
Check this checkbox if the existing application in the supplied context path must be overridden. |
WAR File/Exploded Directory Path: |
Provide the path to the WAR file or exploded directory to upload to the server. If this parameter is sent empty, the plugin will look into the appBase directory of Tomcat for the .war file that match with th Context Path provided to make the deploy. Acceptable formats: file - use the prefix file: and the absolute path of the WAR file or directory. i.e: 'file:/absolute/path/to/a/directory' or 'file:/tmp/app_wars/webapp.war' --- jar - use the prefix jar:. The URL to a local WAR file. You can use any syntax that is valid for the JarURLConnection class for reference to an entire JAR file. --- no prefix - if no prefix is entered, the Tomcat Manager will look in the host’s application base directory for either a WAR file or a directory, relative to the mentioned path. --- no prefix and remote deploy - if no prefix is entered and 'Remote Deployment' is checked, the Tomcat Manager will look into the war path entered for the WAR file. |
DeployApplication
Deploy an application into a Tomcat Server ( using Context files )
DeployApplication parameters
Parameter | Description |
---|---|
Configuration name |
The unique name for the configuration. |
Application Warfile Location: |
Name of the War file which consists of the Web Application to be deployed, with absolute path. For example */var/downloads/hello.war* |
Request URL Context Path: |
The Context path of the URL at which Tomcat serves the application. For example, if tomcat should serve the Application at http://host:port/ws this value should be /ws and if tomcat should serve the Application at http://host:port /abc/ws , this value should be */abc/ws* |
VirtualHost Name: |
Hostname of the Tomcat Server or the virtual host to which the application should be deployed. If this field is left empty, application will be deployed to Tomcat default host (localhost). Warning will be shown if provided name is not defined in conf/server.xml |
Host Application Directory location: |
This is the pathname of a directory where web applications for this host are located (Tomcat calls it appBase folder). If this field is left empty, it will be read from corresponding Host (specified by HostName) appBase attribute in conf/server.xml . Warning will be thrown if directory doesn’t exist. Also procedure will fail if can’t retrieve value either from input or conf/server.xml |
Web Application Context Element: |
The full XML content for the <Context> element of the Context Descriptor. (You can read more about possible attributes in Tomcat documentation ). If no value is provided, default value will be formed dynamically according to values given for Application Warfile Location and Request URL Context Path. <?xml version="1.0" encoding="UTF-8"?> <Context docBase="hello.war" path="/hello" unpackWAR="true"> </Context> Here docBase is path where deployed application warfile lives - /path/to/hello.war (relative to Host’s appBase) and path is the same as "Request URL Context Path" /hello |
Update Action: |
Controls if tomcat should override and deploy over an existing deployment. *No Action* - If the war already exists do not copy over. *Remove and recreate* - If the war exists, copy over and redeploy. |
Server Restart Options: |
Controls if Server should be restarted or not. Values are:
|
UndeployApplication
Undeploy an application from a Tomcat Server ( removing deployment files and Context file )
UndeployApplication parameters
Parameter | Description |
---|---|
Configuration name |
The unique name for the configuration. |
Request URL Context Path: |
The Context path of the URL at which Tomcat serves the application. For example, if tomcat should serve the Application at http://host:port/ws this value should be /ws and if tomcat should serve the Application at http://host:port /abc/ws , this value should be /abc/ws |
Host Application Directory location: |
This is the pathname of a directory where web applications for this host are located (Tomcat calls it appBase folder). If this field is left empty, it will be read from corresponding Host (specified by HostName) appBase attribute in conf/server.xml . Warning will be thrown if directory doesn’t exist. Also procedure will fail if can’t retrieve value either from input or conf/server.xml |
VirtualHost Name: |
Hostname of the Tomcat Server or the virtual host to which the application should be deployed. If this field is left empty, application will be deployed to Tomcat default host (localhost). Warning will be shown if provided name is not defined in conf/server.xml |
Specific Deployment Files: |
If specified procedure will remove context XML file with given Request URL Context Path and any given file paths. If empty, procedure will read docBase attribute from context XML with given Request URL Context Path , then if this is .war file will check for extracted folder and remove both. |
Server Restart Options: |
Controls if Server should be restarted or not. Values are:
|
AddDatasource
Adds a Datasource resource declaration into the Tomcat Context
AddDatasource parameters
Parameter | Description |
---|---|
Context Configuration Path: |
Absolute path of "context.xml", including filename and extension. i.e: '$CATALINA_BASE/conf/context.xml' or '/opt/tomcat/conf/context.xml'. |
Datasource Name: |
The name of the datasource. i.e: 'jdbc/MyTest'. |
URL: |
Connection URL to be passed to our JDBC driver. i.e: 'jdbc:mysql://hostname:3306/databaseName'. |
Max Active Connections: |
The maximum number of connections that can be allocated from this pool at the same time. Default is 8. |
Max Idle Connections: |
The maximum number of connections that can sit idle in this pool at the same time. Default is 8. |
Maximum Wait for Connections: |
The maximum number of milliseconds that the pool will wait (when there are no available connections) for a connection to be returned before throwing an exception. Default is -1 (infinite). |
Minimum Wait for Connections: |
The minimum number of connections that will sit idle in this pool at the same time. |
Additional Attributes: |
Enter additional attributes for the resource. Use this format: 'attributeName="value";attributeName2="value2"' where ';' is used to separate the attributes. Note the "" around the values. |
Driver Class Name: |
Fully qualified Java class name of the JDBC driver to be used. i.e: 'com.mysql.jdbc.Driver'. |
Datasource credential: |
Specify credential that contains username and password for data source. |
CreateOrUpdateJMSConnectionFactory
Adds a new JMS Connection Factory or updates an existing Connection Factory based on the update action (refer to procedure parameter descriptions below), with support for different JMS providers.
CreateOrUpdateJMSConnectionFactory parameters
Parameter | Description |
---|---|
Configuration name |
The unique name for the configuration. |
VirtualHost Name: |
Hostname of the Tomcat Server or the virtual host where application is deployed |
Request URL Context Path: |
The Context path of the URL at which Tomcat serves the application. |
JNDI Name: |
Name used to look up the resource in JNDI |
Provider: |
Select provider for the JMS resources |
ActiveMQ Broker URL: |
The URI is assumed to be a composite uri with multiple uris that are used to bind the connectors of the broker. Parameter is required if selected provider 'Apache ActiveMQ'. |
ActiveMQ Broker Name: |
Broker Name. Parameter is required when 'Provider' is 'Apache ActiveMQ'. |
WebsphereMQ Connection Factory Type: |
Type of resource that is controlled by WebsphereMQ connection factory. Parameter is required when 'Provider' is 'IBM WebSphereMQ'. |
WebsphereMQ Server Hostname: |
Network hostname where Websphere MQ provider is located. Parameter is required when 'Provider' is 'IBM WebSphereMQ'. |
WebsphereMQ Server Port: |
TCP Port (1 - 65535) on server where Websphere MQ provider is located. Parameter is required when 'Provider' is 'IBM WebSphereMQ'. |
WebsphereMQ Channel: |
Name for a channel on WebsphereMQ. Parameter is required when 'Provider' is 'IBM WebSphereMQ'. |
WebsphereMQ Queue Manager: |
Name of a queue manager on WebsphereMQ. Parameter is required when 'Provider' is 'IBM WebSphereMQ'. |
Custom Connection Factory Class: |
Fully qualified name of the Java class to use. i.e: 'org.apache.activemq.ActiveMQConnectionFactory'. Parameter is required when 'Provider' is 'Custom'. |
Custom Connection Factory Factory Class: |
Fully qualified name of the Factory Java class to use. i.e: 'org.apache.activemq.JNDIRefferenceFactory'. Parameter is required when 'Provider' is 'Custom' |
Custom Connection Factory Attributes: |
Enter additional attributes for the resource. Use this format: 'attributeName="value";attributeName2="value2"' where ';' is used to separate the attributes. Note the "" around the values. |
Description: |
Description for this Connection factory |
Update Action: |
This parameter controls as to what the Update Action should be done when resource element with the same JNDI name exists. |
CreateOrUpdateJMSQueue
Adds a new JMS Queue or updates an existing JMS Queue based on the update action (refer to procedure parameter descriptions below), with support for different JMS providers.
CreateOrUpdateJMSQueue parameters
Parameter | Description |
---|---|
Configuration name |
The unique name for the configuration. |
VirtualHost Name: |
Hostname of the Tomcat Server or the virtual host where application is deployed |
Request URL Context Path: |
The Context path of the URL at which Tomcat serves the application. |
JNDI Name: |
Name used to look up the resource in JNDI |
Provider: |
Select provider for the JMS resources |
Custom JMS Queue Class: |
Fully qualified name of the Java class to use. i.e: 'org.apache.activemq.ActiveMQQueue'. |
Custom JMS Queue Factory Class: |
Fully qualified name of the Factory Java class to use. i.e: 'org.apache.activemq.ActiveMQConnectionFactory'. |
Custom JMS Queue Attributes: |
Enter additional attributes for the resource. Use this format: 'attributeName="value";attributeName2="value2"' where ';' is used to separate the attributes. Note the "" around the values. |
Description: |
Description for this JMS Queue |
Update Action: |
This parameter controls as to what the Update Action should be done when resource element with the same JNDI name exists. |
CreateOrUpdateJMSTopic
Adds a new JMS Topic or updates an existing JMS Topic based on the update action (refer to procedure parameter descriptions below), with support for different JMS providers.
CreateOrUpdateJMSTopic parameters
Parameter | Description |
---|---|
Configuration name |
The unique name for the configuration. |
VirtualHost Name: |
Hostname of the Tomcat Server or the virtual host where application is deployed |
Request URL Context Path: |
The Context path of the URL at which Tomcat serves the application. |
JNDI Name: |
Name used to look up the resource in JNDI |
Provider: |
Select provider for the JMS Resources |
Custom JMS Topic Class: |
Fully qualified name of the Java class to use. i.e: 'org.apache.activemq.ActiveMQTopic'. |
Custom JMS Topic Factory Class: |
Fully qualified name of the Factory Java class to use. i.e: 'org.apache.activemq.JNDIReferenceFactory'. |
Custom JMS Topic Attributes: |
Enter additional attributes for the resource. Use this format: 'attributeName="value";attributeName2="value2"' where ';' is used to separate the attributes. Note the "" around the values. |
Description: |
Description for this JMS Topic |
Update Action: |
This parameter controls as to what the Update Action should be done when resource element with the same JNDI name exists. |
CreateOrUpdateMailSession
Adds a new JMS Mail Session or updates an existing Mail Session based on the update action (refer to procedure parameter descriptions below).
CreateOrUpdateMailSession parameters
Parameter | Description |
---|---|
Configuration name |
The unique name for the configuration. |
VirtualHost Name: |
Hostname of the Tomcat Server or the virtual host where application is deployed |
Request URL Context Path: |
The Context path of the URL at which Tomcat serves the application. |
JNDI Name: |
The JNDI name for this Mail session (should be unique for context) |
SMTP Host |
The server that provides SMTP service for your network |
Description: |
Description for this Mail session resource element |
Update Action: |
This parameter controls as to what the Update Action should be done when resource element with the same JNDI name exists. |
DeleteResource
Removes any of these resources - Connection Factory, JMS Queue, JMS Topic and Mail Session
DeleteResource parameters
Parameter | Description |
---|---|
Configuration name |
The unique name for the configuration. |
VirtualHost Name: |
Hostname of the Tomcat Server or the virtual host where application is deployed. |
Request URL Context Path: |
The Context path of the URL at which Tomcat serves the application. |
JNDI Name: |
JNDI name of the Resource delete. |
CheckServerStatus
Check the status of the given server URL.
CheckServerStatus parameters
Parameter | Description |
---|---|
Configuration Name |
Name of the configuration to be used for retrieving Admin Server’s URL and credentials. |
Maximum Elapsed Time |
Defines the maximum time in seconds that the job will try to check into the server. Blank implies no wait time (URL only checked one time). |
Success Criteria |
Indicate the status of the page that must be matched, either a Page found or a Page not found status. If the indicated success criteria matches the returned status at the end of the analysis, it is considered a success. Otherwise, it is an error in the job. |
CheckPageStatus
Check the status of a page on a given URL.
CheckPageStatus parameters
Parameter | Description |
---|---|
Credentials |
Credentials to be entered. |
Maximum Elapsed Time |
Defines the maximum time in seconds that the job will try to check into the server (max of 180 seconds). Blank implies no wait time (0 seconds). |
Success Criteria |
Indicate the status of the page that must be matched, either a Page found or a Page not found status. If the indicated success criteria matches the returned status at the end of the analysis, it is considered a success. Otherwise, it is an error in the job. (Required) |
Page URL |
URL of the page to be checked. For example, |
RunTomcatManager
Run Tomcat Manager in a free-mode.
RunTomcatManager parameters
Parameter | Description |
---|---|
Configuration name |
The unique name for the configuration. |
Command: |
Provide the command to pass to the Tomcat Manager. i.e: 'start', 'stop', 'run'. |
Parameters: |
Provide additional parameters received by Tomcat Manager. Enter as URL parameters. i.e: 'path=/jpetstore&war=file:/tmp/app_wars/jpetstore.war'. |
DeployLibraryFile
Deploys a specified library file to an appropriate destination in the Tomcat Server.
DeployLibraryFile parameters
Parameter | Description |
---|---|
Config Name |
Unique name for the configuration for the Tomcat server. |
Destination Filepath |
Absolute path where deployed library file should appear after procedure run. |
Local Filepath |
Absolute path to a local file that should be deployed. |
Overwrite |
Controls action that should be made if "Destination Filepath" already exists. |
DeployConfigurationFile
Deploys a specified configuration file to an appropriate destination in the Tomcat Server.
DeployConfigurationFile parameters
Parameter | Description |
---|---|
Config Name |
Unique name for the configuration for the Tomcat server. |
Destination Filepath |
Absolute path where configuration XML file should be copied to. |
Local Filepath |
Absolute path to where the configuration XML file is copied from. |
Configuration File Content |
XML content for config file that should be deployed (ignored if "Local Filepath" is given). |
Overwrite |
Controls action to be taken if file already exists in the destination. |
Deploying Applications with RunTomcatManager
This example shows how to deploy an application using the Tomcat Manager and the deploy command.
To deploy the application:
-
Go to the RunTomcatManager procedure.
-
Enter the following parameters:
Figure 1. Enter parameter values to deploy the applicationAfter the job runs, you can view the results, including the following job details, which show the application was deployed:
Figure 2. View the job resultsIn the RunTomcatManager step, select the Log icon to review the diagnostic information. The output is similar to the following diagnostic report:
Figure 3. Diagnostic information
Undeploy Applications with RunTomcatManager
This example shows how to undeploy the application that was deployed in the previous example using the Tomcat Manager and undeploy command.
To undeploy the application:
-
Go to the RunTomcatManager procedure.
-
Enter the following parameters:
Figure 4. Enter parameter values to undeploy the applicationAfter the job runs, you can view the results, including the following job details, which show that the application was not deployed:
Figure 5. View the job resultsIn the RunTomcatManager step, select the Log icon to review the diagnostic information. The output is similar to the following diagnostic report:
Figure 6. Diagnostic information
Release notes
EC-Tomcat 3.0.0
-
The plugin has been migrated to the PDK framework. Support has been added for the new plugin configuration.
EC-Tomcat 2.3.0
-
Following New procedures added to support JMS and Mail Session Resource Management:
-
CreateOrUpdateJMSConnectionFactory
-
CreateOrUpdateJMSQueue
-
CreateOrUpdateJMSTopic
-
CreateOrUpdateMailSession
-
DeleteResource
-
-
Following New procedures added to support configuration and library file deployments:
-
DeployLibraryFile
-
DeployConfigurationFile
-
UndeployFile
-
-
Tomcat Home parameter was added to the plugin configuration (it is used in new procedures).
EC-Tomcat 2.2.0
-
New Procedures have been added to support Tomcat Static Deployment, where in Deployment or Undeployment can be done through file operations with Context XML Files and not using the Tomcat Deployment Manager. These procedures can be used in a pipeline to deploy an Application to multiple virtual environments.
EC-Tomcat 2.1.3
-
Configured the plugin to allow the ElectricFlow UI to create configs inline of procedure form.
EC-Tomcat 2.1.2
-
Configured the plugin to allow the ElectricFlow UI to render the plugin procedure parameters entirely using the configured form XMLs.
-
Enabled the plugin for managing the plugin configurations in-line when defining an application process step or a pipeline stage task.
EC-Tomcat 2.1.1
-
Fixed issue with configurations being cached for IE.
-
Support for Tomcat versions bigger than 6.
EC-Tomcat 2.1.0
-
Replaced Username and Password fields with credential in AddDatasource procedure (backward incompatible change).
-
Renamed ElectricCommander to ElectricFlow.
-
Added link to plugin Configuration Page in plugin step panels.
EC-Tomcat 2.0.9
-
Removed the XML::DOM dependency.
-
Changed the minimum required Flow version to Flow 4.2.
EC-Tomcat 2.0.5
-
Added the functionality to deploy .war files remotely.
-
Added the functionality to deploy, undeploy, start, stop, and reload applications on more than one Tomcat environment.
EC-Tomcat 2.0.2
-
Upgraded the plugin to use the new XML parameter form.
-
Added a link directly to the new Help document.