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
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
404
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
1 ============
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
2 Installation
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
3 ============
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
4
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
5 This are the instructions to install SàT Pubsub.
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
6
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
7 .. note::
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
8
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
9 SàT PubSub is not released yet and this documentation is work in progress
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
10
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
11
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
12 Requirements
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
13 ------------
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
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
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
18 - Twisted >= 15.2.0:
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
19 - Twisted Core
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
20 - Twisted Words
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
21 - Wokkel >= 0.7.1 (http://wokkel.ik.nu/)
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
22 - A XMPP server that supports the component protocol (XEP-0114),
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
23 and, to enable the micro-blogging feature, Namespace Delegation (XEP-0355)
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
24 and privileged entity (XEP-0356) are needed.
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
25 We recommend using Prosody with mod_privilege and mod_delegation modules (those modules
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
26 are maintained by us).
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
27 - SàT tmp (http://repos.goffi.org/sat_tmp) is currently needed for MAM and RSM handling
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
28
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
29 For the PostgreSQL backend, the following is also required:
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
30
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
31 - PostgreSQL >= 9.5 (including development files for psycopg2)
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
32 - psycopg2
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
33
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
34 Installation From Sources
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
35 -------------------------
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
36
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
37 To install SàT PubSub we'll work in a virtual environment. On Debian and derivatives you
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
38 should easily install dependencies with this::
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
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
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
41
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
42 Now go in a location where you can install SàT Pubsub, for instance your home directory::
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
43
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
44 $ cd
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
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
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
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
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
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
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
51 $ pip install hg+https://repos.goffi.org/sat_pubsub
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
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
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
60 Post Installation
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
61 -----------------
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
62
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
63 Once SàT Pubsub is installed, you'll need to create a PostgreSQL user, and create the
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
64 database::
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
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
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
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
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
70
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
71
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
72 .. _prosody_configuration:
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
73
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
74 Prosody Configuration
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
75 ---------------------
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
76
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
77 SàT PubSub can work with any XMPP server (which supports components), but if you want to
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
78 use it as your PEP service, you need a server which supports `XEP-0355`_ and `XEP-0356`_.
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
79
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
80 Below you'll find the instruction to use SàT PubSub as a PEP service with Prosody:
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
81
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
82 - add these two lines at the end of your ``prosody.cfg.lua`` file, adapting them to your XMPP
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
83 server domain (virtual host) and selecting a password of your choice:
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
84
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
85 .. sourcecode:: lua
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
86
425
968091cea547 doc: installation instructions corrections
Goffi <goffi@goffi.org>
parents: 421
diff changeset
87 Component "pubsub.<xmpp_domain>"
404
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
88 component_secret = "<password>"
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
89
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
90 - there are extra steps to enable the micro-blogging feature with Prosody. Please follow
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
91 the installation and configuration instructions that are given on these pages:
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
92
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
93 - https://modules.prosody.im/mod_delegation.html
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
94 - https://modules.prosody.im/mod_privilege.html
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
95
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
96 To keep your modules up to date, we recommend to clone the full modules
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
97 repository and then to symlink them like that:
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
98
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
99 .. sourcecode:: shell
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
100
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
101 % cd /path/to/install_dir
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
102 % hg clone https://hg.prosody.im/prosody-modules
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
103 % cd /path/to/prosody_plugins
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
104 % ln -sf /path/to/install_dir/prosody-modules/mod_delegation ./
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
105 % ln -sf /path/to/install_dir/prosody-modules/mod_privilege ./
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
106
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
107 Or course, you have to adapt ``/path/to/install_dir`` to the directory where you want to
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
108 install the modules, and ``/path/to/prosody_plugins`` to the directory where prosody
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
109 modules are installed (hint: check ``prosodyctl about`` to find the latter). The ``ln``
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
110 commands may have to be run as root depending on your installation.
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
111
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
112 Once your symlinks are set, to update the modules we just need to type this:
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
113
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
114 .. sourcecode:: shell
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
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
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
118
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
119 Here is an example of how your ``prosody.cfg.lua`` should look like with
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
120 ``mod_delegation`` and ``mod_privilege`` activated:
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
121
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
122 .. sourcecode:: lua
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
123
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
124 [...]
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
125 modules_enabled = {
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
126 [...]
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
127 "delegation";
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
128 "privilege";
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
129 }
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
130 [...]
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
131 VirtualHost "<xmpp_domain>"
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
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
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
134 roster = "get";
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
135 message = "outgoing";
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
136 presence = "roster";
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
137 },
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
138 }
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
139 delegations = {
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
140 ["urn:xmpp:mam:2"] = {
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
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
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
143 },
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
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
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
146 },
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
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
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
149 },
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
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
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
152 },
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
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
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
155 },
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
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
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
158 },
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
159 }
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
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
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
162 component_secret = "<password>"
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
163 modules_enabled = {"delegation", "privilege"}
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
164
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
165 Of course, you still have to replace and adapt to your own settings.
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
166
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
167 .. _XEP-0355: https://xmpp.org/extensions/xep-0355.html
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
168 .. _XEP-0356: https://xmpp.org/extensions/xep-0356.html
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
169
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
170 Running SàT PubSub
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
171 ------------------
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
172
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
173 The minimal example for running sat_pubsub is:
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
174
425
968091cea547 doc: installation instructions corrections
Goffi <goffi@goffi.org>
parents: 421
diff changeset
175 % twistd sat-pubsub
404
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
176
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
177 This will start the service and run it in the background. It generates a
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
178 file twistd.pid that holds the PID of the service and a log file twistd.log.
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
179 The twistd utility has a fair number of options that might be useful, and
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
180 can be viewed with:
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
181
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
182 % twistd --help
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
183
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
184 When the service starts, it will connect to the XMPP server at the local machine using the
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
185 component protocol, and assumes the JID ``pubsub``. This assumes a couple of defaults
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
186 which can be overridden by passing parameters to the twistd plugin. You can get an
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
187 overview of the parameters and their defaults using:
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
188
425
968091cea547 doc: installation instructions corrections
Goffi <goffi@goffi.org>
parents: 421
diff changeset
189 % twistd sat-pubsub --help
404
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
190
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
191 In particular, the following parameters will be of interest:
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
192
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
193 ``--jid``
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
194 The Jabber ID the component will assume.
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
195
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
196 ``--rport``
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
197 the port number of the XMPP server to connect to
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
198
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
199 ``--xmpp_pwd``
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
200 the secret used to authenticate with the XMPP server.
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
201
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
202 For example::
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
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
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
205
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
206 You can set your options in ``sat.conf`` which is the same file used as for Salut à Toi
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
207 ecosystem. Please check backend ``configuration`` section for details. The SàT PubSub
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
208 options must be in ``[pubsub]`` section.
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
209