In a few weeks OpenShift will officially move to the new cartridge format. We've been doing everything we can to ensure a smooth transition from the first version of cartridges to this new version. For those that don't know what a cartridge is, let's go over the basics. When someone creates, say, a Jboss application, OpenShift finds a host and creates a gear on it. Then we install the Jboss cartridge in that gear. It's that in-gear cartridge that we're changing.

The reason for this move is to make it easier for 3rd parties to create cartridges for OpenShift. We're doing everything in our power to make sure this is a smooth transition, however as we get closer we've seen a few things that may not work when we move. Everyone should pay special attention to their applications starting the week of June 3, 2013. Applications will automatically start moving over at that time.

So what are these changes that break things? Mostly they're path issues. For example, right now the Jboss-as-7 cartridge gets installed into:


In the future it will simply be


The reason for this is we're moving to a model where you don't have to specify version up front. Some users would like to move back and forth between different versions of the same cartridge as part of the development process and we're trying to make that easy for people.

The issue is some people may have hard-coded the full path to the cartridge directory or specified the home path. For example, one of our quickstarts changes JAVA_HOME during a modules call. To do this they set the JBOSS_HOME variable like this:

export JBOSS_HOME=${OPENSHIFT_HOMEDIR}jbossas-7/jbossas-7/

The problem is ${OPENSHIFT_HOMEDIR}jbossas-7/ won't exist when we do the migration to the new format. It will simply be ${OPENSHIFT_HOMEDIR}jbossas/. Most of our users won't run into this problem. We are also confident that some will, however, and we want to do our best to ensure people are aware of this change and can make proper arrangements.

For those needing to reference the cartridge dirs directly, a new environment variable is being created and can be used when the new format lands. It's the $OPENSHIFT_(CARTRIDGE)_DIR variable. So in our above example we would want to change:

export JBOSS_HOME=${OPENSHIFT_HOMEDIR}jbossas-7/jbossas-7/



That's really the best way to future-proof your code. Most of our users are referencing the data dir (where your application data / cache lives) or the repo dir (where your actual code lives). To be clear, data dir and repo dir are not changing in any way. Only the cartridge dir is changing and it is very possible your application makes no references to it at all. We will be putting symlinks in place to help ease this transition but it won't catch all of the cases and the symlinks are temporary so you'll still need to update your code.

To learn more about the new cartridge format start with Part 1 of the New Cartridge Format Series. As always, if you have any questions please let us know: or #openshift on We'll send more updates over the next week as additional changes become clearer.



< Back to the blog