# HG changeset patch
# User Goffi <goffi@goffi.org>
# Date 1616154392 -3600
# Node ID b38b8beac609d281d0fb339bfe1d8b2823086478
# Parent  9a5e66f8eeca2fd495e1013ac80407b3b75b49af
doc: better dev version instructions + update

diff -r 9a5e66f8eeca -r b38b8beac609 doc/installation.rst
--- a/doc/installation.rst	Fri Mar 19 12:12:17 2021 +0100
+++ b/doc/installation.rst	Fri Mar 19 12:46:32 2021 +0100
@@ -10,7 +10,7 @@
 
 .. note::
 
-    /!\ Beware, if you're installing SàT Pubsub on a server already running in production,
+    /!\\ Beware, if you're installing SàT Pubsub on a server already running in production,
     it will replace your legacy Pubsub service, meaning that everything stored there won't
     be available anymore (this includes, and is not limited to, bookmarks, encryption
     keys, blogs, etc.).
@@ -27,25 +27,52 @@
 - Python 3.7+
 - Python 3 "venv", which may be installed with Python 3
 - Mercurial
-- Twisted >= 15.2.0:
-   - Twisted Core
-   - Twisted Words
-- Wokkel >= 0.7.1 (http://wokkel.ik.nu/)
 - A XMPP server that supports the component protocol (XEP-0114),
   and, to enable the micro-blogging feature, Namespace Delegation (XEP-0355)
   and privileged entity (XEP-0356) are needed.
   We recommend using Prosody with mod_privilege and mod_delegation modules (those modules
   are maintained by us).
-- SàT tmp (http://repos.goffi.org/sat_tmp) is currently needed for MAM and RSM handling
 
 For the PostgreSQL backend, the following is also required:
 
 - PostgreSQL >= 9.5 (including development files for psycopg2)
-- psycopg2
+
+Installation of dev version
+---------------------------
+
+First install system requirements. On a Debian system or derivative, you can use following
+instructions::
+
+    sudo apt-get install postgresql python3-dev python3-venv python3-wheel mercurial
+
+Now go in a location where you can install SàT Pubsub, for instance your home directory::
+
+    $ cd
+
+You'll need to create and activate a Python virtual environment::
+
+    $ python3 -m venv pubsub-venv
+    $ source pubsub-venv/bin/activate
+    $ pip install -U pip wheel
+
+Then you need to clone the repository::
+
+    $ hg clone https://repos.goffi.org/sat_pubsub && cd sat_pubsub
+
+Now you can install requirements::
+
+    $ pip install -r requirements.txt
+
+And that's it! Please refer to :ref:`post_installation` to initialize database.
 
 Installation From Sources
 -------------------------
 
+.. note::
+
+    until the release of SàT Pubsub ``0.4.0`` it is recommended to install dev version
+    with instructions above
+
 To install SàT PubSub we'll work in a virtual environment. On Debian and derivatives you
 should easily install dependencies with this::
 
@@ -59,8 +86,8 @@
 
     $ python3 -m venv env
     $ source env/bin/activate
-    $ pip install wheel
-    $ pip install hg+https://repos.goffi.org/sat_pubsub
+    $ pip install -U pip wheel
+    $ pip install sat-pubsub
 
 .. note::
 
@@ -68,6 +95,7 @@
    installation with ``python setup.py install`` is not working properly. Please use ``pip
    install .`` instead.
 
+.. _post_installation:
 
 Post Installation
 -----------------
@@ -80,6 +108,30 @@
     % cd /tmp && wget https://repos.goffi.org/sat_pubsub/raw-file/tip/db/pubsub.sql
     % psql pubsub < pubsub.sql
 
+Update
+------
+
+If you have updated SàT Pubsub and the database schema has been changed, you may have a
+message indicating that your are using an outdated version.
+
+To update schema, just apply ``sat_pubsub_update_x_y.sql`` files where ``x`` is your
+current version, and ``y`` is the one to update. If you are several versions late, just
+apply updates one by one.
+
+For instance, if you have the following message::
+
+    ERROR:root:Bad database schema version (7), please upgrade to 8
+
+Go to ``db`` directory and enter update instruction::
+
+    $ cd db
+    $ psql pubsub < sat_pubsub_update_7_8.sql
+
+.. note::
+
+    Before any update and specially if there is a schema change, you should backup your
+    database. If anything goes wrong, it will be your best chance to avoid any data loss.
+
 
 .. _prosody_configuration: