Update authors in README
[coquelicot.git] / INSTALL
1 How to setup Coquelicot?
2 ========================
3
4 Coquelicot is written in Ruby using the Sinatra web framework and
5 Rainbows! web server. Coquelicot is intended to be run on a fully encrypted
6 system and accessible only through HTTPS. In order to support HTTPS, Coquelicot
7 needs the help of a non-buffering HTTPS reverse proxy.
8
9 Install dependencies
10 --------------------
11
12 Coquelicot uses Bundler to manage its dependency. To install Bundler on
13 Debian, please issue:
14
15     # apt-get install rubygems libxml2-dev libxslt-dev
16     $ gem install bundler
17
18 Once Bundler is available, simply run:
19
20     $ bundle install --deployment
21
22 AGPL compliance
23 ---------------
24
25 If you have downloaded Coquelicot from Git, AGPL compliance can be made
26 by serving the local Git clone. This can be achieved with the following
27 commands:
28
29     git update-server-info
30     echo '#!/bin/sh' > .git/hooks/post-update
31     echo 'exec git update-server-info' >> .git/hooks/post-update
32     chmod +x .git/hooks/post-update
33
34 Start Coquelicot!
35 -----------------
36
37 To start Coquelicot use:
38
39     $ bundle exec coquelicot start
40
41 `start` can be replaced by `stop` to shut down the server.
42
43 HTTPS reverse proxy
44 -------------------
45
46 Coquelicot itself is able to serve HTTPS directly, so a non-buffering HTTPS
47 reverse proxy needs to be setup to protect users' privacy.
48
49 ### Apache
50
51 To configure [Apache] as a reverse proxy, the `proxy`, `proxy_http` and `ssl`
52 modules must be enabled. A minimal configuration would then look like:
53
54     <VirtualHost *:443>
55             ServerName dl.example.org
56             SSLEngine on
57             [… insert other SSL related directives here …]
58             ProxyPass / http://127.0.0.1:51161/
59             SetEnv proxy-sendchunks 1
60             RequestHeader set X-Forwarded-SSL "on"
61     </VirtualHost>
62
63 If you wish to have Coquelicot served from a “sub-directory”, `path` needs to
64 be set in `settings.yml` to the proper value. For the following example,
65 we use `/coquelicot`:
66
67     <VirtualHost *:443>
68             ServerName dl.example.org
69             SSLEngine on
70             […]
71             <Location /coquelicot>
72                     ProxyPass http://127.0.0.1:51161/coquelicot
73                     SetEnv proxy-sendchunks 1
74                     RequestHeader set X-Forwarded-SSL "on"
75             </Location>
76     </VirtualHost>
77
78 [Apache]: http://httpd.apache.org/
79
80 ### Nginx
81
82 Here is a sample configuration fox Nginx:
83
84     server {
85             listen 443;
86             server_name dl.example.org
87             ssl on;
88             [… insert other SSL related directives here …]
89             location / {
90                     proxy_set_header Host $host;
91                     proxy_set_header X-Real-IP $remote_addr;
92                     proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
93                     proxy_set_header X-Forwarded-SSL on;
94                     proxy_pass http://127.0.0.1:51161;
95                     proxy_buffering off;
96             }
97     }
98
99 [Nginx]: http://nginx.net
100
101 ### Pound
102
103 Here is a sample configuration excerpt for [Pound]:
104
105     ListenHTTPS
106             Address 0.0.0.0
107             Port    443
108             Cert    "/etc/ssl/cert.pem"
109             AddHeader "X-Forwarded-SSL: on"
110             Service
111                     BackEnd
112                             Address 127.0.0.1
113                             Port    51161
114                     End
115             End
116     End
117
118 [Pound]: http://www.apsis.ch/pound/
119
120 ### Using other Rack compatible webservers
121
122 Coquelicot has been written to use [Rainbows!] as its webserver.
123 It can probably be also run with other [Rack] compatible webservers
124 like mod_passenger, Mongrel, Thin. Please note that such configurations
125 have not been tested and that they are likely to **ruin privacy expectations**
126 because of *buffered inputs*. See [HACKING](/HACKING) for details on the later.
127
128 [Rainbows!]: http://rainbows.rubyforge.org/
129 [Rack]: http://rack.rubyforge.org
130
131 Configuration
132 -------------
133
134 By default Coquelicot is configured to authenticate with the
135 "simplepass" mechanism and some other reasonable defaults.
136
137 It is possible to overwrite these settings from a configuration file
138 named `settings.yml` that will be used if it is present in the `conf`
139 directory of the application.
140
141 All available settings with their default values are documented in
142 `conf/settings-default.yml`.
143
144 Further settings example:
145
146  * `conf/settings-simplepass.yml`: shows how to change the default
147    password for the "simplepass" mechanism.
148
149  * `conf/settings-imap.yml`: necessary configuration for the "userpass"
150    authentication mechanism.
151
152  * `conf/settings-imap.yml`: necessary configuration for the "imap"
153    authentication mechanism.
154
155  * `conf/settings-ldap.yml`: necessary configuration for the "ldap"
156    authentication mechanism.
157
158 You can copy one of these examples to `conf/settings.yml` and adjust
159 them according to your environment.
160
161 Using the "userpass" authentication method requires the `bcrypt` gem to
162 be installed manually.
163
164 Using the LDAP authentication method requires the `net-ldap` gem
165 to be installed manually.
166
167 A different location for the configuration file can be specified using
168 the `-c` option when running `bin/coquelicot`.
169
170 Garbage collection
171 ------------------
172
173 To cleanup files automatically when they expired, coquelicot comes with
174 a cleanup script, that does the garbage collection for you. The easiest
175 way is to set up a cron job that will run every 5 minutes (or so):
176
177     bundle exec coquelicot gc
178
179 Migrate from Jyraphe
180 --------------------
181
182 [Jyraphe] is another free software web file sharing application.
183 Coquelicot provides a migration script to import Jyraphe 0.5
184 repositories. It can be run using `bundle exec coquelicot migrate-jyraphe`:
185
186     Usage: coquelicot [options] migrate-jyraphe \ 
187                       [command options] JYRAPHE_VAR > REWRITE_RULES
188
189     Options:
190         -c, --config FILE            read settings from FILE
191
192     Command options:
193         -p, --rewrite-prefix PREFIX  prefix URL in rewrite rules
194
195 The last argument must be a path to the `var` directory of the Jyraphe
196 installation. After migrating the files to Coquelicot, directives for
197 Apache mod_rewrite will be printed on stdout which ought to be
198 redirected to a file. Using the `-p` option will prefix URL with the
199 given path in the rewrite rules.
200
201 [Jyraphe]: http://home.gna.org/jyraphe/