Mercurial > libervia-pubsub
annotate INSTALL @ 196:00a6dbfbee42
Return deferreds on failure, instead of raising exceptions.
| author | Ralph Meijer <ralphm@ik.nu> |
|---|---|
| date | Tue, 10 Jun 2008 08:28:57 +0000 |
| parents | 8ab16e319bb8 |
| children | 43a4d0d6c076 |
| rev | line source |
|---|---|
| 155 | 1 Requirements |
| 2 ============ | |
| 3 | |
| 193 | 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 | |
|
168
e2c2c2baf483
Fix use of uuid module now shipping with Python 2.5.
Ralph Meijer <ralphm@ik.nu>
parents:
167
diff
changeset
|
10 - uuid.py (Python 2.5 std. lib. or http://pypi.python.org/pypi/uuid) |
| 189 | 11 - Wokkel >= 0.3.1 (http://wokkel.ik.nu/) |
| 193 | 12 - simplejson (for idavoll-http) |
| 13 - A Jabber server that supports the component protocol (XEP-0114) | |
| 155 | 14 |
| 15 For the PostgreSQL backend, the following is also required: | |
| 16 | |
| 17 - PostgreSQL | |
| 18 - pyPgSQL | |
| 19 | |
| 193 | 20 |
| 155 | 21 Installation |
| 22 ============ | |
| 23 | |
| 193 | 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: | |
| 155 | 38 |
| 39 python setup.py install | |
| 40 | |
| 193 | 41 See the setuptools documentation for further information on changing |
| 42 installation locations. | |
| 43 | |
| 44 | |
| 155 | 45 Configuration |
| 46 ============= | |
| 47 | |
| 193 | 48 Idavoll uses Twisted's twistd command for running its services. Starting with |
| 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: | |
| 155 | 101 |
| 102 --jid: The Jabber ID the component will assume. | |
| 103 --rport: the port number of the Jabber server to connect to | |
| 104 --secret: the secret used to authenticate with the Jabber server. | |
| 105 --backend: the backend storage facility to be used (memory or PostgreSQL). | |
| 106 | |
| 193 | 107 The defaults for Idavoll use the memory database and assume the default |
| 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 | |
| 155 | 114 |
| 115 jabberd 2.x | |
| 116 =========== | |
| 193 | 117 |
| 155 | 118 You can use the 'legacy' component support that defaults to port 5347 with |
| 193 | 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 | |
| 155 | 122 |
| 123 jabberd 1.4.x | |
| 124 ============= | |
| 125 | |
| 126 Put the following in the jabber.xml configuration file of jabberd: | |
| 127 | |
| 128 <service id='pubsub.localhost'> | |
| 129 <accept> | |
| 130 <ip>127.0.0.1</ip> | |
| 131 <port>5347</port> | |
| 132 <secret>secret</secret> | |
| 133 </accept> | |
| 134 </service> | |
| 135 | |
| 136 and restart jabberd. Unlike jabber 2.x, you can only have one component per | |
| 137 port, so the port number may need to be changed. | |
| 138 | |
| 139 For other server implementations, please refer to its documentation on | |
| 140 how to interact with server side components using the protocol defined in | |
| 141 JEP-0114. | |
| 142 | |
| 193 | 143 Then, you can start Idavoll with: |
| 155 | 144 |
| 193 | 145 twistd idavoll --rport=5347 --jid=pubsub.localhost --secret=secret |
| 155 | 146 |
| 147 This uses the (default) memory based backend. | |
| 148 | |
| 149 | |
| 193 | 150 Using TAC files to store a configuration |
| 151 ======================================== | |
| 155 | 152 |
| 193 | 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: | |
| 155 | 156 |
| 193 | 157 twisted -y idavoll.tac |