Mercurial > libervia-pubsub

comparison doc/installation.rst @ 442:b38b8beac609

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
doc: better dev version instructions + update
author Goffi <goffi@goffi.org>
date Fri, 19 Mar 2021 12:46:32 +0100
parents 80aca1cf1543
children 6cef8aa1c991
comparison
equal deleted inserted replaced
441:9a5e66f8eeca 442:b38b8beac609
8 8
9 SàT PubSub is not released yet and this documentation is work in progress 9 SàT PubSub is not released yet and this documentation is work in progress
10 10
11 .. note:: 11 .. note::
12 12
13 /!\ Beware, if you're installing SàT Pubsub on a server already running in production, 13 /!\\ Beware, if you're installing SàT Pubsub on a server already running in production,
14 it will replace your legacy Pubsub service, meaning that everything stored there won't 14 it will replace your legacy Pubsub service, meaning that everything stored there won't
15 be available anymore (this includes, and is not limited to, bookmarks, encryption 15 be available anymore (this includes, and is not limited to, bookmarks, encryption
16 keys, blogs, etc.). 16 keys, blogs, etc.).
17 17
18 Be sure to save everything from your legacy Pubsub service before switching to SàT 18 Be sure to save everything from your legacy Pubsub service before switching to SàT
25 ------------ 25 ------------
26 26
27 - Python 3.7+ 27 - Python 3.7+
28 - Python 3 "venv", which may be installed with Python 3 28 - Python 3 "venv", which may be installed with Python 3
29 - Mercurial 29 - Mercurial
30 - Twisted >= 15.2.0:
31 - Twisted Core
32 - Twisted Words
33 - Wokkel >= 0.7.1 (http://wokkel.ik.nu/)
34 - A XMPP server that supports the component protocol (XEP-0114), 30 - A XMPP server that supports the component protocol (XEP-0114),
35 and, to enable the micro-blogging feature, Namespace Delegation (XEP-0355) 31 and, to enable the micro-blogging feature, Namespace Delegation (XEP-0355)
36 and privileged entity (XEP-0356) are needed. 32 and privileged entity (XEP-0356) are needed.
37 We recommend using Prosody with mod_privilege and mod_delegation modules (those modules 33 We recommend using Prosody with mod_privilege and mod_delegation modules (those modules
38 are maintained by us). 34 are maintained by us).
39 - SàT tmp (http://repos.goffi.org/sat_tmp) is currently needed for MAM and RSM handling
40 35
41 For the PostgreSQL backend, the following is also required: 36 For the PostgreSQL backend, the following is also required:
42 37
43 - PostgreSQL >= 9.5 (including development files for psycopg2) 38 - PostgreSQL >= 9.5 (including development files for psycopg2)
44 - psycopg2 39
40 Installation of dev version
41 ---------------------------
42
43 First install system requirements. On a Debian system or derivative, you can use following
44 instructions::
45
46 sudo apt-get install postgresql python3-dev python3-venv python3-wheel mercurial
47
48 Now go in a location where you can install SàT Pubsub, for instance your home directory::
49
50 $ cd
51
52 You'll need to create and activate a Python virtual environment::
53
54 $ python3 -m venv pubsub-venv
55 $ source pubsub-venv/bin/activate
56 $ pip install -U pip wheel
57
58 Then you need to clone the repository::
59
60 $ hg clone https://repos.goffi.org/sat_pubsub && cd sat_pubsub
61
62 Now you can install requirements::
63
64 $ pip install -r requirements.txt
65
66 And that's it! Please refer to :ref:`post_installation` to initialize database.
45 67
46 Installation From Sources 68 Installation From Sources
47 ------------------------- 69 -------------------------
48 70
71 .. note::
72
73 until the release of SàT Pubsub ``0.4.0`` it is recommended to install dev version
74 with instructions above
75
49 To install SàT PubSub we'll work in a virtual environment. On Debian and derivatives you 76 To install SàT PubSub we'll work in a virtual environment. On Debian and derivatives you
50 should easily install dependencies with this:: 77 should easily install dependencies with this::
51 78
52 sudo apt-get install postgresql python3-dev python3-venv python3-wheel mercurial 79 sudo apt-get install postgresql python3-dev python3-venv python3-wheel mercurial
53 80
57 84
58 And enter the following commands:: 85 And enter the following commands::
59 86
60 $ python3 -m venv env 87 $ python3 -m venv env
61 $ source env/bin/activate 88 $ source env/bin/activate
62 $ pip install wheel 89 $ pip install -U pip wheel
63 $ pip install hg+https://repos.goffi.org/sat_pubsub 90 $ pip install sat-pubsub
64 91
65 .. note:: 92 .. note::
66 93
67 If your are installing from a local clone of the repository, it has been reported that 94 If your are installing from a local clone of the repository, it has been reported that
68 installation with ``python setup.py install`` is not working properly. Please use ``pip 95 installation with ``python setup.py install`` is not working properly. Please use ``pip
69 install .`` instead. 96 install .`` instead.
70 97
98 .. _post_installation:
71 99
72 Post Installation 100 Post Installation
73 ----------------- 101 -----------------
74 102
75 Once SàT Pubsub is installed, you'll need to create a PostgreSQL user, and create the 103 Once SàT Pubsub is installed, you'll need to create a PostgreSQL user, and create the
77 105
78 % sudo -u postgres createuser -d -P $(whoami) 106 % sudo -u postgres createuser -d -P $(whoami)
79 % createdb pubsub 107 % createdb pubsub
80 % cd /tmp && wget https://repos.goffi.org/sat_pubsub/raw-file/tip/db/pubsub.sql 108 % cd /tmp && wget https://repos.goffi.org/sat_pubsub/raw-file/tip/db/pubsub.sql
81 % psql pubsub < pubsub.sql 109 % psql pubsub < pubsub.sql
110
111 Update
112 ------
113
114 If you have updated SàT Pubsub and the database schema has been changed, you may have a
115 message indicating that your are using an outdated version.
116
117 To update schema, just apply ``sat_pubsub_update_x_y.sql`` files where ``x`` is your
118 current version, and ``y`` is the one to update. If you are several versions late, just
119 apply updates one by one.
120
121 For instance, if you have the following message::
122
123 ERROR:root:Bad database schema version (7), please upgrade to 8
124
125 Go to ``db`` directory and enter update instruction::
126
127 $ cd db
128 $ psql pubsub < sat_pubsub_update_7_8.sql
129
130 .. note::
131
132 Before any update and specially if there is a schema change, you should backup your
133 database. If anything goes wrong, it will be your best chance to avoid any data loss.
82 134
83 135
84 .. _prosody_configuration: 136 .. _prosody_configuration:
85 137
86 Prosody Configuration 138 Prosody Configuration