Wednesday 6 June 2012

Webfaction - Compiling & Installing A Custom Nginx Instance

Sometimes you need to compile your own versions of software and at first it can seem a little daunting and confusing. The truth is that sometimes is it, but fortunately compiling Nginx on webfaction’s servers is quite straightforward.

Download The Latest Nginx Source

The first thing you need to do is download the nginx source and extract it to a local directory. Personally I like to keep all of my source code in ~/src/ folder so I can recompile at a later point in time. At the time of writing the most recent stable version of nginx was 1.2.1. Make sure that if you’re reading this in the future that you check that you have the most recent version.

 # get into the src folder, download & extract nginx source cd ~/src curl -O tar -xzvf nginx-1.2.1.tar.gz cd nginx-1.2.1 

Configure The Source

Now you’re ready to configure your installation and this means that you have to run the configure script with a collection of arguments and there’s no getting away from the fact that the compile for nginx can take a lot. Because we’re going to be installing nginx on a shared server we have to provide a custom values for a lot of the available arguments so that our copy of nginx knows to install itself into our space on the server –

 ./configure   --prefix=$HOME/local/nginx  \ --sbin-path=$HOME/local/sbin/nginx \ --conf-path=$HOME/local/etc/nginx.conf  \ --error-log-path=$HOME/logs/user/nginx/error.log \ --http-log-path=$HOME/logs/user/nginx/access.log \ --pid-path=$HOME/local/run/nginx/ \ --lock-path=$HOME/local/lock/nginx.lock \ --http-client-body-temp-path=$HOME/tmp/nginx/client/ \ --http-proxy-temp-path=$HOME/tmp/nginx/proxy/  \ --http-fastcgi-temp-path=$HOME/tmp/nginx/fcgi/ \ --with-http_flv_module \ --with-http_ssl_module \ --with-http_gzip_static_module  

If all goes according to plan you see a lot of output, with the last of that output being a summary of the install –

 Configuration summary   + using system PCRE library   + using system OpenSSL library   + md5: using OpenSSL library   + sha1: using OpenSSL library   + using system zlib library    nginx path prefix: "/home/you/local/nginx"   nginx binary file: "/home/you/local/sbin/nginx"   nginx configuration prefix: "/home/you/local/etc"   nginx configuration file: "/home/you/local/etc/nginx.conf"   nginx pid file: "/home/you/local/run/nginx/"   nginx error log file: "/home/you/logs/user/nginx/error.log"   nginx http access log file: "/home/you/logs/user/nginx/access.log"   nginx http client request body temporary files: "/home/you/tmp/nginx/client/"   nginx http proxy temporary files: "/home/you/tmp/nginx/proxy/"   nginx http fastcgi temporary files: "/home/you/tmp/nginx/fcgi/"   nginx http uwsgi temporary files: "uwsgi_temp"   nginx http scgi temporary files: "scgi_temp" 

Compile & Install

You’re now ready to compile the source code, this bit is quite straight forward and it’ll spit out a lot of output for such a small command. –


Now you’re ready to install it –

 make install 

That’s the tricky bits done, but we need to create a few directories because when we compiled nginx we specified three directories that don’t currently exist –

  • ~/tmp/nginx/client
  • ~/tmp/nginx/proxy
  • ~/tmp/nginx/fcgi

We need to create these directories otherwise nginx won’t start and our config test will fail –

 mkdir -p ~/tmp/nginx/fcgi ~/tmp/nginx/proxy ~/tmp/nginx/client 

Your Path

You need to add the /home/you/local/sbin directory to your path so that we can type nginx and have our shell be able to reach our nginx install. To do this you need to edit your ~/.bashrc file and modify your path as follows –

 export PATH=/home/you/local/sbin:$PATH 

When you’ve done that you’ll need to reload your bash environment –

 source ~/.bashrc 

Now if you do an echo of your $PATH environmental variable you’ll notice that your custom nginx install path is included in the output

 echo $PATH /home/you/local/sbin:/usr/local/bin:/bin:/usr/bin:/usr/local/sbin:/usr/sbin:/sbin:/home/you/bin 

The Control Panel

You have to do two things in the webfaction control panel to enabled all incoming requests to be handled by your custom nginx install.

Create A Custom Application

You now have to login to the control panel and create a custom application listening on a port. This is because the main apache instance (running on port 80), will proxy all incoming traffic to your custom nginx instance, but before it can do that, you need to create a port for your nginx instance to listen on.

Screenshot of creating an application via the webfaction control panel

After you press the “add application” button a new screen will load that will show you the port number that has been assigned to you. In the below example you can see that my app is in port 20799.

Screenshot of custom application running on port

Whatever your port is, make a note of it because you’ll need it very soon.

Point Your Domain At Your Nginx Instance

If you go to the domains/websites > domains part of the control panel and click through to the edit screen you’ll see something like the below screenshot. However, in the below example I’ve already added the nginx application and mounted it on the root of the URL. You should do the same.

Screenshot of pointing domain at application

So now that you’ve created your custom app and configured your application to your domain, you can move onto the config file.

The Configuration File

Before creating the new config file you should copy the original config file to a backup — just to be safe.

 mv ~/local/etc/nginx.conf ~/local/etc/nginx.conf.backup 

Now that the old config file is safe, I like to replace the old file with a brand new file because I’m a fan of revolution over evolution. The config file I use is very barebones –

 worker_processes  4; events {     worker_connections  1024; } http {     include       mime.types;     default_type  application/octet-stream;     sendfile        on;     keepalive_timeout  65;     gzip  on;     # this is to include my various virtual hosts     include /home/you/local/etc/nginx/*.conf;     # now give the port number to listen on     server{         listen 20799;     } } 

Just make sure the new config file is saved as ~/usr/local/etc/nginx.conf. When you’re done creating the new file you should test the config

 nginx -t # here's the expected output nginx: the configuration file /home/you/local/etc/nginx.conf syntax is ok nginx: configuration file /home/you/local/etc/nginx.conf test is successful 

If you get any errors when testing the config double check that you’ve created all of the directories from the Compile & Install section above. If you don’t get any errors then you should be able to start nginx –


Now open up a web browser and crack in your domain. You should be greeted with something like this –

Screenshot of default nginx page

What’s next?

Now you’re free to start creating virtualhosts. With the config that I added above I’m able to place all of my virtual hosts in ~/local/etc/nginx/mydomain.conf and have that location automatically included whenever I reload or restart nginx.

Bonus: Starting, Stopping & Reloading.

If you’re needing to know how to start, stop or reload your custom nginx install then here’s how to do each –

  • start nginx
  • stop nginx -s stop
  • reload nginx -s reload
  • config test nginx -t

Happy Nginx’ing.