annotate doc/installation.rst @ 1260:6161076193e0

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