annotate INSTALL @ 367:a772f7dac930

backend, storage(pgsql): creation/update date + serial ids: /!\ this patch updates pgqsl schema /!\ Had to set 2 features in the same patch, to avoid updating 2 times the schema. 1) creation/last modification date: column keeping the date of creation of items is renamed from "date" to "created" the date of last modification of items is saved in the new "updated" column 2) serial ids: this experimental feature allows to have ids in series (i.e. 1, 2, 3, etc.) instead of UUID. This is a convenience feature and there are some drawbacks: - PostgreSQL sequences are used, so gaps can happen (see PostgreSQL documentation for more details) - if somebody create an item with a future id in the series, the series will adapt, which can have undesired effect, and may lead to item fail if several items are created at the same time. For instance if next id in series is "8", and somebody hads already created item "8" and "256", the item will be created with biggest value in items +1 (i.e. 257). if 2 people want to create item in this situation, the second will fail with a conflict error.
author Goffi <goffi@goffi.org>
date Sat, 04 Nov 2017 21:31:32 +0100
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