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.
| 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. |
| 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
- 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/setupscript. - The second pass processes entries specified in the
process_templatesentry of the$cartridge_name/metadata/managed_files.ymlfile. This pass occurs after OpenShift Enterprise runs the$cartridge_name/bin/setupscript, but before it runs the$cartridge_name/bin/installscript. This enables thesetupscript to create or modify ERB templates as required, and for theinstallscript 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.
