annotate doc/installation.rst @ 1409:83b477d36725

doc: rename main title
author Goffi <goffi@goffi.org>
date Thu, 22 Apr 2021 18:22:49 +0200
parents aada5471d6bc
children e1ccba0d2b71
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
1401
aada5471d6bc doc: update installation instruction following renaming and new `requirements.txt`:
Goffi <goffi@goffi.org>
parents: 1353
diff changeset
16 Requirements
aada5471d6bc doc: update installation instruction following renaming and new `requirements.txt`:
Goffi <goffi@goffi.org>
parents: 1353
diff changeset
17 ------------
aada5471d6bc doc: update installation instruction following renaming and new `requirements.txt`:
Goffi <goffi@goffi.org>
parents: 1353
diff changeset
18
aada5471d6bc doc: update installation instruction following renaming and new `requirements.txt`:
Goffi <goffi@goffi.org>
parents: 1353
diff changeset
19 - Python 3.7+
aada5471d6bc doc: update installation instruction following renaming and new `requirements.txt`:
Goffi <goffi@goffi.org>
parents: 1353
diff changeset
20 - Python 3 "venv", which may be installed with Python 3
aada5471d6bc doc: update installation instruction following renaming and new `requirements.txt`:
Goffi <goffi@goffi.org>
parents: 1353
diff changeset
21 - Mercurial
aada5471d6bc doc: update installation instruction following renaming and new `requirements.txt`:
Goffi <goffi@goffi.org>
parents: 1353
diff changeset
22
aada5471d6bc doc: update installation instruction following renaming and new `requirements.txt`:
Goffi <goffi@goffi.org>
parents: 1353
diff changeset
23 To install them on a Debian distribution or derivative, you can enter::
aada5471d6bc doc: update installation instruction following renaming and new `requirements.txt`:
Goffi <goffi@goffi.org>
parents: 1353
diff changeset
24
aada5471d6bc doc: update installation instruction following renaming and new `requirements.txt`:
Goffi <goffi@goffi.org>
parents: 1353
diff changeset
25 sudo apt-get install python3-dev python3-venv python3-wheel mercurial
aada5471d6bc doc: update installation instruction following renaming and new `requirements.txt`:
Goffi <goffi@goffi.org>
parents: 1353
diff changeset
26
1209
13447f785ba1 doc: added installation instructions
Goffi <goffi@goffi.org>
parents:
diff changeset
27 Development Version
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
13447f785ba1 doc: added installation instructions
Goffi <goffi@goffi.org>
parents:
diff changeset
30 *Note for Arch users: a pkgbuild is available for your distribution on
13447f785ba1 doc: added installation instructions
Goffi <goffi@goffi.org>
parents:
diff changeset
31 AUR, check sat-libervia-hg (as well as other sat-\* packages).*
13447f785ba1 doc: added installation instructions
Goffi <goffi@goffi.org>
parents:
diff changeset
32
1401
aada5471d6bc doc: update installation instruction following renaming and new `requirements.txt`:
Goffi <goffi@goffi.org>
parents: 1353
diff changeset
33 You can install the latest development version using Mercurial and pip.
aada5471d6bc doc: update installation instruction following renaming and new `requirements.txt`:
Goffi <goffi@goffi.org>
parents: 1353
diff changeset
34
aada5471d6bc doc: update installation instruction following renaming and new `requirements.txt`:
Goffi <goffi@goffi.org>
parents: 1353
diff changeset
35 Select the location where you want to install libervia and virtual environment, for
aada5471d6bc doc: update installation instruction following renaming and new `requirements.txt`:
Goffi <goffi@goffi.org>
parents: 1353
diff changeset
36 instance your ``$HOME`` directory::
1209
13447f785ba1 doc: added installation instructions
Goffi <goffi@goffi.org>
parents:
diff changeset
37
1401
aada5471d6bc doc: update installation instruction following renaming and new `requirements.txt`:
Goffi <goffi@goffi.org>
parents: 1353
diff changeset
38 $ cd
aada5471d6bc doc: update installation instruction following renaming and new `requirements.txt`:
Goffi <goffi@goffi.org>
parents: 1353
diff changeset
39
aada5471d6bc doc: update installation instruction following renaming and new `requirements.txt`:
Goffi <goffi@goffi.org>
parents: 1353
diff changeset
40 You can use the same virtual environment as the one used for installing the backend.
aada5471d6bc doc: update installation instruction following renaming and new `requirements.txt`:
Goffi <goffi@goffi.org>
parents: 1353
diff changeset
41 Otherwise, create a new one (backend will be installed automatically if it's not already
aada5471d6bc doc: update installation instruction following renaming and new `requirements.txt`:
Goffi <goffi@goffi.org>
parents: 1353
diff changeset
42 there)::
1209
13447f785ba1 doc: added installation instructions
Goffi <goffi@goffi.org>
parents:
diff changeset
43
1401
aada5471d6bc doc: update installation instruction following renaming and new `requirements.txt`:
Goffi <goffi@goffi.org>
parents: 1353
diff changeset
44 $ python3 -m venv libervia_venv
aada5471d6bc doc: update installation instruction following renaming and new `requirements.txt`:
Goffi <goffi@goffi.org>
parents: 1353
diff changeset
45 $ source libervia_venv/bin/activate
aada5471d6bc doc: update installation instruction following renaming and new `requirements.txt`:
Goffi <goffi@goffi.org>
parents: 1353
diff changeset
46 $ pip install -U pip wheel
1209
13447f785ba1 doc: added installation instructions
Goffi <goffi@goffi.org>
parents:
diff changeset
47
1401
aada5471d6bc doc: update installation instruction following renaming and new `requirements.txt`:
Goffi <goffi@goffi.org>
parents: 1353
diff changeset
48 Then you need to clone the repository::
1209
13447f785ba1 doc: added installation instructions
Goffi <goffi@goffi.org>
parents:
diff changeset
49
1401
aada5471d6bc doc: update installation instruction following renaming and new `requirements.txt`:
Goffi <goffi@goffi.org>
parents: 1353
diff changeset
50 $ hg clone https://repos.goffi.org/libervia libervia-web && cd libervia-web
aada5471d6bc doc: update installation instruction following renaming and new `requirements.txt`:
Goffi <goffi@goffi.org>
parents: 1353
diff changeset
51
aada5471d6bc doc: update installation instruction following renaming and new `requirements.txt`:
Goffi <goffi@goffi.org>
parents: 1353
diff changeset
52 Now you can install the requirements::
aada5471d6bc doc: update installation instruction following renaming and new `requirements.txt`:
Goffi <goffi@goffi.org>
parents: 1353
diff changeset
53
aada5471d6bc doc: update installation instruction following renaming and new `requirements.txt`:
Goffi <goffi@goffi.org>
parents: 1353
diff changeset
54 $ pip install -r requirements.txt
1209
13447f785ba1 doc: added installation instructions
Goffi <goffi@goffi.org>
parents:
diff changeset
55
13447f785ba1 doc: added installation instructions
Goffi <goffi@goffi.org>
parents:
diff changeset
56 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
57
13447f785ba1 doc: added installation instructions
Goffi <goffi@goffi.org>
parents:
diff changeset
58 $ cd
13447f785ba1 doc: added installation instructions
Goffi <goffi@goffi.org>
parents:
diff changeset
59 $ hg clone https://repos.goffi.org/sat_media
13447f785ba1 doc: added installation instructions
Goffi <goffi@goffi.org>
parents:
diff changeset
60
1401
aada5471d6bc doc: update installation instruction following renaming and new `requirements.txt`:
Goffi <goffi@goffi.org>
parents: 1353
diff changeset
61 then, create the directory ``~/.config/libervia``::
1353
d1032f9ece5b doc: updated installation instructions
Goffi <goffi@goffi.org>
parents: 1209
diff changeset
62
1401
aada5471d6bc doc: update installation instruction following renaming and new `requirements.txt`:
Goffi <goffi@goffi.org>
parents: 1353
diff changeset
63 $ mkdir -p ~/.config/libervia
1353
d1032f9ece5b doc: updated installation instructions
Goffi <goffi@goffi.org>
parents: 1209
diff changeset
64
1401
aada5471d6bc doc: update installation instruction following renaming and new `requirements.txt`:
Goffi <goffi@goffi.org>
parents: 1353
diff changeset
65 and the file ``~/.config/libervia/libervia.conf`` containing:
1353
d1032f9ece5b doc: updated installation instructions
Goffi <goffi@goffi.org>
parents: 1209
diff changeset
66
d1032f9ece5b doc: updated installation instructions
Goffi <goffi@goffi.org>
parents: 1209
diff changeset
67 .. sourcecode:: cfg
d1032f9ece5b doc: updated installation instructions
Goffi <goffi@goffi.org>
parents: 1209
diff changeset
68
d1032f9ece5b doc: updated installation instructions
Goffi <goffi@goffi.org>
parents: 1209
diff changeset
69 [DEFAULT]
d1032f9ece5b doc: updated installation instructions
Goffi <goffi@goffi.org>
parents: 1209
diff changeset
70 media_dir = ~/sat_media
d1032f9ece5b doc: updated installation instructions
Goffi <goffi@goffi.org>
parents: 1209
diff changeset
71
d1032f9ece5b doc: updated installation instructions
Goffi <goffi@goffi.org>
parents: 1209
diff changeset
72 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
73
d1032f9ece5b doc: updated installation instructions
Goffi <goffi@goffi.org>
parents: 1209
diff changeset
74 Please check backend documentation for more details on the settings.
d1032f9ece5b doc: updated installation instructions
Goffi <goffi@goffi.org>
parents: 1209
diff changeset
75
d1032f9ece5b doc: updated installation instructions
Goffi <goffi@goffi.org>
parents: 1209
diff changeset
76 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
77 instructions to install it.
d1032f9ece5b doc: updated installation instructions
Goffi <goffi@goffi.org>
parents: 1209
diff changeset
78
d1032f9ece5b doc: updated installation instructions
Goffi <goffi@goffi.org>
parents: 1209
diff changeset
79 .. note::
d1032f9ece5b doc: updated installation instructions
Goffi <goffi@goffi.org>
parents: 1209
diff changeset
80
d1032f9ece5b doc: updated installation instructions
Goffi <goffi@goffi.org>
parents: 1209
diff changeset
81 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
82 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
83 root (or with ``sudo``).
d1032f9ece5b doc: updated installation instructions
Goffi <goffi@goffi.org>
parents: 1209
diff changeset
84
1209
13447f785ba1 doc: added installation instructions
Goffi <goffi@goffi.org>
parents:
diff changeset
85 Post Installation
13447f785ba1 doc: added installation instructions
Goffi <goffi@goffi.org>
parents:
diff changeset
86 -----------------
13447f785ba1 doc: added installation instructions
Goffi <goffi@goffi.org>
parents:
diff changeset
87
13447f785ba1 doc: added installation instructions
Goffi <goffi@goffi.org>
parents:
diff changeset
88 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
89 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
90 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
91 something like::
13447f785ba1 doc: added installation instructions
Goffi <goffi@goffi.org>
parents:
diff changeset
92
13447f785ba1 doc: added installation instructions
Goffi <goffi@goffi.org>
parents:
diff changeset
93 $ prosodyctl adduser libervia@example.net
13447f785ba1 doc: added installation instructions
Goffi <goffi@goffi.org>
parents:
diff changeset
94
13447f785ba1 doc: added installation instructions
Goffi <goffi@goffi.org>
parents:
diff changeset
95 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
96 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
97 associated SàT profile::
13447f785ba1 doc: added installation instructions
Goffi <goffi@goffi.org>
parents:
diff changeset
98
13447f785ba1 doc: added installation instructions
Goffi <goffi@goffi.org>
parents:
diff changeset
99 $ jp profile create libervia -j libervia@example.net -p <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 .. note::
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 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
104 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
105 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
106 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
107 remove the password from history.
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 Finally, you need to specify to specify the password of this ``libervia`` profile in your
1401
aada5471d6bc doc: update installation instruction following renaming and new `requirements.txt`:
Goffi <goffi@goffi.org>
parents: 1353
diff changeset
110 configuration. To do so, edit your ``libervia.conf`` and edit ``[libervia]`` and set the
1209
13447f785ba1 doc: added installation instructions
Goffi <goffi@goffi.org>
parents:
diff changeset
111 ``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
112
13447f785ba1 doc: added installation instructions
Goffi <goffi@goffi.org>
parents:
diff changeset
113 .. sourcecode:: cfg
13447f785ba1 doc: added installation instructions
Goffi <goffi@goffi.org>
parents:
diff changeset
114
1401
aada5471d6bc doc: update installation instruction following renaming and new `requirements.txt`:
Goffi <goffi@goffi.org>
parents: 1353
diff changeset
115 [libervia_web]
1209
13447f785ba1 doc: added installation instructions
Goffi <goffi@goffi.org>
parents:
diff changeset
116 passphrase = <libervia_password>
13447f785ba1 doc: added installation instructions
Goffi <goffi@goffi.org>
parents:
diff changeset
117
1401
aada5471d6bc doc: update installation instruction following renaming and new `requirements.txt`:
Goffi <goffi@goffi.org>
parents: 1353
diff changeset
118 You should now be good to run the Libervia Web server.
1209
13447f785ba1 doc: added installation instructions
Goffi <goffi@goffi.org>
parents:
diff changeset
119
13447f785ba1 doc: added installation instructions
Goffi <goffi@goffi.org>
parents:
diff changeset
120 .. _Prosody: https://prosody.im
13447f785ba1 doc: added installation instructions
Goffi <goffi@goffi.org>
parents:
diff changeset
121
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 Usage
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
1401
aada5471d6bc doc: update installation instruction following renaming and new `requirements.txt`:
Goffi <goffi@goffi.org>
parents: 1353
diff changeset
126 To launch the Libervia Web server, enter::
1209
13447f785ba1 doc: added installation instructions
Goffi <goffi@goffi.org>
parents:
diff changeset
127
1401
aada5471d6bc doc: update installation instruction following renaming and new `requirements.txt`:
Goffi <goffi@goffi.org>
parents: 1353
diff changeset
128 $ libervia-web
1209
13447f785ba1 doc: added installation instructions
Goffi <goffi@goffi.org>
parents:
diff changeset
129
13447f785ba1 doc: added installation instructions
Goffi <goffi@goffi.org>
parents:
diff changeset
130 …or, if you want to launch it in foreground::
13447f785ba1 doc: added installation instructions
Goffi <goffi@goffi.org>
parents:
diff changeset
131
1401
aada5471d6bc doc: update installation instruction following renaming and new `requirements.txt`:
Goffi <goffi@goffi.org>
parents: 1353
diff changeset
132 $ libervia-web fg
1209
13447f785ba1 doc: added installation instructions
Goffi <goffi@goffi.org>
parents:
diff changeset
133
13447f785ba1 doc: added installation instructions
Goffi <goffi@goffi.org>
parents:
diff changeset
134 You can stop it with::
13447f785ba1 doc: added installation instructions
Goffi <goffi@goffi.org>
parents:
diff changeset
135
1401
aada5471d6bc doc: update installation instruction following renaming and new `requirements.txt`:
Goffi <goffi@goffi.org>
parents: 1353
diff changeset
136 $ libervia-web stop
1209
13447f785ba1 doc: added installation instructions
Goffi <goffi@goffi.org>
parents:
diff changeset
137
13447f785ba1 doc: added installation instructions
Goffi <goffi@goffi.org>
parents:
diff changeset
138 To know if backend is launched or not::
13447f785ba1 doc: added installation instructions
Goffi <goffi@goffi.org>
parents:
diff changeset
139
1401
aada5471d6bc doc: update installation instruction following renaming and new `requirements.txt`:
Goffi <goffi@goffi.org>
parents: 1353
diff changeset
140 $ libervia-web status
1209
13447f785ba1 doc: added installation instructions
Goffi <goffi@goffi.org>
parents:
diff changeset
141
13447f785ba1 doc: added installation instructions
Goffi <goffi@goffi.org>
parents:
diff changeset
142
13447f785ba1 doc: added installation instructions
Goffi <goffi@goffi.org>
parents:
diff changeset
143 SàT Pubsub
13447f785ba1 doc: added installation instructions
Goffi <goffi@goffi.org>
parents:
diff changeset
144 ==========
13447f785ba1 doc: added installation instructions
Goffi <goffi@goffi.org>
parents:
diff changeset
145
13447f785ba1 doc: added installation instructions
Goffi <goffi@goffi.org>
parents:
diff changeset
146 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
147 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
148 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
149 know how to install and use it.