annotate doc/installation.rst @ 445:fe24bb60236f

core: update conf file name following project renaming: As "Salut à Toi" has been renamed to "Libervia", the conf file is now named `libervia.conf`. To keep backward compatibility, `sat.conf` is still checked for the moment.
author Goffi <goffi@goffi.org>
date Sun, 21 Mar 2021 14:38:00 +0100
parents 6cef8aa1c991
children 67da33212b2b
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
436
80aca1cf1543 doc: added a warning for people using SàT Pubsub on a server already used in production
Goffi <goffi@goffi.org>
parents: 427
diff changeset
11 .. note::
80aca1cf1543 doc: added a warning for people using SàT Pubsub on a server already used in production
Goffi <goffi@goffi.org>
parents: 427
diff changeset
12
442
b38b8beac609 doc: better dev version instructions + update
Goffi <goffi@goffi.org>
parents: 436
diff changeset
13 /!\\ Beware, if you're installing SàT Pubsub on a server already running in production,
436
80aca1cf1543 doc: added a warning for people using SàT Pubsub on a server already used in production
Goffi <goffi@goffi.org>
parents: 427
diff changeset
14 it will replace your legacy Pubsub service, meaning that everything stored there won't
80aca1cf1543 doc: added a warning for people using SàT Pubsub on a server already used in production
Goffi <goffi@goffi.org>
parents: 427
diff changeset
15 be available anymore (this includes, and is not limited to, bookmarks, encryption
80aca1cf1543 doc: added a warning for people using SàT Pubsub on a server already used in production
Goffi <goffi@goffi.org>
parents: 427
diff changeset
16 keys, blogs, etc.).
80aca1cf1543 doc: added a warning for people using SàT Pubsub on a server already used in production
Goffi <goffi@goffi.org>
parents: 427
diff changeset
17
80aca1cf1543 doc: added a warning for people using SàT Pubsub on a server already used in production
Goffi <goffi@goffi.org>
parents: 427
diff changeset
18 Be sure to save everything from your legacy Pubsub service before switching to SàT
80aca1cf1543 doc: added a warning for people using SàT Pubsub on a server already used in production
Goffi <goffi@goffi.org>
parents: 427
diff changeset
19 Pubsub.
80aca1cf1543 doc: added a warning for people using SàT Pubsub on a server already used in production
Goffi <goffi@goffi.org>
parents: 427
diff changeset
20
80aca1cf1543 doc: added a warning for people using SàT Pubsub on a server already used in production
Goffi <goffi@goffi.org>
parents: 427
diff changeset
21 Migration scripts are not yet available, help is welcome to write them.
80aca1cf1543 doc: added a warning for people using SàT Pubsub on a server already used in production
Goffi <goffi@goffi.org>
parents: 427
diff changeset
22
404
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
23
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
24 Requirements
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
25 ------------
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
26
421
f124ed5ea78b doc: remove python2 references + added a warning for `python setup.py install`
Goffi <goffi@goffi.org>
parents: 409
diff changeset
27 - Python 3.7+
425
968091cea547 doc: installation instructions corrections
Goffi <goffi@goffi.org>
parents: 421
diff changeset
28 - Python 3 "venv", which may be installed with Python 3
968091cea547 doc: installation instructions corrections
Goffi <goffi@goffi.org>
parents: 421
diff changeset
29 - Mercurial
404
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
30 - A XMPP server that supports the component protocol (XEP-0114),
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
31 and, to enable the micro-blogging feature, Namespace Delegation (XEP-0355)
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
32 and privileged entity (XEP-0356) are needed.
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
33 We recommend using Prosody with mod_privilege and mod_delegation modules (those modules
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
34 are maintained by us).
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
35
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
36 For the PostgreSQL backend, the following is also required:
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
37
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
38 - PostgreSQL >= 9.5 (including development files for psycopg2)
442
b38b8beac609 doc: better dev version instructions + update
Goffi <goffi@goffi.org>
parents: 436
diff changeset
39
b38b8beac609 doc: better dev version instructions + update
Goffi <goffi@goffi.org>
parents: 436
diff changeset
40 Installation of dev version
b38b8beac609 doc: better dev version instructions + update
Goffi <goffi@goffi.org>
parents: 436
diff changeset
41 ---------------------------
b38b8beac609 doc: better dev version instructions + update
Goffi <goffi@goffi.org>
parents: 436
diff changeset
42
b38b8beac609 doc: better dev version instructions + update
Goffi <goffi@goffi.org>
parents: 436
diff changeset
43 First install system requirements. On a Debian system or derivative, you can use following
b38b8beac609 doc: better dev version instructions + update
Goffi <goffi@goffi.org>
parents: 436
diff changeset
44 instructions::
b38b8beac609 doc: better dev version instructions + update
Goffi <goffi@goffi.org>
parents: 436
diff changeset
45
b38b8beac609 doc: better dev version instructions + update
Goffi <goffi@goffi.org>
parents: 436
diff changeset
46 sudo apt-get install postgresql python3-dev python3-venv python3-wheel mercurial
b38b8beac609 doc: better dev version instructions + update
Goffi <goffi@goffi.org>
parents: 436
diff changeset
47
b38b8beac609 doc: better dev version instructions + update
Goffi <goffi@goffi.org>
parents: 436
diff changeset
48 Now go in a location where you can install SàT Pubsub, for instance your home directory::
b38b8beac609 doc: better dev version instructions + update
Goffi <goffi@goffi.org>
parents: 436
diff changeset
49
b38b8beac609 doc: better dev version instructions + update
Goffi <goffi@goffi.org>
parents: 436
diff changeset
50 $ cd
b38b8beac609 doc: better dev version instructions + update
Goffi <goffi@goffi.org>
parents: 436
diff changeset
51
b38b8beac609 doc: better dev version instructions + update
Goffi <goffi@goffi.org>
parents: 436
diff changeset
52 You'll need to create and activate a Python virtual environment::
b38b8beac609 doc: better dev version instructions + update
Goffi <goffi@goffi.org>
parents: 436
diff changeset
53
b38b8beac609 doc: better dev version instructions + update
Goffi <goffi@goffi.org>
parents: 436
diff changeset
54 $ python3 -m venv pubsub-venv
b38b8beac609 doc: better dev version instructions + update
Goffi <goffi@goffi.org>
parents: 436
diff changeset
55 $ source pubsub-venv/bin/activate
b38b8beac609 doc: better dev version instructions + update
Goffi <goffi@goffi.org>
parents: 436
diff changeset
56 $ pip install -U pip wheel
b38b8beac609 doc: better dev version instructions + update
Goffi <goffi@goffi.org>
parents: 436
diff changeset
57
b38b8beac609 doc: better dev version instructions + update
Goffi <goffi@goffi.org>
parents: 436
diff changeset
58 Then you need to clone the repository::
b38b8beac609 doc: better dev version instructions + update
Goffi <goffi@goffi.org>
parents: 436
diff changeset
59
b38b8beac609 doc: better dev version instructions + update
Goffi <goffi@goffi.org>
parents: 436
diff changeset
60 $ hg clone https://repos.goffi.org/sat_pubsub && cd sat_pubsub
b38b8beac609 doc: better dev version instructions + update
Goffi <goffi@goffi.org>
parents: 436
diff changeset
61
b38b8beac609 doc: better dev version instructions + update
Goffi <goffi@goffi.org>
parents: 436
diff changeset
62 Now you can install requirements::
b38b8beac609 doc: better dev version instructions + update
Goffi <goffi@goffi.org>
parents: 436
diff changeset
63
b38b8beac609 doc: better dev version instructions + update
Goffi <goffi@goffi.org>
parents: 436
diff changeset
64 $ pip install -r requirements.txt
b38b8beac609 doc: better dev version instructions + update
Goffi <goffi@goffi.org>
parents: 436
diff changeset
65
443
6cef8aa1c991 doc: add missing `pip install -e .`
Goffi <goffi@goffi.org>
parents: 442
diff changeset
66 And sat-pubsub itself::
6cef8aa1c991 doc: add missing `pip install -e .`
Goffi <goffi@goffi.org>
parents: 442
diff changeset
67
6cef8aa1c991 doc: add missing `pip install -e .`
Goffi <goffi@goffi.org>
parents: 442
diff changeset
68 $ pip install -e .
6cef8aa1c991 doc: add missing `pip install -e .`
Goffi <goffi@goffi.org>
parents: 442
diff changeset
69
6cef8aa1c991 doc: add missing `pip install -e .`
Goffi <goffi@goffi.org>
parents: 442
diff changeset
70 And that's it! Please refer to `Post Installation`_ to initialize database.
6cef8aa1c991 doc: add missing `pip install -e .`
Goffi <goffi@goffi.org>
parents: 442
diff changeset
71
6cef8aa1c991 doc: add missing `pip install -e .`
Goffi <goffi@goffi.org>
parents: 442
diff changeset
72 Next time you can update with::
6cef8aa1c991 doc: add missing `pip install -e .`
Goffi <goffi@goffi.org>
parents: 442
diff changeset
73
6cef8aa1c991 doc: add missing `pip install -e .`
Goffi <goffi@goffi.org>
parents: 442
diff changeset
74 $ hg pull -u
6cef8aa1c991 doc: add missing `pip install -e .`
Goffi <goffi@goffi.org>
parents: 442
diff changeset
75
6cef8aa1c991 doc: add missing `pip install -e .`
Goffi <goffi@goffi.org>
parents: 442
diff changeset
76 .. note::
6cef8aa1c991 doc: add missing `pip install -e .`
Goffi <goffi@goffi.org>
parents: 442
diff changeset
77
6cef8aa1c991 doc: add missing `pip install -e .`
Goffi <goffi@goffi.org>
parents: 442
diff changeset
78 if requirements change, you may have to enter ``pip install -r requirements.txt``
6cef8aa1c991 doc: add missing `pip install -e .`
Goffi <goffi@goffi.org>
parents: 442
diff changeset
79 again, check also `Update`_ below)
404
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
80
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
81 Installation From Sources
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
82 -------------------------
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
83
442
b38b8beac609 doc: better dev version instructions + update
Goffi <goffi@goffi.org>
parents: 436
diff changeset
84 .. note::
b38b8beac609 doc: better dev version instructions + update
Goffi <goffi@goffi.org>
parents: 436
diff changeset
85
b38b8beac609 doc: better dev version instructions + update
Goffi <goffi@goffi.org>
parents: 436
diff changeset
86 until the release of SàT Pubsub ``0.4.0`` it is recommended to install dev version
b38b8beac609 doc: better dev version instructions + update
Goffi <goffi@goffi.org>
parents: 436
diff changeset
87 with instructions above
b38b8beac609 doc: better dev version instructions + update
Goffi <goffi@goffi.org>
parents: 436
diff changeset
88
404
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
89 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
90 should easily install dependencies with this::
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
91
425
968091cea547 doc: installation instructions corrections
Goffi <goffi@goffi.org>
parents: 421
diff changeset
92 sudo apt-get install postgresql python3-dev python3-venv python3-wheel mercurial
404
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
93
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
94 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
95
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
96 $ cd
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
97
421
f124ed5ea78b doc: remove python2 references + added a warning for `python setup.py install`
Goffi <goffi@goffi.org>
parents: 409
diff changeset
98 And enter the following commands::
404
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
99
421
f124ed5ea78b doc: remove python2 references + added a warning for `python setup.py install`
Goffi <goffi@goffi.org>
parents: 409
diff changeset
100 $ python3 -m venv env
404
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
101 $ source env/bin/activate
442
b38b8beac609 doc: better dev version instructions + update
Goffi <goffi@goffi.org>
parents: 436
diff changeset
102 $ pip install -U pip wheel
b38b8beac609 doc: better dev version instructions + update
Goffi <goffi@goffi.org>
parents: 436
diff changeset
103 $ pip install sat-pubsub
404
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
104
421
f124ed5ea78b doc: remove python2 references + added a warning for `python setup.py install`
Goffi <goffi@goffi.org>
parents: 409
diff changeset
105 .. note::
f124ed5ea78b doc: remove python2 references + added a warning for `python setup.py install`
Goffi <goffi@goffi.org>
parents: 409
diff changeset
106
f124ed5ea78b doc: remove python2 references + added a warning for `python setup.py install`
Goffi <goffi@goffi.org>
parents: 409
diff changeset
107 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
108 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
109 install .`` instead.
f124ed5ea78b doc: remove python2 references + added a warning for `python setup.py install`
Goffi <goffi@goffi.org>
parents: 409
diff changeset
110
404
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
111 Post Installation
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
112 -----------------
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
113
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
114 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
115 database::
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
116
425
968091cea547 doc: installation instructions corrections
Goffi <goffi@goffi.org>
parents: 421
diff changeset
117 % sudo -u postgres createuser -d -P $(whoami)
968091cea547 doc: installation instructions corrections
Goffi <goffi@goffi.org>
parents: 421
diff changeset
118 % createdb pubsub
404
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
119 % 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
120 % psql pubsub < pubsub.sql
404
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
121
442
b38b8beac609 doc: better dev version instructions + update
Goffi <goffi@goffi.org>
parents: 436
diff changeset
122 Update
b38b8beac609 doc: better dev version instructions + update
Goffi <goffi@goffi.org>
parents: 436
diff changeset
123 ------
b38b8beac609 doc: better dev version instructions + update
Goffi <goffi@goffi.org>
parents: 436
diff changeset
124
b38b8beac609 doc: better dev version instructions + update
Goffi <goffi@goffi.org>
parents: 436
diff changeset
125 If you have updated SàT Pubsub and the database schema has been changed, you may have a
b38b8beac609 doc: better dev version instructions + update
Goffi <goffi@goffi.org>
parents: 436
diff changeset
126 message indicating that your are using an outdated version.
b38b8beac609 doc: better dev version instructions + update
Goffi <goffi@goffi.org>
parents: 436
diff changeset
127
b38b8beac609 doc: better dev version instructions + update
Goffi <goffi@goffi.org>
parents: 436
diff changeset
128 To update schema, just apply ``sat_pubsub_update_x_y.sql`` files where ``x`` is your
b38b8beac609 doc: better dev version instructions + update
Goffi <goffi@goffi.org>
parents: 436
diff changeset
129 current version, and ``y`` is the one to update. If you are several versions late, just
b38b8beac609 doc: better dev version instructions + update
Goffi <goffi@goffi.org>
parents: 436
diff changeset
130 apply updates one by one.
b38b8beac609 doc: better dev version instructions + update
Goffi <goffi@goffi.org>
parents: 436
diff changeset
131
b38b8beac609 doc: better dev version instructions + update
Goffi <goffi@goffi.org>
parents: 436
diff changeset
132 For instance, if you have the following message::
b38b8beac609 doc: better dev version instructions + update
Goffi <goffi@goffi.org>
parents: 436
diff changeset
133
b38b8beac609 doc: better dev version instructions + update
Goffi <goffi@goffi.org>
parents: 436
diff changeset
134 ERROR:root:Bad database schema version (7), please upgrade to 8
b38b8beac609 doc: better dev version instructions + update
Goffi <goffi@goffi.org>
parents: 436
diff changeset
135
b38b8beac609 doc: better dev version instructions + update
Goffi <goffi@goffi.org>
parents: 436
diff changeset
136 Go to ``db`` directory and enter update instruction::
b38b8beac609 doc: better dev version instructions + update
Goffi <goffi@goffi.org>
parents: 436
diff changeset
137
b38b8beac609 doc: better dev version instructions + update
Goffi <goffi@goffi.org>
parents: 436
diff changeset
138 $ cd db
b38b8beac609 doc: better dev version instructions + update
Goffi <goffi@goffi.org>
parents: 436
diff changeset
139 $ psql pubsub < sat_pubsub_update_7_8.sql
b38b8beac609 doc: better dev version instructions + update
Goffi <goffi@goffi.org>
parents: 436
diff changeset
140
b38b8beac609 doc: better dev version instructions + update
Goffi <goffi@goffi.org>
parents: 436
diff changeset
141 .. note::
b38b8beac609 doc: better dev version instructions + update
Goffi <goffi@goffi.org>
parents: 436
diff changeset
142
b38b8beac609 doc: better dev version instructions + update
Goffi <goffi@goffi.org>
parents: 436
diff changeset
143 Before any update and specially if there is a schema change, you should backup your
b38b8beac609 doc: better dev version instructions + update
Goffi <goffi@goffi.org>
parents: 436
diff changeset
144 database. If anything goes wrong, it will be your best chance to avoid any data loss.
b38b8beac609 doc: better dev version instructions + update
Goffi <goffi@goffi.org>
parents: 436
diff changeset
145
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 .. _prosody_configuration:
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
148
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
149 Prosody Configuration
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
150 ---------------------
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
151
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
152 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
153 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
154
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
155 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
156
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
157 - 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
158 server domain (virtual host) and selecting a password of your choice:
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
159
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
160 .. sourcecode:: lua
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
161
425
968091cea547 doc: installation instructions corrections
Goffi <goffi@goffi.org>
parents: 421
diff changeset
162 Component "pubsub.<xmpp_domain>"
404
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
163 component_secret = "<password>"
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
164
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
165 - 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
166 the installation and configuration instructions that are given on these pages:
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
167
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
168 - https://modules.prosody.im/mod_delegation.html
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
169 - https://modules.prosody.im/mod_privilege.html
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
170
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
171 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
172 repository and then to symlink them like that:
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
173
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
174 .. sourcecode:: shell
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
175
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
176 % cd /path/to/install_dir
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
177 % hg clone https://hg.prosody.im/prosody-modules
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
178 % cd /path/to/prosody_plugins
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
179 % ln -sf /path/to/install_dir/prosody-modules/mod_delegation ./
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
180 % ln -sf /path/to/install_dir/prosody-modules/mod_privilege ./
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
181
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
182 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
183 install the modules, and ``/path/to/prosody_plugins`` to the directory where prosody
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
184 modules are installed (hint: check ``prosodyctl about`` to find the latter). The ``ln``
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
185 commands may have to be run as root depending on your installation.
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
186
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
187 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
188
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
189 .. sourcecode:: shell
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
190
425
968091cea547 doc: installation instructions corrections
Goffi <goffi@goffi.org>
parents: 421
diff changeset
191 % cd /path/to/install_dir/prosody-modules
968091cea547 doc: installation instructions corrections
Goffi <goffi@goffi.org>
parents: 421
diff changeset
192 % hg pull -u
404
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
193
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
194 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
195 ``mod_delegation`` and ``mod_privilege`` activated:
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
196
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
197 .. sourcecode:: lua
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
198
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
199 [...]
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
200 modules_enabled = {
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
201 [...]
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
202 "delegation";
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
203 "privilege";
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
204 }
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
205 [...]
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
206 VirtualHost "<xmpp_domain>"
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
207 privileged_entities = {
427
f6f4f99f1a1b doc: explicite "wheel" installation + renamed "sat-pubsub.*" jids to simpler "pubsub.*"
Goffi <goffi@goffi.org>
parents: 425
diff changeset
208 ["pubsub.<xmpp_domain>"] = {
404
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
209 roster = "get";
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
210 message = "outgoing";
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
211 presence = "roster";
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
212 },
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
213 }
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
214 delegations = {
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
215 ["urn:xmpp:mam:2"] = {
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
216 filtering = {"node"};
427
f6f4f99f1a1b doc: explicite "wheel" installation + renamed "sat-pubsub.*" jids to simpler "pubsub.*"
Goffi <goffi@goffi.org>
parents: 425
diff changeset
217 jid = "pubsub.<xmpp_domain>";
404
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
218 },
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
219 ["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
220 jid = "pubsub.<xmpp_domain>";
404
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
221 },
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
222 ["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
223 jid = "pubsub.<xmpp_domain>";
404
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
224 },
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
225 ["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
226 jid = "pubsub.<xmpp_domain>";
404
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
227 },
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
228 ["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
229 jid = "pubsub.<xmpp_domain>";
404
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
230 },
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
231 ["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
232 jid = "pubsub.<xmpp_domain>";
404
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
233 },
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
234 }
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
235
427
f6f4f99f1a1b doc: explicite "wheel" installation + renamed "sat-pubsub.*" jids to simpler "pubsub.*"
Goffi <goffi@goffi.org>
parents: 425
diff changeset
236 Component "pubsub.<xmpp_domain>"
404
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
237 component_secret = "<password>"
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
238 modules_enabled = {"delegation", "privilege"}
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
239
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
240 Of course, you still have to replace and adapt to your own settings.
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
241
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
242 .. _XEP-0355: https://xmpp.org/extensions/xep-0355.html
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
243 .. _XEP-0356: https://xmpp.org/extensions/xep-0356.html
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
244
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
245 Running SàT PubSub
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
246 ------------------
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
247
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
248 The minimal example for running sat_pubsub is:
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
249
425
968091cea547 doc: installation instructions corrections
Goffi <goffi@goffi.org>
parents: 421
diff changeset
250 % twistd sat-pubsub
404
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
251
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
252 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
253 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
254 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
255 can be viewed with:
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
256
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
257 % twistd --help
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
258
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
259 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
260 component protocol, and assumes the JID ``pubsub``. This assumes a couple of defaults
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
261 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
262 overview of the parameters and their defaults using:
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
263
425
968091cea547 doc: installation instructions corrections
Goffi <goffi@goffi.org>
parents: 421
diff changeset
264 % twistd sat-pubsub --help
404
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
265
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
266 In particular, the following parameters will be of interest:
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
267
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
268 ``--jid``
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
269 The Jabber ID the component will assume.
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
270
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
271 ``--rport``
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
272 the port number of the XMPP server to connect to
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
273
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
274 ``--xmpp_pwd``
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
275 the secret used to authenticate with the XMPP server.
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
276
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
277 For example::
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
278
427
f6f4f99f1a1b doc: explicite "wheel" installation + renamed "sat-pubsub.*" jids to simpler "pubsub.*"
Goffi <goffi@goffi.org>
parents: 425
diff changeset
279 twistd sat-pubsub --jid=pubsub.<your_xmpp_domain> --xmpp_pwd=<password>
404
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
280
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
281 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
282 ecosystem. Please check backend ``configuration`` section for details. The SàT PubSub
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
283 options must be in ``[pubsub]`` section.
105a0772eedd doc: first draft
Goffi <goffi@goffi.org>
parents:
diff changeset
284