Installation/Special Instructions/Nginx
From Habari Project
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;
fastcgi_param REMOTE_ADDR $remote_addr;
fastcgi_param REMOTE_PORT $remote_port;
}
}
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
