How to Install Nginx on WebFaction

As a precursor to a few posts about Nginx I thought I would outline the steps required to install your own instance of Nginx on WebFaction. WebFaction’s servers include an installation of Nginx that you use whenever you create a “static only” or “symlink to static only” app, and for many things this is all you need, but in order to specify any configuration you have to build Nginx in your home directory.  If you want to set HTTP headers, rewrite URLs, or use Nginx’s proxy caching and load balancing features, you’ll need to run your own instance.  Unlike Apache, Nginx does not have an .htaccess option that allows you to override server configuration from any directory.

Fortunately, installing Nginx is a piece of cake.

Update (2/20/10): I’ve created a one-click WebFaction installer script for Nginx.  You can get it as a gist at github.

Control Panel

1. Create a new application with the app type “Custom app (listening on port)” and name it “nginx”.  Make a note of the port number that the installer returns.

2. Create a new domain or add a subdomain to your username.webfactional.com domain (“nginx.username.webfactional.com”, for example).

3. For the last step in the control panel, go to the Websites section and create a site that associates the Nginx app with the Nginx domain.  Bind the app at the root by entering / for the URL path.  Unless you’re new to WebFaction you should be familiar with this three-step app/domain/site process.

To the shell

The installer that we just ran didn’t actually install anything.  It simply created a folder in our webapps directory and assigned a port number to it.  So now we’ll install Nginx.

4. SSH into the server and go to the newly created folder, ~/webapps/nginx.  Before we can build Nginx there’s one dependency we have to take care of, PCRE, which is a C library for matching regex patterns. From within your nginx folder, download and extract PCRE with these two commands:

wget ftp://ftp.csx.cam.ac.uk/pub/software/programming/pcre/pcre-8.01.tar.gz
tar -xzf pcre-8.01.tar.gz

Note: it is not necessary to configure and install PCRE; Nginx just needs the source files.

Update (2/20/10): David Sissitka from WebFaction left a note saying that PCRE is installed on all their servers, so you can skip step 4.  If you use the system install of PCRE, make sure to leave out the --with-pcre=$HOME/webapps/nginx/pcre-8.01/ option in the nginx configure command.

5. Now we’ll download and extract the latest stable version of Nginx, which is 0.7.65 at the time of this writing.

wget https://sysoev.ru/nginx/nginx-0.7.65.tar.gz
tar -xzf nginx-0.7.65.tar.gz

6. Next we run the configure command, specifying the installation path, the path to PCRE, and any extra modules that we want to enable.  All optional and 3rd party modules must be selected at this point; they cannot be added after we’ve compiled Nginx.  For a list of available modules you can run ./configure --help, or visit the Nginx wiki.  (In this example we’re not installing any optional modules.)

Run the following:

cd nginx-0.7.65
./configure --prefix=$HOME/webapps/nginx --with-pcre=$HOME/webapps/nginx/pcre-8.01/

Once that’s done we just need to make and install:

make
make install

You should now have Nginx installed in your ~/webapps/nginx directory.  Before we forget, let’s remove the tarballs and source files:

cd ..
rm -fr pcre-8.01*
rm -fr nginx-0.7.65*

7. Next we need to make a few edits to our Nginx config file.

cd conf
nano nginx.conf

Find the following two lines and replace “80” with the port number you wrote down in the first step, and “localhost” with the domain you created in the second step (nginx.username.webfactional.com, for example).

server {
        listen       80;
        server_name  localhost;

8. The last step is to boot Nginx:

cd ~/webapps/nginx
./sbin/nginx

Open up your domain in a browser and you should see the “Welcome to nginx!” message.  You’re now up and running with a basic installation of Nginx.

One final note, you’ll need to reboot Nginx whenever you make changes to the nginx.conf file.  A helpful tip for setting up stop/start/restart aliases can be found in this Google Groups thread.