Mercurial > libervia-pubsub

comparison INSTALL @ 264:86e767dc6abb

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
packaging for release
author souliane <souliane@mailoo.org>
date Sat, 22 Feb 2014 06:10:24 +0100
parents edabaa535476
children b757c29b20d7
comparison
equal deleted inserted replaced
263:9dfd3890e646 264:86e767dc6abb
1 Requirements 1 Requirements
2 ============ 2 ============
3 3
4 - Twisted >= 8.0.1: 4 - Twisted >= 8.0.1:
5 - Twisted Core 5 - Twisted Core
6 - Twisted Conch (for idavoll-http)
7 - Twisted Web (for idavoll-http)
8 - Twisted Web2 (for idavoll-http)
9 - Twisted Words 6 - Twisted Words
10 - uuid.py (Python 2.5 std. lib. or http://pypi.python.org/pypi/uuid) 7 - uuid.py (Python 2.5 std. lib. or http://pypi.python.org/pypi/uuid)
11 - Wokkel >= 0.5.0 (http://wokkel.ik.nu/) 8 - Wokkel >= 0.5.0 (http://wokkel.ik.nu/)
12 - simplejson (for idavoll-http) 9 - A Jabber server that supports the component protocol (XEP-0114),
13 - A Jabber server that supports the component protocol (XEP-0114) 10 and, to enable the micro-blogging feature, the remote roster
11 management protocol (XEP-0321). We recommend using Prosody.
14 12
15 For the PostgreSQL backend, the following is also required: 13 For the PostgreSQL backend, the following is also required:
16 14
17 - PostgreSQL 15 - PostgreSQL
18 - pyPgSQL 16 - Psycopg 2
19 17
20 18
21 Installation 19 Installation
22 ============ 20 ============
23 21
24 Idavoll uses setuptools for package building and installing, and is also 22 sat_pubsub uses setuptools for package building and installing.
25 available through the Python Package Index (pypi). The easiest way to 23 To build from the source run:
26 install idavoll is:
27
28 easy_install idavoll
29
30 This will pull down the dependencies, if needed, except for the Twisted
31 packages.
32
33 To building from source run:
34 24
35 python setup.py build 25 python setup.py build
36 26
37 Then, to install run the following, possibly as root: 27 Then, to install run the following, possibly as root:
38 28
43 33
44 34
45 Configuration 35 Configuration
46 ============= 36 =============
47 37
48 Idavoll uses Twisted's twistd command for running its services. Starting with 38 sat_pubsub uses Twisted's twistd command for running its services. Starting with
49 Twisted 2.5.0, twistd supports running Twisted Application Plugins directly, 39 Twisted 2.5.0, twistd supports running Twisted Application Plugins directly,
50 without the use of mktap. In Twisted 8.1.0, the use of mktap for configuration 40 without the use of mktap. In Twisted 8.1.0, the use of mktap for configuration
51 is deprecated. These instructions will not cover the use of mktap anymore, but 41 is deprecated.
52 you can use TAC files to store a configuration, as described near the end
53 of this document.
54 42
55 Idavoll provides two types of storage for the backend: a memory-based storage 43 Idavoll, on which sat_pubsub is based, provides two types of storage for the backend:
56 facility, which is volatile, and a persistent storage facility using 44 a memory-based storage facility, which is volatile, and a persistent storage facility
57 PostgreSQL. By default, the memory backend is used. 45 using PostgreSQL. For now, sat_pubsub only uses the persistent storage facility.
58 46
59 For using the PostgreSQL backend, create a database (for example named pubsub) 47 For using the PostgreSQL backend, create a database (for example named pubsub):
60 like so:
61 48
49 sudo -u postgres createuser -d -P `whoami`
62 createdb pubsub 50 createdb pubsub
63 psql pubsub <db/pubsub.sql 51 psql pubsub < sat_pubsub/db/pubsub.sql
64
65 To use this backend, add the --backend=pgsql parameter to twistd, along
66 with the optional connection parameters (see twistd idavoll --help).
67
68 Your Jabber server must also be configured to accept component connections,
69 see below for details.
70 52
71 53
72 Running Idavoll 54 Your Jabber server must also be configured to accept component connections and,
73 =============== 55 to enable the micro-blogging feature, remote roster management. See below for details.
74 56
75 Idavoll provides two twistd plugins: idavoll and idavoll-http. The former
76 provides a generic publish-subscribe service, and the latter adds to that an
77 HTTP interface to access some of the features of the Idavoll backend, and also
78 provides a way to subscribe to, and receive notifications from, remote
79 publish-subscribe nodes.
80 57
81 The minimal example for running idavoll is: 58 Running sat_pubsub
59 ==================
82 60
83 twistd idavoll 61 The minimal example for running sat_pubsub is:
62
63 twistd sat_pubsub
84 64
85 This will start the service and run it in the background. It generates a 65 This will start the service and run it in the background. It generates a
86 file twistd.pid that holds the PID of the service and a log file twistd.log. 66 file twistd.pid that holds the PID of the service and a log file twistd.log.
87 The twistd utility has a fair number of options that might be useful, and 67 The twistd utility has a fair number of options that might be useful, and
88 can be viewed with: 68 can be viewed with:
93 machine using the component protocol, and assumes the JID 'pubsub'. This 73 machine using the component protocol, and assumes the JID 'pubsub'. This
94 assumes a couple of defaults which can be overridden by passing parameters to 74 assumes a couple of defaults which can be overridden by passing parameters to
95 the twistd plugin. You can get an overview of the parameters and their defaults 75 the twistd plugin. You can get an overview of the parameters and their defaults
96 using: 76 using:
97 77
98 twistd idavoll --help 78 twistd sat_pubsub --help
99 79
100 In particular, the following parameters will be of interest: 80 In particular, the following parameters will be of interest:
101 81
102 --jid: The Jabber ID the component will assume. 82 --jid: The Jabber ID the component will assume.
103 --rport: the port number of the Jabber server to connect to 83 --rport: the port number of the Jabber server to connect to
104 --secret: the secret used to authenticate with the Jabber server. 84 --secret: the secret used to authenticate with the Jabber server.
105 --backend: the backend storage facility to be used (memory or PostgreSQL).
106 85
107 The defaults for Idavoll use the memory database and assume the default 86 For example:
108 settings of jabberd 2.x for --rport and --secret. 87
88 twistd sat_pubsub --jid=sat-pubsub.<xmpp_domain> --secret=<password>
109 89
110 You may also want to provide the --verbose flag to see the traffic flow, 90 You may also want to provide the --verbose flag to see the traffic flow,
111 for example to debug the configuration. Below some specifics for the 91 for example to debug the configuration. Below some specifics for the
112 different Jabber server implementations. 92 Prosody XMPP server implementation.
113 93
114 94
115 jabberd 2.x 95 Running sat_pubsub with Prosody
116 =========== 96 ===============================
117 97
118 You can use the 'legacy' component support that defaults to port 5347 with 98 To enable the micro-blogging feature with Prosody XMPP server, you need
119 secret 'secret'. These are the defaults of Idavoll, so you don't need to 99 the remote_roster plugin. Check if the remote_roster plugin is already
120 alter the connection details with a default jabberd 2.x install. 100 in your Prosody installation:
121 101
102 cd prosody/plugins
103 ls mod_remote_roster.lua
122 104
123 jabberd 1.4.x 105 If you can't see it, download it from here:
124 =============
125 106
126 Put the following in the jabber.xml configuration file of jabberd: 107 wget http://prosody-modules.googlecode.com/hg/mod_remote_roster/mod_remote_roster.lua
127 108
128 <service id='pubsub.localhost'> 109 You need to patch the file (commenting two lines to make all contacts available):
129 <accept>
130 <ip>127.0.0.1</ip>
131 <port>5347</port>
132 <secret>secret</secret>
133 </accept>
134 </service>
135 110
136 and restart jabberd. Unlike jabber 2.x, you can only have one component per 111 wget http://paste.debian.net/download/12106
137 port, so the port number may need to be changed. 112 patch -p2 < paste_1206
138 113
139 For other server implementations, please refer to its documentation on 114 Edit the prosodi.cfg.lua file to add this module:
140 how to interact with server side components using the protocol defined in
141 JEP-0114.
142 115
143 Then, you can start Idavoll with: 116 modules_enabled = {
117 [...]
118 "remote_roster";
119 [...]
120 }
144 121
145 twistd idavoll --rport=5347 --jid=pubsub.localhost --secret=secret 122 Also add these two lines at the end of the file, adapting them to your XMPP server
123 domain (virtual host) and selecting a password of your choice:
146 124
147 This uses the (default) memory based backend. 125 Component "sat-pubsub.<xmpp_domain>"
126 component_secret = "<password>"
148 127
128 For a more complete installation and configuration of Prosody to be used with
129 sat_pubsub, please report yourself to the Salut à Toi wiki:
149 130
150 Using TAC files to store a configuration 131 http://wiki.goffi.org/wiki/Libervia/en#XMPP_server
151 ========================================
152
153 Apart from the provided TAPs that can be run with twistd, you can also create
154 a configuration file that can be used by twistd to start up Idavoll. You can
155 find an example in doc/examples/idavoll.tac, which can be run using:
156
157 twisted -y idavoll.tac