Code source wiki de Documentation technique

Version 22.1 par Matthieu Manginot le 17/11/2020 - 14:08
Masquer les derniers auteurs
Cédric Champmartin 9.1 1
2
3 {{toc/}}
4
Cédric Champmartin 2.1 5 == Prérequis ==
6
Matthieu Manginot 10.1 7 * Hypercerts est une application Java qui se connecte à Apogée et au LDAP.
8 * Elle requiert l'utilisation d'une base MariaDB pour son fonctionnement interne.
9 * Elle se déploie sur des serveurs comme une application SpringBoot classique.
10 * Le WAR pourra être pris en charge par un tomcat et servir les utilisateur•ices via l'URL configurée.
Cédric Champmartin 2.1 11
12 |=(((
13 Technologie
14 )))|=(((
15 Version
16 )))
17 |(((
18 JDK
19 )))|(((
20 11+
21 )))
22 |(% colspan="1" %)(((
23 SpringBoot
24 )))|(% colspan="1" %)(((
25 2.3
26 )))
27 |(% colspan="1" %)(((
28 Vaadin (Frontend)
29 )))|(% colspan="1" %)(((
30 14
31 )))
32 |(((
33 Tomcat
34 )))|(((
35 9+
36 )))
37 |(% colspan="1" %)(((
38 MariaDB
39 )))|(% colspan="1" %)(((
40 14+
41 )))
42 |(% colspan="1" %)(((
43 Maven
44 )))|(% colspan="1" %)(((
45 3.6+
46 )))
47 |(% colspan="1" %)(((
48 Connection Apogée
49 )))|(% colspan="1" %)(((
Cédric Champmartin 1.1 50 \\
Cédric Champmartin 2.1 51 )))
52 |(% colspan="1" %)(((
53 Connection Apogée via WS
54 )))|(% colspan="1" %)(((
Matthieu Manginot 21.1 55 6.00.50
Cédric Champmartin 2.1 56 )))
57 |(% colspan="1" %)(((
58 Connection LDAP
59 )))|(% colspan="1" %)(((
60 \\
61 )))
62
63 == Téléchargement des sources ==
64
Cédric Champmartin 17.1 65 Les sources de l'application peuvent être téléchargées à [[cet endroit>>url:https://download-sig.univ-lorraine.fr/public/hypercerts/hypercerts-1.0.2-SNAPSHOT.zip||shape="rect"]].
Cédric Champmartin 2.1 66
67 == Installation d'Hypercerts ==
68
69 === **Initialisation de la base** ===
70
Matthieu Manginot 11.1 71 Après avoir créé une base de données "//hypercerts//", la base de données MariaDB/MySQL s'initialise avec la commande Flyway suivante :
Cédric Champmartin 2.1 72
73 {{code language="bash" theme="Eclipse"}}
74 mvn -Dflyway.configFiles=flyway.properties flyway:migrate
75 {{/code}}
76
77 Le fichier flyway.properties doit être créé à partir du fichier exemple flyway-sample.properties. Il contient les properties standard à Flyway.
78
79 {{code language="bash" theme="Eclipse" linenumbers="true" collapse="true"}}
80 # Flyway
81 # ConfigFiles : https://flywaydb.org/documentation/configfiles
82 # mvn -Dflyway.configFiles=xxx.properties flyway:migrate
83 flyway.url=jdbc:mariadb://localhost/hypercerts?serverTimezone=Europe/Paris
84 flyway.schemas=hypercerts
85 flyway.user=XXX
86 flyway.password=
87 # Emplacement des fichiers sql de migration
88 flyway.locations=classpath:db/migration
89 # baselineOnMigrate
90 flyway.baselineOnMigrate=false
91 {{/code}}
92
93 Au besoin, les fichiers sql de migration peuvent être trouvés sous //src/main/resources/db/migration//.
94
Matthieu Manginot 12.1 95 Pour remettre à zéro la base de données "//hypercerts//", lancer le script //src/main/resources/db/reset/reset.sql //puis exécuter à nouveau Flyway//.//
Cédric Champmartin 2.1 96
97 === Configuration de l'application ===
98
99 Créer et compléter un fichier **application.yaml** à la racine du projet sur le modèle de **application-sample.yaml**
100
101 Des indications sont présentes dans le fichier pour aider à sa configuration.
102
103 === **Éléments de configuration importants** ===
104
105 ==== Property //app.production// ====
106
Matthieu Manginot 13.1 107 Pour les tests, mettre **app.production** à //false// pour obtenir une année supplémentaire (N-2) pour la génération, ainsi des diplômes avec résultats seront plus facilement trouvables.
Cédric Champmartin 2.1 108
Matthieu Manginot 13.1 109 En étant à //false//, cette //property// autorise également la configuration de l'interception de tout les mails applicatifs.
Cédric Champmartin 2.1 110
111 ==== **Envoi de mail** ====
112
113 (% style="color: rgb(0,51,102);" %)__**Sur votre environnement de test/développement**, pour empêcher l'envoi de mails de test en réel, il est conseillé :__
114
115 * d'utiliser un mail catcher ([[https:~~/~~/mailcatcher.me/>>url:https://mailcatcher.me/||shape="rect"]]) en remplacement de votre smtp
Matthieu Manginot 13.1 116 * **ou** de configurer l'application pour intercepter tous les mails applicatifs avec ces valeurs :
117 ** **app.production** à //false//
118 ** **spring.mail.intercept.active** à //true//
Cédric Champmartin 2.1 119 ** et **spring.mail.intercept.mails** contenant une ou plusieurs adresses de réception des mails
120
Matthieu Manginot 13.1 121 Enfin, la //property //**app.mails** sert à définir une ou plusieurs adresses permettant de recevoir les mails applicatifs. ⚠ Aujourd'hui, dans cette version tous les envois de mails ont en copie de cette //property//. Elle est optionnelle et peut être laissée à vide.
Cédric Champmartin 2.1 122
123 ==== WebServices Apogée ====
124
125 Les WebServices Apogée sont appelés par l'intermédiaire d'une librairie UL.
126
Matthieu Manginot 14.1 127 Les //properties// différent du classique fichier de configuration //configUrlServices.properties// de l'AMUE.
Cédric Champmartin 2.1 128
Matthieu Manginot 14.1 129 Des //headers// peuvent être ajoutés en paramètre de chaque WebServices.
Cédric Champmartin 2.1 130
131 Exemple :
132
133 {{code language="bash" theme="Eclipse" linenumbers="true" collapse="true"}}
134 ws:
135 apogee:
136 administratif:
137 url: https://api.univ.fr/apo/amue_apo_administratif
138 headers:
139 # header1: value1
140 # header2: value2
141 username: xxxx
142 password: xxxx
143 {{/code}}
144
145 === Configurer et lancer le projet dans Eclipse ===
146
Matthieu Manginot 14.1 147 * Importer le projet Maven dans Eclipse.
148 * Lorsque la configuration est terminée, démarrer l'application en faisant un clic droit sur la classe {{code language="none"}}fr.univlorraine.hypercerts.Application.java{{/code}} et en choisissant 'Run As / Java Application'.
Cédric Champmartin 2.1 149
150 === Customisation des services ===
151
152 Plusieurs services sont personnalisables en fonction de votre environnement.
153
154 Sous //fr.univlorraine.hypercerts.apogee.service.customs// :
155
Matthieu Manginot 15.1 156 * //ApogeeUserServiceCustomExample//
Cédric Champmartin 2.1 157 ** Personnalisation de la récupération des adresses mails des utilisateurs Apogée à partir de l'uid LDAP
Matthieu Manginot 15.1 158 * //BlocageServiceCustomExample//
Cédric Champmartin 2.1 159 ** Personnalisation de la récupération des blocages/interdits à partir d'un code étudiant Apogée
Matthieu Manginot 15.1 160 * //ComposanteServiceCustomExample//
Cédric Champmartin 2.1 161 ** Personnalisation de la récupération :
Matthieu Manginot 15.1 162 *** de toutes les composantes 
163 **** → utilisé pour donner les droits sur toutes les composantes aux super admins
Cédric Champmartin 2.1 164 *** des composantes pour un utilisateur à partir de l'uid LDAP
165 *** du nombre de composantes pour un utilisateur à partir de l'uid LDAP
166
Matthieu Manginot 15.1 167 (% style="color: rgb(0,51,102);" %)__Pour personnaliser un de ces services :__
Cédric Champmartin 2.1 168
169 1. Copier la classe en la renommant
170 1. Implémenter la ou les méthodes
171 11. Vous êtes libre de créer des repositories ou d'utiliser l'entityManager directement
172 1. (((
173 Dé-commenter les 2 annotations :1. (((
Matthieu Manginot 5.1 174 @Service → Pour que Spring implémente le Service au démarrage
Cédric Champmartin 2.1 175 )))
176 1. (((
Matthieu Manginot 5.1 177 et @Override~*~* → Pour que l'implémentation surcharge le service par défaut
Cédric Champmartin 2.1 178 )))
179 )))
180 1. Au démarrage de l'application
181 11. Une ligne "//Overriding XXX for YYY implementation//" doit apparaître dans les logs
Matthieu Manginot 15.1 182 \\
Cédric Champmartin 2.1 183
Matthieu Manginot 15.1 184 {{code language="java" theme="Eclipse" title="Exemple" linenumbers="true" collapse="true"}}
Cédric Champmartin 2.1 185 /**
186 * Override default ApogeeUserService implementation.
187 * >> README
188 * Décommenter l'annotation @Service pour que le service soit instancié et l'annotation @OverrideApogeeUserService pour que l'implémentation soit utilisée.
189 *
190 * @author Matthieu Manginot
191 */
192 @NoArgsConstructor
193 @Slf4j
194 @Service
195 @OverrideApogeeUserService
196 public class ApogeeUserServicePERSO implements IApogeeUserService {
197
198 @PersistenceContext(unitName = "apogeeEntityManagerFactory")
199 private EntityManager entityManagerApogee;
200
201 @PostConstruct
202 public void init() {
203 log.info("Overriding {} for IApogeeUserService implementation", getClass().getCanonicalName());
204 }
205
206 /**
207 * @see fr.univlorraine.hypercerts.apogee.services.IApogeeUserService#getEmail(java.lang.String)
208 */
209 @Override
210 public String getEmail(final String uidLdap) {
211 /* Implémentation personnalisée de getEmail. entityManagerApogee.createNativeQuery... */
212 return "mail@univ.fr";
213 }
214 }
215 {{/code}}
216
Matthieu Manginot 15.1 217 === Paramétrage de Digiposte ===
Cédric Champmartin 2.1 218
Matthieu Manginot 3.1 219 //Documentation à venir. Toutes les fonctionnalités ne sont pas encore implémentées.//
Cédric Champmartin 2.1 220
Matthieu Manginot 15.1 221 //Il convient donc de laisser la property app.isUsingDigiposteDelivery à false.//
222
Matthieu Manginot 19.1 223 === Maven / Exécution de l'applicatoin ===
Cédric Champmartin 2.1 224
Matthieu Manginot 19.1 225 * Sous un IDE, exemple Eclipse//, avec fichier de config à la racine contenant les sources// :
226 ** (% style="color: rgb(0,0,0);" %)Clic droit sur "Application.java > Run As > Java Application"
227 * Lancer l'application (hors d'un IDE),// avec fichier de config à la racine contenant les sources// :
Cédric Champmartin 2.1 228
229 {{code language="bash" theme="Eclipse"}}
230 mvn spring-boot:run
231 {{/code}}
232
233 * Lancer les tests :
234
235 {{code language="bash" theme="Eclipse"}}
236 mvn verify
237 {{/code}}
238
239 * Créer le package pour production :
240
241 {{code language="bash" theme="Eclipse"}}
242 mvn clean package -Pproduction
243 {{/code}}
244
Matthieu Manginot 19.1 245 * Sous un serveur, comme Tomcat, le fichier de config peut être déposé à la racine du tomcat avec précision de son emplacement via les options JAVA, exemple :
246
247 {{code language="bash" theme="Eclipse"}}
248 export JAVA_OPTS="$JAVA_OPTS -Dspring.config.location=$HOMEDIR/application.yaml"
249 {{/code}}
250
Matthieu Manginot 20.1 251 === Administration ===
Cédric Champmartin 2.1 252
Cédric Champmartin 9.1 253 Les super admins ont accès à des vues supplémentaires. Des onglets pour ces dernières apparaissent dans le panneau de gauche.
254
255 [[image:attach:image2020-7-23_12-41-56.png||align="center" height="400"]]
256
Cédric Champmartin 8.1 257 === Gestion ===
258
259 \\
260
261 |=(((
262 Vue
263 )))|=(((
264 Utilisation
265 )))
266 |(((
267 (% class="content-wrapper" %)
268 (((
269 [[image:attach:image2020-7-23_12-51-28.png||height="400"]]
270 )))
271 )))|(((
272 Cette vue permet de lancer les tâches qui s’exécutent automatiquement de façon manuelle.
273
274 Trigger CRON jobs permet de lancer toutes les tâches de dématérialisation jusqu'à ce qu'elles aboutissent toutes.
275
276 On peut aussi utiliser des boutons pour lancer plus finement des tâches.
277
278 À noter que si l'application n'est pas configurée pour utiliser Digiposte, les boutons sous Digiposte n'auront pas d'effet.
279 )))
Matthieu Manginot 16.1 280
281 === Loggers ===
282
283 \\
284
285 |=(((
286 Vue
287 )))|=(((
288 Utilisation
289 )))
290 |(((
291 (% class="content-wrapper" %)
292 (((
293 [[image:attach:image2020-7-23_15-56-58.png||height="250"]]
294 )))
295 )))|(((
296 Cette vue permet de modifier à chaud sans re-démarrage le niveau de logs de tout les loggers de l'application.
297
298 Utile pour afficher les requêtes SQL (filtre: sql) ou des logs plus précis en fonction des classes/packages.
299 )))