.. Authors :
.. mviewer team

.. _install_python:


Installer mviewerstudio avec Python
###################################

Mviewerstudio est une application web développée en HTML / CSS / JavaScript avec un backend Python. Elle nécessite simplement d'être déployée sur un serveur WEB qui peut être APACHE, NGINX, TOMCAT…

Installation
************

Prérequis
=========

Vous aurez besoin :

-  d'installer les dépendances (Linux/Debian):

.. code-block:: sh

    sudo apt install libxslt1-dev libxml2-dev python3 python3-pip python3-venv

- d'une version Python >= 3.9
- d'une instance mviewer fonctionnelle (/mviewer)

Procédures d'installation
=========================

Installation manuelle
---------------------

.. code-block:: sh

    #Récupération des sources
    git clone https://github.com/mviewer/mviewerstudio.git
    cd mviewerstudio
    #Création de l'environnement virtuel Python et installation des dépendances
    python3 -m venv .venv
    source .venv/bin/activate
    pip install -r install/requirements.txt -r install/dev-requirements.txt
    pip install -e src




Installation scriptée
---------------------

.. code-block:: sh

    git clone https://github.com/mviewer/mviewerstudio.git
    cd mviewerstudio
    bash ./install/install.sh

Le script peut utiliser 3 paramètres :

- ``<parent_directory>`` : Le chemin dans lequel installer mviewerstudio
- ``<branch>`` : La branche à installer
- ``<directory_name>`` : Le nom du répertoire cible (optionnel, par défaut ``mviewerstudio``)

Exemple pour installer mviewerstudio dans le répertoire ``/git`` en utilisant la branche ``develop`` :

.. code-block:: sh

    bash ./install/install.sh /home/monuser/git develop mviewerstudio_develop

Suite à cette commande exemple, le mviewerstudio sera donc accessible sous le chemin suivant et sera directement aligné avec la branche ``develop``: 

``/home/monuser/git/mviewerstudio_develop``

Configuration
=============

Configuration du front
----------------------

Récupérez le fichier ``src/static/config.json`` et adaptez son contenu selon votre environnement.
Adaptez ensuite les paramètres selon votre environnement (aidez-vous de la page :ref:`config_front`).

.. warning::
    Le paramètre ``mviewer_instance`` doit finir par ``/``

.. note::
   Le paramètre ``user_info_visible`` est à utiliser si vous instance est sécurisée (avec geOrchestra par exemple).

.. note::
   Le paramètre ``proxy`` est à laisser vide si vous n'utilisez pas de proxy.


Variables d'environnement du backend
------------------------------------

Ces variables doivent être définies dans l'environnement soit via la console (commande export ou fichier .bashrc) ou le service :

- ``CONF_PATH_FROM_MVIEWER``: répertoire d'accès à partir de l'instance mviewer.
- ``CONF_PUBLISH_PATH_FROM_MVIEWER``: répertoire de publication à partir de l'instance mviewer.
- ``EXPORT_CONF_FOLDER``: répertoire d'accès à partir de l'instance mviewer.
- ``LOG_LEVEL``: Niveau logs (voir https://docs.python.org/3/library/logging.html)
- ``MVIEWERSTUDIO_PUBLISH_PATH``: Répertoire de publication lors du passage du mode brouillon au mode publié.
- ``DEFAULT_ORG``: Nom de l'organisation par défaut à utiliser pour un usage non sécurisé (e.g en dehors d'un georchestra, ANONYMOUS).

Autres Variables
----------------

Pour utiliser les services types OGC (catalogue ou serveurs cartographiques), vous aurez besoin d'utiliser le proxy.
Le Proxy interne proposé par mviewer ("/mviewerstudio/proxy/?url=") utilise un paramètre ``PROXY_WHITE_LIST`` qui doit être complété par tous les domaines (FQDN) des services que vous utiliserez.
Ce paramètre est accessible dans :

- ``src/settings.py``



Lancement de l'application avec Flask (mode developpement)
=====================================


.. code-block:: sh

    cd mviewerstudio
    source .venv/bin/activate
    export FLASK_APP=src/app.py
    export CONF_PATH_FROM_MVIEWER=apps/store
    export EXPORT_CONF_FOLDER=/var/www/mviewer/apps/store/
    export MVIEWERSTUDIO_PUBLISH_PATH=/var/www/mviewer/apps/prod
    export CONF_PUBLISH_PATH_FROM_MVIEWER=apps/prod
    export DEFAULT_ORG=monorg
    flask run -p 5007


Mise en production
******************


**Cette partie décrit l'installation en production de mviewerstudio sur un serveur Linux (Ubuntu / Debian) avec le backend python.**

Prérequis
=========

 - Disposer d'un serveur web (Apache ou Nginx)
 - Disposer d'une instance mviewer sur le même serveur (ex : /var/www/mviewer)
 - Disposer des droits sudo
 - Avoir installé mviewerstudio avec la méthode décrite dans la partie précédante


Mode opératoire
===============

- Servir le backend python et le front de studio avec un service Linux
- Proxyfier ce service avec Nginx ou Apache

1) Création des dossiers de stockage des applications mviewer et de log
-----------------------------------------------------------------

Création du répertoire de stockage des brouillons (store) et des applications publiées (prod) dans mon application mviewer.


 .. code-block:: sh

       mkdir /var/www/mviewer/apps/store
       sudo chown monuser /var/www/mviewer/apps/store
       mkdir /var/www/mviewer/apps/prod
       sudo chown monuser /var/www/mviewer/apps/prod

Création du répertoire de log mviewerstudio

.. code-block:: sh

       sudo mkdir /var/log/mviewerstudio
       sudo chown monuser /var/log/mviewerstudio


2) Création du service et activation du service
-----------------------------------------------

Copier maintenant le fichier disponible dans install/mviewerstudio.service dans `/etc/systemd/system/mviewerstudio.service`.

Enfin, adaptez son contenu (notamment le user, le port, les chemins et l'emplacement des logs).

 .. code-block:: sh

       sudo nano /etc/systemd/system/mviewerstudio.service


N'oubliez pas d'adapter le niveau des logs et les droits des répertoires (à créer si nécessaire) selon l'utilisateur défini dans le fichier mviewerstudio.service (dans la configuration par défaut, l'utilisateur `monuser` devra pouvoir écrire dans `/var/log/mviewerstudio`).

Le porte par défaut est sera le `5007` (à adapter dans mviewerstudio.service).

Activation et démarrage du service :

.. code-block:: sh

       sudo systemctl daemon-reload
       sudo systemctl enable mviewerstudio.service
       sudo systemctl start mviewerstudio.service

A partir de maintenant, il est possible de stopper, redémarrer ou afficher le service avec les commandes :

.. code-block:: sh

       sudo systemctl stop mviewerstudio
       sudo systemctl restart mviewerstudio
       sudo systemctl status mviewerstudio.service


3) Proxyfication du service
---------------------------------

Notre service tourne sur le port 5007. Nous souhaitons que ce service soit accessible sur les ports 80 et 443 à l'adresse **/mviewerstudio/**. Nous allons donc opérer une proxyfication de ce service.

Configuration nginx

.. code-block:: sh

       location /mviewerstudio {
            proxy_pass http://127.0.0.1:5007/;
            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
            proxy_set_header X-Forwarded-Proto $scheme;
            proxy_set_header X-Forwarded-Host $host;
        }

Rechargement de la conf nginx

.. code-block:: sh

       sudo systemctl reload nginx

Configuration apache

.. code-block:: sh

        <Location "/mviewerstudio">
            ProxyPass "http://127.0.0.1:5007"
            ProxyPassReverse "http://127.0.0.1:5007"
        </Location>

Rechargement de la conf apache

.. code-block:: sh

       sudo systemctl reload apache2


Mise à jour de l'application
****************************

Dans cette version (> à 4.2.1), la synchronisation entre la racine et le backend n'est plus à réaliser à la main car, avec un seul backend, tous les fichiers static sont dans /src/static.

Pour la mise à jour du code source, voici donc les commandes à exécuter à partir du répertoire ``/mviewerstudio``  (en partant du principe que vous êtes bien sur la branche master):

.. code-block:: sh

    git pull

.. warning::

    A chaque version, vous devrez comparer le fichier `src/static/config.json`  avec la configuration disponible dans le dépôt github. Ceci afin de vous assurez que vous avez bien toutes les clés de configuration nécessaires au bon fonctionnement de votre instance.

Si vous parter d'une version antérieure (< 4.3), alors il faudra mettre à jour votre service comme mentionné ci-dessus, puis recharger la configuration et redémarrer de votre service (e.g gunicorn) :

.. code-block:: sh

    sudo nano /etc/systemd/system/mviewerstudio.service
    sudo systemctl daemon-reload
    sudo systemctl restart mviewerstudio

Pour tout redémarrage de gunicorn, vérifier que le service a bien démarré :

.. code-block:: sh

    sudo systemctl status mviewerstudio

.. warning::

    Il est possible que Git n'ait pas terminé d'écrire un fichier lors de l'arrêt du service.
    Le service peut alors démarrer et s'arréter.

    Si vous constater dans le fichier de log d'erreur gunicorn que c'est bien le cas, redémarrer le service avec la commande ``systemctl restart mviewerstudio``


Documentation Swagger (API)
****************************

Le backend Python expose une interface Swagger UI ainsi que le fichier OpenAPI :

- Swagger UI : ``/swagger`` (ou ``/swagger/``)
- Spécification OpenAPI : ``/swagger.yaml``

Exemples :

- sans préfixe d'URL : ``http://localhost:5007/swagger``
- avec ``MVIEWERSTUDIO_URL_PATH_PREFIX=mviewerstudio`` : ``http://localhost:5007/mviewerstudio/swagger``

.. note::
   Ces routes sont servies directement par Flask via ``src/route.py``.
   Le fichier de spécification est ``src/swagger.yaml``.