Mercurial > libervia-pubsub
annotate doc/installation.rst @ 427:f6f4f99f1a1b
doc: explicite "wheel" installation + renamed "sat-pubsub.*" jids to simpler "pubsub.*"
| author | Goffi <goffi@goffi.org> |
|---|---|
| date | Fri, 09 Oct 2020 18:22:45 +0200 |
| parents | 968091cea547 |
| children | 80aca1cf1543 |
| rev | line source |
|---|---|
| 404 | 1 ============ |
| 2 Installation | |
| 3 ============ | |
| 4 | |
| 5 This are the instructions to install SàT Pubsub. | |
| 6 | |
| 7 .. note:: | |
| 8 | |
| 9 SàT PubSub is not released yet and this documentation is work in progress | |
| 10 | |
| 11 | |
| 12 Requirements | |
| 13 ------------ | |
| 14 | |
|
421
f124ed5ea78b
doc: remove python2 references + added a warning for `python setup.py install`
Goffi <goffi@goffi.org>
parents:
409
diff
changeset
|
15 - Python 3.7+ |
|
425
968091cea547
doc: installation instructions corrections
Goffi <goffi@goffi.org>
parents:
421
diff
changeset
|
16 - Python 3 "venv", which may be installed with Python 3 |
|
968091cea547
doc: installation instructions corrections
Goffi <goffi@goffi.org>
parents:
421
diff
changeset
|
17 - Mercurial |
| 404 | 18 - Twisted >= 15.2.0: |
| 19 - Twisted Core | |
| 20 - Twisted Words | |
| 21 - Wokkel >= 0.7.1 (http://wokkel.ik.nu/) | |
| 22 - A XMPP server that supports the component protocol (XEP-0114), | |
| 23 and, to enable the micro-blogging feature, Namespace Delegation (XEP-0355) | |
| 24 and privileged entity (XEP-0356) are needed. | |
| 25 We recommend using Prosody with mod_privilege and mod_delegation modules (those modules | |
| 26 are maintained by us). | |
| 27 - SàT tmp (http://repos.goffi.org/sat_tmp) is currently needed for MAM and RSM handling | |
| 28 | |
| 29 For the PostgreSQL backend, the following is also required: | |
| 30 | |
| 31 - PostgreSQL >= 9.5 (including development files for psycopg2) | |
| 32 - psycopg2 | |
| 33 | |
| 34 Installation From Sources | |
| 35 ------------------------- | |
| 36 | |
| 37 To install SàT PubSub we'll work in a virtual environment. On Debian and derivatives you | |
| 38 should easily install dependencies with this:: | |
| 39 | |
|
425
968091cea547
doc: installation instructions corrections
Goffi <goffi@goffi.org>
parents:
421
diff
changeset
|
40 sudo apt-get install postgresql python3-dev python3-venv python3-wheel mercurial |
| 404 | 41 |
| 42 Now go in a location where you can install SàT Pubsub, for instance your home directory:: | |
| 43 | |
| 44 $ cd | |
| 45 | |
|
421
f124ed5ea78b
doc: remove python2 references + added a warning for `python setup.py install`
Goffi <goffi@goffi.org>
parents:
409
diff
changeset
|
46 And enter the following commands:: |
| 404 | 47 |
|
421
f124ed5ea78b
doc: remove python2 references + added a warning for `python setup.py install`
Goffi <goffi@goffi.org>
parents:
409
diff
changeset
|
48 $ python3 -m venv env |
| 404 | 49 $ source env/bin/activate |
|
427
f6f4f99f1a1b
doc: explicite "wheel" installation + renamed "sat-pubsub.*" jids to simpler "pubsub.*"
Goffi <goffi@goffi.org>
parents:
425
diff
changeset
|
50 $ pip install wheel |
| 404 | 51 $ pip install hg+https://repos.goffi.org/sat_pubsub |
| 52 | |
|
421
f124ed5ea78b
doc: remove python2 references + added a warning for `python setup.py install`
Goffi <goffi@goffi.org>
parents:
409
diff
changeset
|
53 .. note:: |
|
f124ed5ea78b
doc: remove python2 references + added a warning for `python setup.py install`
Goffi <goffi@goffi.org>
parents:
409
diff
changeset
|
54 |
|
f124ed5ea78b
doc: remove python2 references + added a warning for `python setup.py install`
Goffi <goffi@goffi.org>
parents:
409
diff
changeset
|
55 If your are installing from a local clone of the repository, it has been reported that |
|
f124ed5ea78b
doc: remove python2 references + added a warning for `python setup.py install`
Goffi <goffi@goffi.org>
parents:
409
diff
changeset
|
56 installation with ``python setup.py install`` is not working properly. Please use ``pip |
|
f124ed5ea78b
doc: remove python2 references + added a warning for `python setup.py install`
Goffi <goffi@goffi.org>
parents:
409
diff
changeset
|
57 install .`` instead. |
|
f124ed5ea78b
doc: remove python2 references + added a warning for `python setup.py install`
Goffi <goffi@goffi.org>
parents:
409
diff
changeset
|
58 |
|
f124ed5ea78b
doc: remove python2 references + added a warning for `python setup.py install`
Goffi <goffi@goffi.org>
parents:
409
diff
changeset
|
59 |
| 404 | 60 Post Installation |
| 61 ----------------- | |
| 62 | |
| 63 Once SàT Pubsub is installed, you'll need to create a PostgreSQL user, and create the | |
| 64 database:: | |
| 65 | |
|
425
968091cea547
doc: installation instructions corrections
Goffi <goffi@goffi.org>
parents:
421
diff
changeset
|
66 % sudo -u postgres createuser -d -P $(whoami) |
|
968091cea547
doc: installation instructions corrections
Goffi <goffi@goffi.org>
parents:
421
diff
changeset
|
67 % createdb pubsub |
| 404 | 68 % cd /tmp && wget https://repos.goffi.org/sat_pubsub/raw-file/tip/db/pubsub.sql |
|
425
968091cea547
doc: installation instructions corrections
Goffi <goffi@goffi.org>
parents:
421
diff
changeset
|
69 % psql pubsub < pubsub.sql |
| 404 | 70 |
| 71 | |
| 72 .. _prosody_configuration: | |
| 73 | |
| 74 Prosody Configuration | |
| 75 --------------------- | |
| 76 | |
| 77 SàT PubSub can work with any XMPP server (which supports components), but if you want to | |
| 78 use it as your PEP service, you need a server which supports `XEP-0355`_ and `XEP-0356`_. | |
| 79 | |
| 80 Below you'll find the instruction to use SàT PubSub as a PEP service with Prosody: | |
| 81 | |
| 82 - add these two lines at the end of your ``prosody.cfg.lua`` file, adapting them to your XMPP | |
| 83 server domain (virtual host) and selecting a password of your choice: | |
| 84 | |
| 85 .. sourcecode:: lua | |
| 86 | |
|
425
968091cea547
doc: installation instructions corrections
Goffi <goffi@goffi.org>
parents:
421
diff
changeset
|
87 Component "pubsub.<xmpp_domain>" |
| 404 | 88 component_secret = "<password>" |
| 89 | |
| 90 - there are extra steps to enable the micro-blogging feature with Prosody. Please follow | |
| 91 the installation and configuration instructions that are given on these pages: | |
| 92 | |
| 93 - https://modules.prosody.im/mod_delegation.html | |
| 94 - https://modules.prosody.im/mod_privilege.html | |
| 95 | |
| 96 To keep your modules up to date, we recommend to clone the full modules | |
| 97 repository and then to symlink them like that: | |
| 98 | |
| 99 .. sourcecode:: shell | |
| 100 | |
| 101 % cd /path/to/install_dir | |
| 102 % hg clone https://hg.prosody.im/prosody-modules | |
| 103 % cd /path/to/prosody_plugins | |
| 104 % ln -sf /path/to/install_dir/prosody-modules/mod_delegation ./ | |
| 105 % ln -sf /path/to/install_dir/prosody-modules/mod_privilege ./ | |
| 106 | |
| 107 Or course, you have to adapt ``/path/to/install_dir`` to the directory where you want to | |
| 108 install the modules, and ``/path/to/prosody_plugins`` to the directory where prosody | |
| 109 modules are installed (hint: check ``prosodyctl about`` to find the latter). The ``ln`` | |
| 110 commands may have to be run as root depending on your installation. | |
| 111 | |
| 112 Once your symlinks are set, to update the modules we just need to type this: | |
| 113 | |
| 114 .. sourcecode:: shell | |
| 115 | |
|
425
968091cea547
doc: installation instructions corrections
Goffi <goffi@goffi.org>
parents:
421
diff
changeset
|
116 % cd /path/to/install_dir/prosody-modules |
|
968091cea547
doc: installation instructions corrections
Goffi <goffi@goffi.org>
parents:
421
diff
changeset
|
117 % hg pull -u |
| 404 | 118 |
| 119 Here is an example of how your ``prosody.cfg.lua`` should look like with | |
| 120 ``mod_delegation`` and ``mod_privilege`` activated: | |
| 121 | |
| 122 .. sourcecode:: lua | |
| 123 | |
| 124 [...] | |
| 125 modules_enabled = { | |
| 126 [...] | |
| 127 "delegation"; | |
| 128 "privilege"; | |
| 129 } | |
| 130 [...] | |
| 131 VirtualHost "<xmpp_domain>" | |
| 132 privileged_entities = { | |
|
427
f6f4f99f1a1b
doc: explicite "wheel" installation + renamed "sat-pubsub.*" jids to simpler "pubsub.*"
Goffi <goffi@goffi.org>
parents:
425
diff
changeset
|
133 ["pubsub.<xmpp_domain>"] = { |
| 404 | 134 roster = "get"; |
| 135 message = "outgoing"; | |
| 136 presence = "roster"; | |
| 137 }, | |
| 138 } | |
| 139 delegations = { | |
| 140 ["urn:xmpp:mam:2"] = { | |
| 141 filtering = {"node"}; | |
|
427
f6f4f99f1a1b
doc: explicite "wheel" installation + renamed "sat-pubsub.*" jids to simpler "pubsub.*"
Goffi <goffi@goffi.org>
parents:
425
diff
changeset
|
142 jid = "pubsub.<xmpp_domain>"; |
| 404 | 143 }, |
| 144 ["http://jabber.org/protocol/pubsub"] = { | |
|
427
f6f4f99f1a1b
doc: explicite "wheel" installation + renamed "sat-pubsub.*" jids to simpler "pubsub.*"
Goffi <goffi@goffi.org>
parents:
425
diff
changeset
|
145 jid = "pubsub.<xmpp_domain>"; |
| 404 | 146 }, |
| 147 ["http://jabber.org/protocol/pubsub#owner"] = { | |
|
427
f6f4f99f1a1b
doc: explicite "wheel" installation + renamed "sat-pubsub.*" jids to simpler "pubsub.*"
Goffi <goffi@goffi.org>
parents:
425
diff
changeset
|
148 jid = "pubsub.<xmpp_domain>"; |
| 404 | 149 }, |
| 150 ["https://salut-a-toi/protocol/schema:0"] = { | |
|
427
f6f4f99f1a1b
doc: explicite "wheel" installation + renamed "sat-pubsub.*" jids to simpler "pubsub.*"
Goffi <goffi@goffi.org>
parents:
425
diff
changeset
|
151 jid = "pubsub.<xmpp_domain>"; |
| 404 | 152 }, |
| 153 ["http://jabber.org/protocol/disco#items:*"] = { | |
|
427
f6f4f99f1a1b
doc: explicite "wheel" installation + renamed "sat-pubsub.*" jids to simpler "pubsub.*"
Goffi <goffi@goffi.org>
parents:
425
diff
changeset
|
154 jid = "pubsub.<xmpp_domain>"; |
| 404 | 155 }, |
| 156 ["https://salut-a-toi.org/spec/pubsub_admin:0"] = { | |
|
427
f6f4f99f1a1b
doc: explicite "wheel" installation + renamed "sat-pubsub.*" jids to simpler "pubsub.*"
Goffi <goffi@goffi.org>
parents:
425
diff
changeset
|
157 jid = "pubsub.<xmpp_domain>"; |
| 404 | 158 }, |
| 159 } | |
| 160 | |
|
427
f6f4f99f1a1b
doc: explicite "wheel" installation + renamed "sat-pubsub.*" jids to simpler "pubsub.*"
Goffi <goffi@goffi.org>
parents:
425
diff
changeset
|
161 Component "pubsub.<xmpp_domain>" |
| 404 | 162 component_secret = "<password>" |
| 163 modules_enabled = {"delegation", "privilege"} | |
| 164 | |
| 165 Of course, you still have to replace and adapt to your own settings. | |
| 166 | |
| 167 .. _XEP-0355: https://xmpp.org/extensions/xep-0355.html | |
| 168 .. _XEP-0356: https://xmpp.org/extensions/xep-0356.html | |
| 169 | |
| 170 Running SàT PubSub | |
| 171 ------------------ | |
| 172 | |
| 173 The minimal example for running sat_pubsub is: | |
| 174 | |
|
425
968091cea547
doc: installation instructions corrections
Goffi <goffi@goffi.org>
parents:
421
diff
changeset
|
175 % twistd sat-pubsub |
| 404 | 176 |
| 177 This will start the service and run it in the background. It generates a | |
| 178 file twistd.pid that holds the PID of the service and a log file twistd.log. | |
| 179 The twistd utility has a fair number of options that might be useful, and | |
| 180 can be viewed with: | |
| 181 | |
| 182 % twistd --help | |
| 183 | |
| 184 When the service starts, it will connect to the XMPP server at the local machine using the | |
| 185 component protocol, and assumes the JID ``pubsub``. This assumes a couple of defaults | |
| 186 which can be overridden by passing parameters to the twistd plugin. You can get an | |
| 187 overview of the parameters and their defaults using: | |
| 188 | |
|
425
968091cea547
doc: installation instructions corrections
Goffi <goffi@goffi.org>
parents:
421
diff
changeset
|
189 % twistd sat-pubsub --help |
| 404 | 190 |
| 191 In particular, the following parameters will be of interest: | |
| 192 | |
| 193 ``--jid`` | |
| 194 The Jabber ID the component will assume. | |
| 195 | |
| 196 ``--rport`` | |
| 197 the port number of the XMPP server to connect to | |
| 198 | |
| 199 ``--xmpp_pwd`` | |
| 200 the secret used to authenticate with the XMPP server. | |
| 201 | |
| 202 For example:: | |
| 203 | |
|
427
f6f4f99f1a1b
doc: explicite "wheel" installation + renamed "sat-pubsub.*" jids to simpler "pubsub.*"
Goffi <goffi@goffi.org>
parents:
425
diff
changeset
|
204 twistd sat-pubsub --jid=pubsub.<your_xmpp_domain> --xmpp_pwd=<password> |
| 404 | 205 |
| 206 You can set your options in ``sat.conf`` which is the same file used as for Salut à Toi | |
| 207 ecosystem. Please check backend ``configuration`` section for details. The SàT PubSub | |
| 208 options must be in ``[pubsub]`` section. | |
| 209 |