small fixes on nginx documentation, refer to fastcgi stuff
[ikiwiki.git] / 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`.
72
73 Then you need an nginx config plugged in that wrapper. Here's an
74 example virtual host configuration:
75
76     server {
77         #listen   80; ## listen for ipv4; this line is default and implied
78         #listen   [::]:80 default_server ipv6only=on; ## listen for ipv6
79
80         root /home/anarcat/public_html/wiki.reseaulibre.ca/;
81         index index.html index.htm;
82
83         # Make site accessible from http://localhost/
84         server_name wiki.reseaulibre.ca;
85
86         location / {
87                 try_files $uri $uri/ /index.html;
88         }
89         location /ikiwiki.cgi {
90                 fastcgi_pass  unix:/tmp/fcgi.socket;
91                 fastcgi_index ikiwiki.cgi;
92                 fastcgi_param SCRIPT_FILENAME   /home/anarcat/public_html/ikiwiki.cgi;
93                 fastcgi_param  DOCUMENT_ROOT      /home/anarcat/public_html/wiki.reseaulibre.ca;
94                 include /etc/nginx/fastcgi_params;
95         }
96     }
97
98 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]]
99
100 ## boa
101
102 Edit /etc/boa/boa.conf and make sure the following line is not commented:
103
104     AddType application/x-httpd-cgi cgi