AWS OpsWorks
User Guide (API Version 2013-02-18)

Configure Recipes

Configure recipes are assigned to the layer's Configure lifecycle event, which occurs on all of the stack's instances whenever an instance enters or leaves the online state. You use Configure recipes to adjust an instance's configuration to respond to the change, as appropriate. When you implement a Configure recipe, keep in mind that a stack configuration change might involve instances that have nothing to do with this layer. The recipe must be able to respond appropriately, which might mean doing nothing in some cases.


The tomcat::configure recipe is intended for a layer's Configure lifecycle event.

include_recipe 'tomcat::context' # Optional: Trigger a Tomcat restart in case of a configure event, if relevant # settings in custom JSON have changed (e.g. java_opts/JAVA_OPTS): #include_recipe 'tomcat::container_config'

The tomcat::configure recipe is basically a metarecipe that runs two dependent recipes.

  1. The tomcat::context recipe create a web app context configuration file.

    This file configures the JDBC resources that applications use to communicate with the MySQL instance, as discussed in the next section. Running this recipe in response to a configure event allows the layer to update the web app context configuration file if the database layer has changed.

  2. The tomcat::container_config Setup recipe is run again to capture any changes in the container configuration.

The include for tomcat::container_config is commented out for this example. If you want to use custom JSON to modify Tomcat settings, you can remove the comment. A Configure lifecycle event then runs tomcat::container_config, which updates the Tomcat related configuration files, as described in tomcat::container_config and restarts the Tomcat service.


The Tomcat cookbook enables applications to access a MySQL database server, which can be running on a separate instance, by using a J2EE DataSource object. With Tomcat, you can enable the connection by creating and installing a web app context configuration file for each application. This file defines the relationship between the application and the JDBC resource that the application will use to communicate with the database. For more information, see The Context Container.

The tomcat::context recipe's primary purpose is to create this configuration file.

include_recipe 'tomcat::service' node[:deploy].each do |application, deploy| context_name = deploy[:document_root].blank? ? application : deploy[:document_root] template "context file for #{application} (context name: #{context_name})" do path ::File.join(node['tomcat']['catalina_base_dir'], 'Catalina', 'localhost', "#{context_name}.xml") source 'webapp_context.xml.erb' owner node['tomcat']['user'] group node['tomcat']['group'] mode 0640 backup false only_if { node['datasources'][context_name] } variables(:resource_name => node['datasources'][context_name], :webapp_name => application) notifies :restart, resources(:service => 'tomcat') end end

In addition to Tomcat cookbook attributes, this recipe uses the stack configuration and deployment attributes that AWS OpsWorks Stacks installs with the Configure event. The AWS OpsWorks Stacks service adds attributes to each instance's node object that contain the information that recipes would typically obtain by using data bags or search and installs the attributes on each instance. The attributes contain detailed information about the stack configuration, deployed apps, and any custom data that a user wants to include. Recipes can obtain data from stack configuration and deployment attributes by using standard Chef node syntax. For more information, see Stack Configuration and Deployment Attributes. With Chef 11.10 stacks, you also can use Chef search to obtain stack configuration and deployment data. For more information, see Using Chef Search.

deploy attributes refers to the [:deploy] namespace, which contains deployment-related attributes that are defined through the console or API, or generated by the AWS OpsWorks Stacks service. The deploy attribute includes an attribute for each deployed app, named with the app's short name. Each app attribute contains a set of attributes that characterize the app, such as the document root ([:deploy][:appname][:document_root]) . For example, here is a JSON representation of a highly abbreviated version of the stack configuration and deployment attributes for an app named my_1st_jsp that was deployed to a Tomcat-based custom layer from an Amazon S3 archive.

{ ... "datasources": { "ROOT": "jdbc/mydb" } ... "deploy": { "my_1st_jsp": { "document_root": "ROOT", ... "scm": { "password": null, "repository": "", "ssh_key": null, "scm_type": "archive", "user": null, "revision": null }, ... "deploy_to": "/srv/www/my_1st_jsp", ... "database": { "password": "86la64jagj", "username": "root", "reconnect": true, "database": "my_1st_jsp", "host": "" }, ... } }, ... }

The context recipe first ensures that the service is defined for this Chef run by calling tomcat::service. It then defines a context_name variable which represents the configuration file's name, excluding the .xml extension. If you use the default document root, context_name is set to the app's short name. Otherwise, it is set to the specified document root. The example discussed in Create a Stack and Run an Application sets the document root to "ROOT", so the context is ROOT and the configuration file is named ROOT.xml.

The bulk of the recipe goes through the list of deployed apps and for each app, uses the webapp_context.xml.erb template to create a context configuration file. The example deploys only one app, but the definition of the deploy attribute requires you to treat it as a list of apps regardless.

The webapp_context.xml.erb template is not operating-system specific, so it is located in the templates directory's default subdirectory.

The recipe creates the configuration file as follows:

  • Using default attribute values, the configuration file name is set to context_name.xml and installed in the /etc/tomcat6/Catalina/localhost/ directory.

    The ['datasources'] node from the stack configuration attributes contains one or more attributes, each of which maps a context name to the JDBC data resource that the associated application will use to communicate with the database. The node and its contents are defined with custom JSON when you create the stack, as described later in Create a Stack and Run an Application. The example has a single attribute that associates the ROOT context name with a JDBC resource named jdbc/mydb.

  • Using default attribute values, the file's user and group are both set to the values defined by the Tomcat package: tomcat (Amazon Linux) or tomcat6 (Ubuntu).

  • The template resource creates the configuration file only if the ['datasources'] node exists and includes a context_name attribute.

  • The template resource defines two variables, resource_name and webapp_name.

    resource_name is set to the resource name that is associated with context_name and webapp_name is set to the app's short name.

  • The template resource restarts the Tomcat service to load and activate the changes.

The webapp_context.xml.erb template consists of a Context element that contains a Resource element with its own set of attributes.

<Context> <Resource name="<%= @resource_name %>" auth="Container" type="javax.sql.DataSource" maxActive="20" maxIdle="5" maxWait="10000" username="<%= node['deploy'][@webapp_name]['database']['username'] %>" password="<%= node['deploy'][@webapp_name]['database']['password'] %>" driverClassName="com.mysql.jdbc.Driver" url="jdbc:mysql://<%= node['deploy'][@webapp_name]['database']['host'] %>:3306/<%= node['deploy'][@webapp_name]['database']['database'] %>" factory="org.apache.commons.dbcp.BasicDataSourceFactory" /> </Context>

These Resource attributes characterize the context configuration:

  • name–The JDBC resource name, which is set to the resource_name value defined in tomcat::context.

    For the example, the resource name is set to jdbc/mydb.

  • auth and type–These are standard settings for JDBC DataSource connections.

  • maxActive, maxIdle, and maxWait–The maximum number of active and idle connections, and the maximum wait time for a connection to be returned.

  • username, and password–The database's user name and root password, which are obtained from the deploy attributes.

  • driverClassName–The JDBC driver's class name, which is set to the MySQL driver.

  • url–The connection URL.

    The prefix depends on the database. It should be set to jdbc:mysql for MySQL, jdbc:postgresql for Postgres, and jdbc:sqlserver for SQL Server. The example sets the URL to jdbc:mysql://host_IP_Address:3306:simplejsp, where simplejsp is the app's short name.

  • factory–The DataSource factory, which is required for MySQL databases.

For more information on this configuration file, see the Tomcat wiki's Using DataSources topic.