GSA/ansible-tomcat

Name: ansible-tomcat

Owner: U.S. General Services Administration

Description: Manage installation of Tomcat

Forked from: silpion/ansible-tomcat

Created: 2017-01-25 03:30:08.0

Updated: 2017-01-25 03:30:11.0

Pushed: 2017-01-25 04:59:49.0

Homepage: null

Size: 211

Language: Shell

GitHub Committers

UserMost Recent Commit# Commits

Other Committers

UserEmailMost Recent Commit# Commits

README

ansible-tomcat

Install Tomcat with configurable Catalina instances.

Compatibility
1.3.0

Starting with this role version default Tomcat major version has been updated to Tomcat 8 (8.0.29).

0.8.0

Starting with this role version managing instances has been changed significantly, mostly to better support capabilities from Systemd (e.g. templated services). Updating the role requires to reconfigure inventory. So please be aware of tomcat_instances documentation below.

Requirements

This role requires local facts in /etc/ansible/facts.d/java.fact to be available. The following variable must be available for the default service templates to work:

Facts are used as

groover.java role may get used to automatically fulfill the requirements.

Dependencies

This role depends on groover.util role. This is configured for ansible-galaxy install in requirements.yml.

NOTE: Requirements are installed as virtual user silpion (silpion.util).

Be sure to install required roles with

ansible-galaxy install --role-file requirements.yml
catalina_base vs catalina_home or “Where to put my webapp and config?”

Tomcat uses two main paths: CATALINA_BASE which contains all common files and CATALINA_HOME which contains instance-specific files. Consequently, any webapp and configuration must be deployed to CATALINA_HOME which defaults to /srv/tomcat/catalina/tomcat.

Role variables
tomcat_instances

Instance configuration default variables may get configured per instance. The following variables are legit to configure per instance.

Configuring more than one instance requires to configure some of the variables documented above per instance. Please see example playbooks below.

Versioned variables

Predefined SHA sums and further version specific configuration may get found in the vars/versions directory. When configuring a version, that is not predefined (so far), the following variables must also be defined in the playbook/inventory:

tomcat_web_xml_schema_version

How to get the schema version for a specific tomcat version? e.g. 8.0.21:

svn cat http://svn.apache.org/repos/asf/tomcat/tc8.0.x/tags/TOMCAT_8_0_21/conf/web.xml 2>&1|grep -v encoding|grep -e web-app_ -e version=

e.g. 7.0.56:

svn cat http://svn.apache.org/repos/asf/tomcat/tc7.0.x/tags/TOMCAT_7_0_56/conf/web.xml 2>&1|grep -v encoding|grep -e web-app_ -e version=
Systemd configuration

Configuring Systemd uses templated services by default. This allows to have Tomcat instances managed with Systemd in the same system slice. By default this role installs one service tomcat@tomcat.service.

This makes it particularly not easy to add Systemd UMask= or DefaultInstance= configuration. If there is more than one instance configured with tomcat_instances to run as the same user, there will be ONE service file /etc/systemd/system/USER@.service.

This behaviour can get overridden by configuring

per Systemd managed Tomcat instance. service_name here is the name addressed as per systemctl restart service_name, service_file is the file written by template: module to /etc/systemd/system/service_file.

When configuring multiple tomcat instances for Systemd please ensure to configure Ansible instance name (- name: INSTANCE_NAME) and item.service instance name (INSTANCE_NAME@slice_name.service) likewise.

- name: FOOBAR
  service_name: FOOBAR@whatever
  service_file: whatever@.service
Example playbook(s)
Default

This playbook will install ONE tomcat instance with default configuration as suggested upstream.

Tomcat will get installed to /opt/tomcat/apache-tomcat-{{ tomcat_version }} as CATALINA_HOME. Default instance tomcat will get installed in /srv/tomcat/catalina/tomcat as CATALINA_BASE.

The following services will get installed based on init system:

---
- hosts: tomcat_server
  roles:
    - { role: ansible-tomcat }
Two instances, one user, Systemd, share slice

This playbook installs two Tomcat instances targeted on a Systemd enabled node running as the same user 'tomcat'.

Tomcat instances foo and bar will get installed in /srv/tomcat/catalina/foo and /srv/tomcat/catalina/bar as CATALINA_BASE.

Both instances share system-tomcat.slice.

Mandatory variables for service management 
---
- hosts: tomcat_server
  vars:
    tomcat_instances:
      - name: foo
        service_name: tomcat@foo
        port_ajp: 18009
        port_connector: 18080
        port_redirect: 18443
        port_shutdown: 18005
      - name: bar
        service_name: tomcat@bar
        port_ajp: 28009
        port_connector: 28080
        port_redirect: 28443
        port_shutdown: 28005
  roles:
    - { role: ansible-tomcat }
Two instances, one user, upstart

The same playbook targeted on an Ubuntu server with Upstart.

Mandatory variables for service management

NOTE: item.service_name and item.service_file names must match except for the service_file extension (.conf).

---
- hosts: tomcat_server
  vars:
    tomcat_instances:
      - name: foo
        service_name: tomcat-foo
        service_file: tomcat-foo.conf
        port_ajp: 18009
        port_connector: 18080
        port_redirect: 18443
        port_shutdown: 18005
      - name: bar
        service_name: tomcat-bar
        service_file: tomcat-bar.conf
        port_ajp: 28009
        port_connector: 28080
        port_redirect: 28443
        port_shutdown: 28005
  roles:
    - { role: ansible-tomcat }
Two instances, different users, SysV

Running two Tomcat instances with different users targeted on a SysV enabled system, e.g. RHEL6.

Mandatory variables for service management

NOTE: item.service_name and item.service_file names must match.

---
- hosts: tomcat_server
  vars:
    tomcat_instances:
      - name: foo
        user: tomcatfoo
        group: tomcatfoo
        path: /srv/tomcatfoo
        home: /home/tomcatfoo
        service_name: tomcat-foo
        service_file: tomcat-foo
        port_ajp: 18009
        port_connector: 18080
        port_redirect: 18443
        port_shutdown: 18005
      - name: bar
        user: tomcatbar
        group: tomcatbar
        path: /srv/tomcatbar
        home: /home/tomcatbar
        service_name: tomcat-bar
        service_file: tomcat-bar
        port_ajp: 28009
        port_connector: 28080
        port_redirect: 28443
        port_shutdown: 28005
  roles:
    - { role: ansible-tomcat }
Two instances, different users, Systemd, share slice

The same playbook targeted on a Systemd enabled node.

Mandatory variables for service management 
---
- hosts: tomcat_server
  vars:
    tomcat_instances:
      - name: foo
        user: tomcatfoo
        group: tomcatfoo
        path: /srv/tomcatfoo
        home: /home/tomcatfoo
        service_name: foo@tomcat
        service_file: foo@.service
        port_ajp: 18009
        port_connector: 18080
        port_redirect: 18443
        port_shutdown: 18005
      - name: bar
        user: tomcatbar
        group: tomcatbar
        path: /srv/tomcatbar
        home: /home/tomcatbar
        service_name: bar@tomcat
        service_file: bar@.service
        port_ajp: 28009
        port_connector: 28080
        port_redirect: 28443
        port_shutdown: 28005
  roles:
    - { role: ansible-tomcat }
Two instances, different users, Systemd, not sharing a slice

The same playbook without sharing Systemd system slice.

Mandatory variables for service management 
---
- hosts: tomcat_server
  vars:
    tomcat_instances:
      - name: foo
        user: tomcatfoo
        group: tomcatfoo
        path: /srv/tomcatfoo
        home: /home/tomcatfoo
        service_name: tomcatfoo
        service_file: tomcatfoo.service
        port_ajp: 18009
        port_connector: 18080
        port_redirect: 18443
        port_shutdown: 18005
      - name: bar
        user: tomcatbar
        group: tomcatbar
        path: /srv/tomcatbar
        home: /home/tomcatbar
        service_name: tomcatbar
        service_file: tomcatbar.service
        port_ajp: 28009
        port_connector: 28080
        port_redirect: 28443
        port_shutdown: 28005
  roles:
    - { role: ansible-tomcat }
Whatever you want setup

Defaults? I don't like defaults on my Ubuntu server. I'll override all the defaults!

---
- hosts: tomcat_server
  vars:
    tomcat_version: 8.0.5
    tomcat_install_base: /srv
    tomcat_default_user_name: xyz
    tomcat_default_user_group: zyx
    tomcat_default_user_home: /var/home/xyz
    tomcat_default_user_system: true
    tomcat_default_instance_path: /srv/xyz
    tomcat_default_server_xml_template: myveryownserverxmltemplate.j2
    tomcat_default_port_ajp: 12345
    tomcat_default_port_connector: 12346
    tomcat_default_port_redirect: 12347
    tomcat_default_port_shutdown: 12348
    tomcat_default_catalina_opts: '-Dwhatever'
    tomcat_default_upstart_template: myveryownupstarttemplate.j2
    tomcat_default_override_uri_encoding: UTF-8
    tomcat_service_allow_restart: false
    tomcat_instances:
      - name: nodefaults
        service_name: motcat
        service_file: motcat.conf
        catalina_opts: '-Dwhatever'
        umask: 0002
  roles:
    - { role: ansible-tomcat }

Defaults again? I still don't like defaults on my CentOS 7 server. I'll override all the configuration but focus on instance configuration.

---
- hosts: tomcat_server
  vars:
    tomcat_version: 8.0.5
    tomcat_install_base: /srv
    tomcat_service_allow_restart: false
    tomcat_instances:
      - name: nodefaults
        user: xyz
        group: zyx
        home: /var/home/xyz
        system: true
        path: /srv/xyz
        service_template: myveryownsystemdtemplate.j2
        server_xml_template: myveryownserverxmltemplate.j2
        port_ajp: 12345
        port_connector: 12346
        port_redirect: 12347
        port_shutdown: 12348
        service_name: motcat
        service_file: motcat.service
        catalina_opts: '-Dwhatever'
        prefer_ipv4: false
        prefer_urandom: false
        umask: 0002
        override_uri_encoding: UTF-8
  roles:
    - { role: ansible-tomcat }
Contributing

If you want to contribute to this repository please be aware that this project uses a gitflow workflow with the next release branch called next.

Please fork this repository and create a local branch split off of the next branch and create pull requests back to the origin next branch.

License

Apache Version 2.0

Integration testing

This role provides integration tests using the Ruby RSpec/serverspec framework with a few drawbacks at the time of writing this documentation.

Running integration tests requires a number of dependencies being installed. As this role uses Ruby RSpec there is the need to have Ruby with rake and bundler available.

# install role specific dependencies with bundler
bundle install

# run the complete test suite with Docker
rake suite

# run the complete test suite with Vagrant
RAKE_ANSIBLE_USE_VAGRANT=1 rake suite

Author information

Contributors
This work is supported by the National Institutes of Health's National Center for Advancing Translational Sciences, Grant Number U24TR002306. This work is solely the responsibility of the creators and does not necessarily represent the official views of the National Institutes of Health.