.. _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 frontend.  To use it, the first step is to
install the backend.

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 **pip**.  You need to have the
following 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)


On Debian and derivatives you can install all of these with the following command::

  $ 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 running:

.. code-block:: bash

   $ pipx install --system-site-packages hg+https://repos.goffi.org/libervia-backend#egg=libervia-backend[all]

Installation with a virtual environment and **pip**
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Alternatively, you can create a virtual environment, clone the repository, and pip install
the backend from there.

Choose a location where you would like to install Libervia – for instance, your home
directory::

  $ cd

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 .[all]


Do not worry if you see a message such as ``Failed building wheel for
<some_package_name>``: Libervia should still work.

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.

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

.. 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
  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::

   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.

frontend
==========

The following frontend are actively maintained:

- **Libervia Desktop** – desktop frontend
- **Libervia Web** – web frontend
- **Libervia TUI** – text‑user interface
- **Libervia CLI** – command‑line 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/
