diff --git a/doc/installation.rst b/doc/installation.rst index 42f755ca..62f1a6e1 100644 --- a/doc/installation.rst +++ b/doc/installation.rst @@ -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 `_ 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 -``: 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//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 `_ 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/ diff --git a/misc/systemd/README.md b/misc/systemd/README.md index 4779b879..c9884b67 100644 --- a/misc/systemd/README.md +++ b/misc/systemd/README.md @@ -7,3 +7,6 @@ Here you'll find [systemd](https://systemd.io/) units to run Libervia: - `libervia@.service`: a template for isolated backend instances. To be used for a component, a dedicated backend for the web frontend, or any other isolated usage. - `libervia-web.service`: Libervia Web frontend. + +See the "System installation" subsection of `doc/installation.rst` for the complete +instructions.