From c1cb70ac1a0fe33ea2e4455956c636a38025b6db Mon Sep 17 00:00:00 2001 From: Goffi Date: Fri, 10 Oct 2025 17:44:04 +0200 Subject: [PATCH] doc (installation): Update instructions: - Instructions have been checked and updated. OS packages dependencies have been added for Arch Linux. - Added missing package. - Reordered/refreshed instructions. - Old/not relevant content has been removed. - Tested on latest docker images of Debian/Arch/Unbutu. rel 466 --- doc/installation.rst | 254 ++++++++++++++++++++++--------------------- 1 file changed, 131 insertions(+), 123 deletions(-) diff --git a/doc/installation.rst b/doc/installation.rst index 4c37869e..42f755ca 100644 --- a/doc/installation.rst +++ b/doc/installation.rst @@ -4,209 +4,217 @@ Installation ============ -These are the instructions to install Libervia using Python. -Note that if you are using GNU/Linux, Libervia may already be present on your distribution. +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 is made of one backend, and several frontends. To use it, the first thing to do is to install the backend. +Libervia consists of one backend and several frontend. To use it, the first step is to +install the backend. -We recommand to use development version for now, until the release of 0.9. +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 -AUR, check libervia-backend-hg (as well as 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 **pip**. You need to have the +following dependencies installed first: -- Python 3 with development headers -- Python 3 "venv", which may already be installed with Python 3 -- Mercurial -- libcairo 2 with development header -- libjpeg with development headers -- libgirepository 1.0 with development headers -- libdbus-1 with development headers -- libdbus-glib-1 with development headers -- libxml2 with development headers -- libxlt2 with development headers -- D-Bus x11 tools (this doesn't needs X11, it is just needed for dbus-launch) -- cmake -- Python GPG package (and its GPG dependencies), those are needed to use all OpenPGP - related features. We need to use the system package as package version needs to match - system GPG version. +- 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) -On Debian and derivatives, you can get all this with following command:: - $ sudo apt-get install python3-dev python3-venv python3-wheel mercurial libxml2-dev libxslt-dev libcairo2-dev libjpeg-dev libgirepository1.0-dev libdbus-1-dev libdbus-glib-1-dev dbus-x11 cmake python3-gpg +On Debian and derivatives you can install all of these with the following command:: -Installation With pipx -~~~~~~~~~~~~~~~~~~~~~~ + $ 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 + +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 + +Installation with **pipx** +~~~~~~~~~~~~~~~~~~~~~~~~~~ If you have `pipx`_ installed, you can easily install the development version of the -backend by entering the following command: +backend by running: .. code-block:: bash $ pipx install --system-site-packages hg+https://repos.goffi.org/libervia-backend#egg=libervia-backend[all] -Installation With Virtual Environment And pip -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Installation with a virtual environment and **pip** +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Alternatively, you can install a virtual environment, clone the repository, and pip -install from there. +Alternatively, you can create a virtual environment, clone the repository, and pip install +the backend from there. -Go in a location where you can install Libervia, for instance your home directory:: +Choose a location where you would like to install Libervia – for instance, your home +directory:: $ cd -And enter the following commands (here we install Libervia with all extra dependencies -support, i.e. will dependencies needed for optional features):: +Then run the following commands (the ``[all]`` extra installs all optional dependencies +for full feature support):: $ 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 . + $ pip install -e .[all] -Don't worry if you see the following message, Libervia should work anyway:: - Failed building wheel for +Do not worry if you see a message such as ``Failed building wheel for +``: Libervia should still work. -Post Installation +Post‑installation ~~~~~~~~~~~~~~~~~ -After installing Libervia, you need to install the media (you may skip this if you don't -plan to use any graphical frontend):: +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 -then, create the directory ``~/.config/libervia``:: +Create the configuration directory:: $ mkdir -p ~/.config/libervia -and the file ``~/.config/libervia/libervia.conf`` containing: +and write the file ``~/.config/libervia/libervia.conf`` containing: .. sourcecode:: cfg - [DEFAULT] - media_dir = ~/libervia-media + [DEFAULT] + media_dir = ~/libervia-media -Of course, replace ``~/libervia-media`` with the actual path you have used. +Replace ``~/libervia-media`` with the actual path you used. -You can check :ref:`configuration` for details +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. Usage ===== -To launch the Libervia backend, enter:: +To launch the Libervia backend, run:: $ libervia-backend -…or, if you want to launch it in foreground:: +To run it in the foreground:: $ libervia-backend fg -You can stop it with:: +To stop the backend:: $ libervia-backend stop -To know if backend is launched or not:: +To check whether the backend is running:: $ libervia-backend status -**NOTE**: if ``misc/org.libervia.Libervia.service`` is installed correctly (which should -be done during the installation), the backend is automatically launched when a frontend -needs it. +.. note:: -You can check that Libervia is installed correctly by trying jp (the backend need to be -launched first, check below):: + 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.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 This program comes with ABSOLUTELY NO WARRANTY; This is free software, and you are welcome to redistribute it under certain conditions. -If you have a similar output, Libervia is working. +If you see a similar output, Libervia is working. .. note:: - You may see an error message indicating that D-Bus is not launched or that its - environment variable is not set, this usually happens when launching Libervia on a - server, without graphic interface like X.org or Wayland (otherwise D-Bus service should - be launched automatically). In this case please follow instructions below. + 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. -Launching D-Bus (on servers) -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +frontend +========== - You can launch the D-Bus service by creating a shell script with the following content - in a file named ``dbus_launch.sh``: +The following frontend are actively maintained: - .. sourcecode:: sh +- **Libervia Desktop** – desktop frontend +- **Libervia Web** – web frontend +- **Libervia TUI** – text‑user interface +- **Libervia CLI** – command‑line interface - #!/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 - - Then run it before the backend or frontend by entering:: - - $ eval $(/path/to/dbus_launch.sh) - - This will launch the D-Bus daemon if necessary, and set the appropriate environment - variable. If you use a new shell, be sure to launch the script again in an ``eval`` - statement to have the environment variable set. You can put this in your ``.zshrc`` (or - whatever you're using) to make it automatic. - - If you don't want to use D-Bus, you can use another bridge, e.g. ``pb`` is a good - choice, by updating your :ref:`configuration` ``[DEFAULT]`` section with ``bridge = - pb``. - -Frontends -========= - -So far, the following frontends exist and are actively maintained: - -Libervia Desktop (aka Cagou) - desktop/mobile (Android) frontend - -Libervia Web - the web frontend - -Libervia TUI (aka Primitivus) - Text User Interface - -Libervia CLI (aka jp or li) - Command Line Interface - -To launch Libervia TUI, just type:: +To launch the TUI, run:: $ libervia-tui -then create a profile (XMPP account must already exist). +Then create a profile (the XMPP account must already exist). -To use Libervia CLI, follow its help (``li`` is a shortcut for ``libervia-cli``):: +For the CLI, use the ``li`` shortcut (``libervia-cli``) and consult the help:: $ li --help - -There are some other frontends: - -Bellaciao - based on Qt, a rich desktop frontend (currently on hold) - -Wix - former desktop frontend based on WxWidgets (deprecated with version 0.6.0) - -Sententia - Emacs frontend developed by a third party (development is currently stalled) - .. _pipx: https://pypa.github.io/pipx/