Mercurial > libervia-backend
comparison doc/overview.rst @ 3488:c80a0f864b5d
doc: updated doc following global renaming
author | Goffi <goffi@goffi.org> |
---|---|
date | Sun, 21 Mar 2021 18:23:58 +0100 |
parents | 7726916c1ba6 |
children | 0985c47ffd96 |
comparison
equal
deleted
inserted
replaced
3487:75427f0a5445 | 3488:c80a0f864b5d |
---|---|
1 ======== | 1 ======== |
2 Overview | 2 Overview |
3 ======== | 3 ======== |
4 | 4 |
5 To have a better understanding of Salut a Toi, this page gives a global view of what it is | 5 To have a better understanding of Libervia, this page gives a global view of what it is |
6 and what are the important concepts linked to it. You don't need to read this to use it, but you | 6 and what are the important concepts linked to it. You don't need to read this to use it, but you |
7 can if you wish to understand "who is doing what". | 7 can if you wish to understand "who is doing what". |
8 | 8 |
9 Salut à Toi (or SàT) is a XMPP client. `XMPP`_ is an open standard used | 9 Libervia is a XMPP client. `XMPP`_ is an open standard used for communication (notably |
10 for communication (notably instant messaging but not only). XMPP is a solid standard, | 10 instant messaging but not only). XMPP is a solid standard, which is decentralised and |
11 which is decentralised and federated. | 11 federated. |
12 | 12 |
13 SàT is not only focusing on instant messaging, and aims to be a universal communication | 13 Libervia is not only focusing on instant messaging, and aims to be a universal communication |
14 tools. In other words, you can use SàT to chat, but also to blog publicly or privately, to | 14 tools. In other words, you can use Libervia to chat, but also to blog publicly or privately, to |
15 share file, photo albums, to create events, to have discussion forum, etc. | 15 share file, photo albums, to create events, to have discussion forum, etc. |
16 | 16 |
17 SàT is actually a whole ecosystem, and is made in a way that you can use it with many | 17 Libervia is actually a whole ecosystem, and is made in a way that you can use it with many |
18 different interfaces (or "frontends"). There is a common central part which is called the | 18 different interfaces (or "frontends"). There is a common central part which is called the |
19 "backend", it handles most of the work, while frontends are mostly about the interactions | 19 "backend", it handles most of the work, while frontends are mostly about the interactions |
20 with user(s). | 20 with user(s). |
21 | 21 |
22 To work, as SàT is a XMPP **client**, a XMPP **server** is needed. You can either run your | 22 To work, as Libervia is a XMPP **client**, a XMPP **server** is needed. You can either run your |
23 own, or use an existing one (either public, or run by an organisation you belong to, like | 23 own, or use an existing one (either public, or run by an organisation you belong to, like |
24 family server, run by a friend, your company, university, association, etc.). If you want | 24 family server, run by a friend, your company, university, association, etc.). If you want |
25 to run your own server, there are already plenty of them and happily most of which are | 25 to run your own server, there are already plenty of them and happily most of which are |
26 `libre <https://en.wikipedia.org/wiki/Free_software>`_, you can check an `up-to-date list | 26 `libre <https://en.wikipedia.org/wiki/Free_software>`_, you can check an `up-to-date list |
27 on the XSF website <https://xmpp.org/software/servers.html>`_ (the XSF or *XMPP Standards | 27 on the XSF website <https://xmpp.org/software/servers.html>`_ (the XSF or *XMPP Standards |
28 Foundation* being the non-profit organisation taking care of the XMPP standard). | 28 Foundation* being the non-profit organisation taking care of the XMPP standard). |
29 | 29 |
30 So to summarise, Salut à Toi, or SàT, is a communication ecosystem. Technically, it is a | 30 So to summarise, Libervia is a communication ecosystem. Technically, it is a **XMPP |
31 **XMPP client** which connect to an **XMPP server**. SàT itself works with a **backend** | 31 client** which connect to an **XMPP server**. Libervia itself works with a **backend** and |
32 and one or many **frontends**. | 32 one or many **frontends**. |
33 | 33 |
34 .. _XMPP: https://xmpp.org | 34 .. _XMPP: https://xmpp.org |
35 | 35 |
36 | 36 |
37 Backend | 37 Backend |
60 not started, you'll see a message telling you so). In most installations, the backend | 60 not started, you'll see a message telling you so). In most installations, the backend |
61 should be started automatically when you want to use a frontend. | 61 should be started automatically when you want to use a frontend. |
62 | 62 |
63 Bellow you'll see a list of the official frontends currently maintained: | 63 Bellow you'll see a list of the official frontends currently maintained: |
64 | 64 |
65 Cagou | 65 Libervia Deskop/Mobile (Cagou) |
66 ----- | 66 ------------------------------ |
67 | 67 |
68 Cagou is the desktop/mobile frontend. It's probably the main interface for most users. It | 68 Libervia Desktop (alias ``Libervia Mobile`` or ``Cagou``) is the desktop/mobile frontend. |
69 is based on the `Kivy`_ framework and should run on most platforms (for now it is | 69 It's probably the main interface for most users. It is based on the `Kivy`_ framework and |
70 officially tested only on GNU/Linux and Android phones and tablets). | 70 should run on most platforms (for now it is officially tested only on GNU/Linux and |
71 Android phones and tablets). | |
71 | 72 |
72 .. _Kivy: https://kivy.org | 73 .. _Kivy: https://kivy.org |
73 | 74 |
74 Libervia | 75 Libervia Web |
75 -------- | 76 ------------ |
76 | 77 |
77 Libervia is the web frontend, and is the second main interface for most users. This | 78 The Web frontend is the second main interface for most users. This frontend has the |
78 frontend has the particularity to be in 2 parts: a server which serves HTTP content, and a | 79 particularity to be in 2 parts: a server which serves HTTP content, and a client which |
79 client which runs in the browser. So you have Libervia server which connect to SàT backend | 80 runs in the browser. So you have Libervia server which connect to Libervia backend which itself |
80 which itself connect to the XMPP server, and your browser will connect to Libervia server. | 81 connect to the XMPP server, and your browser will connect to Libervia server. |
81 | 82 |
82 In the browser, you can access the server in two ways: either directly with what we call | 83 In the browser, you can access the server in two ways: either directly with what we call |
83 **Libervia pages**, or with a JavaScript code in `single-page application`_ which is the | 84 **Libervia pages**, or with a JavaScript code in `single-page application`_ which is the |
84 **Libervia client** (or **Libervia web app**) that we have mentioned above. | 85 **Libervia client** (or **Libervia web app**) that we have mentioned above. |
85 | 86 |
86 The **Libervia pages** are web pages managing a single feature. They can work without | 87 The **Libervia pages** are web pages managing a single feature. They can work without |
87 JavaScript when it's possible (it's not the case for instant messaging or similar highly | 88 JavaScript when it's possible (it's not the case for instant messaging or similar highly |
88 dynamic contents). They aims to be simple and straightforward to use. | 89 dynamic contents). They aims to be simple and straightforward to use. |
89 | 90 |
90 The **Libervia client** is a highly dynamic web application, used to access more features. | 91 The **Libervia client** is a highly dynamic web application, used to access more features. |
91 It's more complete and may be well adapted if you want to let SàT running in a browser tab | 92 It's more complete and may be well adapted if you want to let Libervia running in a browser tab |
92 for an extended period. | 93 for an extended period. |
93 | 94 |
94 Please note that the current web application (SàT 0.7) will be completely rewritten for next 0.8 release. | |
95 | |
96 Last but not least, Libervia is also the central part of the new **web framework** of | 95 Last but not least, Libervia is also the central part of the new **web framework** of |
97 Salut à Toi. Indeed, in addition of being a frontend to SàT features (which is built with | 96 Libervia. Indeed, in addition of being a frontend to Libervia features (which is built with |
98 this framework), you can create totally different websites which are integrated in SàT | 97 this framework), you can create totally different websites which are integrated in Libervia |
99 (and so XMPP) ecosystem. This framework uses SàT template engine (based on `Jinja2`_) and | 98 (and so XMPP) ecosystem. This framework uses Libervia template engine (based on `Jinja2`_) and |
100 makes the creation of decentralised and federated websites simple. Thanks to this framework, | 99 makes the creation of decentralised and federated websites simple. Thanks to this framework, |
101 it's easy to experiment new ideas/features, or to change completely the look and feel of | 100 it's easy to experiment new ideas/features, or to change completely the look and feel of |
102 the Libervia frontend. | 101 the Libervia frontend. |
103 | 102 |
104 The `official SàT website`_ is made with Libervia web framework. | 103 The `official Libervia website`_ is made with Libervia web framework. |
105 | 104 |
106 .. _single-page application: https://en.wikipedia.org/wiki/Single-page_application | 105 .. _single-page application: https://en.wikipedia.org/wiki/Single-page_application |
107 .. _Jinja2: http://jinja.pocoo.org/ | 106 .. _Jinja2: http://jinja.pocoo.org/ |
108 .. _official SàT website: https://salut-a-toi.org | 107 .. _official Libervia website: https://salut-a-toi.org |
109 | 108 |
110 Primitivus | 109 Libervia TUI (Primitivus) |
111 ---------- | 110 ------------------------- |
112 | 111 |
113 Primitivus is the Terminal User Interface (TUI). In other words, it works in console and | 112 Libervia TUI (alias ``Primitivus``) is the Terminal User Interface. In other words, it |
114 is intended for people at ease with it. Its text only interface has several advantages: | 113 works in console and is intended for people at ease with it. Its text only interface has |
115 you get rid of many distracting things (like images), it works without graphical | 114 several advantages: you get rid of many distracting things (like images), it works without |
116 environment installed (which is often the case on servers) and it works on distant shell | 115 graphical environment installed (which is often the case on servers) and it works on |
117 (like `ssh`_) while staying gentle with your bandwidth. | 116 distant shell (like `ssh`_) while staying gentle with your bandwidth. |
118 | 117 |
119 Primitivus is shipped with the backend, so it should be always available once SàT is | 118 Primitivus is shipped with the backend, so it should be always available once Libervia is |
120 installed (but some distributions may provide it separately). | 119 installed (but some distributions may provide it separately). |
121 | 120 |
122 You can check :doc:`Primitivus documentation <primitivus/index>` for more details. | 121 You can check :doc:`Libervia TUI documentation <libervia-tui/index>` for more details. |
123 | 122 |
124 .. _ssh: https://en.wikipedia.org/wiki/Secure_Shell | 123 .. _ssh: https://en.wikipedia.org/wiki/Secure_Shell |
125 | 124 |
126 jp | 125 Libervia CLI (jp) |
127 -- | 126 ----------------- |
128 | 127 |
129 Jp is the Command Line Interface (CLI). It's a powerful tool which allows to do nearly | 128 Libervia CLI (alias ``li`` or ``jp``) is the Command Line Interface. It's a |
130 everything you can do with other frontends. Particularly useful if you want to check | 129 powerful tool which allows to do nearly everything you can do with other frontends. |
131 something quickly, or if you want to do some automation. | 130 Particularly useful if you want to check something quickly, or if you want to do some |
132 | 131 automation. |
133 You can check :doc:`jp documentation <jp/index>` documentation for more details. | 132 |
133 You can check :doc:`Libervia CLI documentation <libervia-cli/index>` documentation for more details. | |
134 | 134 |
135 .. _glossary: | 135 .. _glossary: |
136 | 136 |
137 Glossary | 137 Glossary |
138 ======== | 138 ======== |
139 | 139 |
140 While using SàT you may see some terms or concept. This section explain the most important | 140 While using Libervia you may see some terms or concept. This section explain the most important |
141 ones. | 141 ones. |
142 | 142 |
143 profile | 143 profile |
144 ------- | 144 ------- |
145 | 145 |
146 A profile is the name linked to an account data. Usually a profile correspond to an XMPP | 146 A profile is the name linked to an account data. Usually a profile correspond to an XMPP |
147 account, but you can have several profiles using the same XMPP account (with different | 147 account, but you can have several profiles using the same XMPP account (with different |
148 parameters) even if this is not usual. | 148 parameters) even if this is not usual. |
149 | 149 |
150 On a SàT installation used by a single user, the profiles are usually used for multiple | 150 On a Libervia installation used by a single user, the profiles are usually used for multiple |
151 accounts. On a multi-users installations, there is usually one profile per user. | 151 accounts. On a multi-users installations, there is usually one profile per user. |
152 | 152 |
153 When you connect to a SàT frontend, you need to specify a profile and the associated password. The profile password is not the same as the password of the XMPP account. While this may sounds confusing, there are several reason why we use this notion of profile instead of directly the XMPP account/password: | 153 When you connect to a Libervia frontend, you need to specify a profile and the associated password. The profile password is not the same as the password of the XMPP account. While this may sounds confusing, there are several reason why we use this notion of profile instead of directly the XMPP account/password: |
154 | 154 |
155 - SàT needs to know the plain XMPP password to connect, and it is encrypted in database. | 155 - Libervia needs to know the plain XMPP password to connect, and it is encrypted in database. |
156 The profile password is used to encrypt/decrypt it, this way only a `password hash`_ is | 156 The profile password is used to encrypt/decrypt it, this way only a `password hash`_ is |
157 stored and the XMPP password is encrypted `at rest`_. | 157 stored and the XMPP password is encrypted `at rest`_. |
158 | 158 |
159 - As a further benefit, several passwords could be associated to the same profile (this | 159 - As a further benefit, several passwords could be associated to the same profile (this |
160 feature is currently not used in SàT). | 160 feature is currently not used in Libervia). |
161 | 161 |
162 - profile password can be empty, in which case no password is requested when a profile is | 162 - profile password can be empty, in which case no password is requested when a profile is |
163 used | 163 used |
164 | 164 |
165 .. note:: | 165 .. note:: |
184 most important one is ``@DEFAULT@`` which, as you can guess, means the default profile. | 184 most important one is ``@DEFAULT@`` which, as you can guess, means the default profile. |
185 | 185 |
186 bridge | 186 bridge |
187 ------ | 187 ------ |
188 | 188 |
189 The "bridge" is the name used to design Salut à Toi's `IPC`_, or in other words the way | 189 The "bridge" is the name used to design Libervia's `IPC`_, or in other words the way |
190 the backend communicate with frontends. Several bridges can be used, the default one being | 190 the backend communicate with frontends. Several bridges can be used, the default one being |
191 `D-Bus`_. | 191 `D-Bus`_. |
192 | 192 |
193 The other available bridges are: | 193 The other available bridges are: |
194 | 194 |
203 .. _IPC: https://en.wikipedia.org/wiki/Inter-process_communication | 203 .. _IPC: https://en.wikipedia.org/wiki/Inter-process_communication |
204 .. _D-Bus: https://www.freedesktop.org/wiki/Software/dbus/ | 204 .. _D-Bus: https://www.freedesktop.org/wiki/Software/dbus/ |
205 .. _Perspective Broker: https://twistedmatrix.com/documents/current/core/howto/pb-intro.html | 205 .. _Perspective Broker: https://twistedmatrix.com/documents/current/core/howto/pb-intro.html |
206 .. _Twisted: https://twistedmatrix.com | 206 .. _Twisted: https://twistedmatrix.com |
207 | 207 |
208 SàT Media | 208 Libervia Media |
209 --------- | 209 -------------- |
210 | 210 |
211 Most of the frontends use images or other media. To avoid duplication and to make the code | 211 Most of the frontends use images or other media. To avoid duplication and to make the code |
212 repositories lighter, those media are grouped in a separate repository. The SàT media | 212 repositories lighter, those media are grouped in a separate repository. The Libervia media |
213 repository is available at https://repos.goffi.org/sat_media. You can also download media | 213 repository is available at https://repos.goffi.org/sat_media. You can also download media |
214 at https://ftp.goffi.org/sat_media/sat_media.tar.bz2. The path where SàT media are | 214 at https://ftp.goffi.org/sat_media/sat_media.tar.bz2. The path where Libervia media are |
215 installed must be specified in ``sat.conf`` in ``media_dir`` option of the ``[DEFAULT`` | 215 installed must be specified in ``sat.conf`` in ``media_dir`` option of the ``[DEFAULT`` |
216 section. | 216 section. |
217 | 217 |
218 SàT Templates | 218 Libervia Templates |
219 ------------- | 219 ------------------ |
220 | 220 |
221 SàT embeds a `Jinja2`_ template engine (see `Libervia`_ above). "SàT templates" refers to | 221 Libervia embeds a `Jinja2`_ template engine (see `Libervia Web`_ above). "Libervia templates" refers to |
222 the default templates (i.e. the official templates, the ones used in default Libervia pages). Those template may also be used by other frontends than Libervia (jp can use them with the :ref:`jp-output` arguments). | 222 the default templates (i.e. the official templates, the ones used in default Libervia pages). Those template may also be used by other frontends than Libervia (jp can use them with the :ref:`libervia-cli_output` arguments). |
223 | 223 |
224 SàT templates repository is available at https://repos.goffi.org/sat_templates, they can | 224 Libervia templates repository is available at https://repos.goffi.org/sat_templates, they can |
225 also be downloaded at `PyPI <https://pypi.org/project/sat-templates/>`_ and will be | 225 also be downloaded at `PyPI <https://pypi.org/project/sat-templates/>`_ and will be |
226 installed automatically if you install Libervia. | 226 installed automatically if you install Libervia. |
227 | 227 |
228 Related projects | 228 Related projects |
229 ================ | 229 ================ |
230 | 230 |
231 Some project are closely related to Salut à Toi, here is a list of official related | 231 Some project are closely related to Libervia, here is a list of official related |
232 project. | 232 project. |
233 | 233 |
234 SàT PubSub | 234 Libervia PubSub |
235 ---------- | 235 --------------- |
236 | 236 |
237 Numerous features of Salut à Toi are taking profit of `PubSub`_ functionalities of XMPP. | 237 Numerous features of Libervia are taking profit of `PubSub`_ functionalities of XMPP. |
238 Because PubSub implementations in the wild are not all on the same level, and some | 238 Because PubSub implementations in the wild are not all on the same level, and some |
239 experimental features are sometimes explored, a PubSub service as been written | 239 experimental features are sometimes explored, a PubSub service as been written |
240 specifically for the needs of SàT (but it's not depending on SàT and any XMPP software can | 240 specifically for the needs of Libervia (but it's not depending on Libervia and any XMPP software can |
241 use it). | 241 use it). |
242 | 242 |
243 SàT PubSub aims to be a feature complete, server-independent PubSub implementation, and | 243 Libervia PubSub aims to be a feature complete, server-independent PubSub implementation, and |
244 try to be up-to-date with latest XMPP PubSub extensions. It is the privileged service to | 244 try to be up-to-date with latest XMPP PubSub extensions. It is the privileged service to |
245 use with SàT because it supports everything needed (but SàT can work with any XMPP PubSub | 245 use with Libervia because it supports everything needed (but Libervia can work with any XMPP PubSub |
246 service, it will adapt itself to available features). | 246 service, it will adapt itself to available features). |
247 | 247 |
248 SàT PubSub can also be used as a `PEP`_ service, if some XMPP extensions are supported by | 248 Libervia PubSub can also be used as a `PEP`_ service, if some XMPP extensions are supported by |
249 your server (see below). | 249 your server (see below). |
250 | 250 |
251 .. _PubSub: https://xmpp.org/about/technology-overview.html#pubsub | 251 .. _PubSub: https://xmpp.org/about/technology-overview.html#pubsub |
252 .. _PEP: https://xmpp.org/extensions/xep-0163.html | 252 .. _PEP: https://xmpp.org/extensions/xep-0163.html |
253 | 253 |
254 XMPP Extension Protocols | 254 XMPP Extension Protocols |
255 ------------------------ | 255 ------------------------ |
256 | 256 |
257 For the needs of SàT or SàT PubSub, some `XMPP Extension Protocols`_ (or XEP) have been | 257 For the needs of Libervia or Libervia PubSub, some `XMPP Extension Protocols`_ (or XEP) have been |
258 proposed and got an official number. The current list of extensions is: | 258 proposed and got an official number. The current list of extensions is: |
259 | 259 |
260 `XEP-0355`_: Namespace Delegation | 260 `XEP-0355`_: Namespace Delegation |
261 This has been proposed for the needs of SàT PubSub, and allows the XMPP server to | 261 This has been proposed for the needs of Libervia PubSub, and allows the XMPP server to |
262 "delegate" some features management to a third party service. It is needed to use SàT | 262 "delegate" some features management to a third party service. It is needed to use Libervia |
263 Pubsub as a PEP service. | 263 Pubsub as a PEP service. |
264 | 264 |
265 `XEP-0356`_: Privileged Entity | 265 `XEP-0356`_: Privileged Entity |
266 In the same spirit as previous one, this has been done so SàT PubSub could be used as a | 266 In the same spirit as previous one, this has been done so Libervia PubSub could be used as a |
267 PEP service. This extensions allows a "component" (which is more or less a server | 267 PEP service. This extensions allows a "component" (which is more or less a server |
268 generic plugin) to gain some privileged access to data such as presence information, | 268 generic plugin) to gain some privileged access to data such as presence information, |
269 roster or to send a message like if it was sent by the server. | 269 roster or to send a message like if it was sent by the server. |
270 | 270 |
271 `XEP-0413`_: Order-By | 271 `XEP-0413`_: Order-By |
272 This extension is used to specify the sorting order in which a client wishes to retrieve | 272 This extension is used to specify the sorting order in which a client wishes to retrieve |
273 some results. It is notably used by SàT and SàT PubSub to retrieve items like blog posts | 273 some results. It is notably used by Libervia and Libervia PubSub to retrieve items like blog posts |
274 or tickets in creation order or order of last modification. | 274 or tickets in creation order or order of last modification. |
275 | 275 |
276 .. _XEP-0355: https://xmpp.org/extensions/xep-0355.html | 276 .. _XEP-0355: https://xmpp.org/extensions/xep-0355.html |
277 .. _XEP-0356: https://xmpp.org/extensions/xep-0356.html | 277 .. _XEP-0356: https://xmpp.org/extensions/xep-0356.html |
278 .. _XEP-0413: https://xmpp.org/extensions/xep-0413.html | 278 .. _XEP-0413: https://xmpp.org/extensions/xep-0413.html |
282 Prosody's `mod_delegation`_ and `mod_privilege`_ | 282 Prosody's `mod_delegation`_ and `mod_privilege`_ |
283 ------------------------------------------------- | 283 ------------------------------------------------- |
284 | 284 |
285 Prosody modules have been created to implement the *Namespace Delegation* and *Privileged | 285 Prosody modules have been created to implement the *Namespace Delegation* and *Privileged |
286 Entity* extensions mentioned above. If you use Prosody, you'll have to activate those 2 | 286 Entity* extensions mentioned above. If you use Prosody, you'll have to activate those 2 |
287 modules to use SàT PubSub as a PEP service. | 287 modules to use Libervia PubSub as a PEP service. |
288 | 288 |
289 .. _mod_privilege: https://modules.prosody.im/mod_privilege.html | 289 .. _mod_privilege: https://modules.prosody.im/mod_privilege.html |
290 .. _mod_delegation: https://modules.prosody.im/mod_delegation.html | 290 .. _mod_delegation: https://modules.prosody.im/mod_delegation.html |
291 | 291 |
292 SàT official website | 292 Libervia official website |
293 -------------------- | 293 ------------------------- |
294 | 294 |
295 The official website is made with Libervia web framework. You'll find it at https://repos.goffi.org/sat_web_site | 295 The official website is made with Libervia web framework. You'll find it at https://repos.goffi.org/sat_web_site |
296 | 296 |
297 Salut | 297 Salut |
298 ----- | 298 ----- |
299 Probably the smaller side project used by SàT, it is a simple users directory (registration must be done explicitly by users) using `XEP-0055`_ (Jabber Search). | 299 Probably the smaller side project used by Libervia, it is a simple users directory (registration must be done explicitly by users) using `XEP-0055`_ (Jabber Search). |
300 | 300 |
301 You'll find it at https://repos.goffi.org/salut/ | 301 You'll find it at https://repos.goffi.org/salut/ |
302 | 302 |
303 .. _XEP-0055: https://xmpp.org/extensions/xep-0055.html | 303 .. _XEP-0055: https://xmpp.org/extensions/xep-0055.html |