Table of Contents for

Getting Started with OpenShift

Your application’s remote container, called a gear, can be accessed using the Secure Shell (SSH) protocol in the same way as you access regular machines. To communicate with OpenShift securely, your OpenShift account must first contain an SSH public key belonging to the machine from which you wish to connect. This key is uploaded to OpenShift when you first run the terminal command rhc setup (see Chapter 2 for more on this); you can also add keys manually via the OpenShift Web Console’s Settings section.

The simplest way to connect to an application gear is to go to the command line, change into the directory where your app was cloned locally, and enter the command rhc ssh. This will start an SSH session with your main application gear. If the local clone of your application repository is not linked to your OpenShift app in RHC (in which case you will receive an error message), or you wish to SSH from another directory, you should add the -a appname option, replacing appname with the name of your app.

If you would prefer to use an alternative tool for creating an SSH connection, you can view the SSH URL you will need for your main application gear with the command rhc app show -a appname.

If your app is scalable and you would like to SSH into the other gears, you can use the command rhc app show --gears -a appname to view their SSH URLs and the ssh command-line tool to connect (e.g., ssh user@host).

Once you have connected to the gear via SSH, you will see a “Welcome to OpenShift console” message and a warning about making destructive modifications to your application; you should always take care when making changes on the gear directly as it is possible to make persistent, unversioned changes to your app and its environment. By default, you will find yourself in the home directory of the OpenShift user for your application, which will have a UUID username that doesn’t quite roll off the tongue. If you list the contents of the directory, you will see subdirectories for the cartridges on your gear, as well as Git, your app’s deployment history, and the app itself.

Here is the output from a sample SSH session with our Python demo application. We connect to the application gear, then use the ls command to list the contents of some of the key directories, starting with our OpenShift application user’s home directory:

[me@localhost ~/insultapp]$ rhc ssh
Connecting to 6e7672676e61676976757570@insultapp-osbeginnerbook.rhcloud.com ...

    *********************************************************************

    You are accessing a service that is for use only by authorized users.
    If you do not have authorization, discontinue use at once.
    Any use of the services is subject to the applicable terms of the
    agreement which can be found at:
    https://www.openshift.com/legal

    *********************************************************************

    Welcome to OpenShift console

    This console 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.  Proceed with care!
    If worse comes to worst, destroy your application with "rhc app delete"
    and recreate it
    !!! IMPORTANT !!! IMPORTANT !!! IMPORTANT !!!

    Type "help" for more info.


[insultapp-osbeginnerbook.rhcloud.com 6e7672676e61676976757570]\> ls
app-deployments  app-root  cron  git  postgresql  python
[insultapp-osbeginnerbook.rhcloud.com 6e7672676e61676976757570]\> ls app-root
build-dependencies  data  dependencies  repo  runtime
[insultapp-osbeginnerbook.rhcloud.com 6e7672676e61676976757570]\> ls app-root
/repo
app.py.disabled  data  Insult_App.egg-info  libs  README.md  setup.py  setup.pyc
setup.pyo  wsgi

The demo application uses a Python cartridge, so there is a Python directory in the application’s home directory. The app-root directory contains several important application subdirectories, notably repo, containing the current clone of the application’s Git repository, and data, which is a persistent directory you will read more about later in the book (see Chapter 8).

When accessing an application gear via SSH, you can run the usual Linux commands you might execute on a local machine. However, there are some restrictions. Your app runs within a container secured with SELinux, and you do not have root access. As you would expect, you cannot access other applications running on the same remote machine. If you receive “Permission Denied” errors, it is likely because you have attempted to overstep your bounds. Remember, you are a developer, not an administrator on your gear.

[insultapp-osbeginnerbook.rhcloud.com 6e7672676e61676976757570]\> psql
psql (9.2.4)
Type "help" for help.

insultapp=# help
You are using psql, the command-line interface to PostgreSQL.
Type:  \copyright for distribution terms
       \h for help with SQL commands
       \? for help with psql commands
       \g or terminate with semicolon to execute query
       \q to quit
insultapp=# \q
[insultapp-osbeginnerbook.rhcloud.com 6e7672676e61676976757570]\>

[me@localhost ~/insultapp]$ scp import.sql 6e7672676e61676976757570@insultapp
-osbeginnerbook.rhcloud.com:~/app-root/data
import.sql                                      100% 5360     8.2KB/s   00:00

DROP TABLE IF EXISTS short_adjective;
DROP TABLE IF EXISTS long_adjective;
DROP TABLE IF EXISTS noun;

BEGIN;

CREATE TABLE short_adjective (id serial PRIMARY KEY, string varchar);
CREATE TABLE long_adjective (id serial PRIMARY KEY, string varchar);
CREATE TABLE noun (id serial PRIMARY KEY, string varchar);

INSERT INTO short_adjective (string) VALUES ('artless');
INSERT INTO short_adjective (string) VALUES ('bawdy');
INSERT INTO short_adjective (string) VALUES ('beslubbering');

INSERT INTO long_adjective (string) VALUES ('base-court');
INSERT INTO long_adjective (string) VALUES ('bat-fowling');
INSERT INTO long_adjective (string) VALUES ('beef-witted');

INSERT INTO noun (string) VALUES ('apple-john');
INSERT INTO noun (string) VALUES ('baggage');
INSERT INTO noun (string) VALUES ('barnacle');

[insultapp-osbeginnerbook.rhcloud.com 6e7672676e61676976757570]\> cd app-root
/repo/
[insultapp-osbeginnerbook.rhcloud.com repo]\> psql -f import.sql

Only masochistic developers hardcode database connection strings or server ports; we have environment variables to save us from the pain of marrying code to a particular environment. OpenShift and its standard cartridges have a bunch of useful environment variables available out of the box that you can reference in your applications. It is also possible to set custom environment variables.

You can view the values of some of the essential environment variables, such as your database details, in the output of the command rhc app show -a appname. To view all of the environment variables and their values, SSH into your application gear and execute the command env. To view only the environment variables with names including the word “OPENSHIFT,” use the command env | grep OPENSHIFT.

[me@localhost ~]$ rhc env set API_USERNAME=admin API_PASSWORD=secret -a
insultapp
Setting environment variable(s) ... done
[me@localhost ~]$ rhc env list -a insultapp
API_PASSWORD=secret
API_USERNAME=admin
[me@localhost ~]$ rhc unset API_PASSWORD -a insultapp
Removing environment variables is a destructive operation that may result in
loss of data.
API_PASSWORD

Are you sure you wish to remove the environment variable(s) above from
application 'insultapp'? (yes|no): yes

Removing environment variable(s) ... removed
[me@localhost ~]$ rhc env show API_USERNAME API_PASSWORD -a insultapp
API_USERNAME=admin

[me@localhost ~/insultapp]$ rhc env set OPENSHIFT_SECRET_TOKEN=new_token
Setting environment variable(s) ... done

To ensure your application is working correctly, or troubleshoot when it is not, you may want to view the log files. You can do this by connecting to the application gear via SSH and navigating to the relevant locations, which you can find by checking the environment variables as described in the previous section. In general, you will find the log directories for web cartridges can be referenced with $OPENSHIFT_<cartridge>_LOG_DIR and databases with $OPENSHIFT_<database>_DB_LOG_DIR. For example, our demo application’s logs are directed to $OPENSHIFT_PYTHON_LOG_DIR and $OPENSHIFT_POSTGRESQL_DB_LOG_DIR.

A simpler method for checking the logs is to use RHC’s tail command. By default, rhc tail -a appname will tail the log files within the cartridges’ log directories; in the case of our Python application, this means the files stored in $OPENSHIFT_HOMEDIR/python/logs and $OPENSHIFT_HOMEDIR_postgresql/log. However, you can specify a different or more specific set of files, relative to $OPENSHIFT_HOMEDIR, with the -f option. You can also set various Linux tail command options by adding -o.

The following command tails the insultapp application’s database logs only, outputting the last 50 lines rather than the default of the last 10:

[me@localhost ~]$ rhc tail -f postgresql/log/* -o '-n 50' -a insultapp

Application and database cartridges will be configured to output their logs to the directories referenced by the aforementioned environment variables by default. If you produce application-specific logs, you should direct these to your web cartridge’s log directory as well, e.g., $OPENSHIFT_PYTHON_LOG_DIR. Files in this directory will automatically be included in the output of the rhc tail command.

To learn how to manage disk usage and back up your remote files, including log files, see Chapters 8 and 9.

One of the advantages of using a Platform as a Service is that you do not have to tinker with dozens of configuration files just to get an app running in the cloud. That said, you may well want to alter the out-of-the-box config, and many cartridges facilitate that.

Many basic OpenShift cartridge configuration options are controlled with marker files. If a particular marker file is present, the option is enabled; otherwise, the default behavior prevails. Marker files are added in an OpenShift application’s Git repository, in the .openshift/markers directory. The contents of marker files are irrelevant; they are empty files. They do not have any file extension.

One of the most common marker files used is hot_deploy—as mentioned in Hot-Deploying Code—which tells OpenShift to deploy new builds without restarting the cartridge server. Other marker files you may be interested in include force_clean_build (instructs OpenShift to remove previously built artifacts before building the app), disable_auto_scaling (prevents scalable applications from scaling according to load), and java7 (if this is removed, Java cartridges will use Java 6).

The marker files must be committed and pushed with Git. Here is an example of adding the force_clean_build marker to our example app:

[me@localhost ~/insultapp]$ touch .openshift/markers/force_clean_build
[me@localhost ~/insultapp]$ git add .openshift/markers/force_clean_build
[me@localhost ~/insultapp]$ git commit -m "Adding marker to force clean build"
[me@localhost ~/insultapp]$ git push

This will cause OpenShift to re-create the app’s virtual environment and reinstall the required Python eggs (these are code bundles, like JARs in Java). We do not want this to happen on every build as it takes time to download those dependencies, so once we are satisfied that the environment is clean we would remove the marker file.

It’s time to take a deep breath; we have learned a lot in this chapter. We showed how to use SSH to connect to your application’s gears and interact with databases hosted on OpenShift. We know that application configuration is easier to maintain when we use environment variables rather than hardcoded values; in this chapter we learned how to access the values of OpenShift’s environment vars and how to define our own. We discussed OpenShift application log access with rhc tail and where to direct app log output. Finally, we explained how to make application server and database configuration changes and how to control app config switches with marker files.

In the next chapter, we will dive into application dependencies and show how to connect to a database from your OpenShift app code.