openshift · nhr · Aug 11, 2014 · Aug 11, 2014
diff --git a/cartridge_specification_guide/backing_up_and_restoring_cartridges.adoc b/cartridge_specification_guide/backing_up_and_restoring_cartridges.adoc
@@ -1,11 +1,9 @@
+= Backing Up and Restoring Cartridges
 OpenShift Documentation Project <[email protected]>
 DOC_BRANCH_VERSION
 :data-uri:
 :icons:
 
-[[backing_up_and_restoring_cartridges]]
-== Backing Up and Restoring Cartridges
-
 OpenShift provides +snapshot+ and +restore+ features for user applications. These features enable OpenShift application developers to: 
 
 
@@ -14,7 +12,7 @@ OpenShift provides +snapshot+ and +restore+ features for user applications. Thes
 *  Copy or rename an application by taking a snapshot, creating a new application, then restoring the snapshot data to the new application. 
 
 [[snapshot]]
-=== Snapshot
+== Snapshot
 
 When an application developer runs the +rhc snapshot save+ command, OpenShift creates an archive of the application and performs the following steps: 
 
@@ -53,7 +51,7 @@ snapshot_exclusions:
 OpenShift uses the +tar+ command when performing snapshots. See the +tar+ man page +--exclude-from+ option for more information. 
 
 [[restore]]
-=== Restore
+== Restore
 
 When an application developer runs the +rhc snapshot restore+ command, OpenShift restores the application from an archive in the following steps: 
 

diff --git a/cartridge_specification_guide/cartridge_events.adoc b/cartridge_specification_guide/cartridge_events.adoc
@@ -1,17 +1,15 @@
+= Cartridge Events
 OpenShift Documentation Project <[email protected]>
 DOC_BRANCH_VERSION
 :data-uri:
 :icons:
 
-[[cartridge_events]]
-== Cartridge Events
-
-OpenShift provides a publish and subscribe system that enables a cartridge to act when a developer adds or removes another cartridge in an application. 
+OpenShift provides a publish and subscribe system that enables a cartridge to act when a developer adds or removes another cartridge in an application.
 
 The _Publishes_ and _Subscribes_ elements in the [filename]#$cartridge_name/metadata/manifest.yml# file detail support for cartridge events. 
 
 [[cartridge_event_publishing]]
-=== Cartridge Event Publishing
+== Cartridge Event Publishing
 
 When OpenShift adds a cartridge to an application, it uses entries in the _Publishes_ section of the [filename]#$cartridge_name/metadata/manifest.yml# file to construct events sent to other cartridges in the application. Define publish events in the [filename]#manifest.yml# file using the following format:
 
@@ -37,7 +35,7 @@ For each _Publishes_ entry, OpenShift runs a script named [filename]#$cartridge_
 OpenShift joins lines of output that the [filename]#hooks/$event_name# script writes to [literal]#stdout# with single spaces, then inputs the result to subscriber scripts in other cartridges that match the [variable]#Type# of the publish event. The input to matching subscriber scripts is prefaced with [filename]#hooks/<event_name> <gear_name> <namespace> <gear_uuid>#. 
 
 [[cartridge_event_subscriptions]]
-=== Cartridge Event Subscriptions
+== Cartridge Event Subscriptions
 
 When OpenShift adds a cartridge to an application, it uses entries in the _Subscribes_ section of the [filename]#$cartridge_name/metadata/manifest.yml# file in other cartridges to determine what actions to take for those other cartridges. Define subscribe events in the [filename]#manifest.yml# file using the following format:
 
@@ -71,7 +69,7 @@ For each matching _Subscribes_ entry, OpenShift runs a script named [filename]#$
 The publisher script determines the format of the information input to the subscriber script. Ensure that subscriber script can parse the input correctly. 
 
 [[cartridge_event_example]]
-=== Cartridge Event Example
+== Cartridge Event Example
 In this example, an application developer adds a MySQL database cartridge to a PHP application. The publish and subscribe relationship between the cartridges enables the PHP cartridge to set environment variables on its gear so it can connect to the new MySQL cartridge, which is on a different gear. 
 
 *MySQL Cartridge as Publisher*

diff --git a/cartridge_specification_guide/cartridge_scripts.adoc b/cartridge_specification_guide/cartridge_scripts.adoc
@@ -1,10 +1,9 @@
+= Cartridge Scripts
 OpenShift Documentation Project <[email protected]>
 DOC_BRANCH_VERSION
 :data-uri:
 :icons:
 
-[[cartridge_scripts]]
-== 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 [filename]#$cartridge_name/bin/# directory, and run from the cartridge's home directory. 
@@ -39,7 +38,7 @@ Cartridge scripts are located in the [filename]#$cartridge_name/bin/# directory,
 |===
 
 [[embedded_ruby_processing]]
-=== Embedded Ruby (ERB) Processing
+== 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 enables you to provide certain values as ERB templates. For more information on ERB templates, see the link:http://ruby-doc.org/stdlib-1.9.3/libdoc/erb/rdoc/ERB.html[ERB documentation at ruby-doc.org]. 
 
 OpenShift renders ERB templates at +$$safe_level 2$$+ and processes them in two passes. For more information on Ruby safe levels, see the link:http://www.ruby-doc.org/docs/ProgrammingRuby/html/taint.html[Programming Ruby documentation at ruby-doc.com]. 
@@ -53,7 +52,6 @@ OpenShift renders ERB templates at +$$safe_level 2$$+ and processes them in two
 
 .Environment Variable Template
 ====
-
 ifdef::openshift-online[]
 An [filename]#env/OPENSHIFT_MONGODB_DB_LOG_DIR.erb# file contains: 
 
@@ -65,7 +63,6 @@ An [filename]#env/OPENSHIFT_MONGODB_DB_LOG_DIR.erb# file contains:
 /var/lib/openshift/aa9e0f66e6451791f86904eef0939e/mongodb/log/
 ----
 endif::[]
-
 ifdef::openshift-enterprise[]
 For OpenShift Enterprise release 2.0, an [filename]#env/OPENSHIFT_MONGODB_DB_LOG_DIR.erb# file contains:
 
@@ -80,22 +77,20 @@ For OpenShift Enterprise release 2.1 and later, an [filename]#env/OPENSHIFT_MONG
 ----
 
 The value of [envar]#LOG_DIR# for each cartridge is set to the same value as [envar]#OPENSHIFT_LOG_DIR#.
-
 endif::[]
-
-From that ERB file, OpenShift creates an [envar]#env/OPENSHIFT_MONGODB_DB_LOG_DIR# environment variable containing: 
 ====
 
+From that ERB file, OpenShift creates an [envar]#env/OPENSHIFT_MONGODB_DB_LOG_DIR# environment variable containing:
+
 .[filename]#php.ini# Configuration Template
 ====
-
 A [filename]#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 creates a [filename]#conf/php.ini# file containing:
 
 ----
@@ -107,7 +102,7 @@ session.save_path = "/var/lib/openshift/aa9e0f66e6451791f86904eef0939e/php/sessi
 Other possible uses for ERB templates are +includes+ values in *httpd* configuration files, database configuration values for storing persistent data in the [filename]#OPENSHIFT_DATA_DIR# directory, and the application name value in the [filename]#pom.xml# file. 
 
 [[setup_script]]
-=== setup Script
+== setup Script
 
 The [filename]#setup# script creates and configures files that OpenShift copies from the cartridge repository to the gear's directory. The [filename]#setup# script must be re-entrant. OpenShift runs the script for every upgrade that is not backward compatible. Add logic you want to run only once to the [filename]#install# script, not the [filename]#setup# script. 
 
@@ -125,7 +120,7 @@ If you use ERB templates to configure software, OpenShift processes these files
 
 
 [[install_script]]
-=== install Script
+== install Script
 The [filename]#install# script creates and configures files that OpenShift copies from the cartridge repository to the gear's directory. OpenShift runs the [filename]#install# script only on the first installation of a cartridge. 
 
 Put logic for one-time operations, for example generating passwords, creating ssh keys, and adding environment variables, in the [filename]#install# script. 
@@ -143,7 +138,7 @@ The [filename]#install# script may substitute a version dependent of the _templa
 |===
 
 [[post-install_script]]
-=== post-install Script
+== post-install Script
 The [filename]#post-install# script configures your cartridge after the cartridge starts. OpenShift only runs the [filename]#post-install# script for the first installation of the cartridge. 
 
 [cols="2,7,"]
@@ -155,7 +150,7 @@ The [filename]#post-install# script configures your cartridge after the cartridg
 |===
 
 [[teardown_script]]
-=== teardown Script
+== teardown Script
 The [filename]#teardown# script prepares the gear for cartridge removal. The script only runs when OpenShift removes the cartridge from a gear; it does not run when OpenShift deletes the gear. The gear continues to operate without the functionality of the removed cartridge. 
 
 [cols="2,7,"]
@@ -166,7 +161,7 @@ The [filename]#teardown# script prepares the gear for cartridge removal. The scr
 |===
 
 [[control_script]]
-=== control Script
+== control Script
 The [filename]#control# script enables OpenShift or the application developer to control the state of a cartridge and its packaged software. 
 
 [cols="2,7,"]
@@ -235,7 +230,7 @@ OpenShift maintains the expected state of an application in the [filename]#~/app
 
 ifdef::openshift-enterprise[]
 [[metrics script]]
-=== metrics Script
+== metrics Script
 
 With the release of OpenShift Enterprise 2.1, a metrics entry can be added to the cartridge's [filename]#$cartridge_name/metadata/manifest.yml# file to inform OpenShift Enterprise that it supports metrics. 
 
@@ -395,7 +390,7 @@ If a cartridge script returns a value not included in the following tables, Open
 |===
 
 [[communication_between_openShift_and_cartridges]]
-=== Communication Between OpenShift and Cartridges
+== Communication Between OpenShift and Cartridges
 
 A cartridge can provide services for use by multiple gears in one application. OpenShift enables you to publish these services. Each message writes to [literal]#stdout# or [literal]#stderr# with an exit status, one message per line. 
 

diff --git a/..._specification_guide/creating_template_directories_for_language_cartridges.adoc b/..._specification_guide/creating_template_directories_for_language_cartridges.adoc
@@ -1,10 +1,9 @@
+= Creating Template Directories for Language Cartridges
 OpenShift Documentation Project <[email protected]>
 DOC_BRANCH_VERSION
 :data-uri:
 :icons:
 
-[[creating_template_directories_for_language_cartridges]]
-== Creating Template Directories for Language Cartridges
 Use the [filename]#$cartridge_name/template/# or [filename]#$cartridge_name/template.git/# directory to provide a basic example of an application written in the language or framework your cartridge packages. Welcome the application developer to your cartridge and inform them that the cartridge is operating correctly. 
 
 If you provide a [filename]#$cartridge_name/template.git/# directory, OpenShift copies the directory for the application developer. 
@@ -27,7 +26,7 @@ A Ruby 1.8 cartridge with Passenger support has a [filename]#template/public/# d
 ....
 
 [[marker_files]]
-=== Marker Files
+== Marker Files
 The [filename]#$cartridge_name/template/.openshift/markers/# directory contains example marker files for application developers. These files set conditions for various stages of a cartridge's life cycle. You can add marker files as required to enable application developers to control aspects of your cartridge. 
 
 .Ruby 1.8 Marker Files
@@ -42,7 +41,7 @@ The [filename]#$cartridge_name/template/.openshift/markers/# directory contains
 |====
 
 [[application_developer_action_hooks]]
-=== Action Hooks
+== Action Hooks
 The [filename]#$cartridge_name/template/.openshift/action_hooks/# directory contains examples of application developer action hooks that run during the cartridge life cycle. 
 
 .Action Hooks

diff --git a/cartridge_specification_guide/enabling_logshifter.adoc b/cartridge_specification_guide/enabling_logshifter.adoc
@@ -1,10 +1,9 @@
+= Enabling Logshifter
 OpenShift Documentation Project <[email protected]>
 DOC_BRANCH_VERSION
 :data-uri:
 :icons:
 
-[[enabling_logshifter]]
-== Enabling Logshifter
 Using _logshifter_ enables automatic log rotation and consolidation across cartridges in a gear. In OpenShift, cartridges can log to _Syslog_ using _logshifter_. For more information about _logshifter_, see the _logshifter_ [filename]#README# file. 
 
 When writing a cartridge control script, it is typical to spawn a runtime process such as java or mongod. To take advantage of _logshifter_, redirect the standard out (STDOUT) and standard error (STEDRR) streams of the process to the [filename]#/usr/bin/logshifter# file. For example, for a Java-based cartridge.
@@ -30,6 +29,5 @@ java ... &> $LOGPIPE &
 echo $! > $OPENSHIFT_MY_CARTRIDGE_DIR/my-cartridge.pid
 ----
 
-Setting up the named pipe manually provides the most flexibility for managing both the _logshifter_ and cartridge processes. 
+Setting up the named pipe manually provides the most flexibility for managing both the _logshifter_ and cartridge processes.
 
-
diff --git a/cartridge_specification_guide/environment_variables.adoc b/cartridge_specification_guide/environment_variables.adoc
@@ -1,18 +1,17 @@
+= Environment Variables
 OpenShift Documentation Project <[email protected]>
 DOC_BRANCH_VERSION
 :data-uri:
 :icons:
 
-[[environment_variables]]
-== Environment Variables
 OpenShift uses environment variables to communicate information between cartridges, applications, and the system. 
 
 OpenShift provides several system environment variables that are available for use at all cartridge entry points. 
 
 Place cartridge environment variables in the [filename]#$cartridge_name/env/# directory. OpenShift loads cartridge variables after system environment variables, but before calling your code. 
 
 [[system_environment_variables]]
-=== System Environment Variables
+== System Environment Variables
 
 OpenShift provides several system environment variables. These variables are read-only. 
 
@@ -93,7 +92,7 @@ OpenShift provides several system environment variables. These variables are rea
 |===
 
 [[cartridge_environment_variables]]
-=== Cartridge Environment Variables
+== Cartridge Environment Variables
 OpenShift provides three environment variables for all cartridges by default. These variables are read-only. 
 
 .Cartridge Environment Variables
@@ -119,7 +118,7 @@ OpenShift provides three environment variables for all cartridges by default. Th
 
 
 [[custom_cartridge_environment_variables]]
-=== Custom Cartridge Environment Variables
+== Custom Cartridge Environment Variables
 You can add custom environment variables to a cartridge by adding them to the cartridge's [filename]#$cartridge_name/env/# directory or creating them with the cartridge's [filename]#setup# and [filename]#install# scripts. 
 
 Entries in a cartridge's [filename]#$cartridge_name/env/# directory do not override system-provided environment variables. Using system-provided environment variable names in the [filename]#$cartridge_name/env/# directory prevents the cartridge from installing correctly. 

diff --git a/cartridge_specification_guide/exposing_services.adoc b/cartridge_specification_guide/exposing_services.adoc
@@ -1,10 +1,9 @@
+= Exposing Services
 OpenShift Documentation Project <[email protected]>
 DOC_BRANCH_VERSION
 :data-uri:
 :icons:
 
-[[exposing_services]]
-== Exposing Services
 Most cartridges provide services by binding to ports. Cartridges must declare to which ports they bind, and provide variable names to describe: 
 
 *  The IP addresses provided to the cartridge for binding. 
@@ -13,7 +12,7 @@ Most cartridges provide services by binding to ports. Cartridges must declare to
 *  TCP endpoint mappings that establish a front end for application users. (Optional)
 
 [[tCP_endpoints]]
-=== TCP Endpoints
+== TCP Endpoints
 TCP endpoints are services that are exposed by a cartridge, and are accessible by other cartridges or gears in an application. They may be any protocol which uses TCP, such as *http* or *mysql*. These services may also be exposed to application users through mappings. OpenShift only creates endpoint ports for scalable applications. 
 
 The endpoints can be defined in the [variable]#Endpoints# section of the [filename]#$cartridge_name/metadata/manifest.yml# file. 
@@ -137,7 +136,7 @@ If an endpoint specifies [variable]#Mappings#, a front-end httpd route to the ca
 |===
 
 [[endpoint_example]]
-=== TCP Endpoint Example
+== TCP Endpoint Example
 This section provides an example [variable]#Endpoints# entry in a [filename]#$cartridge_name/metadata/manifest.yml# file, and demonstrates how OpenShift uses this entry to create environment variables, public proxy port mappings, and *httpd* routes. 
 
 .Endpoints Entry
@@ -226,7 +225,7 @@ Alias / <%= ENV['OPENSHIFT_HOMEDIR'] + "/mongodb/httpd.d/index.html" %>
 ----
 
 [[enabling_custom_paths_for_Websockets]]
-=== Enabling Custom Paths for Websockets
+== Enabling Custom Paths for Websockets
 Websockets are used to create real-time events initiated by an OpenShift application. 
 
 The ability to add a custom path for websocket URLs to a cartridge must be enabled in that cartridge's _manifest.yml_ file before it can be used in a new application. Add the following information to the [filename]#/usr/libexec/openshift/cartridges/Cart_Name/metadata/manifest.yml# file of the desired cartridge: 
@@ -253,6 +252,3 @@ After a cartridge has been modified to use custom paths for websocket URLs, a ne
 ----
 ws://app-domain.example.com:8000/file_path
 ----
-
-
-
diff --git a/cartridge_specification_guide/locking_cartridges.adoc b/cartridge_specification_guide/locking_cartridges.adoc
@@ -1,10 +1,9 @@
+= Locking Cartridges
 OpenShift Documentation Project <[email protected]>
 DOC_BRANCH_VERSION
 :data-uri:
 :icons:
 
-[[locking_cartridges]]
-== Locking Cartridges
 Cartridge instances on a gear are either locked or unlocked at any given time. Locking a cartridge enables cartridge scripts to have greater access to the gear's files and directories. Application developers have read and write access to unlocked files, and read-only access to locked files. This means that application scripts and hooks cannot override cartridge code when the cartridge is locked. 
 
 OpenShift controls the lock state of cartridges, moving them between locked and unlocked at various points in the cartridge life cycle. 
@@ -18,7 +17,7 @@ Cartridge file locking is not a security measure. It is designed to prevent appl
 ====
 
 [[lock_Cconfiguration]]
-=== Cartridge Lock Configuration
+== Cartridge Lock Configuration
 The locked_files entry in the [filename]#$cartridge_name/metadata/managed_files.yml# file lists files and directories that OpenShift locks at certain points during the cartridge life cycle. 
 
 If a file in the [parameter]#locked_files# list does not exist, OpenShift creates the file before your +setup+ script is called. OpenShift also creates missing directories if required. 

diff --git a/cartridge_specification_guide/managed_files.adoc b/cartridge_specification_guide/managed_files.adoc
@@ -1,10 +1,9 @@
+= Managed Files
 OpenShift Documentation Project <[email protected]>
 DOC_BRANCH_VERSION
 :data-uri:
 :icons:
 
-[[managed_files]]
-== Managed Files
 Managed files are files that have non-default settings, or that require special handling by OpenShift. 
 
 The [filename]#$cartridge_name/metadata/managed_files.yml# file lists managed files and strings that OpenShift uses during different stages of the cartridge life cycle.