Mercurial > libervia-pubsub

comparison doc/installation.rst @ 404:105a0772eedd

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
doc: first draft
author Goffi <goffi@goffi.org>
date Wed, 24 Jul 2019 19:26:43 +0200
parents
children f527dc927a6a
comparison
equal deleted inserted replaced
403:1dc606612405 404:105a0772eedd
1 ============
2 Installation
3 ============
4
5 This are the instructions to install SàT Pubsub.
6
7 Please note that SàT PubSub, as all SàT ecosystem, is still using Python 2 (this will
8 change for 0.8 version which will be Python 3 only), so all instructions below have to be
9 made using python 2.
10
11 .. note::
12
13 SàT PubSub is not released yet and this documentation is work in progress
14
15
16 Requirements
17 ------------
18
19 - Python 2.7.x
20 - Twisted >= 15.2.0:
21 - Twisted Core
22 - Twisted Words
23 - Wokkel >= 0.7.1 (http://wokkel.ik.nu/)
24 - A XMPP server that supports the component protocol (XEP-0114),
25 and, to enable the micro-blogging feature, Namespace Delegation (XEP-0355)
26 and privileged entity (XEP-0356) are needed.
27 We recommend using Prosody with mod_privilege and mod_delegation modules (those modules
28 are maintained by us).
29 - SàT tmp (http://repos.goffi.org/sat_tmp) is currently needed for MAM and RSM handling
30
31 For the PostgreSQL backend, the following is also required:
32
33 - PostgreSQL >= 9.5 (including development files for psycopg2)
34 - psycopg2
35
36 Installation From Sources
37 -------------------------
38
39 .. note::
40
41 The installation script is not up-to-date (notably requirements). The situation should
42 improve soon.
43
44 To install SàT PubSub we'll work in a virtual environment. On Debian and derivatives you
45 should easily install dependencies with this::
46
47 sudo apt-get install postgresql python-psycopg2 python-dev mercurial virtualenv
48
49 Now go in a location where you can install SàT Pubsub, for instance your home directory::
50
51 $ cd
52
53 And enter the following commands (note that *virtualenv2* may be named
54 *virtualenv* on some distributions, just be sure it's Python **2** version)::
55
56 $ virtualenv2 env
57 $ source env/bin/activate
58 $ pip install uuid twisted wokkel psycopg2 sat_tmp
59 $ pip install hg+https://repos.goffi.org/sat_pubsub
60
61 Post Installation
62 -----------------
63
64 Once SàT Pubsub is installed, you'll need to create a PostgreSQL user, and create the
65 database::
66
67 % sudo -u postgres createuser -d -P $(whoami)
68 % createdb pubsub
69 % cd /tmp && wget https://repos.goffi.org/sat_pubsub/raw-file/tip/db/pubsub.sql
70 % psql pubsub < pubsub.sql
71
72
73 .. _prosody_configuration:
74
75 Prosody Configuration
76 ---------------------
77
78 SàT PubSub can work with any XMPP server (which supports components), but if you want to
79 use it as your PEP service, you need a server which supports `XEP-0355`_ and `XEP-0356`_.
80
81 Below you'll find the instruction to use SàT PubSub as a PEP service with Prosody:
82
83 - add these two lines at the end of your ``prosody.cfg.lua`` file, adapting them to your XMPP
84 server domain (virtual host) and selecting a password of your choice:
85
86 .. sourcecode:: lua
87
88 Component "sat-pubsub.<xmpp_domain>"
89 component_secret = "<password>"
90
91 - there are extra steps to enable the micro-blogging feature with Prosody. Please follow
92 the installation and configuration instructions that are given on these pages:
93
94 - https://modules.prosody.im/mod_delegation.html
95 - https://modules.prosody.im/mod_privilege.html
96
97 To keep your modules up to date, we recommend to clone the full modules
98 repository and then to symlink them like that:
99
100 .. sourcecode:: shell
101
102 % cd /path/to/install_dir
103 % hg clone https://hg.prosody.im/prosody-modules
104 % cd /path/to/prosody_plugins
105 % ln -sf /path/to/install_dir/prosody-modules/mod_delegation ./
106 % ln -sf /path/to/install_dir/prosody-modules/mod_privilege ./
107
108 Or course, you have to adapt ``/path/to/install_dir`` to the directory where you want to
109 install the modules, and ``/path/to/prosody_plugins`` to the directory where prosody
110 modules are installed (hint: check ``prosodyctl about`` to find the latter). The ``ln``
111 commands may have to be run as root depending on your installation.
112
113 Once your symlinks are set, to update the modules we just need to type this:
114
115 .. sourcecode:: shell
116
117 % cd /path/to/install_dir/prosody-modules
118 % hg pull -u
119
120 Here is an example of how your ``prosody.cfg.lua`` should look like with
121 ``mod_delegation`` and ``mod_privilege`` activated:
122
123 .. sourcecode:: lua
124
125 [...]
126 modules_enabled = {
127 [...]
128 "delegation";
129 "privilege";
130 }
131 [...]
132 VirtualHost "<xmpp_domain>"
133 privileged_entities = {
134 ["sat-pubsub.<xmpp_domain>"] = {
135 roster = "get";
136 message = "outgoing";
137 presence = "roster";
138 },
139 }
140 delegations = {
141 ["urn:xmpp:mam:2"] = {
142 filtering = {"node"};
143 jid = "sat-pubsub.<xmpp_domain>";
144 },
145 ["http://jabber.org/protocol/pubsub"] = {
146 jid = "sat-pubsub.<xmpp_domain>";
147 },
148 ["http://jabber.org/protocol/pubsub#owner"] = {
149 jid = "sat-pubsub.<xmpp_domain>";
150 },
151 ["https://salut-a-toi/protocol/schema:0"] = {
152 jid = "sat-pubsub.<xmpp_domain>";
153 },
154 ["http://jabber.org/protocol/disco#items:*"] = {
155 jid = "sat-pubsub.<xmpp_domain>";
156 },
157 ["https://salut-a-toi.org/spec/pubsub_admin:0"] = {
158 jid = "sat-pubsub.<xmpp_domain>";
159 },
160 }
161
162 Component "sat-pubsub.<xmpp_domain>"
163 component_secret = "<password>"
164 modules_enabled = {"delegation", "privilege"}
165
166 Of course, you still have to replace and adapt to your own settings.
167
168 .. _XEP-0355: https://xmpp.org/extensions/xep-0355.html
169 .. _XEP-0356: https://xmpp.org/extensions/xep-0356.html
170
171 Running SàT PubSub
172 ------------------
173
174 The minimal example for running sat_pubsub is:
175
176 % twistd sat_pubsub
177
178 This will start the service and run it in the background. It generates a
179 file twistd.pid that holds the PID of the service and a log file twistd.log.
180 The twistd utility has a fair number of options that might be useful, and
181 can be viewed with:
182
183 % twistd --help
184
185 When the service starts, it will connect to the XMPP server at the local machine using the
186 component protocol, and assumes the JID ``pubsub``. This assumes a couple of defaults
187 which can be overridden by passing parameters to the twistd plugin. You can get an
188 overview of the parameters and their defaults using:
189
190 % twistd sat_pubsub --help
191
192 In particular, the following parameters will be of interest:
193
194 ``--jid``
195 The Jabber ID the component will assume.
196
197 ``--rport``
198 the port number of the XMPP server to connect to
199
200 ``--xmpp_pwd``
201 the secret used to authenticate with the XMPP server.
202
203 For example::
204
205 twistd sat_pubsub --jid=sat-pubsub.<your_xmpp_domain> --xmpp_pwd=<password>
206
207 You can set your options in ``sat.conf`` which is the same file used as for Salut à Toi
208 ecosystem. Please check backend ``configuration`` section for details. The SàT PubSub
209 options must be in ``[pubsub]`` section.
210