A couple of weeks ago I had the opportunity to visit the Red Hat office in Mountain View to take part in a sort of corporate hackathon. Red Hat invited members from various companies to explore its OpenShift PaaS and build something called a cartridge at the event. These cartridges are not gray boxes that you plug into your old Nintendo console after furiously blowing out all the dust. Cartridges are ways users can extend the OpenShift platform. Third Party developers can create support for languages, databases or other environment requirements which might not exist on OpenShift in order to get their applications running.

How are they built?

Within the OpenShift platform, you can create applications. These applications consist of something known as gears. According to one of the Red Hat mentors at the event, gears are essentially a user with a home directory. Cartridges are what we install in our gear to allow our applications to work. This is essentially a directory structure that houses all the logic for components that our applications might need. This could be a language cartridge such as Rails or a DB Cartridge such as Mongo or even something else.

The engineers at Red Hat thought it would be cool to build out a simple Sendgrid cartridge, so OpenShift users can just do a quick install of the cartridge and not have to worry about installing our libraries and any dependencies they might need. This was simple to build and the rest of the post will walk through the file structure of the cartridge and details on the files I used.

Below you can see the OpenShift Cartridge file structure. A big portion of this is optional and largely dependent on the type of cartridge you want to build. If you want to see how other parts of this file structure are you used you can check out OpenShift’s httpd cartridge tutorial.

OpenShift Cartridge File structure


When a developer installs your cartridge, OpenShift will copy this directory structure that a developer created from the cartridge library to your gear. However, the usr directory which holds all the logic for that cartridge will be symlinked in, so it can be shared among all the installed cartridge applications.

Cartridge Metadata

While there are a lot of optional components to this structure, I will cover what I and Principal software engineer, Jhon Honce, worked on at the event. Let’s begin with the Metadata and specifically the manifest.yml file first.


The manifest.yml file lets OpenShift know what features your cartridge requires and also uses this file to present data about your cartridge to potential users. I will cover some key elements of this file below.

Cartridge-Short-Name: SENDGRID

This field basically acts as a prefix for the variables generated by your cartridge. You can have more than one cartridge installed on your gear and this prefix helps with organization.

Cartridge-Version: 1.0.0

This value lets OpenShift keep track of the version of your cartridge. When a new version is published OpenShift will compare there to determine what is necessary to upgrade for the developers application.


This is where we put environment variables our application might need. Since this manifest is for an upcoming Sendgrid cartridge, we have two environment variables that are important to us, which is user auth info.

Source-Url: https://www.example.com/killer-cartridge.zip

This is not shown in my example above, but this url contains the web accessible link of your cartridge. You will need this set when deploying your cartridge.

Managed Files

The managed_files.yml is not something we used but it is important to note. This file keeps track of directories and lets us lock certain files. This means that once our cartridge is installed, people will be able to read data from that specified cartridge path but not write to it.

Cartridge Scripts

These files are bash scripts that let the cartridge author install any environments necessary for their cartridges. The script at bin/setup is used to install the dependencies of our libraries.


Ultimately, creating an OpenShift cartridge is essentially adding your libraries or executable files in the /usr directory. Then modifying the cartridge metadata for potential users who will install the cartridge. Finally modifying the bash scripts in the bin directory to do whatever process is necessary to make sure the environment in the cartridge is right to run the application in the usr directory.

After that is done you are ready to deploy. Make sure you post your manifest.yml file on a public accessible URL. Then with the aid of the OpenShift command line gem which can be downloaded by typing sudo gem install rhc, run:
rhc create-app myapp http://url.to/the/cartridge/manifest.yml

With that, you have built and deployed a Red Hat Cartridge for the Open Shift PaaS.

SendGrid Team
Expert advice and insight about all things email including best practices tips, examples, and advice for marketers, developers, and everyone in between.