Mercurial > libervia-web

comparison doc/installation.rst @ 1209:13447f785ba1

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
doc: added installation instructions
author Goffi <goffi@goffi.org>
date Wed, 24 Jul 2019 07:52:30 +0200
parents
children d1032f9ece5b
comparison
equal deleted inserted replaced
1208:584e29d9510a 1209:13447f785ba1
1 ============
2 Installation
3 ============
4
5 This are the instructions to install Libervia (SàT) using Python.
6 Note that if you are using GNU/Linux, Libervia may already be present on your distribution.
7
8 Libervia is a Salut à Toi frontend, the SàT backend must be installed first (if you
9 haven't installed it yet, it will be downloaded automatically as it is a dependency of
10 Libervia). Libervia and SàT backend must always have the same version (Libervia won't
11 start if the version backend has not the same version).
12
13 We recommend to use development version for now, until the release of
14 0.7 version which will be "general public" version.
15
16 Also note that Libervia as all SàT ecosystem is still using Python 2 (this will change for
17 0.8 version which will be Python 3 only), so all instructions below have to be made using
18 python 2.
19
20 Development Version
21 -------------------
22
23 *Note for Arch users: a pkgbuild is available for your distribution on
24 AUR, check sat-libervia-hg (as well as other sat-\* packages).*
25
26 You can install the latest development version using pip. Please check backend documentation
27 to see the system dependencies needed.
28
29 You can use the same virtual environment as the one used for installing the backend. If
30 you haven't installed it yet, just select a location when you want to install it, for
31 instance your home directory::
32
33 $ cd
34
35 And enter the following commands (note that *virtualenv2* may be named
36 *virtualenv* on some distributions, just be sure it's Python **2** version)::
37
38 $ virtualenv2 env
39 $ source env/bin/activate
40 $ pip install hg+https://repos.goffi.org/libervia
41
42 If you haven't done it for the backend, you need to install the media::
43
44 $ cd
45 $ hg clone https://repos.goffi.org/sat_media
46
47 Post Installation
48 -----------------
49
50 Libervia uses its own XMPP account to fetch public data. You need to create a profile
51 named `libervia` linked to this account to launch Libervia. First create an account
52 dedicated to this on your XMPP server. For instance with `Prosody`_ you would enter
53 something like::
54
55 $ prosodyctl adduser libervia@example.net
56
57 Where you'll obviously change ``libervia@example.net`` for the JID you want to use, with
58 your domain name. You'll then be prompted for a password. You can now create the
59 associated SàT profile::
60
61 $ jp profile create libervia -j libervia@example.net -p <libervia_password>
62
63 .. note::
64
65 jp doesn't prompt for password yet, this means that the password is visible to anybody
66 looking at your screen and will stay in your shell history, and the password will be
67 visible for a few seconds in process list. If this is a concern for you (e.g. you use a
68 shared machine), use an other frontend to create the profile, or do the necessary to
69 remove the password from history.
70
71 Finally, you need to specify to specify the password of this ``libervia`` profile in your
72 configuration. To do so, edit your ``sat.conf`` and edit ``[libervia]`` and set the
73 ``passphrase`` option to the profile password you have used in the command above:
74
75 .. sourcecode:: cfg
76
77 [libervia]
78 passphrase = <libervia_password>
79
80 You should now be good to run the Libervia server.
81
82 .. _Prosody: https://prosody.im
83
84
85 Usage
86 =====
87
88 To launch the Libervia server, enter::
89
90 $ libervia
91
92 …or, if you want to launch it in foreground::
93
94 $ libervia fg
95
96 You can stop it with::
97
98 $ libervia stop
99
100 To know if backend is launched or not::
101
102 $ libervia status
103
104
105 SàT Pubsub
106 ==========
107
108 Some functionalities use advanced or experimental features of XMPP PubSub. We recommend to
109 use the SàT PubSub service that is a side project developed for the needs of Salut à Toi,
110 and consequently implements everything needed. Please refer to SàT PubSub documentation to
111 know how to install and use it.