Merge pull request #9 from CowboysFan/cart_spec_guide

Migrating cart spec guide topics

Author: nhr

_build_cfg.yml

@@ -33,3 +33,30 @@ Topics:
     File: configuring_client_tools
   - Name: Updating Client Tools
     File: updating_client_tools
+
+---
+Name: Reference for Developing Cartridges
+Dir: cartridge_specification_guide
+Topics:
+  - Name: Managed Files
+    File: managed_files
+  - Name: Locking Cartridges
+    File: locking_cartridges
+  - Name: Exposing Services
+    File: exposing_services
+  - Name: Creating Template Directories for Language Cartridges
+    File: creating_template_directories_for_language_cartridges
+  - Name: Cartridge Scripts
+    File: cartridge_scripts
+  - Name: Environment Variables
+    File: environment_variables
+  - Name: Cartridge Events
+    File: cartridge_events
+  - Name: OpenShift Build Process
+    File: openshift_build_process
+  - Name: Backing Up and Restoring Cartridges
+    File: backing_up_and_restoring_cartridges
+  - Name: Upgrading Custom and Community Cartridges
+    File: upgrading_custom_and_community_cartridges
+  - Name: OpenShift Cartridge Reference
+    File: openshift_cartridge_reference

cartridge_specification_guide/backing_up_and_restoring_cartridges.adoc

@@ -0,0 +1,91 @@
+OpenShift Documentation Project <dev@lists.openshift.redhat.com>
+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: 
+
+
+*  Snapshot the current state of an application to create a backup. 
+*  Restore an application from an archived state. 
+*  Copy or rename an application by taking a snapshot, creating a new application, then restoring the snapshot data to the new application. 
+
+[[snapshot]]
+=== Snapshot
+
+When an application developer runs the +rhc snapshot save+ command, OpenShift creates an archive of the application and performs the following steps: 
+
+.  Stops the application by running the +gear stop+ command. 
+.  Runs the +control pre-snapshot+ command for each cartridge on the gear. You can control cartridge serialization in the snapshot by implementing the +control pre-snapshot+ command in conjunction with exclusions. For example, you can snapshot to a database dump instead of a database file. 
+.  Builds a list of exclusions from the [variable]#snapshot_exclusions## entry in the [filename]#$cartridge_name/metadata/managed_files.yml# file for each cartridge on the gear. 
+.  Creates an archive of the application in [filename]#tar.gz# format and writes it to [literal]#stdout# for use by the client tools. In addition to the files listed in the [variable]#snapshot_exclusions# entry in the [filename]#managed_files.yml# file, OpenShift excludes the following files: 
+
+*  Selected gear user files: [filename]#.tmp#, [filename]#.ssh#, [filename]#.sandbox#. 
+
+
+*  Application state file: [filename]#app-root/runtime/.state#. 
+
+
+*  Bash history file: [filename]#$OPENSHIFT_DATA_DIR/.bash_history#. 
+
+
+.  Runs the +control post-snapshot+ command for each cartridge on the gear. Use this script to cleanup after the snapshot runs. 
+
+
+.  Will either stop or start the gear based on the state of the application before the snapshot. 
+
+*Snapshot Exclusions*
+
+Use the optional [variable]#snapshot_exclusions# entry in the [filename]#$cartridge_name/metadata/managed_files.yml# file to list files to exclude from the snapshot and restore process. File patterns originate from the [variable]#OPENSHIFT_HOMEDIR# directory, not the cartridge directory. Do not exclude files that your cartridge requires to operate. 
+
+
+
+.snapshot_exclusions Entry
+----
+snapshot_exclusions Entry
+snapshot_exclusions:
+- mydir/*
+----
+
+OpenShift uses the +tar+ command when performing snapshots. See the +tar+ man page +--exclude-from+ option for more information. 
+
+[[restore]]
+=== Restore
+
+When an application developer runs the +rhc snapshot restore+ command, OpenShift restores the application from an archive in the following steps: 
+
+
+.  Prepares the application for restoration. 
+
+*  If the archive contains a Git repository, OpenShift runs the +gear pre-receive+ command. 
+
+
+*  If the archive does not contain a Git repository, OpenShift runs the +gear stop+ command. 
+
+.  Runs the +control pre-restore+ command for each cartridge on the gear. This enables you to control the restoration of your cartridge, for example by deleting an old database dump. 
+.  Builds a list of file name changes to apply during the restoration from the [variable]#restore_transforms## entry in the [filename]#$cartridge_name/metadata/managed_files.yml# file for each cartridge on the gear. 
+.  Extracts the archive into the gear user's home directory, overwriting existing files and applying the file name changes listed in the [variable]#restore_transforms# entry in the [filename]#managed_files.yml# file. 
+.  Runs the +control post-restore+ command for each cartridge on the gear. Use this script to load a database flat file into the running database. 
+.  Resumes the application. 
+
+*  If the archive contains a Git repository, OpenShift runs the +gear postreceive+ command. 
+*  If the archive does not contain a Git repository, OpenShift runs the +gear start+ command. 
+
+.  Will either stop or start the gear based on the state of the application before restoring. 
+
+*Restoring with Transformed File Names*
+
+Use the optional [variable]#restore_transforms# entry in the [filename]#$cartridge_name/metadata/managed_files.yml# file to provide scripts that transform file names when OpenShift restores an application. This entry enables you to restore older snapshots to a newer cartridge with file name changes. 
+
+
+.restore_transforms Entry
+----
+restore_transforms:
+- s|${OPENSHIFT_GEAR_NAME}/data|app-root/data|
+----
+
+OpenShift uses the +tar+ command when restoring a gear. See the +tar+ man page +--transform+ option for more information. 
+

cartridge_specification_guide/cartridge_events.adoc

@@ -0,0 +1,123 @@
+OpenShift Documentation Project <dev@lists.openshift.redhat.com>
+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. 
+
+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
+
+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:
+
+----
+Publishes:
+  <event_name>:
+    Type: "<event type>"
+----
+
+.PHP Cartridge Publishes Entry
+----
+Publishes:
+  get-php-ini:
+    Type: "FILESYSTEM:php-ini"
+  publish-http-url:
+    Type: "NET_TCP:httpd-proxy-info"
+  publish-gear-endpoint:
+    Type: "NET_TCP:gear-endpoint-info"
+----
+
+For each _Publishes_ entry, OpenShift runs a script named [filename]#$cartridge_name/hooks/$event_name#. 
+
+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
+
+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:
+
+----
+Subscribes:
+  <event_name>:
+    Type: "<event type>"
+----
+
+.PHP Cartridge Subscribes Entry
+----
+Subscribes:
+  set-env:
+    Type: "ENV:*"
+    Required: false
+  set-mysql-connection-info:
+    Type: "NET_TCP:db:mysql"
+    Required: false
+  set-postgres-connection-info:
+    Type: "NET_TCP:db:postgres"
+    Required: false
+  set-doc-url:
+    Type: "STRING:urlpath"
+    Required: false
+----
+
+When OpenShift processes a cartridge publish script, it 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]#$cartridge_name/hooks/<event_name> <gear_name> <namespace> <gear_uuid>#. 
+
+For each matching _Subscribes_ entry, OpenShift runs a script named [filename]#$cartridge_name/hooks/$event_name#. OpenShift must send and process entries marked with +Required: true+. 
+
+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
+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*
+
+The MySQL cartridge lists a [variable]#publish-mysql-connection-info# event in the _Publishes_ section of its [filename]#mysql/metadata/manifest.yml# file:
+
+----
+Publishes:
+  publish-mysql-connection-info:
+    Type: "NET_TCP:db:mysql"
+----
+
+The MySQL cartridge implements a script in [filename]#mysql/hooks/publish-mysql-connection-info#. 
+
+*PHP Cartridge as Subscriber*
+
+The PHP cartridge lists a [variable]#set-mysql-connection-info# event in the _Subscribes_ section of its [filename]#php/metadata/manifest.yml# file:
+
+----
+Subscribes:
+  set-mysql-connection-info:
+    Type: "NET_TCP:db:mysql"
+----
+
+
+The PHP cartridge implements a script in [filename]#php/hooks/set-mysql-connection-info#. 
+
+*Cartridge Event Communication Process*
+
+OpenShift matches the event [variable]#Type# in the PHP cartridge's _Subscribes_ list to the event [variable]#Type# in the MySQL cartridge's _Publishes_ list. In this example, the event [variable]#Type# is "NET_TCP:db:mysql". 
+
+The MySQL cartridge's [filename]#publish-mysql-connection-info# script outputs the username, host, port, URL, and password required to connect to the MySQL instance:
+
+----
+OPENSHIFT_MYSQL_DB_USERNAME=username;
+OPENSHIFT_MYSQL_DB_PASSWORD=password;
+OPENSHIFT_MYSQL_DB_HOST=hostname;
+OPENSHIFT_MYSQL_DB_PORT=port;
+OPENSHIFT_MYSQL_DB_URL=url;
+----
+
+OpenShift sends the output of the MySQL cartridge's [filename]#publish-mysql-connection-info# to the PHP cartridge's [filename]#set-mysql-connection-info# script using the following format:
+
+----
+hooks/publish-mysql-connection-info gear_name namespace gear_uuid 'OPENSHIFT_MYSQL_DB_USERNAME=username;OPENSHIFT_MYSQL_DB_PASSWORD=password;OPENSHIFT_MYSQL_DB_HOST=hostname;OPENSHIFT_MYSQL_DB_PORT=port;OPENSHIFT_MYSQL_DB_URL=url;'
+----
+
+Note that the publisher script determines the format of the information input to the subscriber script. When writing subscriber scripts, ensure that they parse the input correctly. 
+