OpenShift is a PaaS platform from Red Hat which allows for the deployment and scale of apps written using Java PHP Ruby Python Perl, provides continuous integration testing tools (like Jenkins) and even has to offer MySQL, MongoDB, PostgreSQL and SQLite as storage options free of charge; it’s definitely an interesting range of tools.
The deployments can be controlled via a REST api or the rhc command line tool. This short guide aims at helping the newcomers to get started quickly with rhc.
There is a YUM repo available for Fedora and RHEL systems, but rhc is a Ruby gem and it means you can install it with gem once your gems build environment is setup properly.
$ gem install rhc
You should have already created an account on OpenShift, if you haven’t yet, please do.Then let’s create our domain. This is a namespace binded to your username and will affect the apps url, which will look like $APPNAME-$DOMAIN.rhcloud.com
$ rhc domain create -l $USERNAME -n $NAMESPACE
Very simple step needed to create an app inside the namespace defining some of its peculiarities.
$ rhc app create -l $USERNAME -a $APPNAME -t ruby-1.8
This will create an app of type ruby-1.8 called $APPNAME, but other types can be used:
raw-0.1, php-5.3, jbossas-7.0, jenkins-1.4, python-2.6, perl-5.10, ruby-1.8
Here is a complete list of commands you can use to control your app
create Bind a registered rhcloud user to a domain in rhcloud. show Display information about a user start Starts the application (includes embedded) stop Stops the application (includes embedded) force-stop Stops all application processes restart Restart the application reload Reloads application configuration status Returns application status destroy Destroys the application tidy Garbage collects the git repo and empties log/tmp dirs add-alias Add a custom domain name for the application remove-alias Remove a custom domain name for the application threaddump Trigger a thread dump for jbossas applications tail Tail the logs of an application snapshot [save|restore] Saves/Restores an application snapshot to/from a tarball at the location specified using --filepath (default: ./$APPNAME.tar.gz) cartridge ACTION Manage an embedded cartridge
We’ll get back on tail and snapshot later.
This is needed to add support for a specific feature to your app. We are adding here the mysql-5.1 cartridge.
$ rhc app cartridge add -c mysql-5.1 -a $APPNAME -l $USERNAME
Here is a list of available cartridges (as of 24/03/2012)
postgresql-8.4, metrics-0.1, mysql-5.1, jenkins-client-1.4, 10gen-mms-agent-0.1, phpmyadmin-3.4, rockmongo-1.1, cron-1.4, mongodb-2.0
A very common need is to access the same account from different workstations, in this case you’ll have to add the user’s public SSH keys to the account.
$ rhc sshkey add -k /path/to/key.pub -i $NAME -l $USERNAME
$NAME is a general identifier. You can customize which is the default SSH key to be used by rhc in its config file.
$ cat ~/.openshift/express.conf # SSH key file #ssh_key_file = 'libra_id_rsa' # Default rhlogin to use if none is specified #default_rhlogin=$USERNAME
Two very powerful commands allow you to tail log files and to create local copies of the entire workspace where your app is running into remotely.
$ rhc tail -a $APPNAME -l $USERNAME -f $APPNAME/logs/*
This executes the regular tail command on the target host, copying back the output. You can use any other tail option passing the -i argument.
Finally you can get a snapshot of the working environment to look, for example, at custom files or even the execution environment variables.
$ rhc snapshot save -a $APPNAME -l $USERNAME $ tar xzf $APPNAME.tar.gz $ ls $APPID/.env/ OPENSHIFT_APP_CTL_SCRIPT OPENSHIFT_APP_NAME OPENSHIFT_CONTAINER_UUID OPENSHIFT_INTERNAL_IP OPENSHIFT_REPO_DIR PATH OPENSHIFT_APP_DIR OPENSHIFT_APP_TYPE OPENSHIFT_DATA_DIR OPENSHIFT_INTERNAL_PORT OPENSHIFT_RUN_DIR OPENSHIFT_APP_DNS OPENSHIFT_APP_UUID OPENSHIFT_HOMEDIR OPENSHIFT_LOG_DIR OPENSHIFT_TMP_DIR $ cat $APPID/.env/OPENSHIFT_DATA_DIR export OPENSHIFT_DATA_DIR='/var/lib/libra/0f5c99f17db74cf3a93edcf330401208/hellotornado/data/
The tools are quite easy to manage and can be updated easily with a gem update. There are also a lot of other interesting features you may want to look at, like the port forwarding but this was just a quickstart intended to provide a short reference. One last note before closing: you can SSH into your system!
$ rhc-domain-info -l $USERNAME
Password:
Application Info
================
hellotornado
Framework: python-2.6
Creation: 2012-02-22T15:46:02-05:00
UUID: 0f5c99f17db74cf3a93edcf330401208
Git URL: ssh://[email protected]/~/git/hellotornado.git/
Public URL: http://hellotornado-gosns.rhcloud.com/
$ ssh [email protected]
Welcome to OpenShift shell
This shell will assist you in managing openshift applications.
!!! IMPORTANT !!! IMPORTANT !!! IMPORTANT !!!
Shell access is quite powerful and it is possible for you to
accidentally damage your application. Procede with care!
If worse comes to worse, destroy your application with rhc-ctl-app
and recreate it
!!! IMPORTANT !!! IMPORTANT !!! IMPORTANT !!!
type "help" for more info.
[hellotornado-opinoid.rhcloud.com ~]> help
Help menu: The following commands are available to help control your openshift
application and environment.
ctl_app control your application (start, stop, restart, etc)
ctl_all control application and deps like mysql in one command
tail_all tail all log files
export list available environment variables
rm remove files / directories
ls list files / directories
ps list running applications
kill kill running applications
mongo interactive MongoDB shell
Lot of fun in there. There is also a shortcut for the interactive mongo shell. There doesn’t seem to be any for mysql or postgres but you can use the standard command line tools or access to them via port forward as per this blog entry