This Apache Tomcat installer (referred to herein as Setup) is publicly available thanks to permission from the Apache Tomcat Project Management Committee (PMC). If you build a custom version of this installer, you cannot redistribute it publicly without permission from the Apache Tomcat PMC. Please see the Apache Tomcat Legal Page for more information.
- Background
- Download
- Upgrading from the ASF Installer
- Reinstalling or Upgrading
- Setup Command Line Parameters
- Administrative vs. Non-administrative Installation Mode
- Installing Separate Instances
- Setup Type and Components
- Setup Tasks
- Finding the jvm.dll File
- Uninstalling Apache Tomcat
- Setup Limitations
- Sample Command Line Parameters
- Acknowledgments
I wrote this Inno Setup installer because I needed more functionality than was provided by the Apache Software Foundation (ASF) 32-bit/64-bit Windows service installer, which was built using NSIS. Specifically:
-
The ASF installer doesn't provide an easy way to upgrade a Tomcat installation. Using the ASF installer, an upgrade consists of uninstall, click
Nowhen it asks if you want to delete all the files (a dangerous question), then install the new version using the same options (hopefully you documented your settings). If you installed the service, you will need to reconfigure that as well. If you run the service using a specific account, you will need to specify it again and re-enter the credentials (because the uninstall deleted the service). Java runtime parameters (such as memory sizes, JVM options, etc.) must also be reconfigured. -
The installer-specific documentation is quite brief, and it doesn't mention some very peculiar command line parsing rules (e.g., the
/D=command line option must be UPPER CASE and must not be quoted on the command line, even if the target directory name contains whitespace). The configuration options for a silent installation must sit in a text-based configuration file, and some notable Windows service configuration options are missing (service user account, etc.). -
The ASF installer doesn't set file system permissions for the service user account to actually be able to run any web applications because it doesn't have a way to specify the service user account name. This is a peculiar state of affairs when installing the Windows service: The service gets installed, but unless you run the service using the local system or an administrative account (not recommended), web applications won't work because the service user account doesn't have permission to write to the
logs,temp, andworkdirectories.
This custom Apache Tomcat Setup installer rectifies these limitations.
You can download the latest version from the Github Releases page:
https://github.com/Bill-Stewart/ApacheTomcatSetup/releases/
Setup does not upgrade Tomcat if it was installed by the Apache Software Foundation 32-bit/64-bit Windows Service Installer package. To perform an upgrade if Tomcat was installed using the ASF installer, you must perform the following steps:
-
Make a backup of all customized files
-
If the ASF installer installed a Tomcat service:
a. Document any customized service settings (e.g. memory settings, custom command-line options, etc.)
b. Stop the service
-
Uninstall it using the standard Windows application management list
-
Install Tomcat using Setup
-
Restore customized files
-
If using the service: Add back any customized service settings
After successfully installing Tomcat using Setup, upgrades no longer require the above steps.
Please note the following when using Setup to reinstall or upgrade Apache Tomcat:
-
If the Windows service is installed, Setup automatically stops the service, upgrades the binaries, and restarts the service. All service installation details are retained when reinstalling or upgrading.
-
Obsolete files in the included web applications are not removed when upgrading. It is the Tomcat administrator's responsibility to manually manage the web application files in the
webappsdirectory. -
If a file that Setup is installing is both different and has an older timestamp than a file in the
confdirectory, Setup will prompt whether you want to keep or overwrite the file. TheKeep the existing fileoption (recommended) is the default if you use the/suppressmsgboxesparameter (see Setup Command Line Parameters).NOTE: Setup provides this prompt as a safeguard to prevent accidental overwriting of customized configuration files. If you are certain you want to overwrite all files without prompting, specify the
/forceoverwritefilesparameter (not recommended unless you are absolutely sure you want to overwrite all files). -
Setup will not overwrite files in the
confdirectory that have a newer timestamp than the same file(s) it installs. You can prevent overwriting of customized files in theconfdirectory by updating the timestamp of customized files (e.g., open and save or use a "touch" utility) before a reinstall or upgrade.
| Parameter | Description |
|---|---|
/currentuser |
Runs Setup in non-administrative installation mode (not recommended). See Administrative vs. Non-administrative Installation Mode. |
/instancename="name" |
Runs Setup to install a separate instance of Apache Tomcat. See Installing Separate Instances. |
/dir="location" |
Specifies the installation directory. The default location is d:\Program Files\Apache Tomcat (where d: is the Windows system partition). |
/type=type |
Specifies the installation type. See Setup Type and Components. |
/components="componentlist" |
Specifies the components Setup should install. See Setup Type and Components. |
/group="name" |
Specifies the Start Menu group name. The default group name is Apache Tomcat. |
/noicons |
Prevents creation of a Start Menu group. |
/tasks="tasklist" |
Specifies the tasks Setup should perform. See Setup Tasks. |
/jvmpath="location" |
Specifies the path and filename of the jvm.dll file. See Finding the jvm.dll File. |
/silent |
Runs Setup silently (i.e., without user interaction). For a fully hands-free installation when upgrading, it is recommended to also specify the /closeapplications parameter (see below). |
/closeapplications |
Setup should automatically stop running services and applications before installing and restart services after installation. (If you omit this parameter and one or more Tomcat services and/or applications are running, Setup will prompt interactively to close them before continuing.) |
/suppressmsgboxes |
Suppresses message boxes and uses a default answer. This parameter is recommended for silent installations. |
/log="filename" |
Logs Setup activity to the specified file. The default is not to create a log file. |
/forceoverwritefiles |
Overwrites all files in the conf directory that are different and newer without prompting (not recommended). |
The following command line parameters set the default values for the text boxes on the Select Service Configuration Options page and are applicable only when installing the Windows service for the first time:
| Parameter | Description |
|---|---|
/servicename=name |
Specifies the Windows service name. This name cannot contain whitespace. The default is Tomcat. |
/servicedisplayname="displayname" |
Specifies the Windows service display name. The default is Apache Tomcat. |
/serviceusername="username" |
Specifies the name of the user account that will run the Windows service. The default is NT AUTHORITY\Local Service. For a local account, specify .\username. For a domain account, specify domainname\username. |
/jvmoptions="options" |
Specifies a semicolon-delimited list of additional JVM (Java Virtual Machine) options. |
/jvmms=size |
Specifies the initial memory pool size, in megabytes. The default size is 256. |
/jvmmx=size |
Specifies the maximum memory pool size, in megabytes. The default size is 256. |
If the service user account requires a password, you must enter its password in the service configuration dialog after Setup completes.
IMPORTANT: It is not recommended to run the service using an administrative account or the
LocalSystemaccount.
If you install a separate instance (see Installing Separate Instances), the default values of the /dir, /group, /servicename, and /servicedisplayname parameters will include the instance name. For example, if you specify /instancename="XWiki", the following will be defaults:
/dir="d:\Program Files\Apache Tomcat - XWiki"/group="Apache Tomcat - XWiki"/servicename=Tomcat-XWiki/servicedisplayname="Apache Tomcat - XWiki"
Setup is built using Inno Setup, so it supports the command line parameters common to all Inno Setup installers. Run Setup with the /? parameter for more details.
Setup supports both administrative and non-administrative installation modes:
-
In administrative installation mode (the default), Setup installs Apache Tomcat for all users of the computer and allows installation of the Windows service.
-
In non-administrative installation mode (not recommended), Setup installs Apache Tomcat in the current user's profile. To run Setup in non-administrative installation mode, you must specify the
/currentuserparameter on Setup's command line. You cannot install the Windows service using non-administrative installation mode.
An instance is an independent installation of Apache Tomcat in a separate location. You can use the /instancename command line parameter to install multiple Apache Tomcat services on the same computer, or if you need to run separate specific versions of Apache Tomcat.
If you install multiple instances, each installation is considered as a separate application. Each instance will appear as a separate entry in the installed application list in Windows. Each instance must be upgraded, reinstalled, or uninstalled separately. (That is, a reinstall, upgrade, or uninstall of a specific instance affects only that instance.)
Setup's Select Components page allows selection of the setup type and components.
The setup type corresponds to the drop-down list on the Select Components page. Changing the drop-down list selection changes the selected components. The types are as follows:
| Type | Name | Components Selected |
|---|---|---|
| Default installation | default |
core,webapps/docs,webapps/manager |
| Core only | core |
core |
| Full installation | full |
Selects all components |
| Custom installation | custom |
Selects a custom list of components |
The /type command line parameter specifies a default setup type; e.g. /type=core specifies that Core only should be the default type.
The default is /type=default.
The components correspond to the checkboxes that represent individual components. The components are as follows:
| Component | Name | Notes |
|---|---|---|
| Apache Tomcat core | core |
Always selected |
| Web applications | webapps |
Can't be selected alone |
| Documentation bundle | webapps/docs |
|
| Manager application | webapps/manager |
|
| Host Manager application | webapps/hostmanager |
|
| Examples | webapps/examples |
The core component consists of the Apache Tomcat binaries and jar files.
The /components command line parameter is a comma-delimited list of components that should be selected by default. For example, /components="core,webapps/docs" selects the core and webapps/docs components by default. (This is equivalent to /components="webapps/docs" because the core component is always selected.)
The default is /components="core,webapps/docs,webapps/manager".
Setup's Select Additional Tasks page provides a list of additional tasks that Setup should perform:
| Task | Name | Notes |
|---|---|---|
| Install Windows service | installservice |
|
| Set file system permissions for service user account | installservice/setpermissions |
See Setting File System Permissions |
| Automatically start service when computer starts | installservice/setautostart |
|
| Create shortcut to start the service monitor at logon | installservice/startmonitoratlogon |
|
| Back up conf directory before installation | backupconf |
See Backing Up the conf Directory |
The /tasks parameter specifies which tasks are selected by default. Specifying an installservice subtask implies the installservice task (that is, /tasks="installservice/setautostart" is equivalent to /tasks="installservice,installservice/setautostart").
The default is /tasks="installservice/setpermissions,installservice/setautostart,backupconf".
The installservice/setpermissions task grants file system permissions to the account used to run the service, as follows:
-
Apache Tomcat installation directory and subdirectories: Read-only
-
conf\Catalina\localhost,logs,temp, andworkdirectories: Modify
Web applications can start successfully with these minimum permissions.
If the service user account is not found, the permission changes will fail silently. In this case, you will need to grant the permissions manually.
IMPORTANT: You may need to change the permissions on one or more of the directories and/or files to properly secure the Apache Tomcat application. (For example, if you use SSL, you will most likely want to restrict access to the certificate's private key file.)
The backupconf task makes a backup copy of the conf directory if it exists (i.e., when reinstalling or upgrading). The backup directory will be named conf-backup-time (where time is the date and time the backup was created).
Apache Tomcat requires a Java Virtual Machine (JVM), so Setup needs to know the location of the jvm.dll file if you are installing the service. Setup attempts to find it automatically in the following ways:
-
It checks for the presence of the
JAVA_HOME,JDK_HOME, andJRE_HOMEenvironment variables (in that order). The value of the environment variable is the Java home directory. -
If the environment variables noted above are not defined, Setup searches the directories named in the
Pathenvironment variable forjava.exe. The Java home directory is the parent directory of the directory wherejava.exeis found. For example, ifC:\Program Files\Eclipse Adoptium\JRE11\binis in the path (andjava.exeis in that directory), the Java home directory isC:\Program Files\Eclipse Adoptium\JRE11. -
If
java.exeis not found in thePath, Setup searches in the registry for the home directory of the latest Java version installed.
NOTE: If you are running on a 64-bit version of Windows, Setup won't search the 32-bit portion of the registry if it finds any 64-bit versions of Java in the registry. This only applies to the registry search; if Setup finds a 32-bit installation of Java in the environment variables or
Path, it will not search the registry.
If any of the above attempts to find the Java home directory succeed (in the above order), Setup looks for the jvm.dll file in the \bin\server and \jre\bin\server subdirectories of the Java home directory.
If you have Java installed but Setup fails to find it or the path to the jvm.dll file, you must specify the path to the jvm.dll file on the Select Java Virtual Machine page or by using the /jvmpath command line parameter.
Setup installs the 64-bit Apache Tomcat binaries if the jvm.dll file is 64-bit; otherwise, it installs the 32-bit Apache Tomcat binaries.
The file version of jvm.dll must be at least the minimum version required by the version of Tomcat you are installing. If the jvm.dll file version is older than the minimum version required by the version of Tomcat you are installing, Setup will not continue.
If Setup can't find the jvm.dll file, you can work around the problem by setting the JAVA_HOME environment variable to the Java home directory, and then running Setup again. In recent versions of Windows, you can add an environment variable by running the following command:
rundll32 sysdm.cpl EditEnvironmentVariables
You can uninstall Apache Tomcat installed using Setup by using the standard Windows application management list. The uninstall process does not remove the conf directory or any files Setup did not install.
The uninstall program is located in the uninstall directory in the installation directory and is named uninsnnn.exe (where nnn is three digits, usually 000). Some common uninstall command line parameters are the following:
| Parameter | Description |
|---|---|
/silent |
Runs the install silently (i.e., without user interaction). |
/log="filename" |
Logs uninstall activity to the specified file. The default is not to create a log file. |
See the Inno Setup documentation for more uninstaller command line parameters.
-
Setup doesn't provide a way to configure server port (
server.xml) or Manager web application (tomcat-users.xml) details (these items must be configured separately after installation). -
Setup does not provide the ability to uninstall an upgrade (i.e., downgrade). To downgrade, you must first uninstall the current version and then install the desired version. For this reason, it is recommended to keep the Setup programs of previous versions available just in case.
-
Setup uses WMI (Windows Management Instrumentation) API calls to detect running services and applications. If you have stopped or disabled the WMI service (not recommended), Setup will not be able to detect running services and applications and will attempt to replace files that are in use. The only workaround in this case is to manually stop running Tomcat services and/or applications before reinstalling or upgrading.
/type=core
/serviceusername="FABRIKAM\AppService"
/jvmoptions="-Djavax.net.ssl.trustStoreType=WINDOWS-ROOT"
/silent
/closeapplications
/suppressmsgboxes
/log="C:\Users\KenDyer\Documents\ApacheTomcatSetup.log"
(All on one line)
These options perform a silent installation of Apache Tomcat. The service will run using the account FABRIKAM\AppService and will trust the Windows certificate store. Setup will log its activity to the specified log file.
Special thanks to the following:
-
Apache Software Foundation: For providing the Apache Tomcat software.
-
The Apache Tomcat Project Management Committee (PMC): For granting permission to publicly distribute this Setup program with the copyrighted Apache Tomcat images.
-
Jordan Russell and Martijn Laan: For making the excellent Inno Setup tool publicly available.