Mercurial > libervia-web
annotate doc/installation.rst @ 1598:86c7a3a625d5
server: always start a new session on connection:
The session was kept when a user was connecting from service profile (but not from other
profiles), this was leading to session fixation vulnerability (an attacker on the same
machine could get service profile session cookie, and use it when a victim would log-in).
This patch fixes it by always starting a new session on connection.
fix 443
| author | Goffi <goffi@goffi.org> |
|---|---|
| date | Fri, 23 Feb 2024 13:35:24 +0100 |
| parents | c62027660ec1 |
| children | 64bfb6554131 |
| 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 |
|
c62027660ec1
doc (installation): update `pipx` instruction and remove `requirements.txt` mention
Goffi <goffi@goffi.org>
parents:
1521
diff
changeset
|
48 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
|
49 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
|
c62027660ec1
doc (installation): update `pipx` instruction and remove `requirements.txt` mention
Goffi <goffi@goffi.org>
parents:
1521
diff
changeset
|
50 |
|
1401
aada5471d6bc
doc: update installation instruction following renaming and new `requirements.txt`:
Goffi <goffi@goffi.org>
parents:
1353
diff
changeset
|
51 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
|
52 |
|
aada5471d6bc
doc: update installation instruction following renaming and new `requirements.txt`:
Goffi <goffi@goffi.org>
parents:
1353
diff
changeset
|
53 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
|
54 instance your ``$HOME`` directory:: |
| 1209 | 55 |
|
1401
aada5471d6bc
doc: update installation instruction following renaming and new `requirements.txt`:
Goffi <goffi@goffi.org>
parents:
1353
diff
changeset
|
56 $ cd |
|
aada5471d6bc
doc: update installation instruction following renaming and new `requirements.txt`:
Goffi <goffi@goffi.org>
parents:
1353
diff
changeset
|
57 |
|
aada5471d6bc
doc: update installation instruction following renaming and new `requirements.txt`:
Goffi <goffi@goffi.org>
parents:
1353
diff
changeset
|
58 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
|
59 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
|
60 there):: |
| 1209 | 61 |
|
1401
aada5471d6bc
doc: update installation instruction following renaming and new `requirements.txt`:
Goffi <goffi@goffi.org>
parents:
1353
diff
changeset
|
62 $ python3 -m venv libervia_venv |
|
aada5471d6bc
doc: update installation instruction following renaming and new `requirements.txt`:
Goffi <goffi@goffi.org>
parents:
1353
diff
changeset
|
63 $ source libervia_venv/bin/activate |
|
aada5471d6bc
doc: update installation instruction following renaming and new `requirements.txt`:
Goffi <goffi@goffi.org>
parents:
1353
diff
changeset
|
64 $ pip install -U pip wheel |
| 1209 | 65 |
|
1401
aada5471d6bc
doc: update installation instruction following renaming and new `requirements.txt`:
Goffi <goffi@goffi.org>
parents:
1353
diff
changeset
|
66 Then you need to clone the repository:: |
| 1209 | 67 |
|
1401
aada5471d6bc
doc: update installation instruction following renaming and new `requirements.txt`:
Goffi <goffi@goffi.org>
parents:
1353
diff
changeset
|
68 $ 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
|
69 |
|
1521
0d517b596568
doc: update installation instruction
Goffi <goffi@goffi.org>
parents:
1502
diff
changeset
|
70 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
|
71 |
|
1521
0d517b596568
doc: update installation instruction
Goffi <goffi@goffi.org>
parents:
1502
diff
changeset
|
72 $ pip install . |
| 1209 | 73 |
| 74 If you haven't done it for the backend, you need to install the media:: | |
| 75 | |
| 76 $ cd | |
|
1502
e1ccba0d2b71
doc: set `language` and use `libervia-media` instead of `sat_media`
Goffi <goffi@goffi.org>
parents:
1401
diff
changeset
|
77 $ hg clone https://repos.goffi.org/libervia-media |
| 1209 | 78 |
|
1401
aada5471d6bc
doc: update installation instruction following renaming and new `requirements.txt`:
Goffi <goffi@goffi.org>
parents:
1353
diff
changeset
|
79 then, create the directory ``~/.config/libervia``:: |
|
1353
d1032f9ece5b
doc: updated installation instructions
Goffi <goffi@goffi.org>
parents:
1209
diff
changeset
|
80 |
|
1401
aada5471d6bc
doc: update installation instruction following renaming and new `requirements.txt`:
Goffi <goffi@goffi.org>
parents:
1353
diff
changeset
|
81 $ mkdir -p ~/.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 and the file ``~/.config/libervia/libervia.conf`` containing: |
|
1353
d1032f9ece5b
doc: updated installation instructions
Goffi <goffi@goffi.org>
parents:
1209
diff
changeset
|
84 |
|
d1032f9ece5b
doc: updated installation instructions
Goffi <goffi@goffi.org>
parents:
1209
diff
changeset
|
85 .. sourcecode:: cfg |
|
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 [DEFAULT] |
|
1502
e1ccba0d2b71
doc: set `language` and use `libervia-media` instead of `sat_media`
Goffi <goffi@goffi.org>
parents:
1401
diff
changeset
|
88 media_dir = ~/libervia-media |
|
1353
d1032f9ece5b
doc: updated installation instructions
Goffi <goffi@goffi.org>
parents:
1209
diff
changeset
|
89 |
|
1502
e1ccba0d2b71
doc: set `language` and use `libervia-media` instead of `sat_media`
Goffi <goffi@goffi.org>
parents:
1401
diff
changeset
|
90 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
|
91 |
|
d1032f9ece5b
doc: updated installation instructions
Goffi <goffi@goffi.org>
parents:
1209
diff
changeset
|
92 Please check backend documentation for more details on the settings. |
|
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 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
|
95 instructions to install it. |
|
d1032f9ece5b
doc: updated installation instructions
Goffi <goffi@goffi.org>
parents:
1209
diff
changeset
|
96 |
|
d1032f9ece5b
doc: updated installation instructions
Goffi <goffi@goffi.org>
parents:
1209
diff
changeset
|
97 .. note:: |
|
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 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
|
100 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
|
101 root (or with ``sudo``). |
|
d1032f9ece5b
doc: updated installation instructions
Goffi <goffi@goffi.org>
parents:
1209
diff
changeset
|
102 |
| 1209 | 103 Post Installation |
| 104 ----------------- | |
| 105 | |
| 106 Libervia uses its own XMPP account to fetch public data. You need to create a profile | |
| 107 named `libervia` linked to this account to launch Libervia. First create an account | |
| 108 dedicated to this on your XMPP server. For instance with `Prosody`_ you would enter | |
| 109 something like:: | |
| 110 | |
| 111 $ prosodyctl adduser libervia@example.net | |
| 112 | |
| 113 Where you'll obviously change ``libervia@example.net`` for the JID you want to use, with | |
| 114 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
|
115 associated Libervia profile:: |
| 1209 | 116 |
|
1521
0d517b596568
doc: update installation instruction
Goffi <goffi@goffi.org>
parents:
1502
diff
changeset
|
117 $ li profile create libervia -j libervia@example.net -p <libervia_password> |
| 1209 | 118 |
| 119 .. note:: | |
| 120 | |
|
1521
0d517b596568
doc: update installation instruction
Goffi <goffi@goffi.org>
parents:
1502
diff
changeset
|
121 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
|
122 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
|
123 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
|
124 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
|
125 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
|
126 front of the command so that it doesn't appear in the history. |
| 1209 | 127 |
| 128 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
|
129 configuration. To do so, edit your ``libervia.conf`` and edit ``[libervia]`` and set the |
| 1209 | 130 ``passphrase`` option to the profile password you have used in the command above: |
| 131 | |
| 132 .. sourcecode:: cfg | |
| 133 | |
|
1521
0d517b596568
doc: update installation instruction
Goffi <goffi@goffi.org>
parents:
1502
diff
changeset
|
134 [web] |
| 1209 | 135 passphrase = <libervia_password> |
| 136 | |
|
1401
aada5471d6bc
doc: update installation instruction following renaming and new `requirements.txt`:
Goffi <goffi@goffi.org>
parents:
1353
diff
changeset
|
137 You should now be good to run the Libervia Web server. |
| 1209 | 138 |
| 139 .. _Prosody: https://prosody.im | |
| 140 | |
| 141 | |
| 142 Usage | |
| 143 ===== | |
| 144 | |
|
1401
aada5471d6bc
doc: update installation instruction following renaming and new `requirements.txt`:
Goffi <goffi@goffi.org>
parents:
1353
diff
changeset
|
145 To launch the Libervia Web server, enter:: |
| 1209 | 146 |
|
1401
aada5471d6bc
doc: update installation instruction following renaming and new `requirements.txt`:
Goffi <goffi@goffi.org>
parents:
1353
diff
changeset
|
147 $ libervia-web |
| 1209 | 148 |
| 149 …or, if you want to launch it in foreground:: | |
| 150 | |
|
1401
aada5471d6bc
doc: update installation instruction following renaming and new `requirements.txt`:
Goffi <goffi@goffi.org>
parents:
1353
diff
changeset
|
151 $ libervia-web fg |
| 1209 | 152 |
| 153 You can stop it with:: | |
| 154 | |
|
1401
aada5471d6bc
doc: update installation instruction following renaming and new `requirements.txt`:
Goffi <goffi@goffi.org>
parents:
1353
diff
changeset
|
155 $ libervia-web stop |
| 1209 | 156 |
| 157 To know if backend is launched or not:: | |
| 158 | |
|
1401
aada5471d6bc
doc: update installation instruction following renaming and new `requirements.txt`:
Goffi <goffi@goffi.org>
parents:
1353
diff
changeset
|
159 $ libervia-web status |
| 1209 | 160 |
| 161 | |
|
1521
0d517b596568
doc: update installation instruction
Goffi <goffi@goffi.org>
parents:
1502
diff
changeset
|
162 Libervia Pubsub |
|
0d517b596568
doc: update installation instruction
Goffi <goffi@goffi.org>
parents:
1502
diff
changeset
|
163 =============== |
| 1209 | 164 |
| 165 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
|
166 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
|
167 Libervia, and consequently implements everything needed. Please refer to Libervia PubSub |
|
0d517b596568
doc: update installation instruction
Goffi <goffi@goffi.org>
parents:
1502
diff
changeset
|
168 documentation to know how to install and use it. |