Mercurial > libervia-web
annotate doc/installation.rst @ 1504:409d10211b20
server, browser: dynamic pages refactoring:
dynamic pages has been reworked, to change the initial basic implementation.
Pages are now dynamic by default, and a websocket is established by the first connected
page of a session. The socket is used to transmit bridge signals, and then the signal is
broadcasted to other tabs using broadcast channel.
If the connecting tab is closed, an other one is chosen.
Some tests are made to retry connecting in case of problem, and sometimes reload the pages
(e.g. if profile is connected).
Signals (or other data) are cached during reconnection phase, to avoid lost of data.
All previous partial rendering mechanism have been removed, chat page is temporarily not
working anymore, but will be eventually redone (one of the goal of this work is to have
proper chat).
| author | Goffi <goffi@goffi.org> |
|---|---|
| date | Wed, 01 Mar 2023 18:02:44 +0100 |
| parents | e1ccba0d2b71 |
| children | 0d517b596568 |
| rev | line source |
|---|---|
| 1209 | 1 ============ |
| 2 Installation | |
| 3 ============ | |
| 4 | |
| 5 This are the instructions to install Libervia (SàT) using Python. | |
| 6 Note that if you are using GNU/Linux, Libervia may already be present on your distribution. | |
| 7 | |
| 8 Libervia is a Salut à Toi frontend, the SàT backend must be installed first (if you | |
| 9 haven't installed it yet, it will be downloaded automatically as it is a dependency of | |
| 10 Libervia). Libervia and SàT backend must always have the same version (Libervia won't | |
| 11 start if the version backend has not the same version). | |
| 12 | |
| 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 | 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 | 27 Development Version |
| 28 ------------------- | |
| 29 | |
| 30 *Note for Arch users: a pkgbuild is available for your distribution on | |
| 31 AUR, check sat-libervia-hg (as well as other sat-\* packages).* | |
| 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 | 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 | 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 | 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 | 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 | 55 |
| 56 If you haven't done it for the backend, you need to install the media:: | |
| 57 | |
| 58 $ cd | |
|
1502
e1ccba0d2b71
doc: set `language` and use `libervia-media` instead of `sat_media`
Goffi <goffi@goffi.org>
parents:
1401
diff
changeset
|
59 $ hg clone https://repos.goffi.org/libervia-media |
| 1209 | 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] |
|
1502
e1ccba0d2b71
doc: set `language` and use `libervia-media` instead of `sat_media`
Goffi <goffi@goffi.org>
parents:
1401
diff
changeset
|
70 media_dir = ~/libervia-media |
|
1353
d1032f9ece5b
doc: updated installation instructions
Goffi <goffi@goffi.org>
parents:
1209
diff
changeset
|
71 |
|
1502
e1ccba0d2b71
doc: set `language` and use `libervia-media` instead of `sat_media`
Goffi <goffi@goffi.org>
parents:
1401
diff
changeset
|
72 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
|
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 | 85 Post Installation |
| 86 ----------------- | |
| 87 | |
| 88 Libervia uses its own XMPP account to fetch public data. You need to create a profile | |
| 89 named `libervia` linked to this account to launch Libervia. First create an account | |
| 90 dedicated to this on your XMPP server. For instance with `Prosody`_ you would enter | |
| 91 something like:: | |
| 92 | |
| 93 $ prosodyctl adduser libervia@example.net | |
| 94 | |
| 95 Where you'll obviously change ``libervia@example.net`` for the JID you want to use, with | |
| 96 your domain name. You'll then be prompted for a password. You can now create the | |
| 97 associated SàT profile:: | |
| 98 | |
| 99 $ jp profile create libervia -j libervia@example.net -p <libervia_password> | |
| 100 | |
| 101 .. note:: | |
| 102 | |
| 103 jp doesn't prompt for password yet, this means that the password is visible to anybody | |
| 104 looking at your screen and will stay in your shell history, and the password will be | |
| 105 visible for a few seconds in process list. If this is a concern for you (e.g. you use a | |
| 106 shared machine), use an other frontend to create the profile, or do the necessary to | |
| 107 remove the password from history. | |
| 108 | |
| 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 | 111 ``passphrase`` option to the profile password you have used in the command above: |
| 112 | |
| 113 .. sourcecode:: cfg | |
| 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 | 116 passphrase = <libervia_password> |
| 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 | 119 |
| 120 .. _Prosody: https://prosody.im | |
| 121 | |
| 122 | |
| 123 Usage | |
| 124 ===== | |
| 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 | 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 | 129 |
| 130 …or, if you want to launch it in foreground:: | |
| 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 | 133 |
| 134 You can stop it with:: | |
| 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 | 137 |
| 138 To know if backend is launched or not:: | |
| 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 | 141 |
| 142 | |
| 143 SàT Pubsub | |
| 144 ========== | |
| 145 | |
| 146 Some functionalities use advanced or experimental features of XMPP PubSub. We recommend to | |
| 147 use the SàT PubSub service that is a side project developed for the needs of Salut à Toi, | |
| 148 and consequently implements everything needed. Please refer to SàT PubSub documentation to | |
| 149 know how to install and use it. |