It's common to name the cgi "ikiwiki.cgi", and put it somewhere like ~/public_html/ikiwiki.cgi, or /var/www/wiki/ikiwiki.cgi.

If you do that, you may find that when trying to edit a page in your wiki, you see the raw contents of the ikiwiki.cgi program. Or get a permission denied problem.

This is because web servers are generally not configured to run cgi scripts unless they're in /usr/lib/cgi-bin/. While you can put ikiwiki.cgi in there if you like, it's better to configure your web server to run .cgi programs from anywhere.

These instructions are for Debian systems, but the basic configuration changes should work anywhere.

  1. apache 2
  2. lighttpd
  3. nginx
  4. boa
  5. Caddy

apache 2

  • Make sure the cgi module is loaded. (Ie, a2enmod cgi). Note that the cgid module will not work.

  • Edit /etc/apache2/apache2.conf (or /etc/apache2/mods-available/mime.conf) and add a line like this:

    AddHandler cgi-script .cgi

  • Find the "Options" line for the directory where you've put the ikiwiki.cgi, and add "ExecCGI" to the list of options. For example, if ikiwiki.cgi is in /var/www/, edit /etc/apache2/sites-enabled/000-default and add it to the "Options" line in the "Directory /var/www/" stanza. Or, if you've put it in a ~/public_html, edit /etc/apache2/mods-available/userdir.conf.

  • If your wiki is in ~/public_html and does not appear when you enter the URL given by the installer, check that you have the userdir mod enabled (there should be simlinks to userdir.load and userdir.conf in /etc/apache2/modes-enabled). If not, run a2enmod userdir and reload apache2.

  • You may also want to enable the 404 plugin. To make apache use it, the apache config file will need a further modification to make it use ikiwiki's CGI as the apache 404 handler. Something like this, with the path adjusted to where you've put the CGI:

    ErrorDocument 404 /cgi-bin/ikiwiki.cgi

  • On Fedora (and RHEL, CentOS, and derivatives) you may need to change CGI mode from 06755 to 755 as suid/sgid bit is prohibited by suexec. (Bug 1341568)

lighttpd

Here is how to enable cgi on lighttpd and configure it in order to execute ikiwiki.cgi wherever it is located.

  • Activate cgi by linking /etc/lighttpd/conf-available/10-cgi.conf into /etc/lighttpd/conf-enabled (doc).

  • Create /etc/lighttpd/conf-available/90-ikiwiki-cgi.conf and add a line like this:

    cgi.assign = ( "ikiwiki.cgi" => "", )

  • Activate ikiwiki-cgi by linking /etc/lighttpd/conf-available/90-ikiwiki-cgi.conf into /etc/lighttpd/conf-enabled.

  • Restart lighttpd server with something like /etc/init.d/lighttpd restart.

Note that the first part enables cgi server wide but depending on default configuration, it may be not enough. The second part creates a specific rule that allow ikiwiki.cgi to be executed.

Warning: I only use this lighttpd configuration on my development server (offline). I am not sure of how secure this approach is. If you have any thought about it, feel free to let me know.

nginx

To run CGI under nginx, you need to use a FastCGI wrapper. The wrapper must be started somehow just like any other FastCGI program. You can use launchd on OSX.

In Linux, you will need the spawn-fcgi and fcgiwrap packages and start them with:

spawn-fcgi -s /tmp/fcgi.socket -n -- /usr/sbin/fcgiwrap

This needs to be ran as your user. It can be added to inittab or made into a startup script in init.d. You may also need to make this file writable by the webserver, if that's running as a different user, e.g.:

chmod a+w /tmp/fcgi.socket

If you have systemd, you may use a service file like so:

Edit/create a service file (in Debian it would be: sudo vim /lib/systemd/system/ikiwiki.service

Content of ikiwiki.service:

[Unit]
Description=Ikiwiki fcgi socket wrap
After=network.target

[Service]
Type=simple
User=www-data
Group=www-data
ExecStart=/usr/bin/spawn-fcgi -s /tmp/fcgi.socket -n -- /usr/sbin/fcgiwrap

[Install]
WantedBy=multi-user.target

Then run:

# This enables the service at startup
sudo systemctl enable ikiwiki.service
# This attempts to start the service
sudo systemctl start ikiwiki.service

Then you need an nginx config plugged in that wrapper. Here's an example virtual host configuration:

server {
    #listen   80; ## listen for ipv4; this line is default and implied
    #listen   [::]:80 default_server ipv6only=on; ## listen for ipv6

    root /home/anarcat/public_html/wiki.reseaulibre.ca/;
    index index.html index.htm;

    # Make site accessible from http://localhost/
    server_name wiki.reseaulibre.ca;

    location / {
            try_files $uri $uri/ /index.html;
    }
    location /ikiwiki.cgi {
            fastcgi_pass  unix:/tmp/fcgi.socket;
            fastcgi_index ikiwiki.cgi;
            fastcgi_param SCRIPT_FILENAME   /home/anarcat/public_html/ikiwiki.cgi;
            fastcgi_param  DOCUMENT_ROOT      /home/anarcat/public_html/wiki.reseaulibre.ca;
            include /etc/nginx/fastcgi_params;
    }
}

Also, note that the /tmp/fcgi.socket file needs to be writable by the webserver. I am also unsure as to the security of this setup, as I am using this only on my dev server. Needless to say that real fastcgi support would be great. ;) --anarcat

2016-09-23 alexjj: On Debian Jessie creating the fcgi ikiwiki.service is not necessary. Install fcgiwrap, it'll auto start the fcgiwrap systemd service and then add the parameters in the virtual host:

    location / {
            try_files $uri $uri/ =404;
    }

    # Max size of file upload
    client_max_body_size 10m;

    location ~ .cgi {
            #gzip off is recommended in /usr/share/doc/fcgiwrap/README.Debian
            gzip off;
            fastcgi_pass unix:/var/run/fcgiwrap.socket;
            include /etc/nginx/fastcgi_params;
    }

Here's a complete site.conf for nginx if that helps.

boa

Edit /etc/boa/boa.conf and make sure the following line is not commented:

AddType application/x-httpd-cgi cgi

Caddy

add a block to Caddyfile like this

www.myexample.net {
    root * /home/ikiwiki/public_html/myexample
    file_server

    reverse_proxy /ikiwiki.cgi unix//var/run/fcgiwrap.socket {
            transport fastcgi {
                    root /home/ikiwiki/public_html/myexample
                    env SCRIPT_FILENAME /home/ikiwiki/public_html/myexample/ikiwiki.cgi
            }
    }

    encode zstd gzip
}