Mercurial > libervia-web
changeset 1209:13447f785ba1
doc: added installation instructions
author | Goffi <goffi@goffi.org> |
---|---|
date | Wed, 24 Jul 2019 07:52:30 +0200 (2019-07-24) |
parents | 584e29d9510a |
children | 8759c3038d8f |
files | doc/index.rst doc/installation.rst |
diffstat | 2 files changed, 115 insertions(+), 1 deletions(-) [+] |
line wrap: on
line diff
--- a/doc/index.rst Fri Jul 19 18:01:38 2019 +0200 +++ b/doc/index.rst Wed Jul 24 07:52:30 2019 +0200 @@ -18,9 +18,10 @@ You can follow this documentation to learn more on it, or join our official XMPP room at `sat@chat.jabberfr.org <xmpp:sat@chat.jabberfr.org?join>`_ (also available via a `web link <https://chat.jabberfr.org/converse.js/sat@chat.jabberfr.org>`_) .. toctree:: - :maxdepth: 2 + :maxdepth: 3 :caption: Contents: + installation.rst web_framework/quick_start.rst web_framework/css_framework.rst @@ -30,6 +31,8 @@ ================== * :ref:`genindex` + .. * :ref:`modindex` + * :ref:`search`
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/installation.rst Wed Jul 24 07:52:30 2019 +0200 @@ -0,0 +1,111 @@ +============ +Installation +============ + +This are the instructions to install Libervia (SàT) using Python. +Note that if you are using GNU/Linux, Libervia may already be present on your distribution. + +Libervia is a Salut à Toi frontend, the SàT backend must be installed first (if you +haven't installed it yet, it will be downloaded automatically as it is a dependency of +Libervia). Libervia and SàT backend must always have the same version (Libervia won't +start if the version backend has not the same version). + +We recommend to use development version for now, until the release of +0.7 version which will be "general public" version. + +Also note that Libervia as all SàT ecosystem is still using Python 2 (this will change for +0.8 version which will be Python 3 only), so all instructions below have to be made using +python 2. + +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).* + +You can install the latest development version using pip. Please check backend documentation +to see the system dependencies needed. + +You can use the same virtual environment as the one used for installing the backend. If +you haven't installed it yet, just select a location when you want to install it, for +instance your home directory:: + + $ cd + +And enter the following commands (note that *virtualenv2* may be named +*virtualenv* on some distributions, just be sure it's Python **2** version):: + + $ virtualenv2 env + $ source env/bin/activate + $ pip install hg+https://repos.goffi.org/libervia + +If you haven't done it for the backend, you need to install the media:: + + $ cd + $ hg clone https://repos.goffi.org/sat_media + +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 SàT profile:: + + $ jp profile create libervia -j libervia@example.net -p <libervia_password> + +.. note:: + + jp 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. + +Finally, you need to specify to specify the password of this ``libervia`` profile in your +configuration. To do so, edit your ``sat.conf`` and edit ``[libervia]`` and set the +``passphrase`` option to the profile password you have used in the command above: + +.. sourcecode:: cfg + + [libervia] + passphrase = <libervia_password> + +You should now be good to run the Libervia server. + +.. _Prosody: https://prosody.im + + +Usage +===== + +To launch the Libervia server, enter:: + + $ libervia + +…or, if you want to launch it in foreground:: + + $ libervia fg + +You can stop it with:: + + $ libervia stop + +To know if backend is launched or not:: + + $ libervia status + + +SàT Pubsub +========== + +Some functionalities use advanced or experimental features of XMPP PubSub. We recommend to +use the SàT PubSub service that is a side project developed for the needs of Salut à Toi, +and consequently implements everything needed. Please refer to SàT PubSub documentation to +know how to install and use it.