Adoptable Cookbooks List

Looking for a cookbook to adopt? You can now see a list of cookbooks available for adoption!
List of Adoptable Cookbooks

Supermarket Belongs to the Community

Supermarket belongs to the community. While Chef has the responsibility to keep it running and be stewards of its functionality, what it does and how it works is driven by the community. The chef/supermarket repository will continue to be where development of the Supermarket application takes place. Come be part of shaping the direction of Supermarket by opening issues and pull requests or by joining us on the Chef Mailing List.

Select Badges

Select Supported Platforms

Select Status


apache_tomcat (11) Versions 0.4.1

Installs/Configures tomcat

cookbook 'apache_tomcat', '= 0.4.1', :supermarket
cookbook 'apache_tomcat', '= 0.4.1'
knife supermarket install apache_tomcat
knife supermarket download apache_tomcat
Quality 0%


Manage installation and configuration of Apache Tomcat. Includes
support for multiple instances on a single server as well as flexible management
of XML configuration files.

  • Note: This is a work in progress. Documentation and features/stability will improve before 1.0. Initial release is for testing purposes only.

Version 0.4.0 brings breaking changes.

Runit was previously the service manager used with this cookbook. This version
switches to using poise_service, a pluggable service resource. See

To continue using runit as the service manager, add 'poise-service-runit' and
'runit' (= 1.6; runit 1.7 is currently not compatible with poise-service-runit) as
a dependency in your wrapper cookbook. This will install and set the runit service
plugin as the default. That's all you have to do.

This also has the side-effect of adding proper service-type actions on the
apache_tomcat_service resource. You can now notify the resource for :restart,
:reload, :start, :stop, :enable, etc.

One final note, when using the poise-service-runit cookbook the log location is
different than previous versions of this cookbook. Instead of /var/log/tomcat/<instance>
logs are now in /var/log/tomcat-<instance>. A minor change, but one that makes
sense in my opinion.

If you encounter any other breaking changes not outlined here, please file an
issue. After version 1.0.0 this would have warranted a 2.0.0 (major version) bump.


Install Apache Catalina Tomcat

This cookbook takes the approach of splitting CATALINA_BASE and CATALINA_HOME.
CATALINA_HOME is the 'shared' location and defaults to /usr/share/tomcat-<version>.
CATALINA_BASE represents a particular instance of Tomcat where applications (WARs)
are deployed. There can be any number of instances per server. CATALINA_BASE
consists of bin, conf, lib, logs, webapps, work and temp directories. Configuration
like server.xml, web.xml go in conf and applications are deployed in webapps as you
might expect.

apache_tomcat 'my_tomcat' do
  url ''
  # Note: Checksum is SHA-256, not MD5 or SHA1. Generate using `shasum -a 256 /path/to/tomcat.tar.gz`
  checksum 'sha256_checksum'
  version '8.0.24

# Default version is 8.0.24. To use defaults, simply define:
apache_tomcat 'my_tomcat'

Create an instance

For a basic instance, define as seen below. Please note that this will create
a default web.xml, server.xml and context.xml. This will likely meet most
user's needs. However, if you need custom configuration for any of these files
set the corresponding attribute to false.

apache_tomcat_instance 'instance1'

# Non-default attributes
apache_tomcat_instance 'instance1' do
  setenv_options(config: ['export CATALINA_OPTS=foo'])
  include_default_server_xml false
  include_default_web_xml false
  include_default_context_xml false

Create Custom Web XML

If include_default_web_xml is set to false on the instance resource you will
need to define a config resource to build a custom web.xml file.

# Default attributes
# Note: The definition below will result in an identical web.xml as when created
# by the instance resource with `include_default_web_xml true`.
apache_tomcat_config 'web' do
  type :web
  instance 'instance1' # Reference to `apache_tomcat_instance` resource.

# Non-default attributes

## First, disable default web.xml creation in the instance
apache_tomcat_instance 'instance1' do
  create_default_web_xml false

apache_tomcat_config 'web' do
  type :web
  instance 'instance1'
  config_options do
    include_defaults false
    include_default_mime_types true
          'name'            => 'my_servlet',
          'class'           => 'org.mycompany.MyServlet',
          'init_params'      => { 'debug' => '1', 'listings' => true },
          'load_on_startup' => '1'
        # ... additional servlets ...
          'name'            => 'my_servlet',
          'url_pattern'     => '/', # or an array: ['*.jsp', '*.jspx']
        # ... additional servlet mappings ...
          'name'            => 'my_filter',
          'class'           => 'org.mycompany.MyFilter',
          'init_params'     => { 'encoding' => 'UTF8', 'max' => '100' },
          'async_supported' => true
        # ... additional filters ...
          'name' => 'my_filter',
          'url_pattern' => '/*', # or an array: ['/pages/*', '/admin/*']
          'dispatcher' => 'REQUEST'
        # ... additional filter_mappings ...
    session_timeout 30
    welcome_file_list ['index.jsp','index.html']

The above configuration yield the following web.xml:








Create Custom Server XML

## First, disable default server.xml creation in the instance
apache_tomcat_instance 'instance1' do
  create_default_server_xml false

# With defaults
apache_tomcat_config 'server' do
  type :server
  instance 'instance1' # Reference to `apache_tomcat_instance` resource.
  config_options do
    include_default_listeners true
    include_default_user_database true
    include_default_connectors true
    include_default_engine true

    # -- or --

    include_defaults true

# Non-default attributes

## First, disable default web.xml creation in the instance
apache_tomcat_instance 'instance1` do
  create_default_server_xml false

apache_tomcat_config 'server' do
  type :server
  instance 'instance1'
  config_options do
    include_defaults false
    include_default_listeners true
    include_default_engine true
    server_port 9005
          'class_name'  => 'org.mycompany.MyComplexListener',
          'params'      => { 'SSLEngine' => 'on' }
        ... additional listeners ...
    entities [ 'connector-http-9080', 'engine-custom' ]

The above configuration yield the following server.xml:

<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE server-xml [
  <!ENTITY connector-http-9080 SYSTEM "connector-http-9080.xml">
  <!ENTITY engine-custom SYSTEM "engine-custom.xml">
  Licensed to the Apache Software Foundation (ASF) under one or more
  contributor license agreements.  See the NOTICE file distributed with
  this work for additional information regarding copyright ownership.
  The ASF licenses this file to You under the Apache License, Version 2.0
  (the "License"); you may not use this file except in compliance withs
  the License.  You may obtain a copy of the License at

  Unless required by applicable law or agreed to in writing, software
  distributed under the License is distributed on an "AS IS" BASIS,
  See the License for the specific language governing permissions and
  limitations under the License.
<Server port="9005" shutdown="SHUTDOWN" >
    <Listener className="org.apache.catalina.startup.VersionLoggerListener" />
    <Listener className="org.apache.catalina.core.AprLifecycleListener" SSLEngine="on" />
    <Listener className="org.apache.catalina.core.JreMemoryLeakPreventionListener" />
    <Listener className="org.apache.catalina.mbeans.GlobalResourcesLifecycleListener" />
    <Listener className="org.apache.catalina.core.ThreadLocalLeakPreventionListener" />
    <Listener className="org.mycompany.MyListener" />
    <Listener className="org.mycompany.MyComplexListener"

    <Service name="Catalina">

        <Engine name="Catalina" defaultHost="localhost">
            <Realm className="org.apache.catalina.realm.LockOutRealm">
                <Realm className="org.apache.catalina.realm.UserDatabaseRealm"

            <Host name="localhost"


Deploying Tomcat Default Bundle Webapps

Tomcat comes with a bundle of default webapps. These webapps are preserved as
war files in CATALINA_HOME/bundle_wars. To install these webapps to a tomcat
instance set the bundle_webapps_enabled array with the webapps to install. To
ensure that a webapp is removed after it is removed from bundle_webapps_enabled,
add it to the bundle_webapps_managed array passed to the instance. The following
code example will remove host-manager and manager webapps if they are not included
in the bundle_webapps_enabled array, where as the ROOT and docs webapps will remain installed
if they are not included in the bundle_webapps_enabled array. ROOT and docs would
have to be removed manually. If you have a custom webapp that has the same name as
any of the bundle webapps, you will need to make sure that webapp is not included in
bundle_webapps_enabled and bundle_webapps_managed array, otherwise it may be removed
or overriden by the default bundle webapp.

Tomcat default bundle webapps available for installation: ROOT, docs, examples, host-manager, manager

apache_tomcat_instance 'instance1'

# Non-default attributes
apache_tomcat_instance 'instance1' do
  setenv_options(config: ['export CATALINA_OPTS=foo'])
  include_default_server_xml false
  include_default_web_xml false
  include_default_context_xml false
  bundle_webapps_enabled ['ROOT', 'docs', 'host-manager', 'manager']
  bundle_webapps_managed ['host-manager', 'manager']


Code Style

To run style tests (Rubocop and Foodcritic):
rake style

If you want to run either Rubocop or Foodcritic separately, specify the style
test type (Rubocop = ruby, Foodcritic = chef)
rake style:chef
rake style:ruby

RSpec tests

Run RSpec unit tests
rake spec

Test Kitchen

Run Test Kitchen tests (these tests take quite a bit of time)
rake integration:vagrant

If the cookbook has tests that run in EC2
rake integration:cloud


If you choose to fork this cookbook here are some good tips to keep things in

  1. Fork the cookbook before cloning.
  2. Clone the forked repo, not the original.
  3. Once the fork is cloned, go to the repo directory and add an upstream remote git remote add upstream

Now you can pull upstream changes (things merged into the main cookbook repo).
Note that you will also need to push to your fork's master to keep it updated.
The alias below will help you. After adding the alias you will simply be able to
run git-reup and it will pull the upstream changes and push them to
your fork. Then checkout a branch and work as normal.

Add the following alias in ~/.bash_profile.
alias git-reup='git checkout master && git pull upstream master && git push origin master'



No platforms defined


  • poise-service (~> 1.0)
  • ark (~> 0.9)
  • java (~> 1.31)


No attributes defined


  • apache_tomcat::default

License and Maintainer

Maintainer:: Drew A. Blessing (

License:: Apache 2.0



  • Added proper matchers for apache_tomcat_service


  • Modify service to use poise_service. Fixes #7 NOTE: This is technically a breaking change. See for more information.


  • Fixed issue with tomcat bundle wars exploding into nested dir


  • Fixed default manifest creation issue with tomcat bundle wars


  • Default Tomcat webapp bundle management. Thanks to @klangrud


  • Fix bug in server.xml with UserDatabase realm


  • Add LICENSE and license headers. Fixes #1
  • Add ChefSpec matchers. Fixes #3
  • Fix README 'bug'. Fixes #4
  • Fix entity bug in server.xml. Fixes #5
  • Fix style. Fixes #6
  • Fix runit service cookbook name bug.


  • Initial release

Foodcritic Metric

0.4.1 failed this metric

FC031: Cookbook without metadata file: /tmp/cook/2b4e346927268c1136ea849b/apache_tomcat/metadata.rb:1
FC045: Consider setting cookbook name in metadata: /tmp/cook/2b4e346927268c1136ea849b/apache_tomcat/metadata.rb:1