Guide d'hébergement des outils

Introduction

Ce guide vise à accompagner les chercheurs pour l'hébergement et le déploiement d'outils (sous forme d'applications web) sur la plateforme UCLR de La Rochelle Université (LRU).

Si votre application est un site web statique (par exemple produit avec l'outil Quarto ou Shinylive) vous pouvez utiliser le système de pages GitLab avec le serveur GitLab de l'université.

Si votre application a besoin d'un serveur (par exemple pour exécuter un code en R ou en Python), UCLR propose un service de déploiement d'application basé sur ShinyProxy.

Le service est opérationnel, cependant les ressources du serveur UCLR hébergé à la DSI sont limitées (CPU, RAM, espace disque), certaines applications ne peuvent pas être déployées pour le moment.

UCLR dispose de :

• 2 serveurs sous Linux

  • serveur de production : accessible par tous
  • serveur de test : accessible uniquement sur le réseau LRU (VPN LRU, réseau filaire, réseau Wifi ULR-secure)

• licences

  • logiciel Simile : System Dynamics and object-based modelling and simulation software

N'hésitez pas à nous faire remonter des bugs ou des évolutions par e-mail à l'adresse contact-uclr-support@univ-lr.fr pour faire avancer le projet vers une solution qui répond aux besoins de ses utilisateurs.

Pré-requis :

• avoir un compte utilisateur LRU
• connaissance du logiciel de gestion de versions décentralisé Git
• connaissance du logiciel Docker

Démarrage rapide

Les étapes pour héberger votre application :

1. Avoir une application qui fonctionne en local (sur votre PC)

2. Contacter par e-mail l'équipe UCLR à l'adresse contact-uclr-support@univ-lr.fr pour demander la création d'un nouveau projet sur la forge GitLab de l'université gitlab.univ-lr.fr dans le groupe GitLab UCLR.
   Indiquez dans votre e-mail, les réponses aux questions suivantes :

   • Quel est le nom de votre application (il sera utilisé pour l'URL d'accès au format https://data.univ-lr.fr/labs/shinyproxy/nom-application et pour le nom du nouveau projet sur GitLab) ?
   • Est-ce-que votre application sera utilisée par plusieurs utilisateurs en simultané ?
   • Indiquer une brève description de votre application (1 à 3 lignes)
   • Votre application est-elle associée à des données volumineuses (> 100 Mo) ?
   • Disposez-vous d'un Docker file de votre application ?
   • Est-ce que le code source de votre projet doit être ouvert ? (projet GitLab avec une visibilité publique)

3. Attendre le retour de l'équipe UCLR

4. Récupérer le code en local du nouveau projet sur GitLab (git pull)

5. Déposer votre code et pusher vos modifications sur la forge (git add + git commit + git push)

6. Contacter par e-mail l'équipe UCLR pour qu'elle valide l'installation de votre application, attendre sa validation avant de passer à l'étape suivante

7. Lancer la construction puis le déploiement de votre application depuis le dépôt sur la forge (Build > Pipelines)

   

8. Votre application est en ligne sur https://data.univ-lr.fr/labs/shinyproxy/nom-application, vous êtes autonome pour la mettre à jour

Mon dépôt

Après votre demande d'hébergement, l'équipe UCLR va créer un dépôt qui contiendra un template d'application suivant des pré-requis.

Exemple d'un projet d'une application en R Shiny, encadré en rouge les fichiers UCLR.

• .gitignore : fichier qui liste les fichiers et répertoires à ne pas inclure dans le dépôt GitLab.
• .dockerignore : fichier qui liste les fichiers et répertoires à ne pas inclure dans l'image Docker.
• .gitlab-ci.yml : fichier qui gère l'intégration continue pour l'application, voir section Pipeline CI/CD.
• Dockerfile : fichier Docker file qui décrit l'installation et le démarrage de votre application.
  A chaque nouvelle version de votre application, c'est ce fichier qui servira à construire la nouvelle image et qui sera déployée sur le serveur.
• Dockerfile.base : fichier Docker file qui installe l'ensemble des dépendances du projet, le fichier Dockerfile se base sur cette image.
  Il faut construire cette image une première fois, la construction est souvent longue (plusieurs minutes).
  En cas de mise à jour de version ou d'ajout de dépendances, il faut reconstruire cette image.

Il est recommandé d'ajouter une fiche README.md pour décrire votre projet.

Récupérer le dépôt en local, ajouter votre code et pusher vos modifications.

Pipeline CI/CD

Le pipeline d'intégration et de déploiement continu (CI/CD) permet de déclencher des actions (jobs) pour automatiser les builds, tests et déploiements de votre application.

La 1er étape est la construction de votre application (CI), elle permet de "packager" votre application sous forme d'image Docker.
La 2ème étape est le déploiement de votre application sous forme d'image Docker (CD) sur le serveur UCLR.

Accéder au pipeline CI/CD

Depuis l'interface GitLab LRU de votre projet, l'accès au pipeline CI/CD s'effectue via le menu de gauche Build.

Le dernier pipeline activé (au dernier push) est le premier de la liste.

En cliquant sur le pipeline (cliquer sur son n° dans la colonne pipeline, ici #53229), on a accès à différents jobs (actions automatiques ou manuels).

Les différents jobs du pipeline

Les différents jobs du pipeline UCLR :

Le rôle des différents jobs :

• test : job manuel, scan-image vérifie que votre image Docker ne contient pas des dépendances avec des failles de sécurité connues, cette vérification utilise l'outil de scan Trivy. Si votre projet contient une dépendance avec une vulnérabilité de niveau CRITICAL, le job sera en erreur

• build : jobs manuels

  • build-and-push-base : construction de l'image Docker de base
  • build-and-push : construction de l'image Docker de l'application (à partir de l'image de base)

• deploy :

  • deploy-test : job automatique lancer après build-and-push, permet de déployer ou mettre à jour votre application sur le serveur de test https://test-uclr.univ-lr.fr/labs/shinyproxy/nom-application
  • deploy-prod : job manuel à lancer après build-and-push, permet de déployer ou mettre à jour votre application sur le serveur de production https://data.univ-lr.fr/labs/shinyproxy/nom-application

Pour exécuter un job manuel, il faut cliquer sur son bouton Run :

Statut des jobs

En cas de problème lors de l'exécution d'un pipeline, il est possible d'afficher le détail de l'exécution d'un job.

• Sur la page qui liste des pipelines, cliquez sur le bouton du dernier pipeline exécuté dans la colonne `Status (ici "Passed"), vous verrez la chaîne des différents jobs menés par le pipeline

  

• Cliquez sur le nom du job pour accéder au log du job (commandes exécutées par le job).

  

Les statuts de job sont listés ici

Aide

Gestion des données

Les identifiants de connexion (login, clés API, mots de passe...) ne doivent jamais être écrits en clair dans votre code.

Utilisez des variables d'environnement (fichier .env par exemple) pour une gestion sécurisée de vos identifiants.

Plusieurs options sont possibles pour que votre application accède à des données, par exemple :

• fichiers : il n'est pas recommandé d'utiliser Git pour stocker des fichiers de données volumineux (> 50 Mo) ou des fichiers binaires (.exe, .bin...).
  Il faudra transmettre les fichiers/dossiers à l'équipe UCLR pour qu'elle les copie sur le serveur UCLR.
• API web : le temps pour récupérer toutes les données par API est parfois long (> 30 secondes), à chaque fois que l'utilisateur arrive sur l'application, il doit attendre.
  Pour accélérer la chargement de l'application, il est possible de préparer les données (téléchargement et transformation) pour être directement accessible. Les données préparées sont stockés sur le serveur UCLR.

• API web : si les données doivent être mise à jour régulièrement (par exemple pour un dashboard de suivi d'indicateurs), il est possible de créer un nouveau job GitLab qui exécute un code pour mettre à jour vos données.
  Ce code est exécuté périodiquement par un pipeline GitLab planifié, par exemple 1 fois par jour à 23h (Build > Pipelines schedules). En cas d'erreur lors de l'exécution du pipeline vous recevrez un e-mail.

  

Utiliser l'image Docker de mon application en local

Vous pouvez accéder à l'image Docker créée par le pipeline CI/CD depuis le site web GitLab au niveau votre dépôt (consultation, suppression) ou en ligne de commande (utilisation).

Sur le site GitLab :

• L'accès à l'image Docker se fait via le menu à gauche "Deploy -> Container registry".
• Cliquer sur le lien de l'image Docker la plus récente (suffixé latest) pour récupérer l'URL de l'image (exemple : gitlab.univ-lr.fr:5050/uclr/private/traitements/uclreview:latest).

En ligne de commande :

Docker doit être installé sur votre poste https://docs.docker.com/get-started/get-docker/.

Si votre projet est à accès restreint (interne ou privé), il faut :

• Créer un token d'accès personnel (PAT) gitlab.univ-lr.fr (User settings -> Access Tokens -> Add new token)
• Sélectionner le scope read_registry et créer le token (attention le token généré est à conserver en sécurité car il ne sera plus disponible après. En cas de perte, il faudra en créer un nouveau)
• Vous connecter au registre de conteneurs du GitLab LRU :

  docker login -u <votre nom d'utilisateur GitLab LRU (1er lettre du prénom + nom complet)> -p <votre token GitLab LRU> gitlab.univ-lr.fr:5050
  

Créer un nouveau container en local depuis l'image Docker hébergée sur le GitLab LRU, exemple pour une application R Shiny :

docker run -it -p 3838:3838 gitlab.univ-lr.fr:5050/uclr/<chemin de votre projet>:latest

Accéder à l'application en local avec votre navigateur web : http://localhost:3838.

Si vous devez partager des données entre le conteneur et votre poste, il faut monter un volume en ajoutant le paramètre -v <chemin du dossier ou du fichier sur son PC>:<chemin du dossier ou du fichier dans son conteneur> à la commande :

• Sous Linux :
  

  docker run -it -p 3838:3838 -v /home/user/uclr/project/data:/app/data gitlab.univ-lr.fr:5050/uclr/<chemin de votre projet>:latest
  

• Sous Windows :
  

  docker run -it -p 3838:3838 -v //c/Users/uclr/project/data:/app/data gitlab.univ-lr.fr:5050/uclr/<chemin de votre projet>:latest
  

Si vous devez transmettre des valeurs à votre application par des variables d'environnement, il faut ajouter le paramètre -e <nom de la variable>=<valeur de la variable> à la commande :

docker run -it -p 3838:3838 -e DB_PASSWORD="xxxx" -e API_TOKEN_OPEN_API="xxxxx" gitlab.univ-lr.fr:5050/uclr/<chemin de votre projet>:latest

Bonnes pratiques

Sécurité

• Vérifiez toujours que les fichiers contenant des secrets (login, mot de passe, clé d'API...) sont dans votre fichier .gitignore
• Limitez l'accès aux variables secrètes aux seuls utilisateurs nécessaires (application du principe de moindre privilège)
• Mettre à jour vos dépendances si une faille de sécurité est découverte
• Effectuez une rotation régulière des secrets

Reproductibilité

Indiquer la version exacte des dépendances (version du langage, modules, packages...) que vous utilisez.
Outils pratiques pour gérer les versions selon les langages de programmation :

• R : package renv (présentation de l'INRAE)
• Python : package manager uv