File: INSTALL

package info (click to toggle)
coquelicot 0.9.6-1.1
  • links: PTS, VCS
  • area: main
  • in suites: sid
  • size: 1,152 kB
  • sloc: ruby: 4,327; sh: 70; makefile: 69
file content (201 lines) | stat: -rw-r--r-- 6,340 bytes parent folder | download | duplicates (2)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
How to setup Coquelicot?
========================

Coquelicot is written in Ruby using the Sinatra web framework and
Rainbows! web server. Coquelicot is intended to be run on a fully encrypted
system and accessible only through HTTPS. In order to support HTTPS, Coquelicot
needs the help of a non-buffering HTTPS reverse proxy.

Install dependencies
--------------------

Coquelicot uses Bundler to manage its dependency. To install Bundler on
Debian, please issue:

    # apt-get install rubygems libxml2-dev libxslt-dev
    $ gem install bundler

Once Bundler is available, simply run:

    $ bundle install --deployment

AGPL compliance
---------------

If you have downloaded Coquelicot from Git, AGPL compliance can be made
by serving the local Git clone. This can be achieved with the following
commands:

    git update-server-info
    echo '#!/bin/sh' > .git/hooks/post-update
    echo 'exec git update-server-info' >> .git/hooks/post-update
    chmod +x .git/hooks/post-update

Start Coquelicot!
-----------------

To start Coquelicot use:

    $ bundle exec coquelicot start

`start` can be replaced by `stop` to shut down the server.

HTTPS reverse proxy
-------------------

Coquelicot itself is able to serve HTTPS directly, so a non-buffering HTTPS
reverse proxy needs to be setup to protect users' privacy.

### Apache

To configure [Apache] as a reverse proxy, the `proxy`, `proxy_http` and `ssl`
modules must be enabled. A minimal configuration would then look like:

    <VirtualHost *:443>
            ServerName dl.example.org
            SSLEngine on
            [… insert other SSL related directives here …]
            ProxyPass / http://127.0.0.1:51161/
            SetEnv proxy-sendchunks 1
            RequestHeader set X-Forwarded-SSL "on"
    </VirtualHost>

If you wish to have Coquelicot served from a “sub-directory”, `path` needs to
be set in `settings.yml` to the proper value. For the following example,
we use `/coquelicot`:

    <VirtualHost *:443>
            ServerName dl.example.org
            SSLEngine on
            […]
            <Location /coquelicot>
                    ProxyPass http://127.0.0.1:51161/coquelicot
                    SetEnv proxy-sendchunks 1
                    RequestHeader set X-Forwarded-SSL "on"
            </Location>
    </VirtualHost>

[Apache]: http://httpd.apache.org/

### Nginx

Here is a sample configuration fox Nginx:

    server {
            listen 443;
            server_name dl.example.org
            ssl on;
            [… insert other SSL related directives here …]
            location / {
                    proxy_set_header Host $host;
                    proxy_set_header X-Real-IP $remote_addr;
                    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
                    proxy_set_header X-Forwarded-SSL on;
                    proxy_pass http://127.0.0.1:51161;
                    proxy_buffering off;
            }
    }

[Nginx]: http://nginx.net

### Pound

Here is a sample configuration excerpt for [Pound]:

    ListenHTTPS
            Address 0.0.0.0
            Port    443
            Cert    "/etc/ssl/cert.pem"
            AddHeader "X-Forwarded-SSL: on"
            Service
                    BackEnd
                            Address 127.0.0.1
                            Port    51161
                    End
            End
    End

[Pound]: http://www.apsis.ch/pound/

### Using other Rack compatible webservers

Coquelicot has been written to use [Rainbows!] as its webserver.
It can probably be also run with other [Rack] compatible webservers
like mod_passenger, Mongrel, Thin. Please note that such configurations
have not been tested and that they are likely to **ruin privacy expectations**
because of *buffered inputs*. See [HACKING](/HACKING) for details on the later.

[Rainbows!]: http://rainbows.rubyforge.org/
[Rack]: http://rack.rubyforge.org

Configuration
-------------

By default Coquelicot is configured to authenticate with the
"simplepass" mechanism and some other reasonable defaults.

It is possible to overwrite these settings from a configuration file
named `settings.yml` that will be used if it is present in the `conf`
directory of the application.

All available settings with their default values are documented in
`conf/settings-default.yml`.

Further settings example:

 * `conf/settings-simplepass.yml`: shows how to change the default
   password for the "simplepass" mechanism.

 * `conf/settings-imap.yml`: necessary configuration for the "userpass"
   authentication mechanism.

 * `conf/settings-imap.yml`: necessary configuration for the "imap"
   authentication mechanism.

 * `conf/settings-ldap.yml`: necessary configuration for the "ldap"
   authentication mechanism.

You can copy one of these examples to `conf/settings.yml` and adjust
them according to your environment.

Using the "userpass" authentication method requires the `bcrypt` gem to
be installed manually.

Using the LDAP authentication method requires the `net-ldap` gem
to be installed manually.

A different location for the configuration file can be specified using
the `-c` option when running `bin/coquelicot`.

Garbage collection
------------------

To cleanup files automatically when they expired, coquelicot comes with
a cleanup script, that does the garbage collection for you. The easiest
way is to set up a cron job that will run every 5 minutes (or so):

    bundle exec coquelicot gc

Migrate from Jyraphe
--------------------

[Jyraphe] is another free software web file sharing application.
Coquelicot provides a migration script to import Jyraphe 0.5
repositories. It can be run using `bundle exec coquelicot migrate-jyraphe`:

    Usage: coquelicot [options] migrate-jyraphe \ 
                      [command options] JYRAPHE_VAR > REWRITE_RULES

    Options:
        -c, --config FILE            read settings from FILE

    Command options:
        -p, --rewrite-prefix PREFIX  prefix URL in rewrite rules

The last argument must be a path to the `var` directory of the Jyraphe
installation. After migrating the files to Coquelicot, directives for
Apache mod_rewrite will be printed on stdout which ought to be
redirected to a file. Using the `-p` option will prefix URL with the
given path in the rewrite rules.

[Jyraphe]: http://home.gna.org/jyraphe/