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

Denis Laxalde denis.laxalde at logilab.fr
Tue Apr 11 09:27:17 CEST 2017


Sylvain Thenault a écrit :
> # 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

blank line missing after "::"

> +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

Still don't get why CW_MODE=user is needed. Maybe it's for instances
directory, in which case advising about setting CW_INSTANCES_DIR
environment variable in one's .bashrc might be a better idea.

>  .. 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 :
> +

connection -> connexion
server -> serveur

>  ::
>
> -  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 :

déja -> déjà

> +::
> +
> +   salt srv state.sls db-create
> +

In many case, this state will fail because the user running db-create 
cubicweb command will not have permission to create a database on the 
database server.

> +Pour finir l'installation puis lancer l'application, exécuter :
> +
> +::
> +
> +    salt srv state.highstate
> +    ssh saemref at srv supervisorctl start saemref saemref-oai
> +

Why the second command? Doesn't highstate handle this?

> +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.

problème

> +
> +.. _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