Manuale d uso della piattaforma per lo sviluppo e rilascio di componenti software QMSS

Transcript

1 Manuale d uso della piattaforma per lo sviluppo e rilascio di componenti software QMSS Versione OSCAT-QMSS-ManualeUtente doc del v di 17

2 AGGIORNAMENTI Versione Data Paragrafi modificati Motivo modifica /09/2015 Prima emissione /09/2015 4, 5.1 Esplicitata la necessità di richiedere accesso via VPN al sottosistema QMSS OSCAT-QMSS-ManualeUtente doc del v di 17

3 Sommario 1. Scopo del documento Acronimi Diagramma dei componenti del sistema OSCAT Note in merito al sistema QMSS Flusso di operazioni sulla piattaforma QMSS Build del progetto e verifica dell'analisi VPN Accesso a Jenkins Il pannello di lavoro Jenkins Esecuzione del job di BUILD Esecuzione del job di MAIL_DEPLOY Accesso a SonarQube Appendice A - Modulo configurazione progetto Appendice B - sonar.properties OSCAT-QMSS-ManualeUtente doc del v di 17

4 Indice delle Figure FIGURA 1 - COMPONENT DIAGRAM FIGURA 2 - SEQUENCE DIAGRAM FIGURA 3 - JENKINS. FORM DI LOGIN FIGURA 4 - JENKINS. HOME PAGE FIGURA 5 - JENKINS. JOB FIGURA 6 - SONARQUBE. FORM DI LOGIN FIGURA 7 - SONARQUBE. DASHBOARD INIZIALE FIGURA 8 - SONARQUBE. STATISTICHE OSCAT-QMSS-ManualeUtente doc del v di 17

5 1. Scopo del documento Con il presente documento si forniscono informazioni di base per l'uso della piattaforma QMSS (Quality Management Software System) da parte di sviluppatori di applicazioni J2EE, siano dipendenti di Regione Toscana (di seguito indicata con RT) o collaboratori esterni e fornitori di RT, che a vario titolo consegnano applicazioni JAVA Acronimi Nel resto del documento si fa uso degli acronimi che seguono. CI IDM LDAP QMSS SVN Continuous Integration Identity Manager di Regione Toscana Lightweight Directory Access Protocol Quality Management Software System Subversion OSCAT-QMSS-ManualeUtente doc del v di 17

6 2. Diagramma dei componenti del sistema OSCAT Figura 1 - Component diagram 3. Note in merito al sistema QMSS QMSS fa parte della più ampia piattaforma OSCAT utilizzata in regione per lo sviluppo e il rilascio di componenti software. In questo senso il sotto-sistema QMSS integra in OSCAT le funzionalità di build degli artifact e di misurazione della qualità del codice. L interazione puntuale con l attuale piattaforma OSCAT è individuata nelle due seguenti interfacce, mediate dal progetto di riferimento: SVN: il codice sorgente da compilare è scaricato dal repository Subversion Sezione File: il compilato è depositato nella sezione file del portale Il sotto sistema attualmente è composto da due componenti open source: Jenkins e SonarQube. Jenkins è il motore di Continuous Integration server (CI server), ha quindi come obiettivo l integrazione del sistema intesa come collecting dei sorgenti, la loro OSCAT-QMSS-ManualeUtente doc del v di 17

7 compilazione con la contestuale esecuzione dei test legati ad un progetto software condiviso all'interno di un team di sviluppo. Soddisfa quindi la necessità di supportare al meglio: le tecniche di sviluppo agili o test-driven generazione di report analisi SonarQube consente di effettuare la code-review basata sull analisi di parametri di qualità e best-practice nella scrittura del codice. Consente: analisi della qualità del codice aggregazione dei risultati di qualità navigazione delle violazioni sul codice sorgente. Le modalità di supporto sulla piattaforma QMSS sono le medesime della piattaforma OSCAT, pertanto i riferimenti telematici e telefonici sono gli stessi pubblicati sul portale oscat.rete.toscana.it, nella home page in alto a destra, dove è possibile anche scaricare l'ultima versione del presente manuale. 4. Flusso di operazioni sulla piattaforma QMSS Di seguito una brevissima panoramica dei ruoli coinvolti e dei passi che costituiscono il processo. Gestore della Piattaforma (GP): si occupa della gestione dell intera piattaforma Fornitore (FO): coinvolto nel processo di sviluppo e rilascio del software Gestore degli Ambienti Target (GT): coinvolto nella fase di dispiegamento sugli ambienti target Referente Regione Toscana (RRT): utilizza la piattaforma per la verifica dei prodotti, collabora nella definizione del processo validando alcune informazioni e confermando le richieste di deploy. 0. Prerequisiti a. [FO] Se non già in possesso il fornitore deve richiedere le credenziali IDM (LDAP) a RT (mail a idmadmin@regione.toscana.it) b. [FO] Se non già in possesso il fornitore deve richiedere l accesso via VPN al sottosistema QMSS 1. [FO] Richiesta di apertura progetto su OSCAT OSCAT-QMSS-ManualeUtente doc del v di 17

8 2. [RRT] Approva il progetto 3. [GP] Apertura progetto su OSCAT 4. [FO] Commit dei sorgenti su SVN 5. [FO] Caricamento nella sezione Documentazione del portale OSCAT del Modulo di configurazione QMSS - <nome unix progetto> relativo al progetto 6. [FO] Comunicazione di avvenuto deposito del Modulo di configurazione QMSS" di cui al punto "5. [FO]" e delle credenziali (solo username) IDM a GP per la configurazione dei moduli Jenkins/SonarQube 7. [GP] Preparazione del progetto e delle utenze su Jenkins e SonarQube 8. [FO] Esecuzione job di BUILD senza release 9. [FO] Accesso a SonarQube per verifica analisi codice 10. [FO] Esecuzione job di BUILD con release 11. [FO] Esecuzione job di DEPLOY 12. [GT] Dispiegamento software sugli ambienti target. L eventuale deploy automatico potrà avvenire solo in ambiente di certificazione. Figura 2 - Sequence diagram OSCAT-QMSS-ManualeUtente doc del v di 17

9 5. Build del progetto e verifica dell'analisi Il primo passo da compiere è il commit sul sistema SVN di Oscat dei sorgenti del progetto secondo le indicazioni contenute nel manuale Oscat Manuale d Uso della Piattaforma per lo Sviluppo e Rilascio di Componenti Software - Processo di Sviluppo e Rilascio al paragrafo Da questo momento è possibile dai software Jenkins e SonarQube effettuare il build del progetto e l'analisi del codice VPN L accesso alla piattaforma di Continuous Integration avviene tramite VPN: vpn.tix.it. È a cura del fornitore richiedere l abilitazione al sottosistema QMSS. Le URL da utilizzare sono: Accesso a Jenkins Inserire le credenziali IDM (LDAP) fornite da Regione Toscana per accedere al sistema. Figura 3 - Jenkins. Form di login OSCAT-QMSS-ManualeUtente doc del v di 17

10 5.3. Il pannello di lavoro Jenkins Dalla home di Jenkins si possono individuare i Job di Jenkins a cui l'utente può avere accesso. Figura 4 - Jenkins. Home page Secondo la nomenclatura utilizzata per ogni progetto cui l'utente può avere accesso, devono essere presenti due tipologie di job: BUILD e DEPLOY. Il primo sarà utilizzato per la compilazione, il packaging, l'analisi e la creazione della release del progetto. La creazione della release consentirà in seguito all'utente il deploy sugli ambienti di Regione Toscana tramite il job MAIL_DEPLOY Esecuzione del job di BUILD Individuare nella lista dei Job quello nominato <nome_fornitore>.<nome_progetto>.build e cliccare sull'icona in fondo a destra (simbolo orologio con triangolo verde) per effettuare la build. Prima dell'effettiva esecuzione del job l'utente deve scegliere se creare la release del progetto (versione stabile e successivamente dispiegabile) oppure procedere con la sola compilazione e analisi del progetto ad esempio per eseguire le verifiche sulla conformità dei sorgenti alle regole di qualità di Regione Toscana. Se l'utente seleziona la checkbox presente nella form (label RELEASE) il sistema provvederà alla creazione della release ed al successivo inserimento automatico su Oscat per renderla disponibile per un eventuale deploy. Per eseguire la build cliccare sul pulsante Build presente nella form. Durante l'esecuzione del job è mostrata una progress bar nella Build History che consentirà di controllarne l'avanzamento. L'utente potrà anche controllare OSCAT-QMSS-ManualeUtente doc del v di 17

11 l'avanzamento del processo ed eventuali errori cliccando sul link presente sull'icona della sfera colorata presente nella sezione Build History accedendo cosi alla console di output. Analogamente l'utente può accedere alla console cliccando sul link della build dalla Build History e successivamente sul link Output Console che apparte nella pagina di dettagli della build selezionata. L'esecuzione del job può terminare con o senza errori che saranno evidenziati da una sfera colorata (icona) nella sezione Build History con a fianco l'id della build e la data e l'ora di esecuzione: [ [ ] icona blu: job completato con successo ] icona rossa: job terminato con errori (incompleto) [ ] icona gialla: job marcato come non stabile (caso di errori non bloccanti o dovuti ad errori di configurazione per cui si deve contattare l'amministratore della piattaforma verificando il log di console) [ ] icona grigia: job annullato Solo nel caso che il job termini senza errori (icona blu) può essere considerato come stabile e può (solo in questo caso) dar luogo ad una release nel caso l'utente abbia selezionato la check box in fase di avvio della build. Qualora l'utente richieda la creazione di una release del progetto, la build nella Build History presenta un'icona che raffigura una stella gialla. Se l'utente colloca il puntatore del mouse sopra l'icona, viene mostrata la versione della release creata. OSCAT-QMSS-ManualeUtente doc del v di 17

12 Figura 5 - Jenkins. Job 5.5. Esecuzione del job di MAIL_DEPLOY Questo job è dedicato esclusivamente alla richiesta di deploy delle release create tramite il job di BUILD. Il job è configurato automaticamente per inviare le alle persone interessate al progetto e ai gestori della piattaforma di deploy che prenderanno in carico il task. L'esecuzione del job deve essere fatta compilando opportunamente il form che è richiesto in fase di esecuzione della build Accesso a SonarQube Durante l'esecuzione del job che ha effettuato la build del progetto sono state avviate anche diverse tipologie di analisi del codice che è possibile visualizzare tramite SonarQube; è possibile consultare il dettaglio delle analisi accedendo al software SonarQube. Utilizzando le stesse credenziali utilizzate per l'accesso a Jenkins, accedere al software SonarQube OSCAT-QMSS-ManualeUtente doc del v di 17

13 Figura 6 - SonarQube. Form di login Eseguito il login comparirà la seguente dashboard. Figura 7 - SonarQube. Dashboard iniziale Dalla dashboard di SonarQube è visibile un elenco di tutti i progetti a cui l'utente può avere accesso e cliccando sul nome di un progetto si entra nella dashboard di progetto dove è possibile avere un quadro generale del progetto. Selezionando una delle voci, ad esempio pastifruiti J2EE-JAVA saranno visualizzate, anche graficamente, le soglie di qualità del software raggiunte: OSCAT-QMSS-ManualeUtente doc del v di 17

14 Figura 8 - SonarQube. Statistiche OSCAT-QMSS-ManualeUtente doc del v di 17

15 6. Appendice A - Modulo configurazione progetto Il fornitore dovrà depositare nella sezione Documentazione del progetto OSCAT il seguente modulo [ModuloConfigurazioneProgettoQMSS-<nome_unix>.txt] compilato con le informazioni richieste. ********************************** * MODULO CONFIGURAZIONE PROGETTO * ********************************** ********************* * DATI DEL PROGETTO * ********************* NOME (unico su tutti i progetti presenti in RT, rappresenterà anche la parte finale della URL presente nei front-end Apache per l'accesso all'applicazione; il nome è anche l'artifactid che dovrà essere utilizzato nel pom.xml [nome unix]): SOCIETA' FORNITRICE: CODICE FORNITORE (codice mnemonico univoco per ogni fornitore; deve essere composto da soli caratteri alfanumerici con una lunghezza massima di 10 caratteri): ******************************* * REFERIMENTI REGIONE TOSCANA * ******************************* NOME REFERENTE: REFERENTE: TELEFONO REFERENTE: MEMBRI GRUPPO DI LAVORO (consigliato l uso di un indirizzo di mailing list): ************************* * RIFERIMENTI FORNITORE * ************************* NOME REFERENTE: REFERENTE: TELEFONO REFERENTE: MEMBRI GRUPPO DI LAVORO (consigliato l uso di un indirizzo di mailing list): ************************ * TOOL DI COMPILAZIONE * ************************ (Scelta fra MAVEN o ANT. Da notare che il tool standard per i progetti consegnati a Regione Toscana è Maven 2.x. L'utilizzo del tool ANT dovrebbe OSCAT-QMSS-ManualeUtente doc del v di 17

16 essere preso in considerazione solo per progetti datati prima della definizione delle specifiche di rilascio con Maven, o comunque progetti il cui impianto sia cosi consolidato e stabile temporalmente che il cambio di tool sarebbe perseguibile solo con un effort considerevole) ************************************** * DATI PER LA COMPILAZIONE CON MAVEN * ************************************** GROUPID: it.toscana.regione ARTIFACTID (impostare con il nome del progetto definito sopra): NAME (impostare con il nome del progetto definito sopra): VERSIONE MAVEN (deve essere specificata la versione di maven utilizzata; obbligatoriamente >= 2): BUILD (parametri della linea di comando di Maven per l'esecuzione della build i.e. mvn clean install): FILE TARGET: [war ear] ************************************ * DATI PER LA COMPILAZIONE CON ANT * ************************************ VERSIONE ANT (versione utilizzata per la build del progetto, obbligatoriamente >= 1.8.3): NOME DEL FILE ANT PER LA BUILD (nome del file xml di ANT utilizzato per la build): PATH DEL FILE ANT PER LA BUILD (percorso del file di build ANT relativo alla directory del progetto): TASK BUILD (nome del task ANT da eseguire per la build i.e. ant war): PATH FILE sonar.properties (percorso del file sonar.properties relativo alla directory del progetto): FILE TARGET: [war ear] OSCAT-QMSS-ManualeUtente doc del v di 17

17 7. Appendice B - sonar.properties Nel caso di compilazione ANT è necessario fornire anche il file sonar.properties: # ******************************************************** # I seguenti parametri: # - sonar.projectkey # - sonar.projectname # sono stati assegnati direttamente da REGIONE TOSCANA # committente del progetto. # NON DEVONO ESSERE IN ALCUN MODO VARIATI NE' ALTERATI # ******************************************************** sonar.projectkey=it.toscana.regione: <nome progetto> # La build (WAR) dovrà avere il seguente NOME sonar.projectname= # ******************************************************** # TUTTI I PARAMETRI NEL SEGUITO SONO A CARICO DEL FORNITORE # CHE SI IMPEGNA A MANTENERLI AGGIORNATI PER IL CORRETTO # BUILD DEL PROGETTO # ******************************************************** # ******************************************************** # Versione del progetto. # Deve essere variato/incrementato ad ogni rilascio # ******************************************************** sonar.projectversion= # ******************************************************* # Lista delle directory separate da "," # ******************************************************* sonar.sources= # ****************************************************** # Percorso dove risiedono i file compilati (.class) dopo # la compilazione con ANT. # Se vi sono più directory inserirle con la "," come # separatore # ****************************************************** sonar.java.binaries= # ****************************************************** # Percorso dove risiedono le librerie necessarie # per la compilazione con ANT del progetto. # Se vi sono più directory inserirle con la "," come # separatore # ****************************************************** sonar.java.libraries= # encoding dei files JAVA utilizzati nel progetto sonar.sourceencoding= OSCAT-QMSS-ManualeUtente doc del v di 17