Bill Stewart's Apache Tomcat Setup for Windows
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.
Table of Contents
- 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
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 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
This custom Apache Tomcat Setup installer rectifies these limitations.
You can download the latest version from the Github Releases page:
Reinstalling or Upgrading
Please note the following when using Setup to reinstall or upgrade Apache Tomcat:
IMPORTANT: If a file in Setup is newer than the corresponding file already on disk, Setup assumes the file needs to be upgraded and will overwrite it. Therefore, to prevent accidental overwriting of customized files (e.g., configuration files in the
confdirectory), the Tomcat administrator must update all customized configuration files (open and save to update date and time, or use a "touch" utility) before 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
If the Windows service is installed, Setup can automatically stop the service, upgrade the binaries, and restart the service. All service installation details are retained when reinstalling or upgrading.
Setup Command Line Parameters
Common Command Line Parameters
||Runs Setup in non-administrative installation mode (not recommended). See Administrative vs. Non-administrative Installation Mode.|
||Runs Setup to install a separate instance of Apache Tomcat. See Installing Separate Instances.|
||Specifies the installation directory. The default location is d
||Specifies the installation type. See Setup Type and Components.|
||Specifies the components Setup should install. See Setup Type and Components.|
||Specifies the Start Menu group name. The default group name is
||Prevents creation of a Start Menu group.|
||Specifies the tasks Setup should perform. See Setup Tasks.|
||Specifies the path and filename of the
||Runs Setup silently (i.e., without user interaction). For a fully hands-free installation when upgrading, it is recommended to also specify the
||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.)|
||Logs Setup activity to the specified file. The default is not to create a log file.|
Windows Service Installation Command Line Parameters
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:
||Specifies the Windows service name. This name cannot contain whitespace. The default is
||Specifies the Windows service display name. The default is
||Specifies the name of the user account that will run the Windows service. The default is
||Specifies a semicolon-delimited list of additional JVM (Java Virtual Machine) options.|
||Specifies the initial memory pool size, in megabytes. The default size is
||Specifies the maximum memory pool size, in megabytes. The default size is
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
Instance Name Defaults
If you install a separate instance (see Installing Separate Instances), the default values of the
/servicedisplayname parameters will include the instance name. For example, if you specify
/instancename="XWiki", the following will be defaults:
:\Program Files\Apache Tomcat - XWiki"
/group="Apache Tomcat - XWiki"
/servicedisplayname="Apache Tomcat - XWiki"
Other Command Line Parameters
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.
Administrative vs. Non-administrative Installation Mode
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.
Installing Separate Instances
An instance is an independent installation of Apache Tomcat in a separate location. You can use the
/instance 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 Type and Components
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:
||Selects all components|
||Selects a custom list of components|
/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
The components correspond to the checkboxes that represent individual components. The components are as follows:
|Apache Tomcat core||
||Can't be selected alone|
|Host Manager application||
core component consists of the Apache Tomcat binaries and
/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
webapps/docs components by default. (This is equivalent to
/components="webapps/docs" because the
core component is always selected.)
The default is
Setup's Select Additional Tasks page provides a list of additional tasks that Setup should perform:
|Install Windows service||
|Set file system permissions for service user account||
||See Setting File System Permissions|
|Automatically start service when computer starts||
|Create shortcut to start the service monitor at logon||
|Back up conf directory before installation||
||See Backing Up 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
The default is
Setting File System Permissions
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
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.)
Backing Up 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).
Finding the jvm.dll File
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
JRE_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 for
java.exe. The Java home directory is the parent directory of the directory where
java.exeis found. For example, if
C:\Program Files\Eclipse Adoptium\JRE11\binis in the path (and
java.exeis in that directory), the Java home directory is
C:\Program Files\Eclipse Adoptium\JRE11.
java.exeis not found in the
Path, 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 appends
\bin\server\jvm.dll to the Java home directory and uses the result as the path to the
If you have Java installed but Setup fails to find it, 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
Uninstalling Apache Tomcat
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
.exe (where nnn is three digits, usually
000). Some common uninstall command line parameters are the following:
||Runs the install silently (i.e., without user interaction).|
||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.
Sample Command Line Parameters
/type=core /serviceusername="FABRIKAM\AppService" /jvmoptions="-Djavax.net.ssl.trustStoreType=WINDOWS-ROOT" /silent /closeapplications /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.