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

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

    [DEFAULT]
    media_dir = ~/libervia-media

Replace `~/libervia-media` with the actual path you used.

See Configuration for more details.

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

    #!/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