Hooks

• cluster-relation-departed
• cluster-relation-joined
• config-changed
• install
• jndi-db-mysql-relation-broken
• jndi-db-mysql-relation-changed
• jndi-db-mysql-relation-joined
• jndi-db-pgsql-relation-broken
• jndi-db-pgsql-relation-changed
• jndi-db-pgsql-relation-joined
• jndi-memcached-relation-broken
• jndi-memcached-relation-changed
• jndi-memcached-relation-departed
• jndi-memcached-relation-joined
• jndi-terracotta-relation-broken
• jndi-terracotta-relation-departed
• jndi-terracotta-relation-joined
• start
• stop
• terracotta-relation-broken
• terracotta-relation-departed
• terracotta-relation-joined
• tomcat-common
• upgrade-charm
• website-relation-joined

Interfaces

Config

Readme

Overview
--------

Apache Tomcat implements the Java Servlet and the JavaServer Pages (JSP)
specifications from Sun Microsystems, and provides a "pure Java" HTTP
web server environment for Java code to run.

Apache Tomcat 7 implements the Java Servlet 3.0 and JSP 2.0 specification
from Sun Microsystems/Oracle and provides a pure Java HTTP web server.

http://tomcat.apache.org

Usage
-----

General

A tomcat deployment consists of a Tomcat service:

  juju deploy tomcat tomcat

By default, this is Tomcat 7.  You can deploy Tomcat 6 by specifying the version
at deployment.  First create 'config.yaml' with the contents:

  tomcat:
    tomcat_version: tomcat6

Then deploy:

  juju deploy --config config.yaml tomcat tomcat

Once deployed, you can specify what http port to use:

  # use port 80 for http
  juju set tomcat http_port=80

(NOTE: You could also do this at deployment with the '--config' switch)

The Tomcat manager applications, enabled by default, are protected by HTTP basic
password protection.  To access the applications you must set a password for
either the 'admin' or 'status' roles.  The admin role has full access to
configure Tomcat whereas the status role may only see server status.  To set
passwords:

  juju set tomcat "admin_password=<password>"
  juju set tomcat "status_password=<password>"

To expose Tomcat to the Internet:

  juju expose tomcat

  Open web browser at http://<host>/manager or http://<host>/manager/status
  using your admin or status username/password respectively.

(Note: Passwords will be sent to the manager in plain text, so it's recommended
you enable HTTPS as follows)

To enable HTTPS:

  # enable https connector
  juju set tomcat https_enabled=True
  # use port 443 for https
  juju set tomcat https_port=443

  Open web browser at https://<host>/manager or https://<host>/manager/status.

A self-signed certificate will be generated for HTTPS use by default.  You can
specify your own private key and certificate as a PKCS12 file as follows:

  # set pkcs12 file
  juju set tomcat "keystore=`base64 < <pkcs12 file>`"
  # set pkcs12 file password
  juju set tomcat "keystore_password=<password>"

The PKCS12 file is transmitted securely to your Juju cluster and subsequently
used by all service units (added with 'juju add-unit') for easy certificate
management.  Should you remove your certificate by setting 'keystore' to an
empty string, a new self-signed certificate will be generated for use.

Whilst the manager applications are a useful way of testing a Tomcat
installation there's no real usage for them when deploying applications using a
Juju subordinate charm like 'j2ee-deployer'.  Therefore as a security
precaution, it's recommended you disable them in a production environment:

  # disable manager applications
  juju set tomcat manager_enabled=False

Tomcat offers two pure Java HTTP connectors, Blocking I/O ('bio') and
Non-Blocking I/O ('nio').
bio is the default connector and uses a thread per connection.
nio uses a single thread to read connections asynchronously.
If you have enough traffic to be concerned about performance of each,
it's recommended you benchmark both.  Better performance can be achieved with
either depending on conditions.  Traditionally, Java application traffic favours
the bio connector and serving of static content the nio connector.
You may set either as follows:

  # set nio connector
  juju set http_connector=nio

  # set bio connector
  juju set http_connector=bio


JMX

JMX monitoring is disabled by default, but you can enable it with the
following commands:

  juju set tomcat jmx_enabled=True
  juju set tomcat jmx_control_password=<password>
  juju set tomcat jmx_monitor_password=<password>

The control role (username - 'controlRole') allows read/write access, the
monitor role (username - 'monitorRole') read only access.  If a password is
empty, it disables access for that role.

There is a further JMX option, 'jmx_localhost'.  This determines what hostname
is given to the JMX client to connect to.  If false, the internal hostname or IP
address of the unit will be used, meaning connection is suited to either LXC
based deployments or cloud deployments where you have VPN access:

  JConsole or VisualVM connect to <private unit address>:10001 with
  username/password

For cloud deployments, setting this to true uses 'localhost' hostname, which
allows you to connect over a ssh tunnel:

  ssh -L 10001:localhost:10001 -L 10002:localhost:10002 <public unit address>
  JConsole or VisualVM connect to localhost:10001 with username/password

The latter is much more typical of out of the box deployment, so 'jmx-localhost'
defaults to True.


Datasources

You can connect Tomcat to a RDBMS such as MySQL or PostgreSQL for use by
applications via JNDI lookup.  Database configuration is controlled using the
'jndi_db_config' option.  This is a comma separated list of JNDI name, database
service, database and DBCP (http://commons.apache.org/dbcp/) connection pooling
colon separated values:

  <name>:<service>:<database>:<dbcp options>,<name>:<service>:<database>:<dbcp options>

DBCP options are key/value pairs separated by semi-colons.

(Note: You can use multiple databases from the same MySQL service.  When a
database isn't defined for a MySQL service, the database 'tomcat' is used.
PostgreSQL doesn't support multiple databases from the same service, so database
is ignored.)

For example:

  # map mysql database tomcat1 to jndi name 'jdbc/TomcatDB1'
  # map mysql database tomcat2 to jndi name 'jdbc/TomcatDB2'
  juju set tomcat "jndi_db_config=jdbc/TomcatDB1:mysql:tomcat1,jdbc/TomcatDB2:mysql:tomcat2"

  # map mysql database tomcat3 to jndi name 'jdbc/TomcatDB3' using DBCP options
  juju set tomcat "jndi_db_config=jdbc/TomcatDB3:mysql:tomcat3:initialSize=100;maxActive=100;maxIdle=100"

  # map postgresql to jndi name 'jdbc/PostgresqlDB' with DBCP options
  juju set tomcat "db-config=jdbc/PostgresqlDB:postgresql::initialSize=100;maxActive=100;maxIdle=100"

Having deployed the appropriate charm, add the relation:

  # mysql
  juju add-relation tomcat:jndi-db-mysql mysql:shared-db

  # postgresql
  juju add-relation tomcat:jndi-db-pgsql postgresql:db

After configuring and establishing the relation, a pooled DBCP datasource
connector is available for use in your deployed application under the chosen
JNDI name (with base context 'java:comp/env').  The Spring framework supports
using JNDI datasources as part of other constructs within your application, see
http://www.springsource.org for further details.


JNDI

Tomcat supports adding arbitrary configuration parameters for JNDI lookup by
deployed applications.  This enables you to develop applications that discover
configuration details at runtime simply by referencing pre-determined JNDI
names.  This charm supports lookup of different services, each of which may be
configured using the appropriate 'jndi_<type>_config' option.  Unless specified
otherwise, options are generally a comma separated list of JNDI name, service
and type specific colon separated values:

  <name>:<service>:<type options>,<name>:<service>:<type options>

These allow you to map multiple services to multiple JNDI names as follows:

  # map memcached service 'memcached1' to jndi name 'param/Memcached1'
  # map memcached service 'memcached2' to jndi name 'param/Memcached2'
  juju set tomcat "jndi_memcached_config=param/Memcached1:memcached1,param/Memcached2:memcached2"

Then add the relation:

  juju add-relation tomcat:jndi-memcached memcached:cache

The charm will take care of updating the mapped value with changes in the
cluster.  A brief description of the available JNDI relations is below.

Memcached (jndi_memcached_config) - Provides a space separated string of all
unit addresses for specified memcached service.  This can be used directly
in instantiating an instance of a Memcached client such as spymemcached
(http://code.google.com/p/spymemcached/).

Terracotta (jndi_terracotta_config) - Provides a comma separated string of all
unit addresses for the specified Terracotta service.  This can be injected
directly into EHCache or Quartz configuration (see http://www.terracotta.org for
more details).


Clustering

Tomcat supports session clustering, allowing a group of Tomcat units to
replicate J2EE session information to each other.  This is useful for HA
deployments where session contents are important.  To enable clustering across
units:

  # enable clustering
  juju set tomcat cluster_enabled=True

  # add 2 more units to cluster
  juju add-unit -n 2 tomcat

By default, static membership is used over multicast based membership which
means units depend on local cluster configuration to determine cluster groups.
Multicast uses multicast UDP packets on a pre-determined address/port to
determine cluster groups.  Where a cloud provider such as EC2 disables multicast
traffic between instances, static membership must be used.  Where multicast
traffic is allowed, it is preferred and may be enabled as follows:

  # enable multicast clustering
  juju set tomcat multicast=True

  # set multicast address
  juju set tomcat multicast_address=228.0.0.4

  # set multicast port
  juju set tomcat multicast_port=34569

For maximum performance with clustering, it's recommended you use a load
balancer in front of Tomcat that supports 'sticky sessions'.


Terracotta

Terracotta is a distributed HA caching/storage platform for Java.  You can use
this within your application by making use of the JNDI relation (as described
above) and/or you can configure Tomcat to use Terracotta for session clustering
(as opposed to Tomcat's own clustering above).  To use session clustering:

  juju add-relation tomcat:terracotta terracotta:dso

You can use the Terracotta dev console to view active clustering.  See
Terracotta charm or http://www.terracotta.org for more details.

Changes