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
- Background
- Download
- 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
Background
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
No
when 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
logs
,temp
, andwork
directories.
This custom Apache Tomcat Setup installer rectifies these limitations.
Download
You can download the latest version from the Github Releases page:
https://github.com/Bill-Stewart/ApacheTomcatSetup/releases/
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
conf
directory), 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
webapps
directory. -
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
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.) |
/log=" filename" |
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:
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
LocalSystem
account.
Instance Name Defaults
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"
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
/currentuser
parameter 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:
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 Tasks
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"
.
Setting File System Permissions
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
, andwork
directories: 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.)
conf
Directory
Backing Up the 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
JAVA_HOME
,JDK_HOME
, andJRE_HOME
environment 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
Path
environment variable forjava.exe
. The Java home directory is the parent directory of the directory wherejava.exe
is found. For example, ifC:\Program Files\Eclipse Adoptium\JRE11\bin
is in the path (andjava.exe
is in that directory), the Java home directory isC:\Program Files\Eclipse Adoptium\JRE11
. -
If
java.exe
is 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 appends \bin\server\jvm.dll
to the Java home directory and uses the result as the path to the jvm.dll
file.
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 unins
nnn.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 Limitations
-
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.
Acknowledgments
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.