Code source wiki de 01 - Documentation technique

Version 32.1 par Matthieu Manginot le 09/03/2021 - 17:13
Afficher les derniers auteurs
1
2
3 {{toc/}}
4
5 == Prérequis ==
6
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.
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" %)(((
50 \\
51 )))
52 |(% colspan="1" %)(((
53 Connection Apogée via WS
54 )))|(% colspan="1" %)(((
55 6.00.50
56 )))
57 |(% colspan="1" %)(((
58 Connection LDAP
59 )))|(% colspan="1" %)(((
60 \\
61 )))
62
63 == Téléchargement des sources ==
64
65 La dernière version des sources : [[hypercerts-1.0.4-SNAPSHOT.zip>>url:https://download-sig.univ-lorraine.fr/public/hypercerts/hypercerts-1.0.4-SNAPSHOT.zip||shape="rect"]]
66
67 == Installation d'Hypercerts ==
68
69 === **Initialisation / Mise à jour de la base** ===
70
71 La base "//hypercerts//" MariaDB/MySQL s'initialise / se met à jour avec la commande Flyway suivante :
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
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//.//
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 === Lancement de l'application avec Maven ===
104
105 * Lorsque la configuration est terminée, démarrer l'application avec la commande : {{code language="none"}}mvn spring-boot:run{{/code}}{{code language="none"}}{{/code}}
106
107 === Lancement de l'application depuis Eclipse ===
108
109 * Importer le projet Maven dans Eclipse.
110 * 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'.
111
112 === (% style="letter-spacing: -0.006em;" %)**Éléments de configuration importants**(%%) ===
113
114 ==== Property //app.production// ====
115
116 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.
117
118 En étant à //false//, cette //property// autorise également la configuration de l'interception de tout les mails applicatifs.
119
120 ==== **Envoi de mail** ====
121
122 (% 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é :__
123
124 * d'utiliser un mail catcher ([[https:~~/~~/mailcatcher.me/>>url:https://mailcatcher.me/||shape="rect"]]) en remplacement de votre smtp
125 * **ou** de configurer l'application pour intercepter tous les mails applicatifs avec ces valeurs :
126 ** **app.production** à //false//
127 ** **spring.mail.intercept.active** à //true//
128 ** et **spring.mail.intercept.mails** contenant une ou plusieurs adresses de réception des mails
129
130 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.
131
132 ==== WebServices Apogée ====
133
134 Les WebServices Apogée sont appelés par l'intermédiaire d'une librairie UL.
135
136 Les //properties// différent du classique fichier de configuration //configUrlServices.properties// de l'AMUE.
137
138 Des //headers// peuvent être ajoutés en paramètre de chaque WebServices.
139
140 Exemple :
141
142 {{code language="bash" theme="Eclipse" linenumbers="true" collapse="true"}}
143 ws:
144 apogee:
145 administratif:
146 url: https://api.univ.fr/apo/amue_apo_administratif
147 headers:
148 # header1: value1
149 # header2: value2
150 username: xxxx
151 password: xxxx
152 {{/code}}
153
154 === Customisation des services ===
155
156 Plusieurs services sont personnalisables en fonction de votre environnement.
157
158 Sous //fr.univlorraine.hypercerts.apogee.service.customs// :
159
160 * //ApogeeUtilisateurServiceCustomExample
161 //
162 ** Personnalisation de la récupération des adresses mails des utilisateurs Apogée à partir de l'uid Apogée
163 * //ApogeeBlocageServiceCustomExample
164 //
165 ** Personnalisation de la récupération des blocages/interdits à partir d'un code étudiant Apogée
166 * //ApogeeComposanteServiceCustomExample
167 //
168 ** Personnalisation de la récupération :
169 *** de toutes les composantes 
170 **** → utilisé pour donner les droits sur toutes les composantes aux super admins
171 *** des composantes pour un utilisateur à partir de l'uid Apogée
172 *** du nombre de composantes pour un utilisateur à partir de l'uid Apogée
173 * ApogeeUidServiceCustomExample\\
174 ** Personnalisation de la récupération de l'uid Apogée d'un utilisateur à partir de son uid Ldap
175
176 (% style="color: rgb(0,51,102);" %)__Pour personnaliser un de ces services :__
177
178 1. Copier la classe en la renommant
179 1. Implémenter la ou les méthodes
180 11. Vous êtes libre de créer des repositories ou d'utiliser l'entityManager directement
181 1. (((
182 Dé-commenter les 2 annotations :1. (((
183 @Service → Pour que Spring implémente le Service au démarrage
184 )))
185 1. (((
186 et @OverrideXXX → Pour que l'implémentation surcharge le service par défaut
187 )))
188 )))
189 1. Au démarrage de l'application
190 11. Une ligne "//Overriding XXX for YYY implementation//" doit apparaître dans les logs
191 1. Sans IDE, penser à ajouter les imports suivant :
192 11. import org.springframework.stereotype.Service;
193 11. import fr.univlorraine.hypercerts.apogee.services.annotations.OverrideXXX;
194 \\
195
196 {{code language="java" theme="Eclipse" title="Exemple" linenumbers="true" collapse="true"}}
197 /**
198 * Override default ApogeeUtilisateurService implementation.
199 * >> README
200 * Décommenter l'annotation @Service pour que le service soit instancié et l'annotation @OverrideApogeeUtilisateurService pour que l'implémentation soit utilisée.
201 *
202 * @author Matthieu Manginot
203 */
204 @NoArgsConstructor
205 @Slf4j
206 // @Service
207 // @OverrideApogeeUtilisateurService
208 public class ApogeeUtilisateurServiceCustomExample implements IApogeeUtilisateurService {
209
210 @PersistenceContext(unitName = "apogeeEntityManagerFactory")
211 private EntityManager entityManagerApogee;
212
213 @PostConstruct
214 public void init() {
215 log.info("Overriding {} for IApogeeUtilisateurService implementation", getClass().getCanonicalName());
216 }
217
218 /**
219 * @see fr.univlorraine.hypercerts.apogee.services.IApogeeUtilisateurService#getMail(java.lang.String)
220 */
221 @Override
222 public String getMail(final String uidApogee) {
223 /* Implémentation personnalisée de getMail. entityManagerApogee.createNativeQuery... */
224 return null;
225 }
226 }
227 {{/code}}
228
229 === Paramétrage de Digiposte ===
230
231 //Documentation à venir. Toutes les fonctionnalités ne sont pas encore implémentées.//
232
233 //Il convient donc de laisser la property app.isUsingDigiposteDelivery à false.//
234
235 === Maven / Exécution de l'applicatoin ===
236
237 * Sous un IDE, exemple Eclipse//, avec fichier de config à la racine contenant les sources// :
238 ** (% style="color: rgb(0,0,0);" %)Clic droit sur "Application.java > Run As > Java Application"
239 * Lancer l'application (hors d'un IDE),// avec fichier de config à la racine contenant les sources// :
240
241 {{code language="bash" theme="Eclipse"}}
242 mvn spring-boot:run
243 {{/code}}
244
245 * Lancer les tests :
246
247 {{code language="bash" theme="Eclipse"}}
248 mvn verify
249 {{/code}}
250
251 * Créer le package pour production :
252
253 {{code language="bash" theme="Eclipse"}}
254 mvn clean package -Pproduction
255 {{/code}}
256
257 * 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 :
258
259 {{code language="bash" theme="Eclipse"}}
260 export JAVA_OPTS="$JAVA_OPTS -Dspring.config.location=$HOMEDIR/application.yaml"
261 {{/code}}
262
263 === Administration ===
264
265 Les super admins ont accès à des vues supplémentaires. Des onglets pour ces dernières apparaissent dans le panneau de gauche.
266
267 === Gestion ===
268
269 \\
270
271 |=(((
272 Vue
273 )))|=(((
274 Utilisation
275 )))
276 |(((
277 (% class="content-wrapper" %)
278 (((
279 [[image:attach:image2021-2-23_10-42-24.png||height="400"]]
280 )))
281 )))|(((
282 Cette vue permet de lancer les tâches qui s’exécutent automatiquement de façon manuelle.
283
284 Trigger CRON jobs permet de lancer toutes les tâches de dématérialisation jusqu'à ce qu'elles aboutissent toutes.
285
286 On peut aussi utiliser des boutons pour lancer plus finement des tâches.
287
288 À noter que si l'application n'est pas configurée pour utiliser Digiposte, les boutons sous Digiposte n'auront pas d'effet.
289 )))
290
291 === Loggers ===
292
293 \\
294
295 |=(((
296 Vue
297 )))|=(((
298 Utilisation
299 )))
300 |(((
301 (% class="content-wrapper" %)
302 (((
303 [[image:attach:image2021-2-23_10-42-53.png||height="400"]]
304 )))
305 )))|(((
306 Cette vue permet de modifier à chaud sans re-démarrage le niveau de logs de tout les loggers de l'application.
307
308 Utile pour par exemple afficher les requêtes SQL (filtre: sql) ou des logs plus précis en fonction des classes/packages.
309 )))