How to create an OpenShift github quick start project

At OpenShift, we believe in an open PaaS solution.  A PaaS where developers are not locked-in to vendors that require proprietary API calls or data stores.  We want your code to run as is, without modifications.  To illustrate how easy this is, we have created a github space where we provide numerous quick start projects that make deploying common application to the cloud a painless process.  Some of the popular open source projects we provide a quick start for are:

Not finding what you are looking for?  Help us out by creating your own github OpenShift project.  Once you have created a github project, let us know and we will add it to the main OpenShift space and send you a limited edition OpenShift t-shirt for your efforts! Drop us a line at when you are ready. Ok, but how do I get my project into the github repo?  Follow the step-by-step directions below.

Note: These steps assume you that you are using Fedora 15.  However, the commands should be portable across any operating system with git and the OpenShift client tools installed.

Step 1: Decide on a project you want to create a quick start for
This is common sense, right?  The only thing to note is that you should focus on applications that are freely available under an open source license.  You must have the rights to redistribute the code in your own github repository.  For this guide, I have selected to deploy the popular web site analytic software Piwik.

Step 2: Download the code for Piwik
At the time of this writing, you can obtain the code directly from the Piwik website at:  Once downloaded, save the file to ~/code/piwikstage

Step 3: After you download the code, extract the contents

  • $ cd ~
  • $ mkdir code
  • $ mkdir piwikstage
  • $ unzip
  • This will create a piwik directory under the ~/code/piwikstage directory

Step 4: Create an OpenShift application to test the deployment

  • $ cd ~/code
  • $ rhc-create-app -a piwik -t php-5.3 -l yourlogin

Step 5: Create a mysql database if required by your application

  • $ rhc-ctl-app –a piwik –e add-mysql-5.1 –l yourlogin
  • Make a note of the username, password, host, and database name as you will need this later

Step 6: Remove the PHP template that is installed by default

  • rm –rf  ~/code/piwik/php/*

Step 7: Copy the Piwik sources from your staging area to your application directory

  • cp –av ~/code/piwikstage/piwik/* ~/code/piwik /php

Step 8: Add and commit your code to the local git repository

  • $ cd ~/code/piwik/php
  • $ git add .
  • $ git commit –a –m “Initial commit for Piwik”

Step 9: Deploy your application to the cloud and ensure it works

  • $ cd ~/code/piwik
  • $ git push
  • Assuming everything went as expected, you should be able to verify Piwik is running at piwik-$


Step 10: Create a github repository

Note: This step assumes that you already have a github account.  If you don’t, head on over to and sign up (It’s free).

Step 11: Add the new github repository to your piwik code base

  • On your newly created project space, grab the HTTP git url
  • $ cd ~/code/piwik
  • $ git remote add github $The HTTP git URL from above

Step 12: Create a README and with deployment instructions and add it to your repository


Step 13: Push your code up to github

  • $ git push –u github master


Step 14: Verify this quick start is repeatable

At this point, I normally delete my application (after making a backup) and run through the quick start from scratch to ensure that it works.

  • $ cd ~/code
  • $ rhc-ctl-app –a piwik –c destroy –l  yourlogin
  • $ mv piwik piwik.working
  • Follow the instructions you created in your README file to try and deploy the application from scratch

Step 15: Email us and let us know

Once you have created a quick start, send us an email at openshift AT redhat DOT com and we will add it to the main OpenShift space on github.

If your application requires an existing populated database, the way to accomplish this is by using the .openshift/action_hooks/build script located in your application directory.  Once you have your database created locally, do a mysqldump on the table and store the .sql file in the action_hooks directory.  You can then modify an existing build file to import the schema on application deployment.  For an example, please see our wordpess quickstart.

Step 5.5:

cd code/piwik

git clone ssh://xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx.git

In step 4, upon creating the application using the rhc client tools, it will also clone the git repo of the newly created app. You'll need to clone the repo if you're using the web console to create the app, or if there were any errors in creation where it didn't clean up and destroy the app (e.g., DNS timeouts).

the app that am trying to create a quick start for, has a tmp folder which it writes to , so the folder tmp should be there in the php folder, but it is also marked as to be ignored in .gitignore. The last step above ( to test ) would not work cause if you simply copy all the files into the PHP folder and git push , as the tmp folder will never get pushed. ( as it is in my .gitignore, and has to be there ) .

Question , do I need to worry about it ? cause if you simply create a fork off my github repo , then the tmp folder will be created on the cloud, but if you copy it and push it to the cloud repo ( instead of cloning it on the cloud machine ) it will not work. I could handle this in action_hooks ( check if a tmp exists and create one if not ) but is that the only solution ( if there needs to be a solution )?

Hi @adarshvritant;

We have a KB article: that covers a couple of suggestions. Can you please take a look at it and see if it helps?


Adding from email thread:

am not sure if those suggestions help me. I wanted to know, when I submit a quick start , and say it is used as a template in the openshift quickstarts, will the files be cloned on the remote machine or pushed to a repo there? because this one directory is in git ignore, so if it is the latter, i will have to work on a hack for it.

So the way people use the quickstarts is:
1) create an app
2) clone the app repo to local
3) add remote (github) repo
4) do a pull (to local)
5) do a push to origin master (openshift gear)
In short, the later.

Reason I passed along the KB was to help guide the workaround. If the app needs the contents of php/tmp to run/start (not sure if tmp is the best name for the dir if the contents are needed), and it's written to by the app, your git push will overwrite them on the gear. I would suggest moving it to $OPENSHIFT_DATA_DIR so as to protect the contents from git pushes overwriting them.

Thanks @adarshvritant for the discussion as well as for your efforts in building the quickstart!

you says:

"I would suggest moving it to $OPENSHIFT_DATA_DIR so as to protect the contents from git pushes overwriting them. "

i would create a tomee application ( a tomcat modified for ejb ) on openshift with quick start.

but i not understand what i have to change into server.xml of tomcat and:

if int oa web application installed into tomee (tomcat) i would upload image , file ,etc, i would that persist int o $OPENSHIFT_DATA_DIR .

But how i have to get it vlaue it from tomcat? i have into the drectory openshift/action_hooks/ or openshift/action_hooks/build put a instructio that export $OPENSHIFT_DATA_DIR ?????

so the $OPENSHIFT_DATA_DIR value it a readable wiht jva :

String directoryforUpload= System.getProoperties("OPENSHIFT_DATA_DIR");

please help me. mauro .

modifi the server.xml of


Those comments were for a special case. Since you're basically onboarding Tomcat, you can follow this: