annotate doc/installation.rst @ 1367:ce5cfe004d4e

server: new `--bridge-retries` option: If bridge connection fails, it will be retried for the specified number of time (default to 10) before giving up. Each try is spaced by 1 second.
author Goffi <goffi@goffi.org>
date Fri, 20 Nov 2020 18:02:43 +0100
parents d1032f9ece5b
children aada5471d6bc
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
1209
13447f785ba1 doc: added installation instructions
Goffi <goffi@goffi.org>
parents:
diff changeset
1 ============
13447f785ba1 doc: added installation instructions
Goffi <goffi@goffi.org>
parents:
diff changeset
2 Installation
13447f785ba1 doc: added installation instructions
Goffi <goffi@goffi.org>
parents:
diff changeset
3 ============
13447f785ba1 doc: added installation instructions
Goffi <goffi@goffi.org>
parents:
diff changeset
4
13447f785ba1 doc: added installation instructions
Goffi <goffi@goffi.org>
parents:
diff changeset
5 This are the instructions to install Libervia (SàT) using Python.
13447f785ba1 doc: added installation instructions
Goffi <goffi@goffi.org>
parents:
diff changeset
6 Note that if you are using GNU/Linux, Libervia may already be present on your distribution.
13447f785ba1 doc: added installation instructions
Goffi <goffi@goffi.org>
parents:
diff changeset
7
13447f785ba1 doc: added installation instructions
Goffi <goffi@goffi.org>
parents:
diff changeset
8 Libervia is a Salut à Toi frontend, the SàT backend must be installed first (if you
13447f785ba1 doc: added installation instructions
Goffi <goffi@goffi.org>
parents:
diff changeset
9 haven't installed it yet, it will be downloaded automatically as it is a dependency of
13447f785ba1 doc: added installation instructions
Goffi <goffi@goffi.org>
parents:
diff changeset
10 Libervia). Libervia and SàT backend must always have the same version (Libervia won't
13447f785ba1 doc: added installation instructions
Goffi <goffi@goffi.org>
parents:
diff changeset
11 start if the version backend has not the same version).
13447f785ba1 doc: added installation instructions
Goffi <goffi@goffi.org>
parents:
diff changeset
12
13447f785ba1 doc: added installation instructions
Goffi <goffi@goffi.org>
parents:
diff changeset
13 We recommend to use development version for now, until the release of
1353
d1032f9ece5b doc: updated installation instructions
Goffi <goffi@goffi.org>
parents: 1209
diff changeset
14 0.8 version.
1209
13447f785ba1 doc: added installation instructions
Goffi <goffi@goffi.org>
parents:
diff changeset
15
13447f785ba1 doc: added installation instructions
Goffi <goffi@goffi.org>
parents:
diff changeset
16 Development Version
13447f785ba1 doc: added installation instructions
Goffi <goffi@goffi.org>
parents:
diff changeset
17 -------------------
13447f785ba1 doc: added installation instructions
Goffi <goffi@goffi.org>
parents:
diff changeset
18
13447f785ba1 doc: added installation instructions
Goffi <goffi@goffi.org>
parents:
diff changeset
19 *Note for Arch users: a pkgbuild is available for your distribution on
13447f785ba1 doc: added installation instructions
Goffi <goffi@goffi.org>
parents:
diff changeset
20 AUR, check sat-libervia-hg (as well as other sat-\* packages).*
13447f785ba1 doc: added installation instructions
Goffi <goffi@goffi.org>
parents:
diff changeset
21
13447f785ba1 doc: added installation instructions
Goffi <goffi@goffi.org>
parents:
diff changeset
22 You can install the latest development version using pip. Please check backend documentation
13447f785ba1 doc: added installation instructions
Goffi <goffi@goffi.org>
parents:
diff changeset
23 to see the system dependencies needed.
13447f785ba1 doc: added installation instructions
Goffi <goffi@goffi.org>
parents:
diff changeset
24
13447f785ba1 doc: added installation instructions
Goffi <goffi@goffi.org>
parents:
diff changeset
25 You can use the same virtual environment as the one used for installing the backend. If
13447f785ba1 doc: added installation instructions
Goffi <goffi@goffi.org>
parents:
diff changeset
26 you haven't installed it yet, just select a location when you want to install it, for
13447f785ba1 doc: added installation instructions
Goffi <goffi@goffi.org>
parents:
diff changeset
27 instance your home directory::
13447f785ba1 doc: added installation instructions
Goffi <goffi@goffi.org>
parents:
diff changeset
28
13447f785ba1 doc: added installation instructions
Goffi <goffi@goffi.org>
parents:
diff changeset
29 $ cd
13447f785ba1 doc: added installation instructions
Goffi <goffi@goffi.org>
parents:
diff changeset
30
1353
d1032f9ece5b doc: updated installation instructions
Goffi <goffi@goffi.org>
parents: 1209
diff changeset
31 And enter the following commands (note that *virtualenv3* may be named
d1032f9ece5b doc: updated installation instructions
Goffi <goffi@goffi.org>
parents: 1209
diff changeset
32 *virtualenv* on some distributions, just be sure it's Python **3** version)::
1209
13447f785ba1 doc: added installation instructions
Goffi <goffi@goffi.org>
parents:
diff changeset
33
1353
d1032f9ece5b doc: updated installation instructions
Goffi <goffi@goffi.org>
parents: 1209
diff changeset
34 $ python3 -m venv sat
d1032f9ece5b doc: updated installation instructions
Goffi <goffi@goffi.org>
parents: 1209
diff changeset
35 $ source sat/bin/activate
d1032f9ece5b doc: updated installation instructions
Goffi <goffi@goffi.org>
parents: 1209
diff changeset
36 $ pip install wheel
1209
13447f785ba1 doc: added installation instructions
Goffi <goffi@goffi.org>
parents:
diff changeset
37 $ pip install hg+https://repos.goffi.org/libervia
13447f785ba1 doc: added installation instructions
Goffi <goffi@goffi.org>
parents:
diff changeset
38
13447f785ba1 doc: added installation instructions
Goffi <goffi@goffi.org>
parents:
diff changeset
39 If you haven't done it for the backend, you need to install the media::
13447f785ba1 doc: added installation instructions
Goffi <goffi@goffi.org>
parents:
diff changeset
40
13447f785ba1 doc: added installation instructions
Goffi <goffi@goffi.org>
parents:
diff changeset
41 $ cd
13447f785ba1 doc: added installation instructions
Goffi <goffi@goffi.org>
parents:
diff changeset
42 $ hg clone https://repos.goffi.org/sat_media
13447f785ba1 doc: added installation instructions
Goffi <goffi@goffi.org>
parents:
diff changeset
43
1353
d1032f9ece5b doc: updated installation instructions
Goffi <goffi@goffi.org>
parents: 1209
diff changeset
44 then, create the directory ``~/.config/sat``::
d1032f9ece5b doc: updated installation instructions
Goffi <goffi@goffi.org>
parents: 1209
diff changeset
45
d1032f9ece5b doc: updated installation instructions
Goffi <goffi@goffi.org>
parents: 1209
diff changeset
46 $ mkdir -p ~/.config/sat
d1032f9ece5b doc: updated installation instructions
Goffi <goffi@goffi.org>
parents: 1209
diff changeset
47
d1032f9ece5b doc: updated installation instructions
Goffi <goffi@goffi.org>
parents: 1209
diff changeset
48 and the file ``~/.config/sat/sat.conf`` containing:
d1032f9ece5b doc: updated installation instructions
Goffi <goffi@goffi.org>
parents: 1209
diff changeset
49
d1032f9ece5b doc: updated installation instructions
Goffi <goffi@goffi.org>
parents: 1209
diff changeset
50 .. sourcecode:: cfg
d1032f9ece5b doc: updated installation instructions
Goffi <goffi@goffi.org>
parents: 1209
diff changeset
51
d1032f9ece5b doc: updated installation instructions
Goffi <goffi@goffi.org>
parents: 1209
diff changeset
52 [DEFAULT]
d1032f9ece5b doc: updated installation instructions
Goffi <goffi@goffi.org>
parents: 1209
diff changeset
53 media_dir = ~/sat_media
d1032f9ece5b doc: updated installation instructions
Goffi <goffi@goffi.org>
parents: 1209
diff changeset
54
d1032f9ece5b doc: updated installation instructions
Goffi <goffi@goffi.org>
parents: 1209
diff changeset
55 Of course, replace ``~/sat_media`` with the actual path you have used.
d1032f9ece5b doc: updated installation instructions
Goffi <goffi@goffi.org>
parents: 1209
diff changeset
56
d1032f9ece5b doc: updated installation instructions
Goffi <goffi@goffi.org>
parents: 1209
diff changeset
57 Please check backend documentation for more details on the settings.
d1032f9ece5b doc: updated installation instructions
Goffi <goffi@goffi.org>
parents: 1209
diff changeset
58
d1032f9ece5b doc: updated installation instructions
Goffi <goffi@goffi.org>
parents: 1209
diff changeset
59 You'll also need the ``yarn`` packager, please check your distribution documentation for
d1032f9ece5b doc: updated installation instructions
Goffi <goffi@goffi.org>
parents: 1209
diff changeset
60 instructions to install it.
d1032f9ece5b doc: updated installation instructions
Goffi <goffi@goffi.org>
parents: 1209
diff changeset
61
d1032f9ece5b doc: updated installation instructions
Goffi <goffi@goffi.org>
parents: 1209
diff changeset
62 .. note::
d1032f9ece5b doc: updated installation instructions
Goffi <goffi@goffi.org>
parents: 1209
diff changeset
63
d1032f9ece5b doc: updated installation instructions
Goffi <goffi@goffi.org>
parents: 1209
diff changeset
64 On Debian and derivatives, the ``yarn`` packager is installed with the ``yarnpkg``
d1032f9ece5b doc: updated installation instructions
Goffi <goffi@goffi.org>
parents: 1209
diff changeset
65 package (and not ``yarn`` only), you can install it with ``apt install yarnpkg`` as
d1032f9ece5b doc: updated installation instructions
Goffi <goffi@goffi.org>
parents: 1209
diff changeset
66 root (or with ``sudo``).
d1032f9ece5b doc: updated installation instructions
Goffi <goffi@goffi.org>
parents: 1209
diff changeset
67
1209
13447f785ba1 doc: added installation instructions
Goffi <goffi@goffi.org>
parents:
diff changeset
68 Post Installation
13447f785ba1 doc: added installation instructions
Goffi <goffi@goffi.org>
parents:
diff changeset
69 -----------------
13447f785ba1 doc: added installation instructions
Goffi <goffi@goffi.org>
parents:
diff changeset
70
13447f785ba1 doc: added installation instructions
Goffi <goffi@goffi.org>
parents:
diff changeset
71 Libervia uses its own XMPP account to fetch public data. You need to create a profile
13447f785ba1 doc: added installation instructions
Goffi <goffi@goffi.org>
parents:
diff changeset
72 named `libervia` linked to this account to launch Libervia. First create an account
13447f785ba1 doc: added installation instructions
Goffi <goffi@goffi.org>
parents:
diff changeset
73 dedicated to this on your XMPP server. For instance with `Prosody`_ you would enter
13447f785ba1 doc: added installation instructions
Goffi <goffi@goffi.org>
parents:
diff changeset
74 something like::
13447f785ba1 doc: added installation instructions
Goffi <goffi@goffi.org>
parents:
diff changeset
75
13447f785ba1 doc: added installation instructions
Goffi <goffi@goffi.org>
parents:
diff changeset
76 $ prosodyctl adduser libervia@example.net
13447f785ba1 doc: added installation instructions
Goffi <goffi@goffi.org>
parents:
diff changeset
77
13447f785ba1 doc: added installation instructions
Goffi <goffi@goffi.org>
parents:
diff changeset
78 Where you'll obviously change ``libervia@example.net`` for the JID you want to use, with
13447f785ba1 doc: added installation instructions
Goffi <goffi@goffi.org>
parents:
diff changeset
79 your domain name. You'll then be prompted for a password. You can now create the
13447f785ba1 doc: added installation instructions
Goffi <goffi@goffi.org>
parents:
diff changeset
80 associated SàT profile::
13447f785ba1 doc: added installation instructions
Goffi <goffi@goffi.org>
parents:
diff changeset
81
13447f785ba1 doc: added installation instructions
Goffi <goffi@goffi.org>
parents:
diff changeset
82 $ jp profile create libervia -j libervia@example.net -p <libervia_password>
13447f785ba1 doc: added installation instructions
Goffi <goffi@goffi.org>
parents:
diff changeset
83
13447f785ba1 doc: added installation instructions
Goffi <goffi@goffi.org>
parents:
diff changeset
84 .. note::
13447f785ba1 doc: added installation instructions
Goffi <goffi@goffi.org>
parents:
diff changeset
85
13447f785ba1 doc: added installation instructions
Goffi <goffi@goffi.org>
parents:
diff changeset
86 jp doesn't prompt for password yet, this means that the password is visible to anybody
13447f785ba1 doc: added installation instructions
Goffi <goffi@goffi.org>
parents:
diff changeset
87 looking at your screen and will stay in your shell history, and the password will be
13447f785ba1 doc: added installation instructions
Goffi <goffi@goffi.org>
parents:
diff changeset
88 visible for a few seconds in process list. If this is a concern for you (e.g. you use a
13447f785ba1 doc: added installation instructions
Goffi <goffi@goffi.org>
parents:
diff changeset
89 shared machine), use an other frontend to create the profile, or do the necessary to
13447f785ba1 doc: added installation instructions
Goffi <goffi@goffi.org>
parents:
diff changeset
90 remove the password from history.
13447f785ba1 doc: added installation instructions
Goffi <goffi@goffi.org>
parents:
diff changeset
91
13447f785ba1 doc: added installation instructions
Goffi <goffi@goffi.org>
parents:
diff changeset
92 Finally, you need to specify to specify the password of this ``libervia`` profile in your
13447f785ba1 doc: added installation instructions
Goffi <goffi@goffi.org>
parents:
diff changeset
93 configuration. To do so, edit your ``sat.conf`` and edit ``[libervia]`` and set the
13447f785ba1 doc: added installation instructions
Goffi <goffi@goffi.org>
parents:
diff changeset
94 ``passphrase`` option to the profile password you have used in the command above:
13447f785ba1 doc: added installation instructions
Goffi <goffi@goffi.org>
parents:
diff changeset
95
13447f785ba1 doc: added installation instructions
Goffi <goffi@goffi.org>
parents:
diff changeset
96 .. sourcecode:: cfg
13447f785ba1 doc: added installation instructions
Goffi <goffi@goffi.org>
parents:
diff changeset
97
13447f785ba1 doc: added installation instructions
Goffi <goffi@goffi.org>
parents:
diff changeset
98 [libervia]
13447f785ba1 doc: added installation instructions
Goffi <goffi@goffi.org>
parents:
diff changeset
99 passphrase = <libervia_password>
13447f785ba1 doc: added installation instructions
Goffi <goffi@goffi.org>
parents:
diff changeset
100
13447f785ba1 doc: added installation instructions
Goffi <goffi@goffi.org>
parents:
diff changeset
101 You should now be good to run the Libervia server.
13447f785ba1 doc: added installation instructions
Goffi <goffi@goffi.org>
parents:
diff changeset
102
13447f785ba1 doc: added installation instructions
Goffi <goffi@goffi.org>
parents:
diff changeset
103 .. _Prosody: https://prosody.im
13447f785ba1 doc: added installation instructions
Goffi <goffi@goffi.org>
parents:
diff changeset
104
13447f785ba1 doc: added installation instructions
Goffi <goffi@goffi.org>
parents:
diff changeset
105
13447f785ba1 doc: added installation instructions
Goffi <goffi@goffi.org>
parents:
diff changeset
106 Usage
13447f785ba1 doc: added installation instructions
Goffi <goffi@goffi.org>
parents:
diff changeset
107 =====
13447f785ba1 doc: added installation instructions
Goffi <goffi@goffi.org>
parents:
diff changeset
108
13447f785ba1 doc: added installation instructions
Goffi <goffi@goffi.org>
parents:
diff changeset
109 To launch the Libervia server, enter::
13447f785ba1 doc: added installation instructions
Goffi <goffi@goffi.org>
parents:
diff changeset
110
13447f785ba1 doc: added installation instructions
Goffi <goffi@goffi.org>
parents:
diff changeset
111 $ libervia
13447f785ba1 doc: added installation instructions
Goffi <goffi@goffi.org>
parents:
diff changeset
112
13447f785ba1 doc: added installation instructions
Goffi <goffi@goffi.org>
parents:
diff changeset
113 …or, if you want to launch it in foreground::
13447f785ba1 doc: added installation instructions
Goffi <goffi@goffi.org>
parents:
diff changeset
114
13447f785ba1 doc: added installation instructions
Goffi <goffi@goffi.org>
parents:
diff changeset
115 $ libervia fg
13447f785ba1 doc: added installation instructions
Goffi <goffi@goffi.org>
parents:
diff changeset
116
13447f785ba1 doc: added installation instructions
Goffi <goffi@goffi.org>
parents:
diff changeset
117 You can stop it with::
13447f785ba1 doc: added installation instructions
Goffi <goffi@goffi.org>
parents:
diff changeset
118
13447f785ba1 doc: added installation instructions
Goffi <goffi@goffi.org>
parents:
diff changeset
119 $ libervia stop
13447f785ba1 doc: added installation instructions
Goffi <goffi@goffi.org>
parents:
diff changeset
120
13447f785ba1 doc: added installation instructions
Goffi <goffi@goffi.org>
parents:
diff changeset
121 To know if backend is launched or not::
13447f785ba1 doc: added installation instructions
Goffi <goffi@goffi.org>
parents:
diff changeset
122
13447f785ba1 doc: added installation instructions
Goffi <goffi@goffi.org>
parents:
diff changeset
123 $ libervia status
13447f785ba1 doc: added installation instructions
Goffi <goffi@goffi.org>
parents:
diff changeset
124
13447f785ba1 doc: added installation instructions
Goffi <goffi@goffi.org>
parents:
diff changeset
125
13447f785ba1 doc: added installation instructions
Goffi <goffi@goffi.org>
parents:
diff changeset
126 SàT Pubsub
13447f785ba1 doc: added installation instructions
Goffi <goffi@goffi.org>
parents:
diff changeset
127 ==========
13447f785ba1 doc: added installation instructions
Goffi <goffi@goffi.org>
parents:
diff changeset
128
13447f785ba1 doc: added installation instructions
Goffi <goffi@goffi.org>
parents:
diff changeset
129 Some functionalities use advanced or experimental features of XMPP PubSub. We recommend to
13447f785ba1 doc: added installation instructions
Goffi <goffi@goffi.org>
parents:
diff changeset
130 use the SàT PubSub service that is a side project developed for the needs of Salut à Toi,
13447f785ba1 doc: added installation instructions
Goffi <goffi@goffi.org>
parents:
diff changeset
131 and consequently implements everything needed. Please refer to SàT PubSub documentation to
13447f785ba1 doc: added installation instructions
Goffi <goffi@goffi.org>
parents:
diff changeset
132 know how to install and use it.