Mercurial > libervia-backend

comparison doc/overview.rst @ 3021:8ec35cf13f66

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
doc: added, overview, configuration and Primitivus documentation + some small modifications
author Goffi <goffi@goffi.org>
date Sun, 21 Jul 2019 22:14:30 +0200
parents
children 03fe31effa7f
comparison
equal deleted inserted replaced
3020:af9d71303605 3021:8ec35cf13f66
1 ====================
2 Salut à Toi Overview
3 ====================
4
5 To have a better understanding of Salut a Toi, 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
7 can if you wish to understand "who is doing what".
8
9 Salut à Toi (or SàT) is a XMPP client. `XMPP`_ is an open standard used
10 for communication (notably instant messaging but not only). XMPP is a solid standard,
11 which is decentralised and federated.
12
13 SàT 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
15 share file, photo albums, to create events, to have discussion forum, etc.
16
17 SàT 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
19 "backend", it handles most of the work, while frontends are mostly about the interactions
20 with user(s).
21
22 To work, as SàT 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
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
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
28 Foundation* being the non-profit organisation taking care of the XMPP standard).
29
30 So to summarise, Salut à Toi, or SàT, is a communication ecosystem. Technically, it is a
31 **XMPP client** which connect to an **XMPP server**. SàT itself works with a **backend**
32 and one or many **frontends**.
33
34 .. _XMPP: https://xmpp.org
35
36
37 Backend
38 =======
39
40 The backend is a daemon, that means that it's a service running in the background.
41 It takes its main configuration from a file named ``sat.conf`` and can be in different
42 locations (see below). It uses data in a directory called ``local_dir``, and which
43 default, on suitable platforms, to the corresponding `XDG directory`_, which is most of
44 time ``~/.local/share/sat``. In this directory, you'll find the main database in the
45 ``sat.db`` file, which is a `SQLite`_ database.
46
47 The backend is run and stopped with the ``sat`` binary. Running it without argument launch
48 the backend in the background, with ``sat fg`` you run it in the foreground (you'll see
49 log directly and can stop the backend with ``Ctrl + c``). The ``sat status`` commands help
50 you discover if the backend is running or stopped.
51
52 .. _XDG directory: https://www.freedesktop.org/wiki/Software/xdg-user-dirs/
53 .. _SQLite: https://sqlite.org
54
55 Frontends
56 =========
57
58 Frontends are used to make the interface between user and the backend. Frontends are
59 adapted to different use cases, and must be started after the backend (if the backend is
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.
62
63 Bellow you'll see a list of the official frontends currently maintained:
64
65 Cagou
66 -----
67
68 Cagou is the desktop/mobile frontend. It's probably the main interface for most users. It
69 is based on the `Kivy`_ framework and should run of most platforms (for now it is
70 officially tested only on GNU/Linux and Android phones and tablets).
71
72 .. _Kivy: https://kivy.org
73
74 Libervia
75 --------
76
77 Libervia is the web frontend, and is the second main interface for most users. This
78 frontend has the particularity to be in 2 parts: a server which serves HTTP content, and a
79 client which runs in the browser. So you have Libervia server which connect to SàT backend
80 which itself connect to the XMPP server, and your browser will connect to Libervia server.
81
82 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 client** (or **Libervia web app**) that we have mentioned above.
85
86 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 dynamic contents). They aims to be simple and straightforward to use.
89
90 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 for an extended period.
93
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
97 Salut à Toi. Indeed, in addition of being a frontend to SàT features (which is built with
98 this framework), you can create totally different websites which are integrated in SàT
99 (and so XMPP) ecosystem. This framework uses SàT template engine (based on `Jinja2`_) and
100 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
102 the Libervia frontend.
103
104 The `official SàT website`_ is made with Libervia web framework.
105
106 .. _single-page application: https://en.wikipedia.org/wiki/Single-page_application
107 .. _Jinja2: http://jinja.pocoo.org/
108 .. _official SàT website: https://salut-a-toi.org
109
110 Primitivus
111 ----------
112
113 Primitivus is the Terminal User Interface (TUI). In other words, it works in console and
114 is intended for people at ease with it. Its text only interface has several advantages:
115 you get rid of many distracting things (like images), it works without graphical
116 environment installed (which is often the case on servers) and it works on distant shell
117 (like `ssh`_) while staying gentle with your bandwidth.
118
119 Primitivus is shipped with the backend, so it should be always available once SàT is
120 installed (but some distributions may provide it separately).
121
122 You can check :ref:`primitivus-documentation` documentation for more details.
123
124 .. _ssh: https://en.wikipedia.org/wiki/Secure_Shell
125
126 jp
127 --
128
129 Jp is the Command Line Interface (CLI). It's a powerful tool which allows to do nearly
130 everything you can do with other frontends. Particularly useful if you want to check
131 something quickly, or if you want to do some automation.
132
133 You can check :ref:`jp-documentation` documentation for more details.
134
135
136 Glossary
137 ========
138
139 While using SàT you may see some terms or concept. This section explain the most important
140 ones.
141
142 profile
143 -------
144
145 A profile is the name linked to an account data. Usually a profile correspond to an XMPP
146 account, but you can have several profiles using the same XMPP account (with different
147 parameters) even if this is not usual.
148
149 On a SàT installation used by a single user, the profiles are usually used for multiple
150 accounts. On a multi-users installations, there is usually one profile per user.
151
152 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
154 - SàT needs to know the plain XMPP password to connect, and it is encrypted in database.
155 The profile password is used to encrypt/decrypt it, this way only a `password hash`_ is
156 stored and the XMPP password is encrypted `at rest`_.
157
158 - As a further benefit, several passwords could be associated to the same profile (this
159 feature is currently not used in SàT).
160
161 - profile password can be empty, in which case no password is requested when a profile is
162 used
163
164 .. note::
165
166 if you use an empty profile password, the XMPP password won't be encrypted in database
167 (or more precisely, will be trivial to decrypt).
168
169 - a profile is a simple name associated with an account, it's easier to remember than a
170 whole XMPP identifier (also named "JID" for *Jabber ID*)
171
172 You always have a *default* profile which is the profile used when you don't select any
173 (notably used in jp). This is the first profile that you have created except if you have
174 changed it using a frontend (you can change it with jp).
175
176 .. _password hash: https://en.wikipedia.org/wiki/Key_derivation_function
177 .. _at rest: https://en.wikipedia.org/wiki/Data_at_rest
178
179 profile key
180 -----------
181
182 A profile **key** is a special name used as a way to select automatically one profile. The
183 most important one is ``@DEFAULT@`` which, as you can guess, means the default profile.
184
185 bridge
186 ------
187
188 The "bridge" is the name used to design Salut à Toi's `IPC`_, or in other words the way
189 the backend communicate with frontends. Several bridges can be used, the default one being
190 `D-Bus`_.
191
192 The other available bridges are:
193
194 pb
195 `Perspective Broker`_ is a part of `Twisted`_ (the framework used by the backend and some
196 frontends)
197
198 embedded
199 this embeds the backend into the frontend. The frontend is then using the backend as a
200 library.
201
202 .. _IPC: https://en.wikipedia.org/wiki/Inter-process_communication
203 .. _D-Bus: https://www.freedesktop.org/wiki/Software/dbus/
204 .. _Perspective Broker: https://twistedmatrix.com/documents/current/core/howto/pb-intro.html
205 .. _Twisted: https://twistedmatrix.com
206
207 SàT Media
208 ---------
209
210 Most of the frontends use images or other media. To avoid duplication and to make the code
211 repositories lighter, those media are grouped in a separate repository. The SàT media
212 repository is available at https://repos.goffi.org/sat_media. You can also download media
213 at https://ftp.goffi.org/sat_media/sat_media.tar.bz2. The path where SàT media are
214 installed must be specified in ``sat.conf`` in ``media_dir`` option of the ``[DEFAULT``
215 section.
216
217 SàT Templates
218 -------------
219
220 SàT embeds a `Jinja2`_ template engine (see `Libervia`_ above). "SàT templates" refers to
221 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
223 SàT templates repository is available at https://repos.goffi.org/sat_templates, they can
224 also be downloaded at `PyPI <https://pypi.org/project/sat-templates/>`_ and will be
225 installed automatically if you install Libervia.
226
227 Related projects
228 ================
229
230 Some project are closely related to Salut à Toi, here is a list of official related
231 project.
232
233 SàT PubSub
234 ----------
235
236 Numerous features of Salut à Toi are taking profit of `PubSub`_ functionalities of XMPP.
237 Because PubSub implementations in the wild are not all on the same level, and some
238 experimental features are sometimes explored, a PubSub service as been written
239 specifically for the needs of SàT (but it's not depending on SàT and any XMPP software can
240 use it).
241
242 SàT PubSub aims to be a feature complete, server-independent PubSub implementation, and
243 try to be up-to-date with latest XMPP PubSub extensions. It is the privileged service to
244 use with SàT because it supports everything needed (but SàT can work with any XMPP PubSub
245 service, it will adapt itself to available features).
246
247 SàT PubSub can also be used as a `PEP`_ service, if some XMPP extensions are supported by
248 your server (see below).
249
250 .. _PubSub: https://xmpp.org/about/technology-overview.html#pubsub
251 .. _PEP: https://xmpp.org/extensions/xep-0163.html
252
253 XMPP Extension Protocols
254 ------------------------
255
256 For the needs of SàT or SàT PubSub, some `XMPP Extension Protocols`_ (or XEP) have been
257 proposed and got an official number. The current list of extensions is:
258
259 `XEP-0355`_: Namespace Delegation
260 This has been proposed for the needs of SàT PubSub, and allows the XMPP server to
261 "delegate" some features management to a third party service. It is needed to use SàT
262 Pubsub as a PEP service.
263
264 `XEP-0356`_: Privileged Entity
265 In the same spirit as previous one, this has been done so SàT PubSub could be used as a
266 PEP service. This extensions allows a "component" (which is more or less a server
267 generic plugin) to gain some privileged access to data such as presence information,
268 roster or to send a message like if it was sent by the server.
269
270 `XEP-0413`_: Order-By
271 This extension is used to specify the sorting order in which a client wishes to retrieve
272 some results. It is notably used by SàT and SàT PubSub to retrieve items like blog posts
273 or tickets in creation order or order of last modification.
274
275 .. _XEP-0355: https://xmpp.org/extensions/xep-0355.html
276 .. _XEP-0356: https://xmpp.org/extensions/xep-0356.html
277 .. _XEP-0413: https://xmpp.org/extensions/xep-0413.html
278
279 .. _XMPP Extension Protocols: https://xmpp.org/about/standards-process.html
280
281 Prosody's `mod_delegation`_ and `mod_privilege`_
282 -------------------------------------------------
283
284 Prosody modules have been created to implement the *Namespace Delegation* and *Privileged
285 Entity* extensions mentioned above. If you use Prosody, you'll have to activate those 2
286 modules to use SàT PubSub as a PEP service.
287
288 .. _mod_privilege: https://modules.prosody.im/mod_privilege.html
289 .. _mod_delegation: https://modules.prosody.im/mod_delegation.html
290
291 SàT official website
292 --------------------
293
294 The official website is made with Libervia web framework. You'll find it at https://repos.goffi.org/sat_web_site
295
296 Salut
297 -----
298 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
300 You'll find it at https://repos.goffi.org/salut/
301
302 .. _XEP-0055: https://xmpp.org/extensions/xep-0055.html