Download and Run Your Own Cartridges

Downloading cartridges require version 1.9.1 of RHC

In OpenShift, cartridges aren't limited to just to our supported and security maintained stacks. You can also deploy cartridges hosted elsewhere into your app, providing a wide range of technologies. To deploy these custom cartridges, you simply provide the URL of the cartridge manifest in the console or from the CLI. OpenShift will then download and install the cartridge.

How Cartridges are Downloaded

Any OpenShift cartridge can be turned in to a downloadable cartridge. OpenShift accepts a URL to the manifest for your cartridge (a YML document containing information about how your cart runs) and expects the manifest to contain a URL pointing to the actual contents of the cart. Each time that cart is installed, the contents are downloaded into your new application.

Here's an example manifest (taken from the Go cartridge):

Name: go
Display-Name: Go 1.1
Version: "1.1"
...

The source version of this manifest doesn't contain a Source-Url attribute, which means that OpenShift won't be able to download and install the cartridge. To correct that, we could check in a new version of the manifest that points to this Git repository:

Name: go
Display-Name: Go 1.1
Version: "1.1"
Source-Url: git@github.com:smarterclayton/openshift-go-cart.git
...    

OpenShift will recognize the URL as being a Git repository, and when you install the cartridge via RHC:

rhc create-app goapp https://raw.github.com/smarterclayton/openshift-go-cart/master/metadata/manifest.yml

we'll download the latest contents of the Git repository into your gear.

Observant readers will note a limitation of this method - I can't fork this git repository and work on my own copy without changing the manifest.yml. In general, putting Source-Url inside of a checked in repository is a bad practice because it prevents you from hosting that repository in other places. Also, you can only use the most recent version of the code - which makes branches and tags hard to use. To get around this, we've introduced a pair of tools that leverage OpenShift's open hosting platform to let you install and run source versions of cartridges easily.

The Cartridge Development Kit (CDK)

Developing a cartridge involves having a way to build that cartridge and host those builds where OpenShift can access it. The CDK is an application that runs on OpenShift and stores your cartridge source in its Git repository, serving up builds and source versions of your cartridge.

To get started, you can create your own CDK on OpenShift Online and give it the Go cartridge source code:

rhc create-app mycart http://cdk-claytondev.rhcloud.com --from-code="git://github.com/smarterclayton/openshift-go-cart.git"

This will download and install the latest source code for the CDK as a downloadable cartridge (the CDK is self hosted). The source code in the CDK will be a fork of the Go cartridge. Once your app is created, visit it in a web browser:

http://mycart-mydomain.rhcloud.com

You'll see a list of the commits for the cartridge and can switch between branches to get the cartridge URL. Copy any of the manifest URLs to create the cartridge. You can also use the URL of your app as a downloadable cartridge, which will fetch the latest version from the master branch.

For more information on using the CDK, please view the README.md.

The Cartridge Reflector

If you just want to download and run a cartridge whose source is on GitHub, there's a simple app running on OpenShift which can fetch the manifest and automatically add a Source-Url. The reflector is located at cartreflect-claytondev.rhcloud.com and takes a GitHub repository and project name. For example, visit:

http://cartreflect-claytondev.rhcloud.com/github/smarterclayton/openshift-go-cart

in your browser. You'll see the contents of the manifest.yml, plus a Source-Url at the very end. The reflector is fetching your manifest and determining the right URL, which by default will be the master branch:

Source-Url: https://github.com/smarterclayton/openshift-go-cart/archive/master.zip

You can now install the cartridge directly with:

rhc create-app goapp "http://cartreflect-claytondev.rhcloud.com/github/smarterclayton/openshift-go-cart"

If you want to install a particular branch, tag, or commit, just add the commit parameter with that string:

rhc create-app goapp "http://cartreflect-claytondev.rhcloud.com/github/smarterclayton/openshift-go-cart?commit=d48e5b19333bcc8500cb11aef08eed457da7b9f8"

Follow the instructions in the README.md for installing your own Cartridge Reflector.

Limitations of Downloaded Cartridges

In order to prevent abuse by malicious users, the OpenShift server sets limitations on the manifests it will download. Your manifest must meet the following conditions:

  • Be accessible over HTTP or HTTPS from the server (on the public internet for OpenShift Online, or available from your intranet for OpenShift Enterprise)
  • Be no more than 20k in size
  • Must redirect no more than 2 times before the content is served
  • Must download in less than 10 seconds

In addition, each application may have a maximum of 5 downloadable cartridges.

Tips for Developing Cartridges Online

When developing a new cartridge on OpenShift, you won't have access to all of the logging and debug output that happens underneath the covers on the node. It's important to start slowly and add bits of your setup and control scripts in easy to edit pieces. Once you've got a gear created with your cartridge code on it, start adding function, testing as you go.

  • Test your control and setup scripts locally to check for bash script errors
  • Don't check in a manifest.yml with a Source-Url set - use the cart-reflector or the CDK to host the cart for you
  • Try copying your cart source to a new directory on your own system and then running bin/setup and bin/control. Remember, all communication between OpenShift and your cartridge is just simple script calls and environment variables, so it's easy to set up a test environment on your own system.
  • Remember that your cartridges are running in a RHEL 6.4 environment - that means that binaries you compile on other systems may not work properly. If you need to compile binaries, do it from the CDK.
  • Use environment variables for setting config! Since scripts can easily add new environment variables (echo "my value" > env/MY_VAR) it's a great way to store simple config values. In addition, it makes it easier for others to use your environment variables for code.
  • Don't lock your files until you're ready to publish your cart for others to use - unlocked files can be edited in the gear if you want to rapidly test something.
  • Process management can be tricky - try to concentrate all of your process management logic in reusable functions in your bin/control script so you can update it if you need it.

Cartridge Examples From Around the Web

If you'd like to see a cartridge here, send us a link to your GitHub repo in the forums!