|
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 |
|
|
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 |
