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, 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.
  64
  65 In Linux, you will need the spawn-fcgi and fcgiwrap packages and start
  66 them with:
  67
  68     spawn-fcgi -s /tmp/fcgi.socket -n -- /usr/sbin/fcgiwrap
  69
  70 This needs to be ran as your user. It can be added to `inittab` or
  71 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.:
  72
  73     chmod a+w /tmp/fcgi.socket
  74
  75 Then you need an nginx config plugged in that wrapper. Here's an
  76 example virtual host configuration:
  77
  78     server {
  79         #listen   80; ## listen for ipv4; this line is default and implied
  80         #listen   [::]:80 default_server ipv6only=on; ## listen for ipv6
  81
  82         root /home/anarcat/public_html/wiki.reseaulibre.ca/;
  83         index index.html index.htm;
  84
  85         # Make site accessible from http://localhost/
  86         server_name wiki.reseaulibre.ca;
  87
  88         location / {
  89                 try_files $uri $uri/ /index.html;
  90         }
  91         location /ikiwiki.cgi {
  92                 fastcgi_pass  unix:/tmp/fcgi.socket;
  93                 fastcgi_index ikiwiki.cgi;
  94                 fastcgi_param SCRIPT_FILENAME   /home/anarcat/public_html/ikiwiki.cgi;
  95                 fastcgi_param  DOCUMENT_ROOT      /home/anarcat/public_html/wiki.reseaulibre.ca;
  96                 include /etc/nginx/fastcgi_params;
  97         }
  98     }
  99
 100 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]]
 101
 102 ## boa
 103
 104 Edit /etc/boa/boa.conf and make sure the following line is not commented:
 105
 106     AddType application/x-httpd-cgi cgi