Mercurial > libervia-web
annotate doc/installation.rst @ 1521:0d517b596568
doc: update installation instruction
| author | Goffi <goffi@goffi.org> |
|---|---|
| date | Wed, 07 Jun 2023 09:35:36 +0200 |
| parents | e1ccba0d2b71 |
| children | c62027660ec1 |
| rev | line source |
|---|---|
| 1209 | 1 ============ |
| 2 Installation | |
| 3 ============ | |
| 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 | 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 | 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 | 13 |
| 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 | 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 | 28 Development Version |
| 29 ------------------- | |
| 30 | |
| 31 *Note for Arch users: a pkgbuild is available for your distribution on | |
| 32 AUR, check sat-libervia-hg (as well as other sat-\* packages).* | |
| 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 | 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 | 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 | 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 | 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 | 56 |
| 57 If you haven't done it for the backend, you need to install the media:: | |
| 58 | |
| 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 | 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 | 86 Post Installation |
| 87 ----------------- | |
| 88 | |
| 89 Libervia uses its own XMPP account to fetch public data. You need to create a profile | |
| 90 named `libervia` linked to this account to launch Libervia. First create an account | |
| 91 dedicated to this on your XMPP server. For instance with `Prosody`_ you would enter | |
| 92 something like:: | |
| 93 | |
| 94 $ prosodyctl adduser libervia@example.net | |
| 95 | |
| 96 Where you'll obviously change ``libervia@example.net`` for the JID you want to use, with | |
| 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 | 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 | 101 |
| 102 .. note:: | |
| 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 | 110 |
| 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 | 113 ``passphrase`` option to the profile password you have used in the command above: |
| 114 | |
| 115 .. sourcecode:: cfg | |
| 116 | |
|
1521
0d517b596568
doc: update installation instruction
Goffi <goffi@goffi.org>
parents:
1502
diff
changeset
|
117 [web] |
| 1209 | 118 passphrase = <libervia_password> |
| 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 | 121 |
| 122 .. _Prosody: https://prosody.im | |
| 123 | |
| 124 | |
| 125 Usage | |
| 126 ===== | |
| 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 | 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 | 131 |
| 132 …or, if you want to launch it in foreground:: | |
| 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 | 135 |
| 136 You can stop it with:: | |
| 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 | 139 |
| 140 To know if backend is launched or not:: | |
| 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 | 143 |
| 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 | 147 |
| 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. |