Running Foswiki on Nginx

So after scouring the web for wiki engines, I chose Foswiki ... but my webservers are moving to nginx and fast cgi. I want to use foswiki with nginx but as people who use nginx know, it does not have any built-in capability to execute a CGI script. This is explained here along with a workaround.

Helpful IRC people (thank you!) explained to me that the configure script must be run as a regular CGI script because Foswiki::engine() has no support to run it and hence the FastCGIEngineContrib package won't work. You must be able to run configure to run a foswiki. So, with the following reference material:

• http://wiki.nginx.org/NginxSimpleCGI
• http://sys-notes.com/bin/view/Main/NginxFoswiki

I've come up with a working configuration by modifying some of the above data. Here's how you can use this configuration:

1. Make sure you have the foswiki distribution handy. I'll use the variable $fosroot in the following text, with the understanding that you will replace this with the pathname to your foswiki root directory (the one contaning "bin", "templates", etc.).
2. Download this attachment and edit the top variables to suit your site. You must provide sane values for:
   • $configure script - path to the foswiki configure script, should be something like $fosroot/bin/configure
   • $socket_path - pick a path to a dedicated unix domain socket (or ip address:port...but that usage is untested here).
   • $socket_mode, $socket_uid, $socket_gid - set these appropriate to the uid of your webserver; some operating systems check permissions so if your nginx process is uid 100 and that uid does not have permissions to read and write the socket, this will not work!
3. Pick one more socket path, we'll call it $fcgi_socket for now, this will be the main socket used to talk to foswiki
4. Add the following to your nginx.conf

   server {
      listen 80;
      server_name yourwiki.yourdomain.com;
      root $fosroot; # remember number 1 above! Nginx has no definition for $fosroot!
      location / {
          limit_except GET POST { deny all; }
      }
      location ~ /foswiki/bin/configure {
          allow 127.0.0.1;   # add allow statements only for administrative IPs!
          deny all;
          gzip off;
          fastcgi_pass   unix:$socket_path                    # $socket_path is not in nginx, see number 2 above
          fastcgi_split_path_info  ^/foswiki(/bin/configure)(.*);  # Yes, one of the above links had this wrong 
          fastcgi_param  SCRIPT_FILENAME   $configure_script  # $configure_script is not in nginx, see number 2 above
          fastcgi_param  PATH_INFO         $fastcgi_path_info;
          fastcgi_param  SCRIPT_NAME       $fastcgi_script_name;
          include fastcgi_params;
     }
     location ~ /foswiki/bin/.* {
          gzip off;
          fastcgi_pass             unix:$fgci_socket;        # $fcgi_socket comes from #3 above
          fastcgi_split_path_info  ^/foswiki(/bin/\w+)(.*);  # Yes, one of the above links had this wrong 
          fastcgi_param            SCRIPT_FILENAME $fosroot/$fastcgi_script_name;
          fastcgi_param            PATH_INFO       $fastcgi_path_info;
          fastcgi_param            SCRIPT_NAME     $fastcgi_script_name;
          include fastcgi_params;
      }
      location ~ (^/lib|^/data|^/locale|^/templates|^/tools|^/work)  { deny all; }
   }
   

5. Start or restart nginx.
6. Startup the configure.cgi daemon by doing this:

   # $fosroot/bin/configure.cgi
   

7. Startup the foswiki.cgi daemon by doing something like this. Note that you may have to change the permissions of $fcgi_socket after the foswiki.fcgi daemon starts, depending on what permissions nginx has to start as. Remember that nginx has to be able to open $fcgi_socket so set your permissions accordingly.

   # cd $fosroot/bin
   # sudo -u foswiki -g foswiki ./foswiki.fcgi -n 5 -l $fcgi_socket -d
   

8. Navigate to your site's configure URL, should be something like http://yourwiki.yourdomain.com/foswiki/bin/configure

You should now be on your way to using foswiki with nginx.

-- DaveHayes - 03 Nov 2010

It occurs to me that 127.0.0.1 is a dangerous URL for paranoid reasons. Here's my logic. Extensions load other Perl CPAN libraries that might be tricked into accessing a URL on 127.0.0.1 on the server side. It is paranoid but restricting configure to explicit, non-loopback, IPs might be more secure.

-- DaveHayes - 09 Nov 2010