Code source wiki de 01 - Documentation technique

Version 35.1 par Matthieu Manginot le 09/03/2021 - 17:17
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 configuration à la racine// :
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 configuration à la racine// :
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 templates de mail ===
175
176 TODO
177
178 === Customisation des services ===
179
180 Plusieurs services sont personnalisables en fonction de votre environnement.
181
182 Sous //fr.univlorraine.hypercerts.apogee.service.customs// :
183
184 * //ApogeeUtilisateurServiceCustomExample
185 //
186 ** Personnalisation de la récupération des adresses mails des utilisateurs Apogée à partir de l'uid Apogée
187 * //ApogeeBlocageServiceCustomExample
188 //
189 ** Personnalisation de la récupération des blocages/interdits à partir d'un code étudiant Apogée
190 * //ApogeeComposanteServiceCustomExample
191 //
192 ** Personnalisation de la récupération :
193 *** de toutes les composantes 
194 **** → utilisé pour donner les droits sur toutes les composantes aux super admins
195 *** des composantes pour un utilisateur à partir de l'uid Apogée
196 *** du nombre de composantes pour un utilisateur à partir de l'uid Apogée
197 * ApogeeUidServiceCustomExample\\
198 ** Personnalisation de la récupération de l'uid Apogée d'un utilisateur à partir de son uid Ldap
199
200 (% style="color: rgb(0,51,102);" %)__Pour personnaliser un de ces services :__
201
202 1. Copier la classe en la renommant
203 1. Implémenter la ou les méthodes
204 11. Vous êtes libre de créer des repositories ou d'utiliser l'entityManager directement
205 1. (((
206 Dé-commenter les 2 annotations :1. (((
207 @Service → Pour que Spring implémente le Service au démarrage
208 )))
209 1. (((
210 et @OverrideXXX → Pour que l'implémentation surcharge le service par défaut
211 )))
212 )))
213 1. Au démarrage de l'application
214 11. Une ligne "//Overriding XXX for YYY implementation//" doit apparaître dans les logs
215 1. Sans IDE, penser à ajouter les imports suivant :
216 11. import org.springframework.stereotype.Service;
217 11. import fr.univlorraine.hypercerts.apogee.services.annotations.OverrideXXX;
218 \\
219
220 {{code language="java" theme="Eclipse" title="Exemple" linenumbers="true" collapse="true"}}
221 /**
222 * Override default ApogeeUtilisateurService implementation.
223 * >> README
224 * Décommenter l'annotation @Service pour que le service soit instancié et l'annotation @OverrideApogeeUtilisateurService pour que l'implémentation soit utilisée.
225 *
226 * @author Matthieu Manginot
227 */
228 @NoArgsConstructor
229 @Slf4j
230 // @Service
231 // @OverrideApogeeUtilisateurService
232 public class ApogeeUtilisateurServiceCustomExample implements IApogeeUtilisateurService {
233
234 @PersistenceContext(unitName = "apogeeEntityManagerFactory")
235 private EntityManager entityManagerApogee;
236
237 @PostConstruct
238 public void init() {
239 log.info("Overriding {} for IApogeeUtilisateurService implementation", getClass().getCanonicalName());
240 }
241
242 /**
243 * @see fr.univlorraine.hypercerts.apogee.services.IApogeeUtilisateurService#getMail(java.lang.String)
244 */
245 @Override
246 public String getMail(final String uidApogee) {
247 /* Implémentation personnalisée de getMail. entityManagerApogee.createNativeQuery... */
248 return null;
249 }
250 }
251 {{/code}}
252
253 === Paramétrage de Digiposte ===
254
255 //Documentation à venir. Toutes les fonctionnalités ne sont pas encore implémentées.//
256
257 //Il convient donc de laisser la property app.isUsingDigiposteDelivery à false.//
258
259 == (% style="letter-spacing: -0.006em;" %)Administration(%%) ==
260
261 Les super admins ont accès à des vues supplémentaires. Des onglets pour ces dernières apparaissent dans le panneau de gauche.
262
263 === Gestion ===
264
265 \\
266
267 |=(((
268 Vue
269 )))|=(((
270 Utilisation
271 )))
272 |(((
273 (% class="content-wrapper" %)
274 (((
275 [[image:attach:image2021-2-23_10-42-24.png||height="400"]]
276 )))
277 )))|(((
278 Cette vue permet de lancer les tâches qui s’exécutent automatiquement de façon manuelle.
279
280 Trigger CRON jobs permet de lancer toutes les tâches de dématérialisation jusqu'à ce qu'elles aboutissent toutes.
281
282 On peut aussi utiliser des boutons pour lancer plus finement des tâches.
283
284 À noter que si l'application n'est pas configurée pour utiliser Digiposte, les boutons sous Digiposte n'auront pas d'effet.
285 )))
286
287 === Loggers ===
288
289 \\
290
291 |=(((
292 Vue
293 )))|=(((
294 Utilisation
295 )))
296 |(((
297 (% class="content-wrapper" %)
298 (((
299 [[image:attach:image2021-2-23_10-42-53.png||height="400"]]
300 )))
301 )))|(((
302 Cette vue permet de modifier à chaud sans re-démarrage le niveau de logs de tout les loggers de l'application.
303
304 Utile pour par exemple afficher les requêtes SQL (filtre: sql) ou des logs plus précis en fonction des classes/packages.
305 )))