============
Installation
============

This are the instructions to install Libervia Web using Python.
Note that if you are using GNU/Linux, Libervia Web may already be present on your
distribution.

This is the web frontend of Libervia, the Libervia backend must be installed first (if you
haven't installed it yet, it will be downloaded automatically as it is a dependency of
Libervia Web). Libervia Web and Libervia Backend must always have the same version
(Libervia Web won't start if the version backend differs).

We recommend to use development version for now, until the release of
0.8 version.

Requirements
------------

- Python 3.7+
- Python 3 "venv", which may be installed with Python 3
- Mercurial

To install them on a Debian distribution or derivative, you can enter::

    sudo apt-get install python3-dev python3-venv python3-wheel mercurial

Development Version
-------------------

*Note for Arch users: a pkgbuild is available for your distribution on
AUR, check sat-libervia-hg (as well as other sat-\* packages).*


Installation With pipx
~~~~~~~~~~~~~~~~~~~~~~

If you have `pipx`_ installed, you can install the development version of the web frontend
by utilizing the same environment as the backend. First, install the backend as detailed
in the `backend installation instructions
<https://libervia.org/__b/doc/backend/installation.html#installation-with-pipx>`_. After
that, install the web frontend with the following command:

.. code-block:: bash

   $ pipx inject libervia-backend hg+https://repos.goffi.org/libervia-web

.. _pipx: https://pipx.pypa.io

Installation With Virtual Environment And pip
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

You can install the latest development version using Mercurial and pip.

Select the location where you want to install libervia and virtual environment, for
instance your ``$HOME`` directory::

    $ cd

You can use the same virtual environment as the one used for installing the backend.
Otherwise, create a new one (backend will be installed automatically if it's not already
there)::

    $ python3 -m venv libervia_venv
    $ source libervia_venv/bin/activate
    $ pip install -U pip wheel

Then you need to clone the repository::

    $ hg clone https://repos.goffi.org/libervia libervia-web && cd libervia-web

Now you can install the frontend and its requirements::

    $ pip install .

If you haven't done it for the backend, you need to install the media::

  $ cd
  $ hg clone https://repos.goffi.org/libervia-media

then, create the directory ``~/.config/libervia``::

  $ mkdir -p ~/.config/libervia

and the file ``~/.config/libervia/libervia.conf`` containing:

.. sourcecode:: cfg

  [DEFAULT]
  media_dir = ~/libervia-media

Of course, replace ``~/libervia-media`` with the actual path you have used.

Please check backend documentation for more details on the settings.

You'll also need the ``yarn`` packager, please check your distribution documentation for
instructions to install it.

.. note::

    On Debian and derivatives, the ``yarn`` packager is installed with the ``yarnpkg``
    package (and not ``yarn`` only), you can install it with ``apt install yarnpkg`` as
    root (or with ``sudo``).

Post Installation
-----------------

Libervia uses its own XMPP account to fetch public data. You need to create a profile
named `libervia` linked to this account to launch Libervia. First create an account
dedicated to this on your XMPP server. For instance with `Prosody`_ you would enter
something like::

  $ prosodyctl adduser libervia@example.net

Where you'll obviously change ``libervia@example.net`` for the JID you want to use, with
your domain name. You'll then be prompted for a password. You can now create the
associated Libervia profile::

  $ li profile create libervia -j libervia@example.net -p <libervia_password>

.. note::

   Libervia CLI doesn't prompt for password yet, this means that the password is visible
   to anybody looking at your screen and will stay in your shell history, and the password
   will be visible for a few seconds in process list. If this is a concern for you (e.g.
   you use a shared machine), use an other frontend to create the profile, or do the
   necessary to remove the password from history. In most shells, you can add a space in
   front of the command so that it doesn't appear in the history.

Finally, you need to specify to specify the password of this ``libervia`` profile in your
configuration. To do so, edit your ``libervia.conf`` and edit ``[libervia]`` and set the
``passphrase`` option to the profile password you have used in the command above:

.. sourcecode:: cfg

    [web]
    passphrase = <libervia_password>

You should now be good to run the Libervia Web server.

.. _Prosody: https://prosody.im


Usage
=====

To launch the Libervia Web server, enter::

  $ libervia-web

…or, if you want to launch it in foreground::

  $ libervia-web fg

You can stop it with::

  $ libervia-web stop

To know if backend is launched or not::

  $ libervia-web status


Libervia Pubsub
===============

Some functionalities use advanced or experimental features of XMPP PubSub. We recommend to
use the Libervia PubSub service that is a side project developed for the needs of
Libervia, and consequently implements everything needed. Please refer to Libervia PubSub
documentation to know how to install and use it.