Mercurial > libervia-pubsub
annotate doc/installation.rst @ 430:5a0ada3b61ca
Full-Text Search implementation:
/!\ pgsql schema needs to be updated /!\
/!\ Minimal PostgreSQL required version is now 12 /!\
A new options is available to specify main language of a node. By default a `generic`
language is used (which uses the `simple` configuration in PostgreSQL). When a node owner
changes the language, the index is rebuilt accordingly. It is possible to have item
specific language for multilingual nodes (but for the moment the search is done with node
language, so the results won't be good). If an item language is explicitely set in
`item_languages`, the FTS configuration won't be affected by node FTS language setting.
Search is parsed with `websearch_to_tsquery` for now, but this parser doesn't handle
prefix matching, so it may be replaced in the future.
SetConfiguration now only updates the modified values, this avoid triggering the FTS
re-indexing on each config change. `_checkNodeExists` is not called anymore as we can
check if a row has been modified to see if the node exists, this avoid a useless query.
Item storing has been slighly improved with a useless SELECT and condition removed.
To avoid 2 schema updates in a row, the `sat_pubsub_update_5_6.sql` file also prepares the
implementation of XEP-0346 by updating nodes with a schema and creating the suitable
template nodes.
author | Goffi <goffi@goffi.org> |
---|---|
date | Fri, 11 Dec 2020 17:18:52 +0100 |
parents | f6f4f99f1a1b |
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 |