Set up Local Access to OpenShift Hosted Services with Port Forwarding

postgres in local development
As a follow-up to my recent post on building Instant Mapping Applications with PostGIS and Nodejs, I wanted to outline my process for setting up a local application environment for testing and reviewing changes during development.

I’m using a Fedora 19 system – so installing, configuring, and managing my own local Postgres database is definitely one way to meet this application’s local service requirements. However, OpenShift provides an easier way to fulfill these dependencies – offering secured access to your hosted database via on-demand ssh tunnels.

In this post, I’ll show you how I use the rhc port-forward command to deliver local access to your OpenShift-hosted cartridges.

Instant Provisioning on OpenShift

To follow along, you’ll need to provision your own OpenShift-hosted clone of our demo PostGIS mapping application.

This can be done using the rhc command line tool:

rhc app create parks nodejs-0.10 postgresql-9.2 --from-code=https://github.com/ryanj/restify-postGIS.git

Or, by linking to a web-based clone+deploy on OpenShift Online or your own open cloud:

https://openshift.redhat.com/app/console/application_type/custom?name=parks&cartridges%5B%5D=nodejs-0.10&cartridges%5B%5D=postgresql-9.2&initial_git_url=https%3A%2F%2Fgithub.com%2Fryanj%2Frestify-postGIS.git

A live demo of the resulting application is available for comparison at: http://nodegis-shifter.rhcloud.com/

Local Development

You’ll need to have a local copy of the application source code, and an installation of nodejs available on your machine in order to prepare your development environment.

If you created a clone of the application using the rhc command (above), then you should already have a local copy of the project source. If not, you can try cloning the repo using git, or taking advantage of the rhc git-clone command to fetch a local clone of any of your existing OpenShift applications:

rhc git-clone parks

Now that you have a local copy of the project source, you’ll need to run npm install inside the folder to ensure that the application’s npm package dependencies have been made available:

npm install

For hosted apps, OpenShift automatically resolves npm dependencies by calling npm install as a normal part of it’s automated application build process.

Establishing an SSH Tunnel with the rhc port-forward Command

OpenShift’s security model is advanced enough to allow for secured access to hosted services via on-demand ssh tunnels.

The rhc port-forward command can help you establish a local connection to your hosted database – where your DB permissions, table schema, and map data have already been initialized.

The command output provides a list of local connection details:

Service    Local               OpenShift
---------- -------------- ---- ----------------
node       127.0.0.1:8080  =>  127.5.199.1:8080
postgresql 127.0.0.1:5433  =>  127.5.199.2:5432

Press CTRL-C to terminate port forwarding

Make a note of the local postgresql IP address and port number, and leave the command running (in order to keep the connection open). We will need to use these values in the next step.

Basic Configuration

This app uses the config npm module, which loads it’s configuration details from the config/defaults.json file. This configuration takes advantage of several environment variables whenever they are available. On OpenShift, many of these values are automatically provided for your application by their associated cartridge add-on service:

module.exports = {
  port: process.env.PORT || process.env.OPENSHIFT_NODEJS_PORT || 3000,
  ip: process.env.OPENSHIFT_NODEJS_IP || '127.0.0.1',
  pg_config: process.env.OPENSHIFT_POSTGRESQL_DB_URL || 'postgresql://127.0.0.1:5432',
  table_name: process.env.OPENSHIFT_APP_NAME || 'parks'
}

Sensible defaults allow us to run the same code in multiple environments. For example, if the OPENSHIFT_NODEJS_PORT setting is undefined, then our local server will try to bind to the default port value (3000).

If you plan on using the port-forwarded DB connection from the previous step in your local development stage, then you will need to supply some additional DB authentication credentials to your application via the OPENSHIFT_POSTGRESQL_DB_URL environment variable.

Environment Variables

To make a database connection, your app will attempt to read a connection string from the OPENSHIFT_POSTGRESQL_DB_URL environment variable.

You can configure the app to connect to your remote database by substituting your hosted DB’s DB_USERNAME, DB_PASSWORD, and your port-forwarded LOCAL_DB_IP, and LOCAL_DB_PORT into the following command:

export OPENSHIFT_POSTGRESQL_DB_URL="postgres://DB_USERNAME:DB_PASSWORD@LOCAL_DB_IP:LOCAL_DB_PORT"

You can find this information by running env while connected to your OpenShift-hosted application over ssh, or by running the rhc app show command from your local machine.

rhc app show parks

This information is also available via your application’s OpenShift web console:
Cartridge connection information available in the OpenShift Console

My application’s command ended up looking like this:

export OPENSHIFT_POSTGRESQL_DB_URL="postgres://admin32jk510:X_kgB-3LfUd3@127.0.0.1:5433"

This app also expects to use a Postgres table_name that matches your application’s name (as defined within OpenShift).

When running this application on OpenShift, the OPENSHIFT_APP_NAME environment variable will be automatically populated. If you didn’t name your application “parks” (the default value for this option), then you will likely need to set an extra environment variable containing your table name in your local dev environment:

export OPENSHIFT_APP_NAME=parks

Testing your connection

You can verify that your port-forwarding tunnel is active, and that your environment variables are configured correctly by using them to make a DB connection using the psql command-line client:

psql $OPENSHIFT_POSTGRESQL_DB_URL/$OPENSHIFT_APP_NAME

This should provide a direct connection to your OpenShift-hosted database instance.

Here you can verify that your application’s automatic database import procedures have successfully completed, by checking the number of records in our DB table:

select count(*) from parks;

The result should be 547. As usual, if you named your application something other than “parks”, you’ll need to modify above the command to match your particular configuration.

Starting your Local Webserver

Now, you should be able to fire up a local server with:

npm start

Your development server should be available at the default address: localhost:3000

Deploying updates to OpenShift

Make updates to your OpenShift-hosted application using the standard git development workflow.

To set your map’s default location to Boston, MA, you could update your index.html file’s setView function with the following new input value:

var map = L.map('map').setView([42.35, -71.06], 8);

You can verify your changes by reloading your connection to your local webserver.

When you’re ready to save your work and update your OpenShift-hosted application instance:

  1. Add your changes to a changeset:
    git add index.html
    
  2. Mark the changeset as a Commit:
    git commit -m 'changing default map location to Boston, MA'
    
  3. And, Push the Commit to OpenShift
    git push
    

The output from the git push command will echo back the build process as your application is re-staged. Your changes should be visible on OpenShift as soon as the deploy process completes.

Developer Challenge: Add support for HTML5 geolocation and send us a pull request, or post your solution in the comments below.

What’s Next?

Categories
MongoDB, MySQL, Node.js, OpenShift Online, PostgreSQL
Tags
, ,
Comments are closed.