Chapter 6. Using Cartridge Scripts

Cartridge scripts act as the application programming interface (API) for a cartridge. Use these scripts to contain the required code for single version software that configures easily. For complex configurations and software with multiple versions, use these scripts as shim code to set up the required environment and run additional scripts. You can also create symbolic links from these scripts.
Cartridge scripts are located in the $cartridge_name/bin/ directory, and run from the cartridge's home directory.

Table 6.1. Required Scripts

Script Name Usage
setup Creates and configures files that OpenShift Enterprise copies from the cartridge repository to the gear's directory. Runs for the initial installation and every upgrade.
control Enables OpenShift Enterprise or the application developer to control the state of a cartridge and its packaged software.

Table 6.2. Optional Scripts

Script Name Usage
teardown Prepares the gear for cartridge removal.
install Creates and configures files that OpenShift Enterprise copies from the cartridge repository to the gear's directory. Runs only on the first installation of the cartridge.
post-install Configures the cartridge after the cartridge starts. Runs only on the first installation of the cartridge.
metrics Gathers cartridge level metrics.

6.1. Embedded Ruby (ERB) Processing

Embedded Ruby (ERB) is a templating system that embeds Ruby into a text document. To provide more flexible configuration and environment variable options, OpenShift Enterprise enables you to provide certain values as ERB templates. For more information on ERB templates, see http://ruby-doc.org/stdlib-1.9.3/libdoc/erb/rdoc/ERB.html.
OpenShift Enterprise renders ERB templates at safe_level 2 and processes them in two passes. For more information on Ruby safe levels, see http://www.ruby-doc.org/docs/ProgrammingRuby/html/taint.html.

ERB Processing Passes

  1. The first pass processes entries in the $cartridge_name/env/ directory. This pass is mandatory, and occurs before OpenShift Enterprise runs the $cartridge_name/bin/setup script.
  2. The second pass processes entries specified in the process_templates entry of the $cartridge_name/metadata/managed_files.yml file. This pass occurs after OpenShift Enterprise runs the $cartridge_name/bin/setup script, but before it runs the $cartridge_name/bin/install script. This enables the setup script to create or modify ERB templates as required, and for the install script to use the processed values.

Example 6.1. Environment Variable Template

For OpenShift Enterprise release 2.0, an env/OPENSHIFT_MONGODB_DB_LOG_DIR.erb file contains: 
<%= ENV['OPENSHIFT_MONGODB_DIR'] %>/log/
For OpenShift Enterprise release 2.1 and later, an env/OPENSHIFT_MONGODB_DB_LOG_DIR.erb file contains: 
<%= ENV['OPENSHIFT_LOG_DIR'] %>
The value of LOG_DIR for each cartridge is set to the same value as OPENSHIFT_LOG_DIR.
From that ERB file, OpenShift Enterprise creates an env/OPENSHIFT_MONGODB_DB_LOG_DIR environment variable containing: 
/var/lib/openshift/aa9e0f66e6451791f86904eef0939e/mongodb/log/

Example 6.2. php.ini Configuration Template

A conf/php.ini.erb file contains: 
upload_tmp_dir = "<%= "#{ENV['OPENSHIFT_PHP_DIR']}tmp/" %>"
session.save_path = "<%= "#{ENV['OPENSHIFT_PHP_DIR']}sessions/" %>"
From that ERB file, OpenShift Enterprise creates a conf/php.ini file containing: 
upload_tmp_dir = "/var/lib/openshift/aa9e0f66e6451791f86904eef0939e/php/tmp/"
session.save_path = "/var/lib/openshift/aa9e0f66e6451791f86904eef0939e/php/sessions/"
Other possible uses for ERB templates are includes values in httpd configuration files, database configuration values for storing persistent data in the OPENSHIFT_DATA_DIR directory, and the application name value in the pom.xml file.