annotate INSTALL @ 276:b757c29b20d7

import changes from idavoll changeset 233 (24be3a11ddbc), by Ralph Meijer and based on a patch by Nuno Santos
author souliane <souliane@mailoo.org>
date Mon, 13 Oct 2014 15:59:25 +0200
parents 86e767dc6abb
children b76cbf59772b
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
193
8ab16e319bb8 Release Idavoll 0.7.3.
Ralph Meijer <ralphm@ik.nu>
parents: 189
diff changeset
4 - Twisted >= 8.0.1:
8ab16e319bb8 Release Idavoll 0.7.3.
Ralph Meijer <ralphm@ik.nu>
parents: 189
diff changeset
5 - Twisted Core
8ab16e319bb8 Release Idavoll 0.7.3.
Ralph Meijer <ralphm@ik.nu>
parents: 189
diff changeset
6 - Twisted Words
168
e2c2c2baf483 Fix use of uuid module now shipping with Python 2.5.
Ralph Meijer <ralphm@ik.nu>
parents: 167
diff changeset
7 - uuid.py (Python 2.5 std. lib. or http://pypi.python.org/pypi/uuid)
212
edabaa535476 These files also belong to the Idavoll 0.9.0 release.
Ralph Meijer <ralphm@ik.nu>
parents: 207
diff changeset
8 - Wokkel >= 0.5.0 (http://wokkel.ik.nu/)
264
86e767dc6abb packaging for release
souliane <souliane@mailoo.org>
parents: 212
diff changeset
9 - A Jabber server that supports the component protocol (XEP-0114),
86e767dc6abb packaging for release
souliane <souliane@mailoo.org>
parents: 212
diff changeset
10 and, to enable the micro-blogging feature, the remote roster
86e767dc6abb packaging for release
souliane <souliane@mailoo.org>
parents: 212
diff changeset
11 management protocol (XEP-0321). We recommend using Prosody.
155
5191ba7c4df8 Work towards first release 0.5.0.
Ralph Meijer <ralphm@ik.nu>
parents:
diff changeset
12
5191ba7c4df8 Work towards first release 0.5.0.
Ralph Meijer <ralphm@ik.nu>
parents:
diff changeset
13 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
14
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
15 - PostgreSQL (including development files for psycopg2)
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
16 - psycopg2
155
5191ba7c4df8 Work towards first release 0.5.0.
Ralph Meijer <ralphm@ik.nu>
parents:
diff changeset
17
193
8ab16e319bb8 Release Idavoll 0.7.3.
Ralph Meijer <ralphm@ik.nu>
parents: 189
diff changeset
18
155
5191ba7c4df8 Work towards first release 0.5.0.
Ralph Meijer <ralphm@ik.nu>
parents:
diff changeset
19 Installation
5191ba7c4df8 Work towards first release 0.5.0.
Ralph Meijer <ralphm@ik.nu>
parents:
diff changeset
20 ============
5191ba7c4df8 Work towards first release 0.5.0.
Ralph Meijer <ralphm@ik.nu>
parents:
diff changeset
21
264
86e767dc6abb packaging for release
souliane <souliane@mailoo.org>
parents: 212
diff changeset
22 sat_pubsub uses setuptools for package building and installing.
86e767dc6abb packaging for release
souliane <souliane@mailoo.org>
parents: 212
diff changeset
23 To build from the source run:
193
8ab16e319bb8 Release Idavoll 0.7.3.
Ralph Meijer <ralphm@ik.nu>
parents: 189
diff changeset
24
8ab16e319bb8 Release Idavoll 0.7.3.
Ralph Meijer <ralphm@ik.nu>
parents: 189
diff changeset
25 python setup.py build
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 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
28
5191ba7c4df8 Work towards first release 0.5.0.
Ralph Meijer <ralphm@ik.nu>
parents:
diff changeset
29 python setup.py install
5191ba7c4df8 Work towards first release 0.5.0.
Ralph Meijer <ralphm@ik.nu>
parents:
diff changeset
30
193
8ab16e319bb8 Release Idavoll 0.7.3.
Ralph Meijer <ralphm@ik.nu>
parents: 189
diff changeset
31 See the setuptools documentation for further information on changing
8ab16e319bb8 Release Idavoll 0.7.3.
Ralph Meijer <ralphm@ik.nu>
parents: 189
diff changeset
32 installation locations.
8ab16e319bb8 Release Idavoll 0.7.3.
Ralph Meijer <ralphm@ik.nu>
parents: 189
diff changeset
33
8ab16e319bb8 Release Idavoll 0.7.3.
Ralph Meijer <ralphm@ik.nu>
parents: 189
diff changeset
34
155
5191ba7c4df8 Work towards first release 0.5.0.
Ralph Meijer <ralphm@ik.nu>
parents:
diff changeset
35 Configuration
5191ba7c4df8 Work towards first release 0.5.0.
Ralph Meijer <ralphm@ik.nu>
parents:
diff changeset
36 =============
5191ba7c4df8 Work towards first release 0.5.0.
Ralph Meijer <ralphm@ik.nu>
parents:
diff changeset
37
264
86e767dc6abb packaging for release
souliane <souliane@mailoo.org>
parents: 212
diff changeset
38 sat_pubsub uses Twisted's twistd command for running its services. Starting with
193
8ab16e319bb8 Release Idavoll 0.7.3.
Ralph Meijer <ralphm@ik.nu>
parents: 189
diff changeset
39 Twisted 2.5.0, twistd supports running Twisted Application Plugins directly,
8ab16e319bb8 Release Idavoll 0.7.3.
Ralph Meijer <ralphm@ik.nu>
parents: 189
diff changeset
40 without the use of mktap. In Twisted 8.1.0, the use of mktap for configuration
264
86e767dc6abb packaging for release
souliane <souliane@mailoo.org>
parents: 212
diff changeset
41 is deprecated.
193
8ab16e319bb8 Release Idavoll 0.7.3.
Ralph Meijer <ralphm@ik.nu>
parents: 189
diff changeset
42
264
86e767dc6abb packaging for release
souliane <souliane@mailoo.org>
parents: 212
diff changeset
43 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
44 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
45 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
46
264
86e767dc6abb packaging for release
souliane <souliane@mailoo.org>
parents: 212
diff changeset
47 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
48
264
86e767dc6abb packaging for release
souliane <souliane@mailoo.org>
parents: 212
diff changeset
49 sudo -u postgres createuser -d -P `whoami`
86e767dc6abb packaging for release
souliane <souliane@mailoo.org>
parents: 212
diff changeset
50 createdb pubsub
86e767dc6abb packaging for release
souliane <souliane@mailoo.org>
parents: 212
diff changeset
51 psql pubsub < sat_pubsub/db/pubsub.sql
193
8ab16e319bb8 Release Idavoll 0.7.3.
Ralph Meijer <ralphm@ik.nu>
parents: 189
diff changeset
52
8ab16e319bb8 Release Idavoll 0.7.3.
Ralph Meijer <ralphm@ik.nu>
parents: 189
diff changeset
53
264
86e767dc6abb packaging for release
souliane <souliane@mailoo.org>
parents: 212
diff changeset
54 Your Jabber server must also be configured to accept component connections and,
86e767dc6abb packaging for release
souliane <souliane@mailoo.org>
parents: 212
diff changeset
55 to enable the micro-blogging feature, remote roster management. See below for details.
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
8ab16e319bb8 Release Idavoll 0.7.3.
Ralph Meijer <ralphm@ik.nu>
parents: 189
diff changeset
72 When the service starts, it will connect to the Jabber server at the local
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.
5191ba7c4df8 Work towards first release 0.5.0.
Ralph Meijer <ralphm@ik.nu>
parents:
diff changeset
83 --rport: the port number of the Jabber server to connect to
5191ba7c4df8 Work towards first release 0.5.0.
Ralph Meijer <ralphm@ik.nu>
parents:
diff changeset
84 --secret: the secret used to authenticate with the Jabber server.
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
86e767dc6abb packaging for release
souliane <souliane@mailoo.org>
parents: 212
diff changeset
88 twistd sat_pubsub --jid=sat-pubsub.<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
264
86e767dc6abb packaging for release
souliane <souliane@mailoo.org>
parents: 212
diff changeset
95 Running sat_pubsub with Prosody
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
86e767dc6abb packaging for release
souliane <souliane@mailoo.org>
parents: 212
diff changeset
99 the remote_roster plugin. Check if the remote_roster plugin is already
86e767dc6abb packaging for release
souliane <souliane@mailoo.org>
parents: 212
diff changeset
100 in your Prosody installation:
155
5191ba7c4df8 Work towards first release 0.5.0.
Ralph Meijer <ralphm@ik.nu>
parents:
diff changeset
101
264
86e767dc6abb packaging for release
souliane <souliane@mailoo.org>
parents: 212
diff changeset
102 cd prosody/plugins
86e767dc6abb packaging for release
souliane <souliane@mailoo.org>
parents: 212
diff changeset
103 ls mod_remote_roster.lua
86e767dc6abb packaging for release
souliane <souliane@mailoo.org>
parents: 212
diff changeset
104
86e767dc6abb packaging for release
souliane <souliane@mailoo.org>
parents: 212
diff changeset
105 If you can't see it, download it from here:
155
5191ba7c4df8 Work towards first release 0.5.0.
Ralph Meijer <ralphm@ik.nu>
parents:
diff changeset
106
264
86e767dc6abb packaging for release
souliane <souliane@mailoo.org>
parents: 212
diff changeset
107 wget http://prosody-modules.googlecode.com/hg/mod_remote_roster/mod_remote_roster.lua
86e767dc6abb packaging for release
souliane <souliane@mailoo.org>
parents: 212
diff changeset
108
86e767dc6abb packaging for release
souliane <souliane@mailoo.org>
parents: 212
diff changeset
109 You need to patch the file (commenting two lines to make all contacts available):
86e767dc6abb packaging for release
souliane <souliane@mailoo.org>
parents: 212
diff changeset
110
86e767dc6abb packaging for release
souliane <souliane@mailoo.org>
parents: 212
diff changeset
111 wget http://paste.debian.net/download/12106
86e767dc6abb packaging for release
souliane <souliane@mailoo.org>
parents: 212
diff changeset
112 patch -p2 < paste_1206
155
5191ba7c4df8 Work towards first release 0.5.0.
Ralph Meijer <ralphm@ik.nu>
parents:
diff changeset
113
264
86e767dc6abb packaging for release
souliane <souliane@mailoo.org>
parents: 212
diff changeset
114 Edit the prosodi.cfg.lua file to add this module:
155
5191ba7c4df8 Work towards first release 0.5.0.
Ralph Meijer <ralphm@ik.nu>
parents:
diff changeset
115
264
86e767dc6abb packaging for release
souliane <souliane@mailoo.org>
parents: 212
diff changeset
116 modules_enabled = {
86e767dc6abb packaging for release
souliane <souliane@mailoo.org>
parents: 212
diff changeset
117 [...]
86e767dc6abb packaging for release
souliane <souliane@mailoo.org>
parents: 212
diff changeset
118 "remote_roster";
86e767dc6abb packaging for release
souliane <souliane@mailoo.org>
parents: 212
diff changeset
119 [...]
86e767dc6abb packaging for release
souliane <souliane@mailoo.org>
parents: 212
diff changeset
120 }
155
5191ba7c4df8 Work towards first release 0.5.0.
Ralph Meijer <ralphm@ik.nu>
parents:
diff changeset
121
264
86e767dc6abb packaging for release
souliane <souliane@mailoo.org>
parents: 212
diff changeset
122 Also add these two lines at the end of the file, adapting them to your XMPP server
86e767dc6abb packaging for release
souliane <souliane@mailoo.org>
parents: 212
diff changeset
123 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
124
264
86e767dc6abb packaging for release
souliane <souliane@mailoo.org>
parents: 212
diff changeset
125 Component "sat-pubsub.<xmpp_domain>"
86e767dc6abb packaging for release
souliane <souliane@mailoo.org>
parents: 212
diff changeset
126 component_secret = "<password>"
155
5191ba7c4df8 Work towards first release 0.5.0.
Ralph Meijer <ralphm@ik.nu>
parents:
diff changeset
127
264
86e767dc6abb packaging for release
souliane <souliane@mailoo.org>
parents: 212
diff changeset
128 For a more complete installation and configuration of Prosody to be used with
86e767dc6abb packaging for release
souliane <souliane@mailoo.org>
parents: 212
diff changeset
129 sat_pubsub, please report yourself to the Salut à Toi wiki:
86e767dc6abb packaging for release
souliane <souliane@mailoo.org>
parents: 212
diff changeset
130
86e767dc6abb packaging for release
souliane <souliane@mailoo.org>
parents: 212
diff changeset
131 http://wiki.goffi.org/wiki/Libervia/en#XMPP_server