Pre-requisites for setting up Nginx

I was trying to set up Nginx on OpenShift and I'd like to share my experience here.
To get started, you need to have an OpenShift account. You can register for a free OpenShift account.
I recommend you to install the command line client. Follow the getting started guide to install the client tools and to setup the environment on your machine.

Create OpenShift application

To create an OpenShift application, you can use the client tools that you just installed.
Let's name the application as mysite and with diy-0.1 type.

rhc app create mysite diy-0.1

Show the newly created application info:

rhc app show -a mysite

Use the SSH information from the Git URL to SSH into your application.

ssh <random-strings>@mysite-<your-namespace>.rhcloud.com

The environment variables that are available to you in your OpenShift application can be found here. Those environment variables are very useful.

Install Nginx

Now we can start the Nginx installation. Navigate to the tmp dir and download the Nginx source.

cd $OPENSHIFT_TMP_DIR
wget <a href="http://nginx.org/download/nginx-1.2.2.tar.gz" title="http://nginx.org/download/nginx-1.2.2.tar.gz">http://nginx.org/download/nginx-1.2.2.tar.gz</a>
tar zxf nginx-1.2.2.tar.gz
cd nginx-1.2.2

If you run

./configure --prefix=$OPENSHIFT_DATA_DIR

directly, you will get the following errors:

checking for PCRE library ... not found
checking for PCRE library in /usr/local/ ... not found
checking for PCRE library in /usr/include/pcre/ ... not found
checking for PCRE library in /usr/pkg/ ... not found
checking for PCRE library in /opt/local/ ... not found
 
./configure: error: the HTTP rewrite module requires the PCRE library.
You can either disable the module by using --without-http_rewrite_module
option, or install the PCRE library into the system, or build the PCRE library
statically from the source with Nginx by using --with-pcre=<path> option.

There is no way for us to install the PCRE lib into the system, so we are left with second option which is to build it from the source directly.

cd $OPENSHIFT_TMP_DIR
wget ftp://ftp.csx.cam.ac.uk/pub/software/programming/pcre/pcre-8.31.tar.bz2
tar jxf pcre-8.31.tar.bz2

You can check the standard and optional HTTP modules that are supported by Nginx here so that you can enable them when configuring the makefile.

cd nginx-1.2.2
./configure --prefix=$OPENSHIFT_DATA_DIR --with-pcre=$OPENSHIFT_TMP_DIR/pcre-8.31

You should be able to see the following output if it's successful. Those information will be needed for you to configure Nginx later on.

Configuration summary
+ using PCRE library: /tmp//pcre-8.31
+ OpenSSL library is not used
+ md5: using system crypto library
+ sha1: using system crypto library
+ using system zlib library
 
nginx path prefix: "/var/lib/stickshift/c45cdc9a27944dc5b1cd7cb9e5c9f8c7/mysite/runtime/"
nginx binary file: "/var/lib/stickshift/c45cdc9a27944dc5b1cd7cb9e5c9f8c7/mysite/runtime//sbin/nginx"
nginx configuration prefix: "/var/lib/stickshift/c45cdc9a27944dc5b1cd7cb9e5c9f8c7/mysite/runtime//conf"
nginx configuration file: "/var/lib/stickshift/c45cdc9a27944dc5b1cd7cb9e5c9f8c7/mysite/runtime//conf/nginx.conf"
nginx pid file: "/var/lib/stickshift/c45cdc9a27944dc5b1cd7cb9e5c9f8c7/mysite/runtime//logs/nginx.pid"
nginx error log file: "/var/lib/stickshift/c45cdc9a27944dc5b1cd7cb9e5c9f8c7/mysite/runtime//logs/error.log"
nginx http access log file: "/var/lib/stickshift/c45cdc9a27944dc5b1cd7cb9e5c9f8c7/mysite/runtime//logs/access.log"
nginx http client request body temporary files: "client_body_temp"
nginx http proxy temporary files: "proxy_temp"
nginx http fastcgi temporary files: "fastcgi_temp"
nginx http uwsgi temporary files: "uwsgi_temp"
nginx http scgi temporary files: "scgi_temp"

Now we can compile and install the Nginx.

make install

Once it's done, you can navigate to $OPENSHIFT_DATA_DIR where your Nginx is installed.

Configure Nginx

OpenShift only allow an internal IP address and port for your application which are available through $OPENSHIFT_INTERNAL_IP and $OPENSHIFT_INTERNAL_PORT enviroment variables. And these values may change.

It will be easy if we can simply specify these environment variables directly to nginx.conf by using the env directive. But those env variables can only be referred in the main block of the config, not the http, server or location blocks.

So, we need to do a little trick here to bind the internal IP address and port in Nginx configuration dynamically. Let's edit the Nginx configuration file:

vi $OPENSHIFT_DATA_DIR/conf/nginx.conf

Modify the listen value to:

http {

server {
listen $OPENSHIFT_IP:$OPENSHIFT_PORT;
server_name localhost;

}

}

Rename the modified configuration file.

mv $OPENSHIFT_DATA_DIR/conf/nginx.conf $OPENSHIFT_DATA_DIR/conf/nginx.conf.template

We will modify the $OPENSHIFT_IP and $OPENSHIFT_PORT values when the start action hook is called. I am going to show it to you in the next section.

Final touch up

To start up your application automatically, edit the .openshift/action_hooks/start file.
Exit from your ssh session. On your machine,

cd mysite
vi .openshift/action_hooks/start
#!/bin/bash
# The logic to start up your application should be put in this
# script. The application will work only if it binds to
# $OPENSHIFT_INTERNAL_IP:8080
# nohup $OPENSHIFT_REPO_DIR/diy/testrubyserver.rb $OPENSHIFT_INTERNAL_IP $OPENSHIFT_REPO_DIR/diy > $OPENSHIFT_DIY_LOG_DIR/server.log 2>&1 &
# replace the $OPENSHIFT_INTERNAL_IP and $OPENSHIFT_INTERNAL_PORT before starting up the server
sed -e "s/`echo '$OPENSHIFT_IP:$OPENSHIFT_PORT'`/`echo $OPENSHIFT_INTERNAL_IP:$OPENSHIFT_INTERNAL_PORT`/" $OPENSHIFT_DATA_DIR/conf/nginx.conf.template > $OPENSHIFT_DATA_DIR/conf/nginx.conf
nohup $OPENSHIFT_DATA_DIR/sbin/nginx > $OPENSHIFT_DIY_LOG_DIR/server.log 2>&1 &
git commit -a -m "start nginx when starting up the app"
git push

Finally, use your browser again to navigate to http://mysite-.rhcloud.com. The same welcome page earlier will be displayed. And we are done.

Note:
Use rhc tail -a mysite command to troubleshoot the problem if you are having problem with the start script.