c1cb70ac1a
- 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
220 lines
6.6 KiB
ReStructuredText
220 lines
6.6 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 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/
|