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-userpass.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/