doc (installation): update/rewrite of installation instructions:
- 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.
This commit is contained in:
Goffi
parent
2af29e7999
commit
184718e3ed
2 changed files with 165 additions and 142 deletions
|
|
@ -7,157 +7,132 @@ 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 frontend. To use it, the first step is to
|
||||
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).
|
||||
.. *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 **pip**. You need to have the
|
||||
following dependencies installed first:
|
||||
You can install the latest development version using **uv**. You need to have the
|
||||
following system dependencies installed first:
|
||||
|
||||
- Python 3 with development headers
|
||||
- Python 3 ``venv`` (usually installed with Python 3)
|
||||
- Mercurial
|
||||
- libcairo 2 with development headers
|
||||
- libjpeg with development headers
|
||||
- libgirepository 2.0 with development headers
|
||||
- libdbus‑1 with development headers
|
||||
- libdbus‑glib‑1 with development headers
|
||||
- libxml2 with development headers
|
||||
- libxslt with development headers
|
||||
- D‑Bus X11 tools (required for ``dbus-launch``; does not need an X server)
|
||||
- CMake
|
||||
- Python GPG package (and its GPG dependencies). The system package must be
|
||||
used because the package version has to match the system GPG version.
|
||||
- build-essential (basic build tools – e.g., make, GCC – for compiling native extensions)
|
||||
- python3-wheel (Python wheel support – pip uses it to install pre-compiled packages)
|
||||
- gir1.2-glib-2.0 (GObject‑Introspection bindings for GLib – required by some rontends)
|
||||
- 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
|
||||
|
||||
On Debian and derivatives you can install all of these with the following command::
|
||||
$ curl -LsSf https://astral.sh/uv/install.sh | sh
|
||||
|
||||
$ sudo apt-get install build-essential python3-dev python3-venv python3-wheel mercurial libxml2-dev libxslt-dev libcairo2-dev libjpeg-dev libgirepository-2.0-dev gir1.2-glib-2.0 libdbus-1-dev libdbus-glib-1-dev dbus-x11 cmake python3-gpg
|
||||
- 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 python python-wheel mercurial libxml2 libxslt cairo libjpeg-turbo gobject-introspection dbus-glib cmake python-gpgme
|
||||
$ sudo pacman -S --needed base-devel git gnupg uv
|
||||
|
||||
Installation with **pipx**
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
Additional packages
|
||||
~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
If you have `pipx`_ installed, you can easily install the development version of the
|
||||
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
|
||||
|
||||
$ pipx install --system-site-packages hg+https://repos.goffi.org/libervia-backend#egg=libervia-backend[all]
|
||||
$ uv tool install 'libervia-backend[main] @ git+https://www.goffi.org/forge/goffi/libervia-backend/' --python 3.13
|
||||
|
||||
Installation with a virtual environment and **pip**
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
The ``main`` extra adds the recommended set of features.
|
||||
|
||||
Alternatively, you can create a virtual environment, clone the repository, and pip install
|
||||
the backend from there.
|
||||
``--python 3.13`` is used for now, as the ``serverless`` extra requires it (temporarily).
|
||||
|
||||
Choose a location where you would like to install Libervia – for instance, your home
|
||||
directory::
|
||||
The following extras are available to install additional features:
|
||||
|
||||
$ cd
|
||||
**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).
|
||||
|
||||
Then run the following commands (the ``[all]`` extra installs all optional dependencies
|
||||
for full feature support)::
|
||||
You can use additional features by replacing ``main`` or adding other extras, for
|
||||
instance::
|
||||
|
||||
$ python3 -m venv --system-site-packages libervia
|
||||
$ source libervia/bin/activate
|
||||
$ pip install -U pip wheel
|
||||
$ hg clone https://repos.goffi.org/libervia-backend
|
||||
$ cd libervia-backend
|
||||
$ pip install -e .[all]
|
||||
$ uv tool install 'libervia-backend[main,serverless] @ git+https://www.goffi.org/forge/goffi/libervia-backend/' --python 3.13
|
||||
|
||||
to activate serverless feature, or::
|
||||
|
||||
Do not worry if you see a message such as ``Failed building wheel for
|
||||
<some_package_name>``: Libervia should still work.
|
||||
$ uv tool install 'libervia-backend[all] @ git+https://www.goffi.org/forge/goffi/libervia-backend/' --python 3.13
|
||||
|
||||
Post‑installation
|
||||
~~~~~~~~~~~~~~~~~
|
||||
|
||||
After installing the backend, you may want to install the media repository (if you plan to
|
||||
use a graphical frontend, you may skip otherwise)::
|
||||
|
||||
$ cd
|
||||
$ hg clone https://repos.goffi.org/libervia-media
|
||||
|
||||
Create the configuration directory::
|
||||
|
||||
$ mkdir -p ~/.config/libervia
|
||||
|
||||
and write the file ``~/.config/libervia/libervia.conf`` containing:
|
||||
|
||||
.. sourcecode:: cfg
|
||||
|
||||
[DEFAULT]
|
||||
media_dir = ~/libervia-media
|
||||
|
||||
Replace ``~/libervia-media`` with the actual path you used.
|
||||
|
||||
See :ref:`configuration` for more details.
|
||||
|
||||
|
||||
.. _installation_dbus:
|
||||
|
||||
Launching D‑Bus (on servers)
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
If you run Libervia on a server without a desktop environment, you may need to start D‑Bus
|
||||
manually.
|
||||
|
||||
Create a shell script named ``dbus_launch.sh`` with the following content:
|
||||
|
||||
.. sourcecode:: sh
|
||||
|
||||
#!/bin/sh
|
||||
|
||||
DBUS_PATH="/tmp/.dbus.`whoami`"
|
||||
|
||||
if [ ! -e "$DBUS_PATH" ]; then
|
||||
dbus-launch --sh-syntax > "$DBUS_PATH"
|
||||
chmod 400 "$DBUS_PATH"
|
||||
fi
|
||||
|
||||
cat "$DBUS_PATH"
|
||||
|
||||
Make it executable::
|
||||
|
||||
$ chmod +x /path/to/dbus_launch.sh
|
||||
|
||||
Before starting the backend or any frontend, evaluate the script::
|
||||
|
||||
$ eval $(/path/to/dbus_launch.sh)
|
||||
|
||||
This will launch the D-Bus daemon if needed and set the necessary environment variables.
|
||||
To ensure D-Bus is active in new shell sessions, run the script again using ``eval`` in
|
||||
each session. For convenience, you can add the script execution (using ``eval``) to your
|
||||
shell configuration file (e.g., ``.zshrc``).
|
||||
|
||||
|
||||
|
||||
If you prefer not to use D‑Bus, you can use an alternative bridge such as ``pb`` by
|
||||
updating the ``[DEFAULT]`` section of the configuration file::
|
||||
|
||||
bridge = pb
|
||||
|
||||
.. note::
|
||||
|
||||
Currently only D‑Bus is supported by all frontend. In particular, the
|
||||
web frontend supports D‑Bus exclusively. This limitation is temporary.
|
||||
to have all features.
|
||||
|
||||
Usage
|
||||
=====
|
||||
-----
|
||||
|
||||
To launch the Libervia backend, run::
|
||||
|
||||
|
|
@ -175,46 +150,91 @@ To check whether the backend is running::
|
|||
|
||||
$ libervia-backend status
|
||||
|
||||
.. note::
|
||||
|
||||
If ``misc/org.libervia.Libervia.service`` is installed correctly (it should be
|
||||
installed as part of the installation process), the backend is automatically launched
|
||||
when a frontend needs it.
|
||||
|
||||
You can verify that Libervia is installed correctly by checking its version::
|
||||
|
||||
$ li --version
|
||||
Libervia CLI 0.8.0D « La Cecília » (rev 184c66256bbc [M] (default 2021-06-09 11:35 +0200) +524) Copyright (C) 2009‑2021 Jérôme Poisson, Adrien Cossa
|
||||
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.
|
||||
|
||||
.. note::
|
||||
Post installation
|
||||
-----------------
|
||||
|
||||
You may encounter an error indicating that D‑Bus is not launched or that its
|
||||
environment variable is unset. This usually happens when launching Libervia
|
||||
on a server without a graphical environment (X.org or Wayland). Follow the
|
||||
instructions above to start D‑Bus manually.
|
||||
D-Bus
|
||||
~~~~~
|
||||
|
||||
frontend
|
||||
==========
|
||||
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.
|
||||
|
||||
The following frontend are actively maintained:
|
||||
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 Desktop** – desktop frontend
|
||||
- **Libervia Web** – web frontend
|
||||
- **Libervia TUI** – text‑user interface
|
||||
- **Libervia CLI** – command‑line interface
|
||||
- **Libervia CLI** – command-line interface
|
||||
|
||||
To launch the TUI, run::
|
||||
----
|
||||
|
||||
$ libervia-tui
|
||||
The following frontends are temporarily on hold, to focus on the development of
|
||||
Libervia Web and Libervia CLI:
|
||||
|
||||
Then create a profile (the XMPP account must already exist).
|
||||
- **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
|
||||
|
||||
.. _pipx: https://pypa.github.io/pipx/
|
||||
.. _uv: https://docs.astral.sh/uv/
|
||||
|
|
|
|||
Loading…
Reference in a new issue