doc/tips/dot_cgi.mdwn

   1 It's common to name the [[cgi]] "ikiwiki.cgi", and put it somewhere
   2 like `~/public_html/ikiwiki.cgi`, or `/var/www/wiki/ikiwiki.cgi`.
   3
   4 If you do that, you may find that when trying to edit a page in your wiki,
   5 you see the raw contents of the ikiwiki.cgi program. Or get a permission
   6 denied problem.
   7
   8 This is because web servers are generally not configured to run cgi scripts
   9 unless they're in `/usr/lib/cgi-bin/`. While you can put ikiwiki.cgi in
  10 there if you like, it's better to configure your web server to
  11 run `.cgi`  programs from anywhere.
  12
  13 These instructions are for Debian systems, but the basic
  14 configuration changes should work anywhere.
  15
  16 ## apache 2
  17
  18 * Edit /etc/apache2/apache2.conf and add a line like this:
  19
  20         AddHandler cgi-script .cgi
  21
  22 * Find the "Options" line for the directory where you've put the
  23   ikiwiki.cgi, and add "ExecCGI" to the list of options. For example, if
  24   ikiwiki.cgi is in /var/www/, edit `/etc/apache2/sites-enabled/000-default`
  25   and add it to the "Options" line in the "Directory /var/www/" stanza.
  26   Or, if you've put it in a `~/public_html`, edit
  27   `/etc/apache2/mods-available/userdir.conf`.
  28
  29   You may also want to install some dependencies to enable CGI in apache2 setup as: `libcgi-formbuilder-perl` and `libcgi-session-perl`.
  30
  31 * You may also want to enable the [[plugins/404]] plugin.
  32   To make apache use it, the apache config file will need a further
  33   modification to make it use ikiwiki's CGI as the apache 404 handler.
  34   Something like this, with the path adjusted to where you've put the CGI:
  35
  36         ErrorDocument 404 /cgi-bin/ikiwiki.cgi
  37
  38 ## lighttpd
  39
  40 Here is how to enable cgi on [lighttpd](http://www.lighttpd.net/) and
  41 configure it in order to execute ikiwiki.cgi wherever it is located.
  42
  43 * Activate cgi by linking `/etc/lighttpd/conf-available/10-cgi.conf` into `/etc/lighttpd/conf-enabled` ([doc](http://trac.lighttpd.net/trac/wiki/Docs%3AModCGI)).
  44
  45 * Create `/etc/lighttpd/conf-available/90-ikiwiki-cgi.conf` and add a line like this:
  46
  47     cgi.assign = ( "ikiwiki.cgi"  => "", )
  48
  49 * Activate ikiwiki-cgi by linking `/etc/lighttpd/conf-available/90-ikiwiki-cgi.conf` into `/etc/lighttpd/conf-enabled`.
  50
  51 * Restart lighttpd server with something like `/etc/init.d/lighttpd restart`.
  52
  53 Note that the first part enables cgi server wide but depending on default
  54 configuration, it may be not enough. The second part creates a specific
  55 rule that allow `ikiwiki.cgi` to be executed.
  56
  57 **Warning:** I only use this lighttpd configuration on my development
  58 server (offline). I am not sure of how secure this approach is.
  59 If you have any thought about it, feel free to let me know.
  60
  61 ## nginx
  62
  63 * To run CGI under nginx, just use a FastCGI wrapper like [this one](http://technotes.1000lines.net/?p=23). The wrapper must be started somehow just like any other FastCGI program. I use launchd on OSX.
  64
  65 ## boa
  66
  67 Edit /etc/boa/boa.conf and make sure the following line is not commented:
  68
  69     AddType application/x-httpd-cgi cgi