Code source wiki de 01 - Documentation technique

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