To have a better understanding of Libervia, this page gives a global view of what it is and what are the important concepts linked to it. You don’t need to read this to use it, but you can if you wish to understand “who is doing what”.
Libervia is a XMPP client. XMPP is an open standard used for communication (notably instant messaging but not only). XMPP is a solid standard, which is decentralised and federated.
Libervia is not only focusing on instant messaging, and aims to be a universal communication tools. In other words, you can use Libervia to chat, but also to blog publicly or privately, to share file, photo albums, to create events, to have discussion forum, etc.
Libervia is actually a whole ecosystem, and is made in a way that you can use it with many different interfaces (or “frontends”). There is a common central part which is called the “backend”, it handles most of the work, while frontends are mostly about the interactions with user(s).
To work, as Libervia is a XMPP client, a XMPP server is needed. You can either run your own, or use an existing one (either public, or run by an organisation you belong to, like family server, run by a friend, your company, university, association, etc.). If you want to run your own server, there are already plenty of them and happily most of which are libre, you can check an up-to-date list on the XSF website (the XSF or XMPP Standards Foundation being the non-profit organisation taking care of the XMPP standard).
So to summarise, Libervia is a communication ecosystem. Technically, it is a XMPP client which connect to an XMPP server. Libervia itself works with a backend and one or many frontends.
The backend is a daemon, that means that it’s a service running in the background.
It takes its main configuration from a file named
libervia.conf and can be in different
locations (see below). It uses data in a directory called
local_dir, and which
default, on suitable platforms, to the corresponding XDG directory, which is most of
~/.local/share/libervia. In this directory, you’ll find the main database in the
libervia.db file, which is a SQLite database.
The backend is run and stopped with the
libervia-backend executable. Running it
without argument launch the backend in the background, with
libervia-backend fg you
run it in the foreground (you’ll see log directly and can stop the backend with
Ctrl + c). The
libervia-backend status commands help you discover if the backend
is running or stopped.
Frontends are used to make the interface between user and the backend. Frontends are adapted to different use cases, and must be started after the backend (if the backend is not started, you’ll see a message telling you so). In most installations, the backend should be started automatically when you want to use a frontend.
Bellow you’ll see a list of the official frontends currently maintained:
Libervia Deskop/Mobile (Cagou)¶
Libervia Desktop (alias
Libervia Mobile or
Cagou) is the desktop/mobile frontend.
It’s probably the main interface for most users. It is based on the Kivy framework and
should run on most platforms (for now it is officially tested only on GNU/Linux and
Android phones and tablets).
The Web frontend is the second main interface for most users. This frontend has the particularity to be in 2 parts: a server which serves HTTP content, and a client which runs in the browser. So you have Libervia Web server which connect to Libervia backend which itself connect to the XMPP server, and your browser will connect to Libervia Web server.
Libervia Web is also the central part of the Web Framework. Indeed, in addition of being a frontend to Libervia features (which is built with this framework), you can create totally different websites which are integrated in Libervia (and so XMPP) ecosystem. This framework uses Libervia template engine (based on Jinja2) and makes the creation of decentralised and federated websites simple. Thanks to this framework, it’s easy to experiment new ideas/features, or to change completely the look and feel of the Libervia frontend.
The official Libervia website is made with Libervia web framework.
Libervia TUI (Primitivus)¶
Libervia TUI (alias
Primitivus) is the Terminal User Interface. In other words, it
works in console and is intended for people at ease with it. Its text only interface has
several advantages: you get rid of many distracting things (like images), it works without
graphical environment installed (which is often the case on servers) and it works on
distant shell (like ssh) while staying gentle with your bandwidth.
Primitivus is shipped with the backend, so it should be always available once Libervia is installed (but some distributions may provide it separately).
You can check Libervia TUI documentation for more details.
Libervia CLI (jp)¶
Libervia CLI (alias
jp) is the Command Line Interface. It’s a
powerful tool which allows to do nearly everything you can do with other frontends.
Particularly useful if you want to check something quickly, or if you want to do some
You can check Libervia CLI documentation documentation for more details.
While using Libervia you may see some terms or concept. This section explain the most important ones.
A profile is the name linked to an account data. Usually a profile correspond to an XMPP account, but you can have several profiles using the same XMPP account (with different parameters) even if this is not usual.
On a Libervia installation used by a single user, the profiles are usually used for multiple accounts. On a multi-users installations, there is usually one profile per user.
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:
Libervia needs to know the plain XMPP password to connect, and it is encrypted in database. The profile password is used to encrypt/decrypt it, this way only a password hash is stored and the XMPP password is encrypted at rest.
As a further benefit, several passwords could be associated to the same profile (this feature is currently not used in Libervia).
profile password can be empty, in which case no password is requested when a profile is used
if you use an empty profile password, the XMPP password won’t be encrypted in database (or more precisely, will be trivial to decrypt).
a profile is a simple name associated with an account, it’s easier to remember than a whole XMPP identifier (also named “JID” for Jabber ID)
You always have a default profile which is the profile used when you don’t select any (notably used in jp). This is the first profile that you have created except if you have changed it using a frontend (you can change it with jp).
A profile key is a special name used as a way to select automatically one profile. The
most important one is
@DEFAULT@ which, as you can guess, means the default profile.
The other available bridges are:
Most of the frontends use images or other media. To avoid duplication and to make the code
repositories lighter, those media are grouped in a separate repository. The Libervia media
repository is available at https://repos.goffi.org/sat_media. You can also download media
at https://ftp.goffi.org/sat_media/sat_media.tar.bz2. The path where Libervia media are
installed must be specified in
media_dir option of the
Libervia embeds a Jinja2 template engine (see Libervia Web above). “Libervia templates” refers to 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 output arguments).