Running Foswiki on Nginx

  • Tip Category - Installation and Upgrading
  • Tip Added By - DaveHayes - 03 Nov 2010 - 21:12
  • Extensions Used - FastCGIEngineContrib
  • Useful To - Beginners
  • Tip Status - New
  • Related Topics -
Updated for Foswiki 2.0, along with short URLs. See FoswikiOnNginx rev 11 for the old version of this document supporting Foswiki 1.x support.

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 alert Warnings or ALERT! errors.

Note: With Nginx and FCGI, you must set the {SaveEnvPath}. Typically /bin:/usr/bin It will be flagged with a alert 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

-- 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

-- 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
 

BestPracticeTipsForm edit

Category Installation and Upgrading
Related Topics
I Attachment Action Size Date Who Comment
blacklist.confconf blacklist.conf manage 135 K 12 Apr 2018 - 07:08 MichaelDaum $bad_clients and $bad_referer config for nginx
foswikiEXT foswiki manage 2 K 13 Mar 2014 - 09:03 MichaelDaum  
foswiki-dav.init-scriptinit-script foswiki-dav.init-script manage 2 K 29 Apr 2014 - 15:22 MichaelDaum  
foswiki-nginx.confconf foswiki-nginx.conf manage 2 K 13 Mar 2014 - 11:15 LauHub An example of NGINX configuration file for Debian Wheezy (credits: MichaelDaum)
foswiki.init-scriptinit-script foswiki.init-script manage 2 K 15 Jan 2015 - 16:36 MichaelDaum  
Topic revision: r24 - 11 Aug 2021, LynnwoodBrown
The copyright of the content on this website is held by the contributing authors, except where stated elsewhere. See Copyright Statement. Creative Commons License    Legal Imprint    Privacy Policy