ESUP Stage

ESUP STAGE est la refonte de l’application PStage. L’application a été complètement réécrite pour reprendre et améliorer les grandes et fonctionnalités : produire une convention de stage et ses avenants dans le cadre d’un processus de validation adapté.

→ Documentation technique Esup-Stage

Prérequis

Les prérequis sont les suivants sur votre serveur :

Git
Java OpenJdk 21
Apache Maven
Installation Mariadb
Installation du projet Esup-SIscol (sur le même serveur ou sur un serveur dédié)

La base de données

Création de la base et de l’utilisateur

CREATE DATABASE estage;
CREATE USER 'esupstage_user'@'%' IDENTIFIED BY 'password';
GRANT ALL PRIVILEGES ON estage.* TO 'esupstage_user'@'%';
FLUSH PRIVILEGES;

Import de la base pStage et passage du patch

Pour importer votre base pStage d’une installation en production, vous devez réaliser un dump, ici le fichier :
mysql-pstage-2022-01-25-16h00.sql.gz

Votre dump ne doit pas comporter de CREATE DATABASE ou USE DATABASE

Les commandes suivantes permettent d’importer votre dump (pStage) dans votre base estage (ESUP STAGE) :

zcat /opt/estage/mysql-pstage-2022-01-25-16h00.sql.gz | mysql -u esupstage_user -p estage
cat /opt/estage/src/main/resources/db/changelog/init-changelog.sql | mysql -u esupstage_user -p estage

Par la suite, dans le application.properties, devrez renseigner le paramètre suivant :

appli.datasource.context=legacy

Base données sans import de pStage

Si vous n’avez pas de base pStage à importer, vous devrez renseigner le paramètre suivant dans le application.properties pour créer une nouvelle base de données vide :

appli.datasource.context=baseline

Clonage du projet

cd /opt
git clone https://github.com/EsupPortail/esup-stage.git

mkdir -p /etc/estage
cp /opt/esup-stage/application-example.properties /etc/estage/application.properties

Modification du fichier de configuration

Modifications apportées au fichier de configuration pour la version 3

Renommage du fichier de config estage.properties en application.properties
- A placer à la racine du projet, il sera interprété automatiquement par Spring Boot
appli.tokens : précédement appli.public.tokens, renommé pour cause technique (le mot clé public étant réservé)
Pour éviter les redondances de valeurs, les champs suivants ont été modifiés :
- cas.url.login : devient optionnel et ne peut maintenant contenir que le path de connexion : /login (saisie de l’url entière toujours possible)
- cas.url.logout : devient optionnel et ne peut maintenant contenir que le path de déconnexion : /logout (saisie de l’url entière toujours possible)
- appli.localapi : devient optionnel, sera utilisé en remplacement de appli.url lors des appels api sur elle-même (cas d’un reverse proxy par exemple)
- appli.prefix : supprimé, car en doublon avec appli.url
Ajout d’une nouvelle propriété
- Ajout de la propriété appli.datasource.context à partir de la version 3.1.0, qui permet de choisir entre la création d’une nouvelle base de données vide ou la reprise d’une base de données existante (comme avant l’introduction de ce paramètre). Cette propriété doit obligatoirement être renseignée.

/etc/estage/application.properties

# parametres des URLs pour l'authentication CAS
cas.url.login=https://cas.monuniv.fr/cas/login?service={service}
cas.url.service=https://cas.monuniv.fr/cas/p3/serviceValidate?service={service}&ticket={ticket}&format=json
cas.url.logout=https://cas.monuniv.fr/cas/logout

# parametres base de donnees
appli.datasource.url=jdbc:mariadb://monserversql.monuniv.fr:3306/estage
appli.datasource.username=estage
appli.datasource.password=xxx
appli.datasource.driver=org.mariadb.jdbc.Driver
# =============================== IMPORTANT ==================================
# Contexte de la base de donnees
# * Pour utiliser une nouvelle base de donnees, utiliser le contexte "baseline"
# * Pour utiliser une base de donnees existante, utiliser le contexte "legacy"
# Une fois le contexte choisi, il ne faut pas le changer
# ============================================================================
appli.datasource.context=baseline

# url de l'application (notamment utilisée pour envoyer des liens par mail)
appli.url=http://esupstage.monuniv.fr:8080/frontend/#/

# logins des admin technique, séparés par des ; (utilisateurs à créer au 1er lancement pour paramétrer l'application)
appli.admin_technique=xxx;yyy

# identifiant pour l'accès au web services référentiel (cela correspond aux identifiants du WS esup-SIscol)
referentiel.ws.login=root
referentiel.ws.password=xxx
# url du service LDAP
referentiel.ws.ldap_url=https://referentiel.monuniv.fr/ldap
# url du service Apogée
referentiel.ws.apogee_url=https://referentiel.monuniv.fr/apogee

# mailer
appli.mailer.protocol=smtp
appli.mailer.host=smtp.monuniv.fr
appli.mailer.port=25
appli.mailer.auth=true
appli.mailer.username=username@monuniv.fr
appli.mailer.password=xxx
appli.mailer.from=from@monuniv.fr
appli.mailer.disable_delivery=true
# paramètres pour le développement, par défaut disable_delivery=false, delivery_address=null
# si appli.mailer.disable_delivery=true alors l'envoi de mail est désactivé sinon si false alors l'envoi de mail est activé
appli.mailer.delivery_address=user@monuniv.fr
# Permet de rediriger les mails vers une adresse mail. Si adresse mail renseignée alors les mails sont redirigés vers cette adresse. Si null alors les mails sont envoyés aux utilisateurs.

# chemin vers le dossier contenant les uploads
# pour les logos des centres de gestion il faut que le dossier ${appli.data_dir}/centregestion/logos soit existant sur le serveur
appli.data_dir=/data_esup_stage

il faut que l’utilisateur faisant tourner votre Tomcat puisse avoir les droits en écriture sur le répertoire data_esup_stage

Stockage de fichiers

La variable appli.data_dir dans application.properties définie le répertoire de stockage des fichiers. L’application se charge de créer les répertoires suivants : si appli.data_dir=/volume/data on aura :

/volume
    |_/data
        |_/centregestion
            |_/consigne-documents
            |_/logos
        |_/images
        |_/signatures

→ Signature électronique (optionnel)

Génération de l’application (.war)

Build du war de l’application : esup-stage-3.x.x.war

mvn clean package

Pour une exécution en local de l’application

A la racine de l’application, renommer et complèter le fichier application-example.properties en application.properties, puis exécuter :

mvn clean package cargo:run

Déploiement / Lancement de l’application

Après la compilation, le chemin complet du fichier de déploiement est le suivant : /opt/estage/target/ROOT.war

Exécution de l’application avec Docker

Créer un fichier .env basé sur le fichier example.env
- Adapter les paramètres, notamment DATA_PATH qui doit correspondre au volume de stockage des fichiers
Lancer la commande docker-compose up depuis la racine du projet
- docker-compose utilisera les fichiers de configuration .env et application.properties présent à la racine du projet
- L’exécution récupère une image docker publique de l’application disponible sur https://harbor.esup-portail.org/

Pour utiliser un tag particulier, consultez le dernier tag à utiliser ici

L’application est alors accessible sur : http://localhost:8080/

Exécution de l’application avec Tomcat

Cette documentation ne va pas décrire l’installation d’un Tomcat. ESUP STAGE a été déployé et testé sur une version TOMCAT 10

Vous pouvez télécharger tomcat ici : https://tomcat.apache.org/download-10.cgi

Nous considérons par exemple le chemin du répertoire tomcat ainsi : /opt/tomcat-esup-stage

Paramétré Tomcat

Pour exécuter l’application avec Tomcat, il faut lui renseigné les paramètre de jvm nécessaire. Pour ce faire, créer un fichier setenv.sh :

nano /opt/tomcat-esup-stage/bin/setenv.sh

Renseigné les paramètres suivant dans le fichier, les deux premiers étant les options de jvm et la troisième le répertoire où trouver l’application.properties.

export JAVA_OPTS="-Xms1024m -Xmx1024m -Dspring.config.additional-location=/etc/estage/application.properties"

Cela permet d’éviter de devoir penser a remettre les options a chaque fois qu’on relance Tomcat.

Vous pouvez placer le .properties dans le répertoire de votre choix, il suffit de le renseigner dans Dspring.config.location

Exécution avec Tomcat

Supprimer (ou déplacer une sauvegarde) votre répertoire /opt/tomcat-esup-stage/webapp/ROOT avant le déploiement

Copier directement votre fichier /opt/estage/target/ROOT.war dans votre répertoire webapp de tomcat

cp /opt/esup-stage/target/esup-stage-3.0.0.4.war /opt/tomcat-esup-stage/webapps/

On arrête le tomcat avant et on le redémarre ensuite

/opt/tomcat-esup-stage/bin/shutdown.sh

Démarrage :

/opt/tomcat-esup-stage/bin/startup.sh

Bravo, l’installation est terminée ! Vous pouvez y accéder sur http://localhost:8080

Lancement direct du war (ne pas utiliser : en cours de debug) java -jar /opt/estage/target/ROOT.war

Dans le cas de l’utilisation d’un proxy (apache proxypass par exemple) il est conseillé d’utiliser le protocole AJP.

Exemple de configuration Apache :

<VirtualHost *:80>
    ServerAdmin admin@monuniv.fr
    ServerName esup-stage.monuniv.fr
    DefaultType text/html
    ProxyRequests off
    ProxyPreserveHost On
    ProxyPass / http://localhost:8080/
    ProxyPassReverse / http://localhost:8080/
</VirtualHost>

Le fichier application.properties peut être positionné à la racine du tomcat et renseigné dans la commande d’exécution avec -Dspring.config.location=$HOMEDIR/application.properties

Exécution local en mode pour dév avec l'hot reload d’angular

Créer un fichier application.properties basé sur le fichier application-example.properties
Lancer le serveur avec une commande maven clean package cargo:run
- L’application est alors accessible sur : http://localhost:8080/
Pour lancer le frontend avec le mode dev d’angular, en hot reload (rechargement à chaud en cas de modification du code) :
- Exécuter la commande ng serve --host localhost --proxy-config src/proxy.conf.json au niveau du dossier frontend (node et npm devront être installés)
Se rendre sur l’application à l’adresse http://localhost:8080/ pour se connecter une première fois
Puis se rendre sur http://localhost:4200
Pour se déconnecter, aller sur http://localhost:4200/logout