Code source wiki de 01 - Documentation technique

Version 32.1 par Matthieu Manginot le 09/03/2021 - 17:13

version	line-number	content
9.1	1
	2
	3	{{toc/}}
	4
2.1	5	== Prérequis ==
	6
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.
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" %)(((
1.1	50	\\
2.1	51	)))
	52	\|(% colspan="1" %)(((
	53	Connection Apogée via WS
	54	)))\|(% colspan="1" %)(((
21.1	55	6.00.50
2.1	56	)))
	57	\|(% colspan="1" %)(((
	58	Connection LDAP
	59	)))\|(% colspan="1" %)(((
	60	\\
	61	)))
	62
	63	== Téléchargement des sources ==
	64
28.1	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"]]
2.1	66
	67	== Installation d'Hypercerts ==
	68
27.1	69	=== Initialisation / Mise à jour de la base ===
2.1	70
27.1	71	La base "//hypercerts//" MariaDB/MySQL s'initialise / se met à jour avec la commande Flyway suivante :
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
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//.//
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
32.1	103	=== Lancement de l'application avec Maven ===
2.1	104
32.1	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
2.1	114	==== Property //app.production// ====
	115
13.1	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.
2.1	117
13.1	118	En étant à //false//, cette //property// autorise également la configuration de l'interception de tout les mails applicatifs.
2.1	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
13.1	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//
2.1	128	et spring.mail.intercept.mails** contenant une ou plusieurs adresses de réception des mails
	129
13.1	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.
2.1	131
	132	==== WebServices Apogée ====
	133
	134	Les WebServices Apogée sont appelés par l'intermédiaire d'une librairie UL.
	135
14.1	136	Les //properties// différent du classique fichier de configuration //configUrlServices.properties// de l'AMUE.
2.1	137
14.1	138	Des //headers// peuvent être ajoutés en paramètre de chaque WebServices.
2.1	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
25.1	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	//
2.1	165	** Personnalisation de la récupération des blocages/interdits à partir d'un code étudiant Apogée
25.1	166	* //ApogeeComposanteServiceCustomExample
	167	//
2.1	168	** Personnalisation de la récupération :
15.1	169	*** de toutes les composantes
	170	**** → utilisé pour donner les droits sur toutes les composantes aux super admins
25.1	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
2.1	175
15.1	176	(% style="color: rgb(0,51,102);" %)__Pour personnaliser un de ces services :__
2.1	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. (((
5.1	183	@Service → Pour que Spring implémente le Service au démarrage
2.1	184	)))
	185	1. (((
23.1	186	et @OverrideXXX → Pour que l'implémentation surcharge le service par défaut
2.1	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
25.1	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;
15.1	194	\\
2.1	195
15.1	196	{{code language="java" theme="Eclipse" title="Exemple" linenumbers="true" collapse="true"}}
2.1	197	/**
26.1	198	* Override default ApogeeUtilisateurService implementation.
2.1	199	* >> README
26.1	200	* Décommenter l'annotation @Service pour que le service soit instancié et l'annotation @OverrideApogeeUtilisateurService pour que l'implémentation soit utilisée.
2.1	201	*
	202	* @author Matthieu Manginot
	203	*/
	204	@NoArgsConstructor
	205	@Slf4j
26.1	206	// @Service
	207	// @OverrideApogeeUtilisateurService
	208	public class ApogeeUtilisateurServiceCustomExample implements IApogeeUtilisateurService {
2.1	209
	210	@PersistenceContext(unitName = "apogeeEntityManagerFactory")
	211	private EntityManager entityManagerApogee;
	212
	213	@PostConstruct
	214	public void init() {
26.1	215	log.info("Overriding {} for IApogeeUtilisateurService implementation", getClass().getCanonicalName());
2.1	216	}
	217
	218	/**
26.1	219	* @see fr.univlorraine.hypercerts.apogee.services.IApogeeUtilisateurService#getMail(java.lang.String)
2.1	220	*/
	221	@Override
26.1	222	public String getMail(final String uidApogee) {
	223	/* Implémentation personnalisée de getMail. entityManagerApogee.createNativeQuery... */
	224	return null;
2.1	225	}
	226	}
	227	{{/code}}
	228
15.1	229	=== Paramétrage de Digiposte ===
2.1	230
3.1	231	//Documentation à venir. Toutes les fonctionnalités ne sont pas encore implémentées.//
2.1	232
15.1	233	//Il convient donc de laisser la property app.isUsingDigiposteDelivery à false.//
	234
19.1	235	=== Maven / Exécution de l'applicatoin ===
2.1	236
19.1	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// :
2.1	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
19.1	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
20.1	263	=== Administration ===
2.1	264
9.1	265	Les super admins ont accès à des vues supplémentaires. Des onglets pour ces dernières apparaissent dans le panneau de gauche.
	266
8.1	267	=== Gestion ===
	268
	269	\\
	270
	271	\|=(((
	272	Vue
	273	)))\|=(((
	274	Utilisation
	275	)))
	276	\|(((
	277	(% class="content-wrapper" %)
	278	(((
31.1	279	[[image:attach:image2021-2-23_10-42-24.png\|\|height="400"]]
8.1	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	)))
16.1	290
	291	=== Loggers ===
	292
	293	\\
	294
	295	\|=(((
	296	Vue
	297	)))\|=(((
	298	Utilisation
	299	)))
	300	\|(((
	301	(% class="content-wrapper" %)
	302	(((
31.1	303	[[image:attach:image2021-2-23_10-42-53.png\|\|height="400"]]
16.1	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
31.1	308	Utile pour par exemple afficher les requêtes SQL (filtre: sql) ou des logs plus précis en fonction des classes/packages.
16.1	309	)))

Code source wiki de 01 - Documentation technique

Arborescence des pages

Pour vous aider