Mercurial > libervia-pubsub

comparison INSTALL @ 193:8ab16e319bb8

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Release Idavoll 0.7.3.
author Ralph Meijer <ralphm@ik.nu>
date Fri, 30 May 2008 10:04:24 +0000
parents c61034369463
children 43a4d0d6c076
comparison
equal deleted inserted replaced
192:a219fe70a762 193:8ab16e319bb8
1 Requirements 1 Requirements
2 ============ 2 ============
3 3
4 - Twisted >= 8.0.1 4 - Twisted >= 8.0.1:
5 - Twisted Core
6 - Twisted Conch (for idavoll-http)
7 - Twisted Web (for idavoll-http)
8 - Twisted Web2 (for idavoll-http)
9 - Twisted Words
5 - uuid.py (Python 2.5 std. lib. or http://pypi.python.org/pypi/uuid) 10 - uuid.py (Python 2.5 std. lib. or http://pypi.python.org/pypi/uuid)
6 - A Jabber server that supports the component protocol (JEP-0114)
7 - Wokkel >= 0.3.1 (http://wokkel.ik.nu/) 11 - Wokkel >= 0.3.1 (http://wokkel.ik.nu/)
12 - simplejson (for idavoll-http)
13 - A Jabber server that supports the component protocol (XEP-0114)
8 14
9 For the PostgreSQL backend, the following is also required: 15 For the PostgreSQL backend, the following is also required:
10 16
11 - PostgreSQL 17 - PostgreSQL
12 - pyPgSQL 18 - pyPgSQL
13 19
20
14 Installation 21 Installation
15 ============ 22 ============
16 23
17 Run: 24 Idavoll uses setuptools for package building and installing, and is also
25 available through the Python Package Index (pypi). The easiest way to
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
35 python setup.py build
36
37 Then, to install run the following, possibly as root:
18 38
19 python setup.py install 39 python setup.py install
40
41 See the setuptools documentation for further information on changing
42 installation locations.
43
20 44
21 Configuration 45 Configuration
22 ============= 46 =============
23 47
24 The configuration file is created using Twisted's mktap, which needs a number 48 Idavoll uses Twisted's twistd command for running its services. Starting with
25 of parameters: 49 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
51 is deprecated. These instructions will not cover the use of mktap anymore, but
52 you can use TAC files to store a configuration, as described near the end
53 of this document.
54
55 Idavoll provides two types of storage for the backend: a memory-based storage
56 facility, which is volatile, and a persistent storage facility using
57 PostgreSQL. By default, the memory backend is used.
58
59 For using the PostgreSQL backend, create a database (for example named pubsub)
60 like so:
61
62 createdb pubsub
63 psql 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
71
72 Running Idavoll
73 ===============
74
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
81 The minimal example for running idavoll is:
82
83 twistd idavoll
84
85 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.
87 The twistd utility has a fair number of options that might be useful, and
88 can be viewed with:
89
90 twistd --help
91
92 When the service starts, it will connect to the Jabber server at the local
93 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
95 the twistd plugin. You can get an overview of the parameters and their defaults
96 using:
97
98 twistd idavoll --help
99
100 In particular, the following parameters will be of interest:
26 101
27 --jid: The Jabber ID the component will assume. 102 --jid: The Jabber ID the component will assume.
28 --rport: the port number of the Jabber server to connect to 103 --rport: the port number of the Jabber server to connect to
29 --secret: the secret used to authenticate with the Jabber server. 104 --secret: the secret used to authenticate with the Jabber server.
30 --backend: the backend storage facility to be used (memory or PostgreSQL). 105 --backend: the backend storage facility to be used (memory or PostgreSQL).
31 106
32 The default settings of mktap for Idavoll use the memory database and assume 107 The defaults for Idavoll use the memory database and assume the default
33 the default settings of jabberd 2.x for --rport and --secret. 108 settings of jabberd 2.x for --rport and --secret.
109
110 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
112 different Jabber server implementations.
113
34 114
35 jabberd 2.x 115 jabberd 2.x
36 =========== 116 ===========
117
37 You can use the 'legacy' component support that defaults to port 5347 with 118 You can use the 'legacy' component support that defaults to port 5347 with
38 secret 'secret'. You do not need to add anything specific for this service. 119 secret 'secret'. These are the defaults of Idavoll, so you don't need to
120 alter the connection details with a default jabberd 2.x install.
121
39 122
40 jabberd 1.4.x 123 jabberd 1.4.x
41 ============= 124 =============
42 125
43 Put the following in the jabber.xml configuration file of jabberd: 126 Put the following in the jabber.xml configuration file of jabberd:
55 138
56 For other server implementations, please refer to its documentation on 139 For other server implementations, please refer to its documentation on
57 how to interact with server side components using the protocol defined in 140 how to interact with server side components using the protocol defined in
58 JEP-0114. 141 JEP-0114.
59 142
60 Then, in the same directory as this file run: 143 Then, you can start Idavoll with:
61 144
62 mktap idavoll --rport=5347 --jid=pubsub.localhost --secret=secret 145 twistd idavoll --rport=5347 --jid=pubsub.localhost --secret=secret
63 146
64 This uses the (default) memory based backend. 147 This uses the (default) memory based backend.
65 148
66 For using the PostgreSQL backend, create a database (for example named pubsub)
67 like so:
68 149
69 createdb pubsub 150 Using TAC files to store a configuration
70 psql pubsub <db/pubsub.sql 151 ========================================
71 152
72 To use this backend, add the --backend=pgsql parameter to mktap. 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:
73 156
74 For viewing all options, run: 157 twisted -y idavoll.tac
75
76 mktap idavoll --help
77
78 The generated file idavoll.tap now holds the configuration.
79
80 Running
81 =======
82
83 Using the configuration file idavoll.tap, run:
84
85 twistd -of idavoll.tap
86
87 This will start the service and run it in the background. It generates a
88 file twistd.pid that holds the PID of the service and a log file twistd.log.
89 The twistd utility has a fair number of options that might be useful, and
90 can be viewed with:
91
92 twistd --help