Installation/Special Instructions/Nginx

From Habari Project

Jump to: navigation, search

Contents

Installing Habari to Run on Nginx [engine x]

There are a few special considerations to get Habari up and running on Nginx. The first being that Nginx does not provide FastCGI for you, so you've got to have a way to spawn your own FastCGI processes...

Spawning FastCGI Processes

I prefer to use the spawn-fcgi program provided with the lighttpd web server. You can use PHP's built-in FastCGI manager php-cgi to do the same thing, but it's a bit more work and not as straight-forward. Plus, if you learn how to use spawn-fcgi, you can use it for other FastCGI applications aside from ones that are PHP-based.

Install spawn-fcgi

To download and install spawn-fcgi to your machine, run the following commands. Feel free to adjust the path where you want the binary and don't worry, all of the building happens in your current directory...nothing else will be installed on your machine. 

$ wget http://www.lighttpd.net/download/lighttpd-1.4.18.tar.bz2
$ tar -xvjf lighttpd-1.4.18.tar.bz2
$ cd lighttpd-1.4.18/
$ ./configure
$ make
$ sudo cp src/spawn-fcgi /usr/bin/spawn-fcgi

NOTE: You will need to be root in order to copy the binary to its final location, everything else should work fine as a normal user. To gain root privileges, the program sudo was used in the example above, you may or may not have access to sudo on your machine.

After spawn-fcgi has been copied to the desired location, you can safely remove the build directory and original source file: 

$ cd ..
$ rm -rf lighttpd-1.4.18/
$ rm lighttpd-1.4.18.tar.bz2

Run spawn-fcgi

This part will be fairly distribution-specific, but I'll provide the basic command that you'll need. What you'll want to do is find a way to run this command as part of your init scripts so the processes will be spawned automatically when you reboot your server. 

/usr/bin/spawn-fcgi -f /usr/bin/php-cgi -a 127.0.0.1 -p 53217 -P /var/run/habari.pid
  • -f -> the filename of the fcgi-application; in our case we want php-cgi, which is provided by your distribution's php package. If you don't know where to find it, try running which php-cgi on the command line.
  • -a -> the address to bind the processes to; in our case we want the localhost
  • -p -> the port number to bind the processes to; pick whatever you want (technically it would be best to pick one between 49152 and 65535), just make sure to remember the number and use that same one for your Nginx configuration file
  • -P -> the location where to save the process id file; you can use this file to easily kill the processes later

For better security, you can also set the user/group that the spawned processes will run as to a non-privileged user. To do this, you use the -u and -g flags respectively. For more information on all the available options, run spawn-fcgi -h on the command line.

Configure Nginx

The key part here is that Habari uses the FrontController design pattern, and thus requires any unrecognized URL request (meaning a request for a file that does not exist on the server) to be forwarded to and handled by the main index.php file. The file you need to edit is called nginx.conf and is installed in different places depending on your Linux distribution. For me, it was located here: /etc/nginx/conf/nginx.conf (installed from source, the default location is /usr/local/nginx/conf/nginx.conf) 

server {
    listen       12.345.678.90:80;  # YOUR PUBLIC IP ADDRESS (just use listen 80 to bind to all interfaces)
    server_name  domain.com;        # YOUR DOMAIN NAME (subdomains [blog.yourdomain.com] will also work here)

    root   /srv/www/nginx/domain.com/habari;  # ABSOLUTE PATH TO YOUR HABARI INSTALLATION

    location / {
        index  index.php index.html index.htm;

        # serve static files that exist without running other rewrite tests
        if (-f $request_filename) {
            expires  30d;
            break;
        }

        # send all non-existing file or directory requests to index.php
        # GOTCHA: Make sure your rewrite rules are inside the location block. 
        if (!-e $request_filename) {
            rewrite  ^  /index.php  last;
        }
    }

    location ~ \.php$ {
        fastcgi_pass   localhost:53217;  # PORT NUMBER WHERE YOU SPAWNED YOUR FCGI PROCESSES
        fastcgi_index  index.php;

        fastcgi_param  SERVER_SOFTWARE  nginx;
        fastcgi_param  QUERY_STRING     $query_string;
        fastcgi_param  REQUEST_METHOD   $request_method;
        fastcgi_param  CONTENT_TYPE     $content_type;
        fastcgi_param  CONTENT_LENGTH   $content_length;
        fastcgi_param  SCRIPT_NAME      $fastcgi_script_name;
        fastcgi_param  SCRIPT_FILENAME  $document_root$fastcgi_script_name;  # SAME PATH AS ABOVE
        fastcgi_param  REQUEST_URI      $request_uri;
        fastcgi_param  REDIRECT_STATUS  200;
    }
}

After you've added these settings to your configuration, restart the nginx daemon and your settings should take effect.

How to Properly Kill spawn-fcgi Processes

If you need to kill the FastCGI processes that you spawned (for instance, when stopping an init script), then you can run the following command since we saved the process id to a file: 

kill $(cat /var/run/habari.pid) &>/dev/null
Retrieved from "http://wiki.habariproject.org/en/Installation/Special_Instructions/Nginx"
Personal tools