Running Foswiki on Nginx

Foswiki 2.0 ships with several configuration files ready for use with Nginx, but they do need some tailoring.

Prerequisites

Before installing Foswiki, be sure that the Perl dependencies identified in SystemRequirements have been installed. The following packages are required for Foswiki under Nginx:

CPAN Module	Debian/Ubuntu package
FCGI	libfcgi-perl
FCGI::ProcManager	libfcgi-procmanager-perl

Configuration

These instructions are specific for Debian / Ubuntu installations. File locations and init scripts may be different on other systems.

1. Download the Latest Foswiki release and extract it into your website directory (ex. /var/www, /srv/www, or /home/www-data )
2. Copy tools/foswiki.defaults to /etc/default/foswiki, and tailor it for your installation. If your distribution does not use etc/default files, then these settings need to be manually inserted into the init script.

   FOSWIKI_ROOT=/var/www/foswiki             <=== Location of the expanded foswiki distribution
   FOSWIKI_FCGI=foswiki.fcgi
   FOSWIKI_BIND=127.0.0.1:9000               <=== Must match settings in nginx host configuration
   ... (Remaining defaults are tuning)

3. Copy tools/foswiki.init-script to /etc/init.d/foswiki and make it executable ( chmod 755 /etc/init.d/foswiki ).
4. Create a file named /etc/nginx/sites-available/foswiki.conf with the following:

   
   # set to maximum upload size ... or to zero to disable the check in nginx so that foswiki's ATTACHFILESIZELIMIT takes precedence
   client_max_body_size 0;
   
   # enable this to redirect any http to https, see "listen" in next server block below
   # server {
   #   server_name ~^(www\.)?(?<domain>.+)$;
   #   listen 80;
   #
   #   return 301 https://$host$request_uri;
   #}
   
   server {
     server_name  yourhostname.com;           # <=== Replace with your hostname
   
     # alternatively match any domain of the server
     # server_name ~^(www\.)?(?<domain>.+)$;
   
     set $foswiki_root /var/www/foswiki;      # <=== Path to expanded foswiki distribution
   
     root /var/www/html;
     index index.html;
   
     # enable for bad clients detection, see below
   #  if ($bad_client) {
   #    return 403;
   #  }  
   #  if ($bad_referer) {
   #     return 444;
   #  }
   
     # listen to http in case you don't want to redirect all http to https, see above
     listen 80;
   
     # listen for both, http and https
     # listen 443 ssl http2;
     # ssl_certificate     /etc/ssl/certs/server.crt; 
     # ssl_certificate_key /etc/ssl/private/server.key; 
   
     # enable when listening to 443 only 
     # ssl on;
   
     # Uncomment for htpasswd
     #auth_basic "FOSWiki";
     #auth_basic_user_file $foswiki_root/data/.htpasswd;
   
     # browsers tend to search for a favicons and robots.txt in the root directory: if it is there fine, if not don't bother
     location /favicon.ico {
       log_not_found off;
       access_log off;
     }
     location /robots.txt {
       allow all;
       log_not_found off;
       access_log off;
     }
   
     # first test for static files in the document root, then redirect to foswiki backend
     location / {
       try_files $uri @foswiki;
     }
   
     # redirect short urls to view
     location ~ ^/(?:bin/)?([A-Z_].*)$ {
       rewrite ^/(.*)$ /bin/view/$1 last;
     }
   
     # any /bin goes to foswiki
     location /bin {
       try_files $uri @foswiki;
     }
   
     # static files that we don't need to authenticate, i.e. css and js
     location ~ ^/pub/(System|Applications|cache)/ {
       root $foswiki_root;
       expires 8h;
       gzip_static on;
     }
   
     # any other static files need to be sanctioned by the foswiki backened
     location /pub {
       root $foswiki_root;
   
       # either by the standard viewfile approach ...
       rewrite ^/pub/(.*)$ /bin/viewfile/$1;
   
       # or by XSendFileContrib using
       #
       # {XSendFileContrib}{Header} = 'X-Accel-Redirect';
       # {XSendFileContrib}{Location} = '/files';
       #rewrite ^/pub/(.*)$ /bin/xsendfile/$1;
     }
   
     # internal location that sendfile serves sanctioned static files from
     location /files {
       internal;
       alias $foswiki_root/pub/;
       expires 8h;
       access_log off;
     }
   
     # deny any direct access to these directores
     # note that this only is required in case the document root equals the $foswiki_root
     location ~ (^/lib|^/data|^/locale|^/templates|^/tools|^/work) {
        deny all;
     }
   
     # optional location for WebDAVContrib. 
     location /dav {
        gzip off;
    
        fastcgi_pass   127.0.0.1:9001;                  # <=== Must match FOSWIKI_BIND parameters in /etc/default/foswiki-dav
   
        # connection settings to mitigate some buggy webdav clients
        keepalive_timeout 0;
        fastcgi_keep_conn off;
   
        fastcgi_split_path_info ^/dav/(.+?)(/.*)$;
        fastcgi_param  SCRIPT_FILENAME  $foswiki_root/tools/wedav.fcgi;
        fastcgi_param  PATH_INFO $fastcgi_path_info;
   
        # set a HTTP2 env variable to indicate the kind of connection to foswiki 
        fastcgi_param  HTTP2 $http2;
    
        include fastcgi_params;
     }
   
     # internal location for anything foswiki
     location @foswiki {
        gzip off;
   
        fastcgi_pass   127.0.0.1:9000;                   # <=== Must match FOSWIKI_BIND parameters in /etc/default/foswiki-da
   
        # a request taking more than 2 minutes is considered an error
        fastcgi_read_timeout 120s; 
   
        fastcgi_split_path_info ^/bin/(.+?)(/.*)$;
        fastcgi_param  SCRIPT_FILENAME  $foswiki_root/bin/foswiki.fcgi;
        fastcgi_param  PATH_INFO $fastcgi_path_info;
        # Uncomment the next 2 if using htpasswd
        #fastcgi_param  AUTH_USER  $remote_user;
        #fastcgi_param  REMOTE_USER  $remote_user;
        # set a HTTP2 env variable to indicate the kind of connection to foswiki 
        fastcgi_param  HTTP2 $http2;
   
        include fastcgi_params;
     }
   }
   

5. Link /etc/nginx/sites-available/foswiki.conf to /etc/nginx/sites-enabled/foswiki.conf
6. If you like to block bad clients and referers copy blacklist.conf to /etc/nginx/conf.d/ and enable above conditionals for $bad_client and $bad_referer
7. Start or restart nginx. (service nginx start or service nginx restart)
8. Startup the foswiki fcgi handlers (service foswiki start)
9. Navigate to your site's default URL, should be something like http://yourwiki.yourdomain.com/Main/WebHome
10. Follow the link in the banner from there to configure, and address any Warnings or errors.

Note: With Nginx and FCGI, you must set the {SaveEnvPath}. Typically /bin:/usr/bin It will be flagged with a warning until it has been configured.

If you discover that the command service foswiki stop fails to stop the foswiki fcgi processes, verify that the module FCGI::ProcManager is installed.

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

Discussion

There appears to be another page on FosWiki.org with instructions for Nginx with FastCGI: http://foswiki.org/Extensions/FastCGIEngineContrib#Nginx

The instructions there appear to be slightly different.

-- ManasB 7 Jan 2017

Why is the SCRIPT_NAME parameter set twice?

I'm having issues saving updates - it appears the arguments aren't passed properly.

Also, is fastcgi_params isn't necessarily all that standard, from what I can see.

-- DavidAustin42 1 Jan 2016

• Good question about the SCRIPT_NAME. The above example clearly needs some work.
• No idea about saving updates issues.
• fastcgi_params_ is documented here: http://nginx.org/en/docs/http/ngx_http_fastcgi_module.html#fastcgi_param

-- Main.GeorgeClark - 02 Jan 2016 - 15:58

---

Prior discussion:

---

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

Here are the scripts I use to run foswiki under nginx

• foswiki: foswiki
• foswiki.init-script: foswiki.init-script

-- MichaelDaum - 13 Mar 2014

Updated the nginx settings. Please test.

-- MichaelDaum - 12 Apr 2018

I'm doing my first nginx/foswiki install from scratch and I'm wondering how installation on nginx affects the dependency list in SystemRequirements. Specifically, I'm wondering if CGI and CGI::Session are still needed. Minor details but just curious.

-- LynnwoodBrown - 07 Jan 2020

Yes, they are still required. The choice of a webserver does not change this. Though we'd like to Development.ReduceImpactOfCGIDotPMinFoswiki. The main difference between apache and nginx is that you need to run a foswiki service manually that nginx is proxying requests to.

-- MichaelDaum - 07 Jan 2020

Another small addition to these notes. After doing setup as described above, my nginx/foswiki installation worked fine except when I reboot the server and the foswiki service was not starting. I found the following comment in FastCGIEngineContrib instructions for configuring for nginx: "Finally, add the service to the runlevels using update-rc.d foswiki defaults to make sure the service is started on system startup time." That fixed it so foswiki service would restart on reboot.

-- LynnwoodBrown - 13 Jan 2020

In regards to the section below the comment that reads "# static files that we don't need to authenticate", keep in mind that any attached file that is not in the list of webs there will not be accessible to non-authenticated users (assuming viewfile is is included in {AuthScripts} ). The result will be that user will get a 502 for that file and the browser console will show error reading "html/text type not supported".

-- LynnwoodBrown - 11 Aug 2021

Commenting is disabled while not logged in