Installation using 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  example.com;        # YOUR DOMAIN NAME (subdomains [blog.example.com] will also work here)

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

    # curiosity killed the cat
    location ~ ^/system/(classes|locale|schema) {
        deny all;
    }

    index  index.php index.html index.htm;

    # try to serve static first, then index pages and finally index.php
    try_files $uri $uri/ /index.php?$args;

    # ... but do not expose PHP source code!
    location \.php$ {
        deny all;
    }

    # static files do not change that much.
    expires  30d;
 
    location = /index.php {
        # PHP files are volatile!
        expires off;

        fastcgi_pass   localhost:53217;  # PORT NUMBER WHERE YOU SPAWNED YOUR FCGI PROCESSES

        # include common params as shipped with nginx
        include fastcgi_params;
        fastcgi_param  SCRIPT_NAME     $fastcgi_script_name;
        fastcgi_param  SCRIPT_FILENAME $document_root$fastcgi_script_name;
    }
}

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

SSL

Since nginx 1.1.10 and with a sufficiently recent/complete fastcgi configuration, it is sufficient to add certificate and listen directives to the http configuration. If you are using older nginx, you need to add additional directives as shown below:

# the following must be removed for nginx 1.1.11 and newer as the $https variable is already set
map $scheme $https {
    https on;
}

server {
    listen  80;
    listen  443 ssl;

    # other directives like server_name, try_files, expires, location, ...
 
    location = /index.php {
        # other directives like expires, fastcgi_pass, include, fastcgi_param, ...

        # the include fastcgi_params file should provide this already:
        fastcgi_param  HTTPS           $https if_not_empty;
    }
}

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
Personal tools
This is a cached copy of the requested page, and may not be up to date.

Sorry! This site is experiencing technical difficulties.
Try waiting a few minutes and reloading.

(Cannot contact the database server: Access denied for user 'habari'@'localhost' to database 'habari_wiki' (localhost))


You can try searching via Google in the meantime.
Note that their indexes of our content may be out of date.