Mercurial > libervia-web
annotate doc/installation.rst @ 1495:081b4f8a63d8
pages (blog/edit): allow comments when editing a post
author | Goffi <goffi@goffi.org> |
---|---|
date | Sat, 14 May 2022 22:45:11 +0200 |
parents | aada5471d6bc |
children | e1ccba0d2b71 |
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 | |
59 $ hg clone https://repos.goffi.org/sat_media | |
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] |
d1032f9ece5b
doc: updated installation instructions
Goffi <goffi@goffi.org>
parents:
1209
diff
changeset
|
70 media_dir = ~/sat_media |
d1032f9ece5b
doc: updated installation instructions
Goffi <goffi@goffi.org>
parents:
1209
diff
changeset
|
71 |
d1032f9ece5b
doc: updated installation instructions
Goffi <goffi@goffi.org>
parents:
1209
diff
changeset
|
72 Of course, replace ``~/sat_media`` with the actual path you have used. |
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. |