annotate INSTALL @ 401:907b10480394

mam: fixed confusion between twisted log.msg and log.warning used elsewhere
author Goffi <goffi@goffi.org>
date Tue, 07 May 2019 09:15:20 +0200
parents e93a9fd329d9
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
155
5191ba7c4df8 Work towards first release 0.5.0.
Ralph Meijer <ralphm@ik.nu>
parents:
diff changeset
1 Requirements
5191ba7c4df8 Work towards first release 0.5.0.
Ralph Meijer <ralphm@ik.nu>
parents:
diff changeset
2 ============
5191ba7c4df8 Work towards first release 0.5.0.
Ralph Meijer <ralphm@ik.nu>
parents:
diff changeset
3
327
6662cc9519cc updated INSTALL file
Goffi <goffi@goffi.org>
parents: 326
diff changeset
4 - Python 2.7.x
6662cc9519cc updated INSTALL file
Goffi <goffi@goffi.org>
parents: 326
diff changeset
5 - Twisted >= 15.2.0:
193
8ab16e319bb8 Release Idavoll 0.7.3.
Ralph Meijer <ralphm@ik.nu>
parents: 189
diff changeset
6 - Twisted Core
8ab16e319bb8 Release Idavoll 0.7.3.
Ralph Meijer <ralphm@ik.nu>
parents: 189
diff changeset
7 - Twisted Words
327
6662cc9519cc updated INSTALL file
Goffi <goffi@goffi.org>
parents: 326
diff changeset
8 - Wokkel >= 0.7.1 (http://wokkel.ik.nu/)
6662cc9519cc updated INSTALL file
Goffi <goffi@goffi.org>
parents: 326
diff changeset
9 - A XMPP server that supports the component protocol (XEP-0114),
6662cc9519cc updated INSTALL file
Goffi <goffi@goffi.org>
parents: 326
diff changeset
10 and, to enable the micro-blogging feature, Namespace Delegation (XEP-0355)
6662cc9519cc updated INSTALL file
Goffi <goffi@goffi.org>
parents: 326
diff changeset
11 and privileged entity (XEP-0356) are needed.
6662cc9519cc updated INSTALL file
Goffi <goffi@goffi.org>
parents: 326
diff changeset
12 We recommend using Prosody with mod_privilege and mod_delegation modules.
6662cc9519cc updated INSTALL file
Goffi <goffi@goffi.org>
parents: 326
diff changeset
13 - SàT backend (http://repos.goffi.org/sat) is currently needed for MAM and RSM handling
155
5191ba7c4df8 Work towards first release 0.5.0.
Ralph Meijer <ralphm@ik.nu>
parents:
diff changeset
14
5191ba7c4df8 Work towards first release 0.5.0.
Ralph Meijer <ralphm@ik.nu>
parents:
diff changeset
15 For the PostgreSQL backend, the following is also required:
5191ba7c4df8 Work towards first release 0.5.0.
Ralph Meijer <ralphm@ik.nu>
parents:
diff changeset
16
331
e93a9fd329d9 affiliations XMPP handling:
Goffi <goffi@goffi.org>
parents: 327
diff changeset
17 - PostgreSQL >= 9.5 (including development files for psycopg2)
276
b757c29b20d7 import changes from idavoll changeset 233 (24be3a11ddbc), by Ralph Meijer and based on a patch by Nuno Santos
souliane <souliane@mailoo.org>
parents: 264
diff changeset
18 - psycopg2
155
5191ba7c4df8 Work towards first release 0.5.0.
Ralph Meijer <ralphm@ik.nu>
parents:
diff changeset
19
193
8ab16e319bb8 Release Idavoll 0.7.3.
Ralph Meijer <ralphm@ik.nu>
parents: 189
diff changeset
20
155
5191ba7c4df8 Work towards first release 0.5.0.
Ralph Meijer <ralphm@ik.nu>
parents:
diff changeset
21 Installation
5191ba7c4df8 Work towards first release 0.5.0.
Ralph Meijer <ralphm@ik.nu>
parents:
diff changeset
22 ============
5191ba7c4df8 Work towards first release 0.5.0.
Ralph Meijer <ralphm@ik.nu>
parents:
diff changeset
23
264
86e767dc6abb packaging for release
souliane <souliane@mailoo.org>
parents: 212
diff changeset
24 sat_pubsub uses setuptools for package building and installing.
86e767dc6abb packaging for release
souliane <souliane@mailoo.org>
parents: 212
diff changeset
25 To build from the source run:
193
8ab16e319bb8 Release Idavoll 0.7.3.
Ralph Meijer <ralphm@ik.nu>
parents: 189
diff changeset
26
8ab16e319bb8 Release Idavoll 0.7.3.
Ralph Meijer <ralphm@ik.nu>
parents: 189
diff changeset
27 python setup.py build
8ab16e319bb8 Release Idavoll 0.7.3.
Ralph Meijer <ralphm@ik.nu>
parents: 189
diff changeset
28
8ab16e319bb8 Release Idavoll 0.7.3.
Ralph Meijer <ralphm@ik.nu>
parents: 189
diff changeset
29 Then, to install run the following, possibly as root:
155
5191ba7c4df8 Work towards first release 0.5.0.
Ralph Meijer <ralphm@ik.nu>
parents:
diff changeset
30
5191ba7c4df8 Work towards first release 0.5.0.
Ralph Meijer <ralphm@ik.nu>
parents:
diff changeset
31 python setup.py install
5191ba7c4df8 Work towards first release 0.5.0.
Ralph Meijer <ralphm@ik.nu>
parents:
diff changeset
32
193
8ab16e319bb8 Release Idavoll 0.7.3.
Ralph Meijer <ralphm@ik.nu>
parents: 189
diff changeset
33 See the setuptools documentation for further information on changing
8ab16e319bb8 Release Idavoll 0.7.3.
Ralph Meijer <ralphm@ik.nu>
parents: 189
diff changeset
34 installation locations.
8ab16e319bb8 Release Idavoll 0.7.3.
Ralph Meijer <ralphm@ik.nu>
parents: 189
diff changeset
35
8ab16e319bb8 Release Idavoll 0.7.3.
Ralph Meijer <ralphm@ik.nu>
parents: 189
diff changeset
36
155
5191ba7c4df8 Work towards first release 0.5.0.
Ralph Meijer <ralphm@ik.nu>
parents:
diff changeset
37 Configuration
5191ba7c4df8 Work towards first release 0.5.0.
Ralph Meijer <ralphm@ik.nu>
parents:
diff changeset
38 =============
5191ba7c4df8 Work towards first release 0.5.0.
Ralph Meijer <ralphm@ik.nu>
parents:
diff changeset
39
327
6662cc9519cc updated INSTALL file
Goffi <goffi@goffi.org>
parents: 326
diff changeset
40 sat_pubsub uses Twisted's twistd command for running its services.
193
8ab16e319bb8 Release Idavoll 0.7.3.
Ralph Meijer <ralphm@ik.nu>
parents: 189
diff changeset
41
264
86e767dc6abb packaging for release
souliane <souliane@mailoo.org>
parents: 212
diff changeset
42 Idavoll, on which sat_pubsub is based, provides two types of storage for the backend:
86e767dc6abb packaging for release
souliane <souliane@mailoo.org>
parents: 212
diff changeset
43 a memory-based storage facility, which is volatile, and a persistent storage facility
86e767dc6abb packaging for release
souliane <souliane@mailoo.org>
parents: 212
diff changeset
44 using PostgreSQL. For now, sat_pubsub only uses the persistent storage facility.
193
8ab16e319bb8 Release Idavoll 0.7.3.
Ralph Meijer <ralphm@ik.nu>
parents: 189
diff changeset
45
264
86e767dc6abb packaging for release
souliane <souliane@mailoo.org>
parents: 212
diff changeset
46 For using the PostgreSQL backend, create a database (for example named pubsub):
193
8ab16e319bb8 Release Idavoll 0.7.3.
Ralph Meijer <ralphm@ik.nu>
parents: 189
diff changeset
47
264
86e767dc6abb packaging for release
souliane <souliane@mailoo.org>
parents: 212
diff changeset
48 sudo -u postgres createuser -d -P `whoami`
86e767dc6abb packaging for release
souliane <souliane@mailoo.org>
parents: 212
diff changeset
49 createdb pubsub
86e767dc6abb packaging for release
souliane <souliane@mailoo.org>
parents: 212
diff changeset
50 psql pubsub < sat_pubsub/db/pubsub.sql
193
8ab16e319bb8 Release Idavoll 0.7.3.
Ralph Meijer <ralphm@ik.nu>
parents: 189
diff changeset
51
8ab16e319bb8 Release Idavoll 0.7.3.
Ralph Meijer <ralphm@ik.nu>
parents: 189
diff changeset
52
327
6662cc9519cc updated INSTALL file
Goffi <goffi@goffi.org>
parents: 326
diff changeset
53 Your XMPP server must also be configured to accept component connections and,
6662cc9519cc updated INSTALL file
Goffi <goffi@goffi.org>
parents: 326
diff changeset
54 to enable the micro-blogging feature, privileged entity and namespace delegation.
6662cc9519cc updated INSTALL file
Goffi <goffi@goffi.org>
parents: 326
diff changeset
55 See below for details.
264
86e767dc6abb packaging for release
souliane <souliane@mailoo.org>
parents: 212
diff changeset
56
193
8ab16e319bb8 Release Idavoll 0.7.3.
Ralph Meijer <ralphm@ik.nu>
parents: 189
diff changeset
57
264
86e767dc6abb packaging for release
souliane <souliane@mailoo.org>
parents: 212
diff changeset
58 Running sat_pubsub
86e767dc6abb packaging for release
souliane <souliane@mailoo.org>
parents: 212
diff changeset
59 ==================
193
8ab16e319bb8 Release Idavoll 0.7.3.
Ralph Meijer <ralphm@ik.nu>
parents: 189
diff changeset
60
264
86e767dc6abb packaging for release
souliane <souliane@mailoo.org>
parents: 212
diff changeset
61 The minimal example for running sat_pubsub is:
193
8ab16e319bb8 Release Idavoll 0.7.3.
Ralph Meijer <ralphm@ik.nu>
parents: 189
diff changeset
62
264
86e767dc6abb packaging for release
souliane <souliane@mailoo.org>
parents: 212
diff changeset
63 twistd sat_pubsub
193
8ab16e319bb8 Release Idavoll 0.7.3.
Ralph Meijer <ralphm@ik.nu>
parents: 189
diff changeset
64
8ab16e319bb8 Release Idavoll 0.7.3.
Ralph Meijer <ralphm@ik.nu>
parents: 189
diff changeset
65 This will start the service and run it in the background. It generates a
8ab16e319bb8 Release Idavoll 0.7.3.
Ralph Meijer <ralphm@ik.nu>
parents: 189
diff changeset
66 file twistd.pid that holds the PID of the service and a log file twistd.log.
8ab16e319bb8 Release Idavoll 0.7.3.
Ralph Meijer <ralphm@ik.nu>
parents: 189
diff changeset
67 The twistd utility has a fair number of options that might be useful, and
8ab16e319bb8 Release Idavoll 0.7.3.
Ralph Meijer <ralphm@ik.nu>
parents: 189
diff changeset
68 can be viewed with:
8ab16e319bb8 Release Idavoll 0.7.3.
Ralph Meijer <ralphm@ik.nu>
parents: 189
diff changeset
69
8ab16e319bb8 Release Idavoll 0.7.3.
Ralph Meijer <ralphm@ik.nu>
parents: 189
diff changeset
70 twistd --help
8ab16e319bb8 Release Idavoll 0.7.3.
Ralph Meijer <ralphm@ik.nu>
parents: 189
diff changeset
71
327
6662cc9519cc updated INSTALL file
Goffi <goffi@goffi.org>
parents: 326
diff changeset
72 When the service starts, it will connect to the XMPP server at the local
193
8ab16e319bb8 Release Idavoll 0.7.3.
Ralph Meijer <ralphm@ik.nu>
parents: 189
diff changeset
73 machine using the component protocol, and assumes the JID 'pubsub'. This
8ab16e319bb8 Release Idavoll 0.7.3.
Ralph Meijer <ralphm@ik.nu>
parents: 189
diff changeset
74 assumes a couple of defaults which can be overridden by passing parameters to
8ab16e319bb8 Release Idavoll 0.7.3.
Ralph Meijer <ralphm@ik.nu>
parents: 189
diff changeset
75 the twistd plugin. You can get an overview of the parameters and their defaults
8ab16e319bb8 Release Idavoll 0.7.3.
Ralph Meijer <ralphm@ik.nu>
parents: 189
diff changeset
76 using:
8ab16e319bb8 Release Idavoll 0.7.3.
Ralph Meijer <ralphm@ik.nu>
parents: 189
diff changeset
77
264
86e767dc6abb packaging for release
souliane <souliane@mailoo.org>
parents: 212
diff changeset
78 twistd sat_pubsub --help
193
8ab16e319bb8 Release Idavoll 0.7.3.
Ralph Meijer <ralphm@ik.nu>
parents: 189
diff changeset
79
8ab16e319bb8 Release Idavoll 0.7.3.
Ralph Meijer <ralphm@ik.nu>
parents: 189
diff changeset
80 In particular, the following parameters will be of interest:
155
5191ba7c4df8 Work towards first release 0.5.0.
Ralph Meijer <ralphm@ik.nu>
parents:
diff changeset
81
5191ba7c4df8 Work towards first release 0.5.0.
Ralph Meijer <ralphm@ik.nu>
parents:
diff changeset
82 --jid: The Jabber ID the component will assume.
327
6662cc9519cc updated INSTALL file
Goffi <goffi@goffi.org>
parents: 326
diff changeset
83 --rport: the port number of the XMPP server to connect to
6662cc9519cc updated INSTALL file
Goffi <goffi@goffi.org>
parents: 326
diff changeset
84 --secret: the secret used to authenticate with the XMPP server.
155
5191ba7c4df8 Work towards first release 0.5.0.
Ralph Meijer <ralphm@ik.nu>
parents:
diff changeset
85
264
86e767dc6abb packaging for release
souliane <souliane@mailoo.org>
parents: 212
diff changeset
86 For example:
86e767dc6abb packaging for release
souliane <souliane@mailoo.org>
parents: 212
diff changeset
87
327
6662cc9519cc updated INSTALL file
Goffi <goffi@goffi.org>
parents: 326
diff changeset
88 twistd sat_pubsub --jid=sat-pubsub.<your_xmpp_domain> --secret=<password>
193
8ab16e319bb8 Release Idavoll 0.7.3.
Ralph Meijer <ralphm@ik.nu>
parents: 189
diff changeset
89
8ab16e319bb8 Release Idavoll 0.7.3.
Ralph Meijer <ralphm@ik.nu>
parents: 189
diff changeset
90 You may also want to provide the --verbose flag to see the traffic flow,
8ab16e319bb8 Release Idavoll 0.7.3.
Ralph Meijer <ralphm@ik.nu>
parents: 189
diff changeset
91 for example to debug the configuration. Below some specifics for the
264
86e767dc6abb packaging for release
souliane <souliane@mailoo.org>
parents: 212
diff changeset
92 Prosody XMPP server implementation.
193
8ab16e319bb8 Release Idavoll 0.7.3.
Ralph Meijer <ralphm@ik.nu>
parents: 189
diff changeset
93
155
5191ba7c4df8 Work towards first release 0.5.0.
Ralph Meijer <ralphm@ik.nu>
parents:
diff changeset
94
327
6662cc9519cc updated INSTALL file
Goffi <goffi@goffi.org>
parents: 326
diff changeset
95 Running sat_pubsub with Prosody
264
86e767dc6abb packaging for release
souliane <souliane@mailoo.org>
parents: 212
diff changeset
96 ===============================
155
5191ba7c4df8 Work towards first release 0.5.0.
Ralph Meijer <ralphm@ik.nu>
parents:
diff changeset
97
264
86e767dc6abb packaging for release
souliane <souliane@mailoo.org>
parents: 212
diff changeset
98 To enable the micro-blogging feature with Prosody XMPP server, you need
327
6662cc9519cc updated INSTALL file
Goffi <goffi@goffi.org>
parents: 326
diff changeset
99 the mod_delegation and privileged_entity plugins.
6662cc9519cc updated INSTALL file
Goffi <goffi@goffi.org>
parents: 326
diff changeset
100 Check if the mod_delegation and mod_privilege plugins are already
6662cc9519cc updated INSTALL file
Goffi <goffi@goffi.org>
parents: 326
diff changeset
101 in your Prosody installation:
155
5191ba7c4df8 Work towards first release 0.5.0.
Ralph Meijer <ralphm@ik.nu>
parents:
diff changeset
102
327
6662cc9519cc updated INSTALL file
Goffi <goffi@goffi.org>
parents: 326
diff changeset
103 cd prosody/plugins
6662cc9519cc updated INSTALL file
Goffi <goffi@goffi.org>
parents: 326
diff changeset
104 ls mod_delegation.lua
6662cc9519cc updated INSTALL file
Goffi <goffi@goffi.org>
parents: 326
diff changeset
105 ls mod_privilege.lua
264
86e767dc6abb packaging for release
souliane <souliane@mailoo.org>
parents: 212
diff changeset
106
327
6662cc9519cc updated INSTALL file
Goffi <goffi@goffi.org>
parents: 326
diff changeset
107 If you can't see it, download them from http://modules.prosody.im:
6662cc9519cc updated INSTALL file
Goffi <goffi@goffi.org>
parents: 326
diff changeset
108
6662cc9519cc updated INSTALL file
Goffi <goffi@goffi.org>
parents: 326
diff changeset
109 wget http://hg.prosody.im/prosody-modules/raw-file/tip/mod_delegation/mod_delegation.lua
6662cc9519cc updated INSTALL file
Goffi <goffi@goffi.org>
parents: 326
diff changeset
110 wget http://hg.prosody.im/prosody-modules/raw-file/tip/mod_privilege/mod_privilege.lua
264
86e767dc6abb packaging for release
souliane <souliane@mailoo.org>
parents: 212
diff changeset
111
327
6662cc9519cc updated INSTALL file
Goffi <goffi@goffi.org>
parents: 326
diff changeset
112 Edit the prosody.cfg.lua file to add this module:
6662cc9519cc updated INSTALL file
Goffi <goffi@goffi.org>
parents: 326
diff changeset
113
6662cc9519cc updated INSTALL file
Goffi <goffi@goffi.org>
parents: 326
diff changeset
114 modules_enabled = {
6662cc9519cc updated INSTALL file
Goffi <goffi@goffi.org>
parents: 326
diff changeset
115 [...]
6662cc9519cc updated INSTALL file
Goffi <goffi@goffi.org>
parents: 326
diff changeset
116 "delegation";
6662cc9519cc updated INSTALL file
Goffi <goffi@goffi.org>
parents: 326
diff changeset
117 "privilege";
6662cc9519cc updated INSTALL file
Goffi <goffi@goffi.org>
parents: 326
diff changeset
118 [...]
6662cc9519cc updated INSTALL file
Goffi <goffi@goffi.org>
parents: 326
diff changeset
119 }
6662cc9519cc updated INSTALL file
Goffi <goffi@goffi.org>
parents: 326
diff changeset
120
6662cc9519cc updated INSTALL file
Goffi <goffi@goffi.org>
parents: 326
diff changeset
121 In your VirtualHost, add this lines:
6662cc9519cc updated INSTALL file
Goffi <goffi@goffi.org>
parents: 326
diff changeset
122
6662cc9519cc updated INSTALL file
Goffi <goffi@goffi.org>
parents: 326
diff changeset
123 VirtualHost "<your_xmpp_domain>"
326
b76cbf59772b update INSTALL file, we don't use remote roster anymore
souliane <souliane@mailoo.org>
parents: 276
diff changeset
124 privileged_entities = {
327
6662cc9519cc updated INSTALL file
Goffi <goffi@goffi.org>
parents: 326
diff changeset
125 ["sat-pubsub.<your_xmpp_domain>"] = {
326
b76cbf59772b update INSTALL file, we don't use remote roster anymore
souliane <souliane@mailoo.org>
parents: 276
diff changeset
126 roster = "get";
b76cbf59772b update INSTALL file, we don't use remote roster anymore
souliane <souliane@mailoo.org>
parents: 276
diff changeset
127 message = "outgoing";
b76cbf59772b update INSTALL file, we don't use remote roster anymore
souliane <souliane@mailoo.org>
parents: 276
diff changeset
128 },
b76cbf59772b update INSTALL file, we don't use remote roster anymore
souliane <souliane@mailoo.org>
parents: 276
diff changeset
129 }
b76cbf59772b update INSTALL file, we don't use remote roster anymore
souliane <souliane@mailoo.org>
parents: 276
diff changeset
130 delegations = {
b76cbf59772b update INSTALL file, we don't use remote roster anymore
souliane <souliane@mailoo.org>
parents: 276
diff changeset
131 ["urn:xmpp:mam:1"] = {
b76cbf59772b update INSTALL file, we don't use remote roster anymore
souliane <souliane@mailoo.org>
parents: 276
diff changeset
132 filtering = {"node"};
327
6662cc9519cc updated INSTALL file
Goffi <goffi@goffi.org>
parents: 326
diff changeset
133 jid = "sat-pubsub.<your_xmpp_domain>";
326
b76cbf59772b update INSTALL file, we don't use remote roster anymore
souliane <souliane@mailoo.org>
parents: 276
diff changeset
134 },
b76cbf59772b update INSTALL file, we don't use remote roster anymore
souliane <souliane@mailoo.org>
parents: 276
diff changeset
135 ["http://jabber.org/protocol/pubsub"] = {
327
6662cc9519cc updated INSTALL file
Goffi <goffi@goffi.org>
parents: 326
diff changeset
136 jid = "sat-pubsub.<your_xmpp_domain>";
326
b76cbf59772b update INSTALL file, we don't use remote roster anymore
souliane <souliane@mailoo.org>
parents: 276
diff changeset
137 },
264
86e767dc6abb packaging for release
souliane <souliane@mailoo.org>
parents: 212
diff changeset
138 }
155
5191ba7c4df8 Work towards first release 0.5.0.
Ralph Meijer <ralphm@ik.nu>
parents:
diff changeset
139
327
6662cc9519cc updated INSTALL file
Goffi <goffi@goffi.org>
parents: 326
diff changeset
140 Also add these two lines at the end of the file, adapting them to your XMPP server
6662cc9519cc updated INSTALL file
Goffi <goffi@goffi.org>
parents: 326
diff changeset
141 domain (virtual host) and selecting a password of your choice:
155
5191ba7c4df8 Work towards first release 0.5.0.
Ralph Meijer <ralphm@ik.nu>
parents:
diff changeset
142
327
6662cc9519cc updated INSTALL file
Goffi <goffi@goffi.org>
parents: 326
diff changeset
143 Component "sat-pubsub.<your_xmpp_domain>"
6662cc9519cc updated INSTALL file
Goffi <goffi@goffi.org>
parents: 326
diff changeset
144 component_secret = "<password>"
6662cc9519cc updated INSTALL file
Goffi <goffi@goffi.org>
parents: 326
diff changeset
145 modules_enabled = {"delegation", "privilege"}
155
5191ba7c4df8 Work towards first release 0.5.0.
Ralph Meijer <ralphm@ik.nu>
parents:
diff changeset
146
327
6662cc9519cc updated INSTALL file
Goffi <goffi@goffi.org>
parents: 326
diff changeset
147 For a more complete installation and configuration of Prosody to be used with
6662cc9519cc updated INSTALL file
Goffi <goffi@goffi.org>
parents: 326
diff changeset
148 sat_pubsub, please report yourself to the Salut à Toi wiki:
264
86e767dc6abb packaging for release
souliane <souliane@mailoo.org>
parents: 212
diff changeset
149
327
6662cc9519cc updated INSTALL file
Goffi <goffi@goffi.org>
parents: 326
diff changeset
150 http://wiki.goffi.org/wiki/Libervia/en#XMPP_server