.. _installation:
============
Installation
============
These are the instructions to install **Libervia** using Python. Note that if you are
using GNU/Linux, Libervia may already be available in your distribution’s repositories.
Libervia consists of one backend and several frontends. To use it, the first step is to
install the backend.
.. note::
If you plan to use only the web frontend in local mode, the backend is automatically
embedded: you don't need to install it separately. In normal mode, or when using other
frontends, a separate backend installation is required.
We recommend using the development version for now, until the release of 0.9.
Development version
-------------------
.. *Note for Arch users*: a PKGBUILD is available for your distribution on the AUR;
.. check ``libervia-backend-hg`` (as well as the other ``libervia-*`` packages).
You can install the latest development version using **uv**. You need to have the
following system dependencies installed first:
- Git
- `uv`_ – available as a system package on some distributions (e.g. Arch Linux);
if it is not packaged for your distribution, install it with the official
installer:
.. code-block:: bash
$ curl -LsSf https://astral.sh/uv/install.sh | sh
- GPG (providing the ``gpg`` command line tool)
- build-essential (build tools needed to compile native extensions)
.. note::
There is no need to install Python: ``uv`` downloads and uses the required Python
version on its own.
On Debian and derivatives you can use the following command::
$ sudo apt-get install build-essential git gnupg
On Arch Linux the command is::
$ sudo pacman -S --needed base-devel git gnupg uv
Additional packages
~~~~~~~~~~~~~~~~~~~~
Pre-compiled packages (wheels) are available for most of the dependencies, so the packages
above are sufficient in the common case. Additional system packages are required to build
dependencies from source, or by some optional features:
- To build from source: libxml2, libxslt, and libjpeg with development headers.
- For ``webrtc`` extra (needed for audio/video calls and direct file transfer on local
frontends only, it is **not** required for Libervia Web): libcairo 2 and libgirepository
2.0 with development headers, and gir1.2-glib-2.0 (GObject-Introspection bindings for
GLib).
On Debian and derivatives::
$ sudo apt-get install libcairo2-dev libgirepository-2.0-dev gir1.2-glib-2.0 pkg-config
On Arch Linux::
$ sudo pacman -S --needed cairo gobject-introspection
- For ``serverless`` extra: GMP development headers (``libgmp-dev`` on Debian, already in
the base on Arch Linux); on Debian, ``python3-dev`` as well if a system Python is
installed (``uv`` reuses it if it matches the requested version).
Installation with **uv**
~~~~~~~~~~~~~~~~~~~~~~~~
Once you have `uv`_ installed, you can easily install the development version of the
backend by running:
.. code-block:: bash
$ uv tool install 'libervia-backend[main] @ git+https://www.goffi.org/forge/goffi/libervia-backend/' --python 3.13
The ``main`` extra adds the recommended set of features.
``--python 3.13`` is used for now, as the ``serverless`` extra requires it (temporarily).
The following extras are available to install additional features:
**all**
All the features, including the experimental ones.
**conferences**
Needed if you want to run the Audio/Video conferences component (requires the
`galene `_ executable).
**GUI**
Qt bindings required by the WIP Libervia Desktop frontend, and some extra CLI
features.
**main**
The recommended set of features for a good experience (currently ``tor``
and ``ox``).
**netifaces**
Legacy, only used by the IP plugin; not required.
**ox** (included in ``main``)
Message/Pubsub encryption with OpenPGP (requires the ``gpg`` command line tool).
**remote-control**
Experimental remote control feature.
**serverless**
Serverless feature (work in progress).
**SVG**
SVG image rendering, only used by Libervia Desktop Kivy.
**tor** (included in ``main``)
Connect through the Tor daemon, access `.onion` XMPP servers (requires a running Tor
daemon).
**webrtc**
Audio/video calls and WebRTC based file transfer in local frontends (i.e. all
frontends but web).
You can use additional features by replacing ``main`` or adding other extras, for
instance::
$ uv tool install 'libervia-backend[main,serverless] @ git+https://www.goffi.org/forge/goffi/libervia-backend/' --python 3.13
to activate serverless feature, or::
$ uv tool install 'libervia-backend[all] @ git+https://www.goffi.org/forge/goffi/libervia-backend/' --python 3.13
to have all features.
Usage
-----
To launch the Libervia backend, run::
$ libervia-backend
To run it in the foreground::
$ libervia-backend fg
To stop the backend::
$ libervia-backend stop
To check whether the backend is running::
$ libervia-backend status
You can verify that Libervia is installed correctly by checking its version::
$ li --version
Libervia CLI 0.9.0.dev0 « La Ruche » (repository data unknown) Copyright (C) 2009-2026 Jérôme Poisson, Adrien Cossa
This program comes with ABSOLUTELY NO WARRANTY;
This is free software, and you are welcome to redistribute it under certain conditions.
If you see a similar output, Libervia is working.
Post installation
-----------------
D-Bus
~~~~~
When the D-Bus bridge is used (the default on desktop systems), you can install the
D-Bus activation service file so that the backend is launched automatically when a
frontend needs it.
Copy the file ``org.libervia.Libervia.service`` (in the ``misc/`` directory of the source
code) to your D-Bus services directory: ``~/.config/dbus-1/services/`` for a per-user
installation, or ``/usr/share/dbus-1/services/`` for a system-wide one.
.. _installation_system:
System installation
~~~~~~~~~~~~~~~~~~~
When using Libervia as a server (e.g., to run components, or use the web frontend), you
usually want to run automatically services when booting the OS. This can be done using
systemd.
The systemd unit files are in the ``misc/systemd/`` directory of the source code:
- ``libervia-backend.service``: runs the backend, used to handle all the components and
clients in a single instance; it is the service used by ``libervia-web.service``, and
can be used along with ``libervia@.service`` if desired;
- ``libervia@.service``: a template for isolated instances, each with its own logs,
database, and data, useful if one wants to run one or several components separately;
- ``libervia-web.service``: the Libervia Web frontend service.
Copy the units you need to ``/etc/systemd/system/`` and enable and start them.
For a component, the isolated instance is named after the component entry point, with
dashes replaced by underscores (e.g. ``ap-gateway`` gives ``libervia@ap_gateway``), and
the component is configured in the instance configuration file, see :ref:`components` for
the configuration (for the default ``libervia`` user, it is at
``/var/lib/libervia/.config/libervia/isolated//libervia.toml``).
So to run isolated instances of the pubsub component and the ActivityPub Gateway, you can
use::
$ sudo systemctl enable --now libervia@pubsub
$ sudo systemctl enable --now libervia@ap_gateway
The instance name is used as the isolation name, so to work with the instance from
the CLI, use the ``-i/--isolation`` option with this name (see :ref:`li_isolation`),
e.g. ``li -i pubsub profile list``.
See the `systemd documentation `_ to manage the services.
Frontends
---------
The following frontends are actively maintained:
- **Libervia Web** – web frontend
- **Libervia CLI** – command-line interface
----
The following frontends are temporarily on hold, to focus on the development of
Libervia Web and Libervia CLI:
- **Libervia Desktop Kivy** – desktop frontend
- **Libervia TUI** – text-user interface
.. To launch the TUI, run::
..
.. $ libervia-tui
..
.. Then create a profile (the XMPP account must already exist).
For the CLI, use the ``li`` shortcut (``libervia-cli``) and consult the help::
$ li --help
.. _uv: https://docs.astral.sh/uv/