[PATCH 06 of 10 saem_ref] [doc] Update install and upgrade procedure

Sylvain Thenault sylvain.thenault at logilab.fr
Mon Apr 10 17:53:27 CEST 2017


# HG changeset patch
# User Sylvain Thénault <sylvain.thenault at logilab.fr>
# Date 1491826614 -7200
#      Mon Apr 10 14:16:54 2017 +0200
# Node ID a494a9b677ce65e822d7a3b48a125044041eb01e
# Parent  45f72f19776612b2f7bcfeeafaee60bedeaf86d0
[doc] Update install and upgrade procedure

diff --git a/doc/install.rst b/doc/install.rst
--- a/doc/install.rst
+++ b/doc/install.rst
@@ -1,54 +1,38 @@
+============
 Installation
 ============
 
-Configuration des entrepôts yum
--------------------------------
+Pour installer le référentiel, plusieurs moyens sont à votre disposition :
 
-Télécharger et installer les RPMs suivants (ils n'installent que des fichiers
-.repo dans ``/etc/yum.repos.d/``) :
+* en utilisant pip_ ;
 
-* https://dl.fedoraproject.org/pub/epel/epel-release-latest-6.noarch.rpm
-* http://yum.postgresql.org/9.4/redhat/rhel-6-x86_64/pgdg-centos94-9.4-1.noarch.rpm
+* en utilisant la formule Salt_.
+
+Ces différentes options sont décrites dans les sections suivantes. La formule Salt effectue une
+installation destinée à la production : elle automatise la création de l'application avec une
+instance dédiée au point d'accès OAI-PMH.
+
+
+Installation avec pip
+=====================
+
+
+Configuration du serveur PostgreSQL
+-----------------------------------
+
+Si vous n'en n'avez pas encore un disponible, il faut commencer par installer un serveur PostgreSQL
+(pas nécessairement sur la même machine que le réferentiel). Sur une distribution Red-Hat / CentOS,
+il faut commencer par installer les paquets suivants :
 
 ::
 
-    rpm -ivh epel-release-latest-6.noarch.rpm
-    rpm -ivh pgdg-centos94-9.4-1.noarch.rpm
-
-
-Créer ``/etc/yum.repos.d/logilab-extranet-BRDX.repo`` avec le contenu suivant,
-en remplaçant ``LOGIN`` et ``PASSWORD`` par le nom d'utilisateur et le mot de
-passe de l'extranet Logilab :
-
-::
-
-    [logilab-extranet-BRDX]
-    name=Logilab Extranet BRDX EPEL $releasever - $basearch
-    baseurl=https://LOGIN:PASSWORD@extranet.logilab.fr/static/BRDX/rpms/epel-$releasever-$basearch
-    enabled=1
-    gpgcheck=0
-
-
-Installation des paquets nécessaires
-------------------------------------
-
-
-Ensuite installer :
-
-::
-
-    yum install cubicweb-saem-ref
     yum install postgresql94-contrib
     yum install postgresql94-plpython
     yum install postgresql94-server
     yum install mailcap # pour /etc/mime.types
 
-
-Configuration du serveur PostgreSQL
------------------------------------
-
 Créer et démarrer un *cluster* PostgreSQL
 
 ::
 
     service postgresql-9.4 initdb
@@ -87,19 +71,46 @@ commande suivante doit afficher le conte
 ::
 
     psql -U cubicweb -l
 
 
+Installation du référentiel
+---------------------------
+
+Nous recommandons d'installer le code du référentiel avec un utilisateur
+standard (pas *root*) :
+
+::
+
+    adduser saemref
+    su - saemref
+
+et dans un virtualenv_, qu'il convient donc de créer puis d'activer :
+
+::
+    virtualenv saemref-venv
+    . saemref-venv/bin/activate
+
+Par la suite, nous supposerons que vous tapez les commandes indiquées en tant qu'utilisateur
+`saemref` et avec le *virtualenv* activé.
+
+Installer le référentiel :
+
+::
+
+    pip install cubicweb-saem-ref
+
+
 Création de l'instance
 ----------------------
 
 Une fois le cube saem_ref et ses dépendances installées, il reste à créer une
 instance de celui-ci :
 
 ::
 
-  cubicweb-ctl create saem_ref saem_ref
+  CW_MODE=user cubicweb-ctl create saem_ref saemref
 
 .. note ::
 
     La phase finale de création prend quelques minutes, afin de remplir la base
     avec quelques données nécessaires au bon fonctionnement de l'application.
@@ -108,44 +119,138 @@ instance de celui-ci :
 
 * Choisir un login / mot de passe administrateur sécurisé (admin/admin est une
   mauvaise idée, nous recommandons d'installer le paquet ``pwgen`` et de
   générer un mot de passe aléatoire avec la commande ``pwgen 20``).
 
-Puis à la lancer :
+Selon votre configuration postgres, vous pouvez avoir à modifier le fichier sources pour y spécifier
+les informations de connection au server (hôte, port, utilisateur et mot de passe). Le plus simple
+est de répondre non à la question "Run db-create to create the system database ?", d'éditer le
+fichier `~/etc/cubicweb.d/saemref/sources` puis de reprendre le processus d'initialisation en
+tapant :
+
 ::
 
-  cubicweb-ctl start saem_ref
+  CW_MODE=user cubicweb-ctl db-create saemref
+
+Vous pouvez maintenant lancer l'instance :
+
+::
+
+  CW_MODE=user cubicweb-ctl pyramid saemref
 
 L'instance est désormais lancée et disponible sur le port 8080.
 
+Pour une instance de production, il est recommandé d'utilisé un serveur d'application WSGI tel que
+`gunicorn`_ et un superviseur tel que `supervisor`_.
+
+
+Installation avec Salt
+======================
+
+Une `formule Salt`_ est à votre disposition pour installer le référentiel.
+
+L'usage recommandé est le suivant, en supposant que l'identifiant du minion est 'srv' :
+
+
+`/srv/salt/top.sls`::
+
+    base:
+        'srv':
+            - saemref
+            - saemref.supervisor
+
+
+`/srv/pillar/top.sls`::
+
+    base:
+        'srv':
+            - saemref
+
+
+`/srv/pillar/saemref.sls`: voir le fichier `pillar.example`_
+
+
+Pour la première installation, il faut d'abord créer la base de données (**cela détruira la base de
+données déja existante le cas échéant**) en exécutant :
+
+::
+
+   salt srv state.sls db-create
+
+Pour finir l'installation puis lancer l'application, exécuter :
+
+::
+
+    salt srv state.highstate
+    ssh saemref at srv supervisorctl start saemref saemref-oai
+
+La formule installe deux instances : une qui servira le point d'accès OAI-PMH, et l'autre toutes les
+autres requêtes. On veut en général un frontal qui routera les différentes requêtes sur l'instance
+qui va bien. Ci-dessous un exemple de configuration pour nginx :
+
+::
+
+    server {
+        listen 80;
+        server_name saemref.example.com;
+        location / {
+            proxy_pass http://srv:8080;
+        }
+        location /oai {
+            proxy_pass http://srv:8081;
+        }
+    }
+
 
 Mise à jour de l'instance
 =========================
 
-Lors qu'une nouvelle version est livrée, il faut commencer par mettre à jour les paquets installés
-sur le système :
-
-::
+.. warning::
 
-  yum check-update
-  yum update
+  Il y aura donc une interruption de service pendant cette opération
 
-Il est possible que ``check-update`` ne détecte pas les paquets à mettre jour
-du fait d'un problème de cache. Dans ce cas, on peut nettoyer le cache (pour
-l'entrepôt ``logilab-extranet-BRDX``) de cette façon :
+Lors qu'une nouvelle version est livrée, il faut commencer par mettre à jour le code de
+l'application. Le plus simple pour cela est de supprimer le *virtualenv* et de le recréer. Si vous
+avez installé le référentiel avec pip :
 
 ::
 
-  yum --disablerepo='*' --enablerepo=logilab-extranet-BRDX clean expire-cache
+    # Ctrl-C pour couper l'instance qui tourne
+    rm -rf saemref-venv
+    virtualenv saemref-venv
+    . saemref-venv/bin/activate
+    pip install cubicweb_saem-ref
 
-
-Puis il reste à mettre à jour l'instance CubicWeb. Celle-ci sera automatiquement stoppée (et
-redémarrée le cas échéant), il y aura donc une interruption de service pendant cette opération.
+Puis il reste à mettre à jour l'instance CubicWeb. Pour une installation avec pip :
 
 ::
 
-  cubicweb-ctl upgrade saem_ref
-
-Cette commande pose un certain nombre de questions, auxquelles il faut toujours répondre par oui (en
-tapant 'y' ou Entrée directement).
+    CW_MODE=USER cubicweb-ctl upgrade saemref
+    CW_MODE=USER cubicweb-ctl pyramid saemref
 
 
+Si vous avez installé le référentiel avec la formule Salt, connectez vous sur le minion en tant que *root* puis :
+
+::
+
+    [root at minion] % supervisorctl stop all
+    [root at minion] % salt-call state.sls saemref.install pillar='{"upgrade": true}'
+    # soyez patient...
+    [root at minion] % su - saemref
+    [saemref at minion] % . venv/bin/activate
+    (venv) [saemref at minion] % cubicweb-ctl upgrade saemref
+    # répondre 'yes' aux questions
+    (venv) [saemref at minion] % exit
+    [root at minion] % supervisorctl start all
+
+Dans les deux cas, la commande `cubicweb-ctl upgrade` pose un certain nombre de questions,
+auxquelles il faut toujours répondre par oui (en tapant 'y' ou Entrée directement). Un backup de la
+base de données est effectué avant la migration afin de pouvoir rejouer une migration en cas de
+problement.
+
+.. _pip: https://pip.pypa.io/
+.. _virtualenv: https://virtualenv.pypa.io/
+.. _gunicorn: http://gunicorn.org/
+.. _supervisor: http://supervisord.org/
+.. _Salt: https://saltstack.com/
+.. _`formule Salt`: https://github.com/logilab/saemref-formula
+.. _`pillar.example`: https://github.com/logilab/saemref-formula/blob/master/test/pillar/example.sls
\ No newline at end of file


More information about the saem-devel mailing list