INSTALL.md 8.71 KB
Newer Older
1
2
3
Belenios compilation instructions
=================================

4
5
6
7
8
9
10
Read this document if you want to deploy your own instance of
Belenios. To get help or share your experience, please use in priority
the [public
mailing-list](https://sympa.inria.fr/sympa/info/belenios-discuss). To
give feedback on deploying an instance, you can also [mail
us](mailto:contact@belenios.org).

11
12
13
14
15
16
17
18
19
20
Using containers
----------------

If you are using Linux and have root privileges, you might be
interested in our documentation on [deploying Belenios using
systemd-nspawn](doc/nspawn/README.md).

The rest of this file documents other ways to build Belenios on
standard POSIX systems.

21
22
23
24
25
26
27
28
29
The easy way
------------

Belenios is written in OCaml and has some dependencies towards
third-party OCaml libraries. The easiest and most portable way to
compile Belenios from source is to use
[OPAM](http://opam.ocamlpro.com/), which is a package manager for
OCaml projects.

Stephane Glondu's avatar
Stephane Glondu committed
30
The non-OCaml prerequisites are:
31

32
 * a POSIX system with a C compiler and a `/usr/lib/sendmail` command
33
 * on Linux, [Bubblewrap](https://github.com/projectatomic/bubblewrap)
Stephane Glondu's avatar
Stephane Glondu committed
34
 * [GMP](http://gmplib.org/)
Stephane Glondu's avatar
Stephane Glondu committed
35
 * [libsodium](https://www.libsodium.org/)
Stephane Glondu's avatar
Stephane Glondu committed
36
37
38
39
40
 * [PCRE](http://www.pcre.org/)
 * [pkg-config](http://www.freedesktop.org/wiki/Software/pkg-config/)
 * [m4](https://www.gnu.org/software/m4/)
 * [SQLite3](https://www.sqlite.org/)
 * [OpenSSL](https://www.openssl.org/)
41
 * [Wget](https://www.gnu.org/software/wget/) or [curl](http://curl.haxx.se/)
42
 * [Zip](http://www.info-zip.org/Zip.html)
43
 * [Unzip](http://www.info-zip.org/UnZip.html)
Stephane Glondu's avatar
Stephane Glondu committed
44
 * [ncurses](http://invisible-island.net/ncurses/)
45
 * [GD-SecurityImage](https://metacpan.org/release/GD-SecurityImage)
Stephane Glondu's avatar
Stephane Glondu committed
46
 * [cracklib](https://github.com/cracklib/cracklib)
Stephane Glondu's avatar
Stephane Glondu committed
47
 * [jq](https://github.com/stedolan/jq)
Swergas's avatar
Swergas committed
48
 * [npm](https://www.npmjs.com/)
Stephane Glondu's avatar
Stephane Glondu committed
49
50
51
52
53

These libraries and tools are pretty common, and might be directly part
of your operating system. On [Debian](http://www.debian.org/) and its
derivatives, they can be installed with the following command:

Stephane Glondu's avatar
Stephane Glondu committed
54
    sudo apt install bubblewrap build-essential libgmp-dev libsodium-dev libpcre3-dev pkg-config m4 libssl-dev libsqlite3-dev wget ca-certificates zip unzip libncurses-dev zlib1g-dev libgd-securityimage-perl cracklib-runtime jq npm
Stephane Glondu's avatar
Stephane Glondu committed
55
56
57
58
59

If you are unfamiliar with OCaml or OPAM, we provide an
`opam-bootstrap.sh` shell script that creates a whole, hopefully
self-contained, OCaml+OPAM install, and then installs all the
dependencies of Belenios, everything into a single directory. You can
Stephane Glondu's avatar
Stephane Glondu committed
60
choose the directory by setting the `BELENIOS_SYSROOT` environment
Stephane Glondu's avatar
Stephane Glondu committed
61
variable, or it will take `~/.belenios` by default. Just run:
62

63
    ./opam-bootstrap.sh
64

65
On a modern desktop system, this needs approximately 30 minutes and 3.3
Stephane Glondu's avatar
Stephane Glondu committed
66
gigabytes of disk space.
67
68
69
70

If everything goes successfully, follow the given instructions to
update your shell environment, then run:

71
    make build-release-server
72

73
74
and you can skip the next two sections and go directly to the
_Documentation_ section.
75

76
You can also compile a debug version by using:
77

78
    make build-debug-server
79
80
81
82

Note that this version may introduce vulnerabilities and should not be
used in production!

83
84
85
86
To make sure everything went well, you can run tests:

    make check

Stephane Glondu's avatar
Stephane Glondu committed
87
88
89
90
If you are familiar with OCaml, please read the `opam-bootstrap.sh`
shell script, or the following two sections to compile Belenios with
your existing OCaml installation.

91
92
93
94
95
Command-line tool
-----------------

To compile the command-line tool, you will need:

Stephane Glondu's avatar
Stephane Glondu committed
96
 * [OCaml](https://ocaml.org/)
97
 * [Dune](https://dune.build/)
Stephane Glondu's avatar
Stephane Glondu committed
98
99
100
101
 * [Zarith](https://github.com/ocaml/Zarith)
 * [Cryptokit](https://github.com/xavierleroy/cryptokit)
 * [Atdgen](https://github.com/ahrefs/atd)
 * [Yojson](https://github.com/ocaml-community/yojson)
102
 * [Cmdliner](http://erratique.ch/software/cmdliner)
103

104
105
With OPAM, these dependencies can be installed with the following
command:
106

107
    opam install dune atdgen zarith cryptokit cmdliner
108
109
110
111
112
113

Once all the dependencies have been installed, the command-line tool
can be compiled with:

    make

114
115
116
117
It produces a single executable, `belenios-tool`, in the
`_build/install/default/bin` directory. You can install it in your
`PATH` (which we will assume in the guides), or refer to it with a
full path.
118
119
120
121

Web server
----------

122
The web server has the following additional dependencies:
123

124
 * [Calendar](http://calendar.forge.ocamlcore.org/)
Stephane Glondu's avatar
Stephane Glondu committed
125
 * [Eliom](http://ocsigen.org/eliom/)
Stephane Glondu's avatar
Stephane Glondu committed
126
 * [Csv](https://github.com/Chris00/ocaml-csv)
127

128
129
With OPAM, you can install them with:

130
    opam install calendar eliom csv
131
132
133
134

Once all the dependencies have been installed, the Eliom module can be
compiled with:

135
    make build-release-server
136

137
138
139
140
It will produce a full installation of Belenios, its libraries and its
server, in the `_run/usr` directory. See `demo/ocsigenserver.conf.in`
for an ocsigenserver configuration template, and the _Server
administrator's guide_ for more information on how to use it.
141
142
143
144

Documentation
-------------

145
You will need LaTeX to compile the specification.
146
147
148
149

On Debian-based systems, you can install the dependencies needed to
compile the documentation with:

150
    sudo apt install texlive-latex-extra texlive-fonts-recommended texlive-fonts-extra lmodern texlive-science
151
152
153
154
155

Once all the dependencies have been installed, the documentation can
be compiled with:

    make doc
156

157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
Compiling on Windows using Cygwin
---------------------------------

Windows is not yet a fully supported platform, but you can compile at
least the command-line tool on Windows + 32-bit
[Cygwin](http://cygwin.com/index.html). You might need the following
packages:

 * curl
 * dos2unix
 * flexdll
 * gcc-core
 * gcc-g++
 * git
 * gmp
 * libgmp-devel
Stephane Glondu's avatar
Stephane Glondu committed
173
 * libsodium-devel
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
 * libncursesw-devel
 * libpcre-devel
 * libsqlite3-devel
 * m4
 * make
 * ocaml
 * ocaml-base
 * ocaml-camlp4
 * ocaml-compiler-libs
 * openssh
 * patch
 * pkg-config
 * zlib-devel

With these packages installed, you should be able to install OPAM by
following its [installation instructions from
190
sources](http://opam.ocaml.org/doc/Install.html#FromSources).
191
192
193
Once OPAM is installed, follow the instructions in the _Command-line
tool_ section above.

194
195
196
Troubleshooting
---------------

197
198
199
200
201
202
203
204
205
### Bootstrap fails if dune is already installed

The script `opam-bootstrap.sh` fails when a not suitable version of
dune is already installed in your `$PATH`. This is due to [a bug in
opam](https://github.com/ocaml/opam/issues/3987). If you face this
issue, either uninstall dune before running `opam-bootstrap.sh`, or
manage to get opam running by other means, and directly use it to
install the dependencies of Belenios.

206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
### Bootstrap fails because of an error with an OPAM package

For reproducibility purposes, the `opam-bootstrap.sh` script hardcodes
a specific revision of the OPAM repository. However, it may happen
that this revision becomes unusable, e.g. the URL of some tarball
changes. This may give errors like bad checksums when running the
script.

To recover from such errors, update your local copy of the OPAM
repository with the following commands:

    source env.sh
    cd $OPAMROOT/../opam-repository
    git pull --ff-only
    opam update

then run the `opam install` command that can be found in the
`opam-bootstrap.sh` script.

225
226
227
228
229
230
231
232
233
234
### Missing sources

The instructions outlined in this document and in the
`opam-bootstrap.sh` script imply downloading files from third-party
servers. Sometimes, these servers can be down. For example, you can
get:

    =-=-= Installing ocamlnet.3.7.3 =-=-=
    ocamlnet.3.7.3 Downloading http://download.camlcity.org/download/ocamlnet-3.7.3.tar.gz
    [ERROR] http://download.camlcity.org/download/ocamlnet-3.7.3.tar.gz is not available
235
    
236
237
238
239
240
241
242
243
244
245
246
247
248
249
    ===== ERROR while installing ocamlnet.3.7.3 =====
    Could not get the source for ocamlnet.3.7.3.

This can be worked around with the following steps:

 * source the generated `env.sh` file (you must adapt it if you use an
   incompatible shell such as tcsh);
 * download the file from an alternate source (for example
   [Debian source packages](http://www.debian.org/distrib/packages));
 * run `opam pin <package-name> <path-to-file-download-above>` (in the
   example above, `<package-name>` would be `ocamlnet`);
 * resume the installation by running again the `opam install` command
   found in `opam-bootstrap.sh`;
 * follow the instructions given at the end of `opam-bootstrap.sh`.
Stephane Glondu's avatar
Stephane Glondu committed
250

Stephane Glondu's avatar
Stephane Glondu committed
251
252
253
254
255
256
257
258
### Errors while compiling ocsigenserver

If ocsigenserver fails to install because of a SSL-related error:

 * edit `opam-bootstrap.sh` by adding ` ssl=0.5.2` to the `opam
   install` call;
 * run `./opam-bootstrap.sh`.

Stephane Glondu's avatar
Stephane Glondu committed
259
260
261
262
263
264
### Errors while compiling Belenios itself

If you succeeded installing all dependencies, but you get errors while
compiling Belenios, maybe you installed an incompatible version of a
dependency. The `opam-bootstrap.sh` script is tuned to install only
compatible versions; you can have a look at it to get these versions.