annotate doc/installation.rst @ 1531:d7c78722e4f8

browser (cache): make `fill_identities` async + use `json` module: - `json` module has been greatly improved in Brython, the former workaround is not needed anymore. - `fill_identities` is now async so an async method can wait for it to complete
author Goffi <goffi@goffi.org>
date Thu, 22 Jun 2023 16:35:34 +0200
parents 0d517b596568
children c62027660ec1
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
1521
0d517b596568 doc: update installation instruction
Goffi <goffi@goffi.org>
parents: 1502
diff changeset
5 This are the instructions to install Libervia Web using Python.
0d517b596568 doc: update installation instruction
Goffi <goffi@goffi.org>
parents: 1502
diff changeset
6 Note that if you are using GNU/Linux, Libervia Web may already be present on your
0d517b596568 doc: update installation instruction
Goffi <goffi@goffi.org>
parents: 1502
diff changeset
7 distribution.
1209
13447f785ba1 doc: added installation instructions
Goffi <goffi@goffi.org>
parents:
diff changeset
8
1521
0d517b596568 doc: update installation instruction
Goffi <goffi@goffi.org>
parents: 1502
diff changeset
9 This is the web frontend of Libervia, the Libervia backend must be installed first (if you
1209
13447f785ba1 doc: added installation instructions
Goffi <goffi@goffi.org>
parents:
diff changeset
10 haven't installed it yet, it will be downloaded automatically as it is a dependency of
1521
0d517b596568 doc: update installation instruction
Goffi <goffi@goffi.org>
parents: 1502
diff changeset
11 Libervia Web). Libervia Web and Libervia Backend must always have the same version
0d517b596568 doc: update installation instruction
Goffi <goffi@goffi.org>
parents: 1502
diff changeset
12 (Libervia Web won't start if the version backend differs).
1209
13447f785ba1 doc: added installation instructions
Goffi <goffi@goffi.org>
parents:
diff changeset
13
13447f785ba1 doc: added installation instructions
Goffi <goffi@goffi.org>
parents:
diff changeset
14 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
15 0.8 version.
1209
13447f785ba1 doc: added installation instructions
Goffi <goffi@goffi.org>
parents:
diff changeset
16
1401
aada5471d6bc doc: update installation instruction following renaming and new `requirements.txt`:
Goffi <goffi@goffi.org>
parents: 1353
diff changeset
17 Requirements
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
aada5471d6bc doc: update installation instruction following renaming and new `requirements.txt`:
Goffi <goffi@goffi.org>
parents: 1353
diff changeset
20 - Python 3.7+
aada5471d6bc doc: update installation instruction following renaming and new `requirements.txt`:
Goffi <goffi@goffi.org>
parents: 1353
diff changeset
21 - 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
22 - Mercurial
aada5471d6bc doc: update installation instruction following renaming and new `requirements.txt`:
Goffi <goffi@goffi.org>
parents: 1353
diff changeset
23
aada5471d6bc doc: update installation instruction following renaming and new `requirements.txt`:
Goffi <goffi@goffi.org>
parents: 1353
diff changeset
24 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
25
aada5471d6bc doc: update installation instruction following renaming and new `requirements.txt`:
Goffi <goffi@goffi.org>
parents: 1353
diff changeset
26 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
27
1209
13447f785ba1 doc: added installation instructions
Goffi <goffi@goffi.org>
parents:
diff changeset
28 Development Version
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
13447f785ba1 doc: added installation instructions
Goffi <goffi@goffi.org>
parents:
diff changeset
31 *Note for Arch users: a pkgbuild is available for your distribution on
13447f785ba1 doc: added installation instructions
Goffi <goffi@goffi.org>
parents:
diff changeset
32 AUR, check sat-libervia-hg (as well as other sat-\* packages).*
13447f785ba1 doc: added installation instructions
Goffi <goffi@goffi.org>
parents:
diff changeset
33
1401
aada5471d6bc doc: update installation instruction following renaming and new `requirements.txt`:
Goffi <goffi@goffi.org>
parents: 1353
diff changeset
34 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
35
aada5471d6bc doc: update installation instruction following renaming and new `requirements.txt`:
Goffi <goffi@goffi.org>
parents: 1353
diff changeset
36 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
37 instance your ``$HOME`` directory::
1209
13447f785ba1 doc: added installation instructions
Goffi <goffi@goffi.org>
parents:
diff changeset
38
1401
aada5471d6bc doc: update installation instruction following renaming and new `requirements.txt`:
Goffi <goffi@goffi.org>
parents: 1353
diff changeset
39 $ cd
aada5471d6bc doc: update installation instruction following renaming and new `requirements.txt`:
Goffi <goffi@goffi.org>
parents: 1353
diff changeset
40
aada5471d6bc doc: update installation instruction following renaming and new `requirements.txt`:
Goffi <goffi@goffi.org>
parents: 1353
diff changeset
41 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
42 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
43 there)::
1209
13447f785ba1 doc: added installation instructions
Goffi <goffi@goffi.org>
parents:
diff changeset
44
1401
aada5471d6bc doc: update installation instruction following renaming and new `requirements.txt`:
Goffi <goffi@goffi.org>
parents: 1353
diff changeset
45 $ python3 -m venv libervia_venv
aada5471d6bc doc: update installation instruction following renaming and new `requirements.txt`:
Goffi <goffi@goffi.org>
parents: 1353
diff changeset
46 $ source libervia_venv/bin/activate
aada5471d6bc doc: update installation instruction following renaming and new `requirements.txt`:
Goffi <goffi@goffi.org>
parents: 1353
diff changeset
47 $ pip install -U pip wheel
1209
13447f785ba1 doc: added installation instructions
Goffi <goffi@goffi.org>
parents:
diff changeset
48
1401
aada5471d6bc doc: update installation instruction following renaming and new `requirements.txt`:
Goffi <goffi@goffi.org>
parents: 1353
diff changeset
49 Then you need to clone the repository::
1209
13447f785ba1 doc: added installation instructions
Goffi <goffi@goffi.org>
parents:
diff changeset
50
1401
aada5471d6bc doc: update installation instruction following renaming and new `requirements.txt`:
Goffi <goffi@goffi.org>
parents: 1353
diff changeset
51 $ 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
52
1521
0d517b596568 doc: update installation instruction
Goffi <goffi@goffi.org>
parents: 1502
diff changeset
53 Now you can install the frontend and its requirements::
1401
aada5471d6bc doc: update installation instruction following renaming and new `requirements.txt`:
Goffi <goffi@goffi.org>
parents: 1353
diff changeset
54
1521
0d517b596568 doc: update installation instruction
Goffi <goffi@goffi.org>
parents: 1502
diff changeset
55 $ pip install .
1209
13447f785ba1 doc: added installation instructions
Goffi <goffi@goffi.org>
parents:
diff changeset
56
13447f785ba1 doc: added installation instructions
Goffi <goffi@goffi.org>
parents:
diff changeset
57 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
58
13447f785ba1 doc: added installation instructions
Goffi <goffi@goffi.org>
parents:
diff changeset
59 $ cd
1502
e1ccba0d2b71 doc: set `language` and use `libervia-media` instead of `sat_media`
Goffi <goffi@goffi.org>
parents: 1401
diff changeset
60 $ hg clone https://repos.goffi.org/libervia-media
1209
13447f785ba1 doc: added installation instructions
Goffi <goffi@goffi.org>
parents:
diff changeset
61
1401
aada5471d6bc doc: update installation instruction following renaming and new `requirements.txt`:
Goffi <goffi@goffi.org>
parents: 1353
diff changeset
62 then, create the directory ``~/.config/libervia``::
1353
d1032f9ece5b doc: updated installation instructions
Goffi <goffi@goffi.org>
parents: 1209
diff changeset
63
1401
aada5471d6bc doc: update installation instruction following renaming and new `requirements.txt`:
Goffi <goffi@goffi.org>
parents: 1353
diff changeset
64 $ mkdir -p ~/.config/libervia
1353
d1032f9ece5b doc: updated installation instructions
Goffi <goffi@goffi.org>
parents: 1209
diff changeset
65
1401
aada5471d6bc doc: update installation instruction following renaming and new `requirements.txt`:
Goffi <goffi@goffi.org>
parents: 1353
diff changeset
66 and the file ``~/.config/libervia/libervia.conf`` containing:
1353
d1032f9ece5b doc: updated installation instructions
Goffi <goffi@goffi.org>
parents: 1209
diff changeset
67
d1032f9ece5b doc: updated installation instructions
Goffi <goffi@goffi.org>
parents: 1209
diff changeset
68 .. sourcecode:: cfg
d1032f9ece5b doc: updated installation instructions
Goffi <goffi@goffi.org>
parents: 1209
diff changeset
69
d1032f9ece5b doc: updated installation instructions
Goffi <goffi@goffi.org>
parents: 1209
diff changeset
70 [DEFAULT]
1502
e1ccba0d2b71 doc: set `language` and use `libervia-media` instead of `sat_media`
Goffi <goffi@goffi.org>
parents: 1401
diff changeset
71 media_dir = ~/libervia-media
1353
d1032f9ece5b doc: updated installation instructions
Goffi <goffi@goffi.org>
parents: 1209
diff changeset
72
1502
e1ccba0d2b71 doc: set `language` and use `libervia-media` instead of `sat_media`
Goffi <goffi@goffi.org>
parents: 1401
diff changeset
73 Of course, replace ``~/libervia-media`` with the actual path you have used.
1353
d1032f9ece5b doc: updated installation instructions
Goffi <goffi@goffi.org>
parents: 1209
diff changeset
74
d1032f9ece5b doc: updated installation instructions
Goffi <goffi@goffi.org>
parents: 1209
diff changeset
75 Please check backend documentation for more details on the settings.
d1032f9ece5b doc: updated installation instructions
Goffi <goffi@goffi.org>
parents: 1209
diff changeset
76
d1032f9ece5b doc: updated installation instructions
Goffi <goffi@goffi.org>
parents: 1209
diff changeset
77 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
78 instructions to install it.
d1032f9ece5b doc: updated installation instructions
Goffi <goffi@goffi.org>
parents: 1209
diff changeset
79
d1032f9ece5b doc: updated installation instructions
Goffi <goffi@goffi.org>
parents: 1209
diff changeset
80 .. note::
d1032f9ece5b doc: updated installation instructions
Goffi <goffi@goffi.org>
parents: 1209
diff changeset
81
d1032f9ece5b doc: updated installation instructions
Goffi <goffi@goffi.org>
parents: 1209
diff changeset
82 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
83 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
84 root (or with ``sudo``).
d1032f9ece5b doc: updated installation instructions
Goffi <goffi@goffi.org>
parents: 1209
diff changeset
85
1209
13447f785ba1 doc: added installation instructions
Goffi <goffi@goffi.org>
parents:
diff changeset
86 Post Installation
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
13447f785ba1 doc: added installation instructions
Goffi <goffi@goffi.org>
parents:
diff changeset
89 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
90 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
91 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
92 something like::
13447f785ba1 doc: added installation instructions
Goffi <goffi@goffi.org>
parents:
diff changeset
93
13447f785ba1 doc: added installation instructions
Goffi <goffi@goffi.org>
parents:
diff changeset
94 $ prosodyctl adduser libervia@example.net
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 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
97 your domain name. You'll then be prompted for a password. You can now create the
1521
0d517b596568 doc: update installation instruction
Goffi <goffi@goffi.org>
parents: 1502
diff changeset
98 associated Libervia profile::
1209
13447f785ba1 doc: added installation instructions
Goffi <goffi@goffi.org>
parents:
diff changeset
99
1521
0d517b596568 doc: update installation instruction
Goffi <goffi@goffi.org>
parents: 1502
diff changeset
100 $ li profile create libervia -j libervia@example.net -p <libervia_password>
1209
13447f785ba1 doc: added installation instructions
Goffi <goffi@goffi.org>
parents:
diff changeset
101
13447f785ba1 doc: added installation instructions
Goffi <goffi@goffi.org>
parents:
diff changeset
102 .. note::
13447f785ba1 doc: added installation instructions
Goffi <goffi@goffi.org>
parents:
diff changeset
103
1521
0d517b596568 doc: update installation instruction
Goffi <goffi@goffi.org>
parents: 1502
diff changeset
104 Libervia CLI doesn't prompt for password yet, this means that the password is visible
0d517b596568 doc: update installation instruction
Goffi <goffi@goffi.org>
parents: 1502
diff changeset
105 to anybody looking at your screen and will stay in your shell history, and the password
0d517b596568 doc: update installation instruction
Goffi <goffi@goffi.org>
parents: 1502
diff changeset
106 will be visible for a few seconds in process list. If this is a concern for you (e.g.
0d517b596568 doc: update installation instruction
Goffi <goffi@goffi.org>
parents: 1502
diff changeset
107 you use a shared machine), use an other frontend to create the profile, or do the
0d517b596568 doc: update installation instruction
Goffi <goffi@goffi.org>
parents: 1502
diff changeset
108 necessary to remove the password from history. In most shells, you can add a space in
0d517b596568 doc: update installation instruction
Goffi <goffi@goffi.org>
parents: 1502
diff changeset
109 front of the command so that it doesn't appear in the history.
1209
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 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
112 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
113 ``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
114
13447f785ba1 doc: added installation instructions
Goffi <goffi@goffi.org>
parents:
diff changeset
115 .. sourcecode:: cfg
13447f785ba1 doc: added installation instructions
Goffi <goffi@goffi.org>
parents:
diff changeset
116
1521
0d517b596568 doc: update installation instruction
Goffi <goffi@goffi.org>
parents: 1502
diff changeset
117 [web]
1209
13447f785ba1 doc: added installation instructions
Goffi <goffi@goffi.org>
parents:
diff changeset
118 passphrase = <libervia_password>
13447f785ba1 doc: added installation instructions
Goffi <goffi@goffi.org>
parents:
diff changeset
119
1401
aada5471d6bc doc: update installation instruction following renaming and new `requirements.txt`:
Goffi <goffi@goffi.org>
parents: 1353
diff changeset
120 You should now be good to run the Libervia Web server.
1209
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 .. _Prosody: https://prosody.im
13447f785ba1 doc: added installation instructions
Goffi <goffi@goffi.org>
parents:
diff changeset
123
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 Usage
13447f785ba1 doc: added installation instructions
Goffi <goffi@goffi.org>
parents:
diff changeset
126 =====
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 To launch the Libervia Web server, enter::
1209
13447f785ba1 doc: added installation instructions
Goffi <goffi@goffi.org>
parents:
diff changeset
129
1401
aada5471d6bc doc: update installation instruction following renaming and new `requirements.txt`:
Goffi <goffi@goffi.org>
parents: 1353
diff changeset
130 $ libervia-web
1209
13447f785ba1 doc: added installation instructions
Goffi <goffi@goffi.org>
parents:
diff changeset
131
13447f785ba1 doc: added installation instructions
Goffi <goffi@goffi.org>
parents:
diff changeset
132 …or, if you want to launch it in foreground::
13447f785ba1 doc: added installation instructions
Goffi <goffi@goffi.org>
parents:
diff changeset
133
1401
aada5471d6bc doc: update installation instruction following renaming and new `requirements.txt`:
Goffi <goffi@goffi.org>
parents: 1353
diff changeset
134 $ libervia-web fg
1209
13447f785ba1 doc: added installation instructions
Goffi <goffi@goffi.org>
parents:
diff changeset
135
13447f785ba1 doc: added installation instructions
Goffi <goffi@goffi.org>
parents:
diff changeset
136 You can stop it with::
13447f785ba1 doc: added installation instructions
Goffi <goffi@goffi.org>
parents:
diff changeset
137
1401
aada5471d6bc doc: update installation instruction following renaming and new `requirements.txt`:
Goffi <goffi@goffi.org>
parents: 1353
diff changeset
138 $ libervia-web stop
1209
13447f785ba1 doc: added installation instructions
Goffi <goffi@goffi.org>
parents:
diff changeset
139
13447f785ba1 doc: added installation instructions
Goffi <goffi@goffi.org>
parents:
diff changeset
140 To know if backend is launched or not::
13447f785ba1 doc: added installation instructions
Goffi <goffi@goffi.org>
parents:
diff changeset
141
1401
aada5471d6bc doc: update installation instruction following renaming and new `requirements.txt`:
Goffi <goffi@goffi.org>
parents: 1353
diff changeset
142 $ libervia-web status
1209
13447f785ba1 doc: added installation instructions
Goffi <goffi@goffi.org>
parents:
diff changeset
143
13447f785ba1 doc: added installation instructions
Goffi <goffi@goffi.org>
parents:
diff changeset
144
1521
0d517b596568 doc: update installation instruction
Goffi <goffi@goffi.org>
parents: 1502
diff changeset
145 Libervia Pubsub
0d517b596568 doc: update installation instruction
Goffi <goffi@goffi.org>
parents: 1502
diff changeset
146 ===============
1209
13447f785ba1 doc: added installation instructions
Goffi <goffi@goffi.org>
parents:
diff changeset
147
13447f785ba1 doc: added installation instructions
Goffi <goffi@goffi.org>
parents:
diff changeset
148 Some functionalities use advanced or experimental features of XMPP PubSub. We recommend to
1521
0d517b596568 doc: update installation instruction
Goffi <goffi@goffi.org>
parents: 1502
diff changeset
149 use the Libervia PubSub service that is a side project developed for the needs of
0d517b596568 doc: update installation instruction
Goffi <goffi@goffi.org>
parents: 1502
diff changeset
150 Libervia, and consequently implements everything needed. Please refer to Libervia PubSub
0d517b596568 doc: update installation instruction
Goffi <goffi@goffi.org>
parents: 1502
diff changeset
151 documentation to know how to install and use it.