Code source wiki de Documentation technique

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