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