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 * If your wiki is in `~/public_html` and does not appear when you enter the URL given by the installer, check that you have
  32   the userdir mod enabled (there should be simlinks to userdir.load and userdir.conf in /etc/apache2/modes-enabled).  If not,
  33   run `a2enmod userdir` and reload apache2.
  34
  35 * You may also want to enable the [[plugins/404]] plugin.
  36   To make apache use it, the apache config file will need a further
  37   modification to make it use ikiwiki's CGI as the apache 404 handler.
  38   Something like this, with the path adjusted to where you've put the CGI:
  39
  40         ErrorDocument 404 /cgi-bin/ikiwiki.cgi
  41
  42 ## lighttpd
  43
  44 Here is how to enable cgi on [lighttpd](http://www.lighttpd.net/) and
  45 configure it in order to execute ikiwiki.cgi wherever it is located.
  46
  47 * 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)).
  48
  49 * Create `/etc/lighttpd/conf-available/90-ikiwiki-cgi.conf` and add a line like this:
  50
  51     cgi.assign = ( "ikiwiki.cgi"  => "", )
  52
  53 * Activate ikiwiki-cgi by linking `/etc/lighttpd/conf-available/90-ikiwiki-cgi.conf` into `/etc/lighttpd/conf-enabled`.
  54
  55 * Restart lighttpd server with something like `/etc/init.d/lighttpd restart`.
  56
  57 Note that the first part enables cgi server wide but depending on default
  58 configuration, it may be not enough. The second part creates a specific
  59 rule that allow `ikiwiki.cgi` to be executed.
  60
  61 **Warning:** I only use this lighttpd configuration on my development
  62 server (offline). I am not sure of how secure this approach is.
  63 If you have any thought about it, feel free to let me know.
  64
  65 ## nginx
  66
  67 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.
  68
  69 In Linux, you will need the spawn-fcgi and fcgiwrap packages and start
  70 them with:
  71
  72     spawn-fcgi -s /tmp/fcgi.socket -n -- /usr/sbin/fcgiwrap
  73
  74 This needs to be ran as your user. It can be added to `inittab` or
  75 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.:
  76
  77     chmod a+w /tmp/fcgi.socket
  78
  79 Then you need an nginx config plugged in that wrapper. Here's an
  80 example virtual host configuration:
  81
  82     server {
  83         #listen   80; ## listen for ipv4; this line is default and implied
  84         #listen   [::]:80 default_server ipv6only=on; ## listen for ipv6
  85
  86         root /home/anarcat/public_html/wiki.reseaulibre.ca/;
  87         index index.html index.htm;
  88
  89         # Make site accessible from http://localhost/
  90         server_name wiki.reseaulibre.ca;
  91
  92         location / {
  93                 try_files $uri $uri/ /index.html;
  94         }
  95         location /ikiwiki.cgi {
  96                 fastcgi_pass  unix:/tmp/fcgi.socket;
  97                 fastcgi_index ikiwiki.cgi;
  98                 fastcgi_param SCRIPT_FILENAME   /home/anarcat/public_html/ikiwiki.cgi;
  99                 fastcgi_param  DOCUMENT_ROOT      /home/anarcat/public_html/wiki.reseaulibre.ca;
 100                 include /etc/nginx/fastcgi_params;
 101         }
 102     }
 103
 104 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|todo/fastcgi_or_modperl_installation_instructions]] would be great. ;) --[[anarcat]]
 105
 106 ## boa
 107
 108 Edit /etc/boa/boa.conf and make sure the following line is not commented:
 109
 110     AddType application/x-httpd-cgi cgi