tomcat-multiple-instances

Deploys and manages multiple independent Apache Tomcat instances on a single host, using binaries from the distribution packages. Each instance runs under its own systemd unit (or SysV init script), has its own directory tree, log directory, and configuration, and can be individually tuned for JVM options, connectors, SSL/TLS, JMX, and remote debugging.

Requirements

• The tomcat role (declared as a dependency) must be applied first. It installs the base Tomcat distribution packages.
• For SSL/TLS with mkcert certificates: the os-bootstrap role must have been applied to provision mkcert_cert_file_path and mkcert_key_file_path.
• For SSL/TLS with Let’s Encrypt certificates: the acme-sh-client role must be applied and letsencrypt_acme_sh_certificates_install_path must be set.
• Ansible >= 2.9, Ubuntu focal or jammy.

Role Variables

Global defaults

Variable	Default	Description
tomcat_m_instances_base_path	/var/lib/tomcat_instances	Base directory for all instance directories
tomcat_m_instances_logdir_base	/var/log/tomcat_instances	Base directory for all instance log directories
tomcat_m_cache_base	/var/cache/tomcat-instances	Base directory for instance work directories
tomcat_m_default_user	tomcat{{ tomcat_version }}	System user owning instances when tomcat_m_use_default_user is true
tomcat_m_use_default_user	true	Use a single shared system user for all instances
tomcat_m_default_user_shell	/bin/false	Shell for the Tomcat system user
tomcat_m_expose_log_directory	false	Make log dirs group-readable by www-data
tomcat_m_max_threads	200	Default HTTP connector max threads
tomcat_m_min_heap_size	2048m	JVM minimum heap (-Xms)
tomcat_m_heap_size	{{ tomcat_m_min_heap_size }}	JVM maximum heap (-Xmx)
tomcat_m_restart_timeout	300	systemd TimeoutStopSec in seconds
tomcat_m_shutdown_port	-1	Shutdown port (-1 disables it)
tomcat_m_webapps_autodeploy	false	Enable Tomcat autodeploy
tomcat_m_webapps_unpack	false	Unpack WARs on deploy
tomcat_m_start_instances	true	Start instances after first install
tomcat_m_enable_instances	true	Enable instances at boot
tomcat_m_jndi_pool	false	Install a JNDI connection pool context.xml
tomcat_m_direct_access	false	Allow direct access (no reverse proxy)
tomcat_systemd_additional_rw_paths	[]	Extra read-write paths for the systemd unit sandbox

Reverse proxy and HTTP proxy

Variable	Default	Description
tomcat_m_reverse_proxy_name_enabled	false	Enable proxyName/proxyPort on the HTTP connector
tomcat_m_reverse_proxy_name	{{ ansible_fqdn }}	Proxy name
tomcat_m_reverse_proxy_port	{{ http_port \| default(80) }}	Proxy port
tomcat_m_proxy_enabled	false	Configure JVM HTTP/HTTPS proxy settings
tomcat_m_proxy_http_host	localhost	Proxy host
tomcat_m_proxy_http_port	3128	Proxy port

Manager and Host Manager

Variable	Default	Description
tomcat_m_manager_install	false	Install the Tomcat Manager application
tomcat_m_host_manager_install	false	Install the Host Manager application
tomcat_m_manager_gui_user_enabled	false	Enable a manager-gui user
tomcat_m_manager_script_user_enabled	true	Enable a manager-script user
tomcat_m_manager_jmx_user_enabled	false	Enable a manager-jmx user
tomcat_m_manager_status_user_enabled	false	Enable a manager-status user

Manager passwords must be set in a vault file (e.g. tomcat_m_manager_gui_pwd, tomcat_m_manager_script_pwd).

JMX

Variable	Default	Description
tomcat_m_jmx_enabled	false	Enable JMX remote monitoring
tomcat_m_jmx_port	8186	JMX remote port
tomcat_m_jmx_auth_enabled	false	Require JMX authentication
tomcat_m_jmx_use_ssl	false	Enable SSL for JMX
tomcat_m_jmx_disable_additional_ports	true	Use a single JMX port (requires JDK >= 7.0.25)
tomcat_m_jmx_localhost_only	false	Bind JMX to localhost only
tomcat_m_jmx_ip_address	{{ ansible_default_ipv4.address }}	JMX bind address

JMX passwords (tomcat_m_jmx_monitorpass, tomcat_m_jmx_controlpass) must be set in a vault file.

Remote debugging

Variable	Default	Description
tomcat_m_enable_remote_debugging	false	Enable JDWP remote debugging
tomcat_m_remote_debugging_host	0.0.0.0	Debugging bind address
tomcat_m_remote_debugging_port	8100	Debugging port

SSL/TLS

Variable	Default	Description
tomcat_m_ssl_cert_source	letsencrypt	Certificate source: letsencrypt or mkcert
tomcat_m_ssl_protocols	TLSv1.2+TLSv1.3	Allowed TLS protocols
tomcat_m_ssl_fullchain_filename	fullchain.pem	Destination filename for the certificate chain
tomcat_m_ssl_key_filename	privkey.pem	Destination filename for the private key
tomcat_m_ssl_max_parameter_count	1000	maxParameterCount on the SSL connector
tomcat_m_ssl_letsencrypt_cert_dir	{{ letsencrypt_acme_sh_certificates_install_path \| default(...) }}	Source directory for Let’s Encrypt certificates
tomcat_m_letsencrypt_hooks_dir	{{ letsencrypt_acme_services_scripts_dir \| default('/usr/lib/acme/hooks') }}	Directory for Let’s Encrypt renewal hooks

For mkcert certificates the role reads mkcert_cert_file_path and mkcert_key_file_path from the os-bootstrap role directly. No additional variables need to be defined.

SSL is activated per instance with ssl_enabled: true. The destination directory defaults to <instance_path>/ssl and is created automatically.

Instance list

tomcat_m_instances is the central variable. Each entry is a dict with the following keys:

Key	Required	Description
instance_path	yes	Absolute path for the instance directory tree
user	yes	System user running this instance
http_port	yes	HTTP connector port (also used to name log dirs, units, and hooks)
http_enabled	no	Enable the HTTP connector (default: true)
http_address	no	HTTP connector bind address (default: 127.0.0.1)
ajp_enabled	no	Enable the AJP connector (default: false)
ajp_port	no	AJP connector port
ajp_address	no	AJP connector bind address
ssl_enabled	no	Enable the HTTPS connector (default: false)
ssl_port	no	HTTPS connector port (default: 8443)
ssl_cert_dir	no	Override SSL cert directory (default: <instance_path>/ssl)
shutdown_port	no	Shutdown port (default: -1, disabled)
java_home	no	JAVA_HOME for this instance
user_home	no	Home directory for the system user
user_shell	no	Shell for the system user
max_threads	no	HTTP connector max threads
autodeploy	no	Enable autodeploy
unpack	no	Unpack WARs
install_server_xml	no	Install a managed server.xml
default_conf	no	Install default configuration files
java_opts	no	JVM memory options
java_gc_opts	no	JVM GC options
other_java_opts	no	Additional JVM options
proxy_enabled	no	Enable HTTP proxy JVM options
jmx_enabled	no	Enable JMX for this instance
jmx_auth_enabled	no	Enable JMX authentication
jmx_auth_dir	no	Directory for JMX password files
jmx_port	no	JMX port
jmx_monitorpass	no	JMX monitor password (use a vault)
jmx_controlpass	no	JMX control password (use a vault)
jmx_disable_additional_ports	no	Use a single JMX port
remote_debugging	no	Enable remote debugging
remote_debugging_uri	no	Debugging bind URI (host:port)
access_log_enabled	no	Enable access log valve
log_rotation_freq	no	Logrotate frequency (e.g. daily)
log_retain	no	Number of rotated logs to keep
restart_timeout	no	systemd stop timeout in seconds
allowed_hosts	no	List of allowed remote host CIDRs (remote address filter valve)
app_contexts	no	List of application context paths (used by proxy roles)
catalina_tmp_directory	no	Custom java.io.tmpdir path

Dependencies

• tomcat role (installed from the internal Gitea): installs the base Tomcat packages and provides variables such as tomcat_version, tomcat_user, tomcat_use_systemd_unit, and jdk_java_home.
• os-bootstrap role (optional): required when tomcat_m_ssl_cert_source: mkcert, provides mkcert_cert_file_path and mkcert_key_file_path.
• acme-sh-client role (optional): required when tomcat_m_ssl_cert_source: letsencrypt.

Example Playbook

- hosts: appservers
  roles:
    - role: tomcat-multiple-instances
      vars:
        tomcat_m_instances:
          - instance_path: /var/lib/tomcat_instances/8180
            user: "{{ tomcat_m_default_user }}"
            http_enabled: true
            http_port: "8180"
            http_address: "127.0.0.1"
            ajp_enabled: false
            ajp_port: "8109"
            ajp_address: "127.0.0.1"
            ssl_enabled: true
            ssl_port: "8443"
            shutdown_port: "-1"
            java_home: "{{ jdk_java_home }}"
            install_server_xml: true
            default_conf: true
            access_log_enabled: true
            log_rotation_freq: daily
            log_retain: 30
            app_contexts:
              - app1
              - app2

Tags

Tag	Scope
tomcat	All tasks
tomcat_instances	All instance management tasks
tomcat_conf	Configuration file tasks
tomcat_serverxml	server.xml and web.xml
tomcat_init	Startup scripts and systemd units
tomcat_default	/etc/default environment files
tomcat_ssl	SSL/TLS certificate tasks
tomcat_jmx	JMX configuration tasks
tomcat_manager	Manager application tasks
tomcat_host_manager	Host Manager application tasks
tomcat_log_dir	Log directory tasks

License

EUPL-1.2

Author Information

Andrea Dell’Amico, ISTI-CNR — andrea.dellamico@isti.cnr.it