Mercurial > libervia-web
annotate doc/installation.rst @ 1607:64bfb6554131
doc (installation): add missing pipx link
| author | Goffi <goffi@goffi.org> |
|---|---|
| date | Thu, 30 May 2024 23:56:05 +0200 |
| parents | c62027660ec1 |
| children |
| 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 | |
|
1552
c62027660ec1
doc (installation): update `pipx` instruction and remove `requirements.txt` mention
Goffi <goffi@goffi.org>
parents:
1521
diff
changeset
|
34 |
|
c62027660ec1
doc (installation): update `pipx` instruction and remove `requirements.txt` mention
Goffi <goffi@goffi.org>
parents:
1521
diff
changeset
|
35 Installation With pipx |
|
c62027660ec1
doc (installation): update `pipx` instruction and remove `requirements.txt` mention
Goffi <goffi@goffi.org>
parents:
1521
diff
changeset
|
36 ~~~~~~~~~~~~~~~~~~~~~~ |
|
c62027660ec1
doc (installation): update `pipx` instruction and remove `requirements.txt` mention
Goffi <goffi@goffi.org>
parents:
1521
diff
changeset
|
37 |
|
c62027660ec1
doc (installation): update `pipx` instruction and remove `requirements.txt` mention
Goffi <goffi@goffi.org>
parents:
1521
diff
changeset
|
38 If you have `pipx`_ installed, you can install the development version of the web frontend |
|
c62027660ec1
doc (installation): update `pipx` instruction and remove `requirements.txt` mention
Goffi <goffi@goffi.org>
parents:
1521
diff
changeset
|
39 by utilizing the same environment as the backend. First, install the backend as detailed |
|
c62027660ec1
doc (installation): update `pipx` instruction and remove `requirements.txt` mention
Goffi <goffi@goffi.org>
parents:
1521
diff
changeset
|
40 in the `backend installation instructions |
|
c62027660ec1
doc (installation): update `pipx` instruction and remove `requirements.txt` mention
Goffi <goffi@goffi.org>
parents:
1521
diff
changeset
|
41 <https://libervia.org/__b/doc/backend/installation.html#installation-with-pipx>`_. After |
|
c62027660ec1
doc (installation): update `pipx` instruction and remove `requirements.txt` mention
Goffi <goffi@goffi.org>
parents:
1521
diff
changeset
|
42 that, install the web frontend with the following command: |
|
c62027660ec1
doc (installation): update `pipx` instruction and remove `requirements.txt` mention
Goffi <goffi@goffi.org>
parents:
1521
diff
changeset
|
43 |
|
c62027660ec1
doc (installation): update `pipx` instruction and remove `requirements.txt` mention
Goffi <goffi@goffi.org>
parents:
1521
diff
changeset
|
44 .. code-block:: bash |
|
c62027660ec1
doc (installation): update `pipx` instruction and remove `requirements.txt` mention
Goffi <goffi@goffi.org>
parents:
1521
diff
changeset
|
45 |
|
c62027660ec1
doc (installation): update `pipx` instruction and remove `requirements.txt` mention
Goffi <goffi@goffi.org>
parents:
1521
diff
changeset
|
46 $ pipx inject libervia-backend hg+https://repos.goffi.org/libervia-web |
|
c62027660ec1
doc (installation): update `pipx` instruction and remove `requirements.txt` mention
Goffi <goffi@goffi.org>
parents:
1521
diff
changeset
|
47 |
|
1607
64bfb6554131
doc (installation): add missing pipx link
Goffi <goffi@goffi.org>
parents:
1552
diff
changeset
|
48 .. _pipx: https://pipx.pypa.io |
|
64bfb6554131
doc (installation): add missing pipx link
Goffi <goffi@goffi.org>
parents:
1552
diff
changeset
|
49 |
|
1552
c62027660ec1
doc (installation): update `pipx` instruction and remove `requirements.txt` mention
Goffi <goffi@goffi.org>
parents:
1521
diff
changeset
|
50 Installation With Virtual Environment And pip |
|
c62027660ec1
doc (installation): update `pipx` instruction and remove `requirements.txt` mention
Goffi <goffi@goffi.org>
parents:
1521
diff
changeset
|
51 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
|
c62027660ec1
doc (installation): update `pipx` instruction and remove `requirements.txt` mention
Goffi <goffi@goffi.org>
parents:
1521
diff
changeset
|
52 |
|
1401
aada5471d6bc
doc: update installation instruction following renaming and new `requirements.txt`:
Goffi <goffi@goffi.org>
parents:
1353
diff
changeset
|
53 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
|
54 |
|
aada5471d6bc
doc: update installation instruction following renaming and new `requirements.txt`:
Goffi <goffi@goffi.org>
parents:
1353
diff
changeset
|
55 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
|
56 instance your ``$HOME`` directory:: |
| 1209 | 57 |
|
1401
aada5471d6bc
doc: update installation instruction following renaming and new `requirements.txt`:
Goffi <goffi@goffi.org>
parents:
1353
diff
changeset
|
58 $ cd |
|
aada5471d6bc
doc: update installation instruction following renaming and new `requirements.txt`:
Goffi <goffi@goffi.org>
parents:
1353
diff
changeset
|
59 |
|
aada5471d6bc
doc: update installation instruction following renaming and new `requirements.txt`:
Goffi <goffi@goffi.org>
parents:
1353
diff
changeset
|
60 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
|
61 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
|
62 there):: |
| 1209 | 63 |
|
1401
aada5471d6bc
doc: update installation instruction following renaming and new `requirements.txt`:
Goffi <goffi@goffi.org>
parents:
1353
diff
changeset
|
64 $ python3 -m venv libervia_venv |
|
aada5471d6bc
doc: update installation instruction following renaming and new `requirements.txt`:
Goffi <goffi@goffi.org>
parents:
1353
diff
changeset
|
65 $ source libervia_venv/bin/activate |
|
aada5471d6bc
doc: update installation instruction following renaming and new `requirements.txt`:
Goffi <goffi@goffi.org>
parents:
1353
diff
changeset
|
66 $ pip install -U pip wheel |
| 1209 | 67 |
|
1401
aada5471d6bc
doc: update installation instruction following renaming and new `requirements.txt`:
Goffi <goffi@goffi.org>
parents:
1353
diff
changeset
|
68 Then you need to clone the repository:: |
| 1209 | 69 |
|
1401
aada5471d6bc
doc: update installation instruction following renaming and new `requirements.txt`:
Goffi <goffi@goffi.org>
parents:
1353
diff
changeset
|
70 $ 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
|
71 |
|
1521
0d517b596568
doc: update installation instruction
Goffi <goffi@goffi.org>
parents:
1502
diff
changeset
|
72 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
|
73 |
|
1521
0d517b596568
doc: update installation instruction
Goffi <goffi@goffi.org>
parents:
1502
diff
changeset
|
74 $ pip install . |
| 1209 | 75 |
| 76 If you haven't done it for the backend, you need to install the media:: | |
| 77 | |
| 78 $ cd | |
|
1502
e1ccba0d2b71
doc: set `language` and use `libervia-media` instead of `sat_media`
Goffi <goffi@goffi.org>
parents:
1401
diff
changeset
|
79 $ hg clone https://repos.goffi.org/libervia-media |
| 1209 | 80 |
|
1401
aada5471d6bc
doc: update installation instruction following renaming and new `requirements.txt`:
Goffi <goffi@goffi.org>
parents:
1353
diff
changeset
|
81 then, create the directory ``~/.config/libervia``:: |
|
1353
d1032f9ece5b
doc: updated installation instructions
Goffi <goffi@goffi.org>
parents:
1209
diff
changeset
|
82 |
|
1401
aada5471d6bc
doc: update installation instruction following renaming and new `requirements.txt`:
Goffi <goffi@goffi.org>
parents:
1353
diff
changeset
|
83 $ mkdir -p ~/.config/libervia |
|
1353
d1032f9ece5b
doc: updated installation instructions
Goffi <goffi@goffi.org>
parents:
1209
diff
changeset
|
84 |
|
1401
aada5471d6bc
doc: update installation instruction following renaming and new `requirements.txt`:
Goffi <goffi@goffi.org>
parents:
1353
diff
changeset
|
85 and the file ``~/.config/libervia/libervia.conf`` containing: |
|
1353
d1032f9ece5b
doc: updated installation instructions
Goffi <goffi@goffi.org>
parents:
1209
diff
changeset
|
86 |
|
d1032f9ece5b
doc: updated installation instructions
Goffi <goffi@goffi.org>
parents:
1209
diff
changeset
|
87 .. sourcecode:: cfg |
|
d1032f9ece5b
doc: updated installation instructions
Goffi <goffi@goffi.org>
parents:
1209
diff
changeset
|
88 |
|
d1032f9ece5b
doc: updated installation instructions
Goffi <goffi@goffi.org>
parents:
1209
diff
changeset
|
89 [DEFAULT] |
|
1502
e1ccba0d2b71
doc: set `language` and use `libervia-media` instead of `sat_media`
Goffi <goffi@goffi.org>
parents:
1401
diff
changeset
|
90 media_dir = ~/libervia-media |
|
1353
d1032f9ece5b
doc: updated installation instructions
Goffi <goffi@goffi.org>
parents:
1209
diff
changeset
|
91 |
|
1502
e1ccba0d2b71
doc: set `language` and use `libervia-media` instead of `sat_media`
Goffi <goffi@goffi.org>
parents:
1401
diff
changeset
|
92 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
|
93 |
|
d1032f9ece5b
doc: updated installation instructions
Goffi <goffi@goffi.org>
parents:
1209
diff
changeset
|
94 Please check backend documentation for more details on the settings. |
|
d1032f9ece5b
doc: updated installation instructions
Goffi <goffi@goffi.org>
parents:
1209
diff
changeset
|
95 |
|
d1032f9ece5b
doc: updated installation instructions
Goffi <goffi@goffi.org>
parents:
1209
diff
changeset
|
96 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
|
97 instructions to install it. |
|
d1032f9ece5b
doc: updated installation instructions
Goffi <goffi@goffi.org>
parents:
1209
diff
changeset
|
98 |
|
d1032f9ece5b
doc: updated installation instructions
Goffi <goffi@goffi.org>
parents:
1209
diff
changeset
|
99 .. note:: |
|
d1032f9ece5b
doc: updated installation instructions
Goffi <goffi@goffi.org>
parents:
1209
diff
changeset
|
100 |
|
d1032f9ece5b
doc: updated installation instructions
Goffi <goffi@goffi.org>
parents:
1209
diff
changeset
|
101 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
|
102 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
|
103 root (or with ``sudo``). |
|
d1032f9ece5b
doc: updated installation instructions
Goffi <goffi@goffi.org>
parents:
1209
diff
changeset
|
104 |
| 1209 | 105 Post Installation |
| 106 ----------------- | |
| 107 | |
| 108 Libervia uses its own XMPP account to fetch public data. You need to create a profile | |
| 109 named `libervia` linked to this account to launch Libervia. First create an account | |
| 110 dedicated to this on your XMPP server. For instance with `Prosody`_ you would enter | |
| 111 something like:: | |
| 112 | |
| 113 $ prosodyctl adduser libervia@example.net | |
| 114 | |
| 115 Where you'll obviously change ``libervia@example.net`` for the JID you want to use, with | |
| 116 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
|
117 associated Libervia profile:: |
| 1209 | 118 |
|
1521
0d517b596568
doc: update installation instruction
Goffi <goffi@goffi.org>
parents:
1502
diff
changeset
|
119 $ li profile create libervia -j libervia@example.net -p <libervia_password> |
| 1209 | 120 |
| 121 .. note:: | |
| 122 | |
|
1521
0d517b596568
doc: update installation instruction
Goffi <goffi@goffi.org>
parents:
1502
diff
changeset
|
123 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
|
124 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
|
125 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
|
126 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
|
127 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
|
128 front of the command so that it doesn't appear in the history. |
| 1209 | 129 |
| 130 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
|
131 configuration. To do so, edit your ``libervia.conf`` and edit ``[libervia]`` and set the |
| 1209 | 132 ``passphrase`` option to the profile password you have used in the command above: |
| 133 | |
| 134 .. sourcecode:: cfg | |
| 135 | |
|
1521
0d517b596568
doc: update installation instruction
Goffi <goffi@goffi.org>
parents:
1502
diff
changeset
|
136 [web] |
| 1209 | 137 passphrase = <libervia_password> |
| 138 | |
|
1401
aada5471d6bc
doc: update installation instruction following renaming and new `requirements.txt`:
Goffi <goffi@goffi.org>
parents:
1353
diff
changeset
|
139 You should now be good to run the Libervia Web server. |
| 1209 | 140 |
| 141 .. _Prosody: https://prosody.im | |
| 142 | |
| 143 | |
| 144 Usage | |
| 145 ===== | |
| 146 | |
|
1401
aada5471d6bc
doc: update installation instruction following renaming and new `requirements.txt`:
Goffi <goffi@goffi.org>
parents:
1353
diff
changeset
|
147 To launch the Libervia Web server, enter:: |
| 1209 | 148 |
|
1401
aada5471d6bc
doc: update installation instruction following renaming and new `requirements.txt`:
Goffi <goffi@goffi.org>
parents:
1353
diff
changeset
|
149 $ libervia-web |
| 1209 | 150 |
| 151 …or, if you want to launch it in foreground:: | |
| 152 | |
|
1401
aada5471d6bc
doc: update installation instruction following renaming and new `requirements.txt`:
Goffi <goffi@goffi.org>
parents:
1353
diff
changeset
|
153 $ libervia-web fg |
| 1209 | 154 |
| 155 You can stop it with:: | |
| 156 | |
|
1401
aada5471d6bc
doc: update installation instruction following renaming and new `requirements.txt`:
Goffi <goffi@goffi.org>
parents:
1353
diff
changeset
|
157 $ libervia-web stop |
| 1209 | 158 |
| 159 To know if backend is launched or not:: | |
| 160 | |
|
1401
aada5471d6bc
doc: update installation instruction following renaming and new `requirements.txt`:
Goffi <goffi@goffi.org>
parents:
1353
diff
changeset
|
161 $ libervia-web status |
| 1209 | 162 |
| 163 | |
|
1521
0d517b596568
doc: update installation instruction
Goffi <goffi@goffi.org>
parents:
1502
diff
changeset
|
164 Libervia Pubsub |
|
0d517b596568
doc: update installation instruction
Goffi <goffi@goffi.org>
parents:
1502
diff
changeset
|
165 =============== |
| 1209 | 166 |
| 167 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
|
168 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
|
169 Libervia, and consequently implements everything needed. Please refer to Libervia PubSub |
|
0d517b596568
doc: update installation instruction
Goffi <goffi@goffi.org>
parents:
1502
diff
changeset
|
170 documentation to know how to install and use it. |