184718e3ed
- We are now using `uv`, so documentation has been updated accordingly. - Commented out instruction on unmaintained things (AUR packages, TUI). - Add instructions on using systemd services.
240 lines
8.1 KiB
ReStructuredText
240 lines
8.1 KiB
ReStructuredText
.. _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 <https://galene.org/>`_ 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/<name>/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 <https://systemd.io/>`_ 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/
|