linkitaly/govway repository overview

⁠Docker Image

⁠Tags supportati e link ai rispettivi Dockerfile

⁠3.4.x

• 3.4.3, latest
• 3.4.3_run
• 3.4.3_manager
• 3.4.3_batch
• Dockerfile⁠
• 3.4.2.p1
• 3.4.2.p1_run
• 3.4.2.p1_manager
• 3.4.2.p1_batch
• Dockerfile⁠

⁠3.3.x

• 3.3.20
• 3.3.20_run
• 3.3.20_manager
• 3.3.20_batch
• Dockerfile⁠
• 3.3.19.p1
• 3.3.19.p1_run
• 3.3.19.p1_manager
• 3.3.19.p1_batch
• Dockerfile⁠

⁠Riferimenti al progetto

• Informazioni sul progetto GovWay⁠
• Sorgenti GovWay su GitHub⁠
• Progetto Govway-Docker su GitHub⁠

⁠Cosa è GovWay

Dall’esperienza della Porta di Dominio italiana, l’API Gateway conforme alle normative della Pubblica Amministrazione:

• Conformità agli standard di mercato: gestione protocolli standard di mercato, come SOAP 1.1 e 1.2, API restful serializzate in Json o XML o semplici dati binari su Http.
• Conformità alle specifiche italiane per l'interoperabilità: supporto delle nuove linee guida per l'interoperabilità di AGID (ModI) e gestione dei token rilasciati dalla PDND. Viene inoltre assicurata la retrocompatibilità con il protocollo SPCoop, ancora ampiamente adottato per i servizi della PA.
• Conformità alle specifiche per la fatturazione elettronica sul canale SdiCoop.

⁠Release Notes

• 3.4.3 / 3.3.20

  • Aggiornato driver jdbc di postgresql alla versione 42.7.11

• 3.4.3

  • Aggiornato application server di base (Tomcat) alla versione 11.0.22.
  • Aggiornato il runtime Java alla versione 25 per le immagini basate su Tomcat 11 e WildFly 39 (in precedenza Java 21).

• 3.3.20

  • Aggiornato application server di base (Tomcat) alla versione 9.0.118.

• 3.4.2

  • Aggiornato application server di base (Tomcat) alla versione 11.0.18.

• 3.3.19

  • Aggiornato application server di base (Tomcat) alla versione 9.0.115.

• 3.4.2 / 3.3.19

  • Aggiornato driver jdbc di postgresql alla versione 42.7.9
  • Aggiunto supporto per il database mysql/mariadb e sqlserver
  • Una singola immagine supporta ora tutti i database, semplificando build e deployment. Introdotta la variabile obbligatoria GOVWAY_DB_TYPE a runtime per selezionare il database (hsql, postgresql, mysql, mariadb, oracle).

• 3.4.1 / 3.3.18

  • Aggiornato driver jdbc di postgresql alla versione 42.7.8
  • Eliminata esposizione di informazioni sulla versione di Tomcat;
  • Introdotte le variabili 'GOVWAY_SERVICE_PROTOCOL', 'GOVWAY_SERVICE_HOST' e 'GOVWAY_SERVICE_PORT' che consentono di definire l'indirizzamento dei nodi run senza dover definire il file '/etc/govway/govway.nodirun.properties';
  • Introdotta la variabile 'GOVWAY_DB_MAPPING' che consente di definire la distribuzione delle diverse categorie di dati su database distinti;
  • Aggiunta possibilità di modificare i parametri di gestione della memoria usata dalla JVM.
  • Introdotto 'Health Check' per ambiente manager
  • Aggiornato application server di base (Tomcat) alla versione 9.0.111 per la 3.3.18 e alla versione 11.0.13 per la 3.4.1.

• Storico completo delle modifiche consultabile nel ChangeLog⁠ del progetto Govway-Docker⁠.

⁠Nomenclatura delle immagini fornite

⁠Versioni 3.4.2 / 3.3.19 e successive

A partire dalla versione 3.4.2 / 3.3.19, l'immagine Docker è unica e multi-database: supporta i database hsql, postgresql, mysql, mariadb, oracle e sqlserver. La scelta del database avviene a runtime tramite la variabile obbligatoria GOVWAY_DB_TYPE.

• standalone (GOVWAY_DB_TYPE=hsql): fornisce un ambiente di prova di GovWay funzionante dove i dati di configurazione e tracciamento vengono mantenuti su un database HSQL interno al container;

• orchestrate (GOVWAY_DB_TYPE=postgresql|mysql|mariadb|oracle|sqlserver): fornisce un'installazione che consente di avere i dati di configurazione e tracciamento su un database esterno, gestito esternamente o su ambienti orchestrati (Es. Kubernetes, OpenShift).

Esistono ulteriori immagini che suddividono i componenti applicativi tra componenti di runtime e componenti dedicati alla gestione e il monitoraggio. Una suddivisione dei componenti consente di attuare una scalabilità dei nodi run proporzionata alla mole di richieste che devono essere gestite dall'api gateway:

• run: contiene solamente il componente runtime di api gateway;

• manager: contiene solamente le console e i servizi API di configurazione e monitoraggio.

⁠Versioni precedenti alla 3.4.2 / 3.3.19

Nelle versioni precedenti, venivano fornite immagini separate per ogni tipo di database:

• standalone: ambiente con database HSQL interno al container;

• postgres o oracle: immagine specifica per database postgresql o oracle esterno;

• run_postgres o run_oracle: componente runtime per database postgresql o oracle;

• manager_postgres o manager_oracle: console e servizi API per database postgresql o oracle.

⁠Ambienti run e manager

Le console disponibili nell’ambiente manager necessitano di accedere ad alcuni servizi esposti dai nodi run, utilizzati per il monitoraggio e la gestione distribuita:

• servizio 'check': consente di monitorare lo stato del servizio dei nodi run; è possibile invocare il contesto "/govway/check" di un qualsiasi nodo run (riferendo l'endpoint di esposizione del servizio dei nodi run) o un servizio fornito dal container;

• servizio 'proxy': consente di inviare un comando ad ogni nodo run attivo; deve essere indirizzato il servizio "/govway/proxy" di un qualsiasi nodo attivo.

L’ambiente manager accede ai due servizi tramite le seguenti URL di default:

• ${GOVWAY_SERVICE_PROTOCOL}://${GOVWAY_SERVICE_HOST}:${GOVWAY_SERVICE_PORT}/govway/check
• ${GOVWAY_SERVICE_PROTOCOL}://${GOVWAY_SERVICE_HOST}:${GOVWAY_SERVICE_PORT}/govway/proxy

Se non ridefinite, le variabili d’ambiente assumono i seguenti valori predefiniti:

• GOVWAY_SERVICE_PROTOCOL = http
• GOVWAY_SERVICE_HOST = 127.0.0.1
• GOVWAY_SERVICE_PORT = 8082

In alternativa è possibile ridefinire completamente l’indirizzamento dei servizi dei nodi run tramite il file di configurazione "/etc/govway/govway.nodirun.properties", come nell’esempio seguente:

# ===================================================================
# Indirizzamento servizi dei nodi 'run' 
# Servizio 'proxy'
GovWay.remoteAccess.url=http://<service-name:8082>/govway/proxy
# Servizio 'check'
GovWay.remoteAccess.checkStatus.url=http://<service-name>:8082/govway/check
# ===================================================================

⁠Health Check

I seguenti contesti possono essere utilizzati come health check:

• run: /govway/check
• manager: /govwayMonitor/check

⁠Avviare l'immagine standalone

Eseguire il run dell'immagine:

$ docker run \
  -e GOVWAY_DB_TYPE=hsql \
  -e GOVWAY_DEFAULT_ENTITY_NAME=Ente \
  -e GOVWAY_POP_DB_SKIP=false \
  -e TZ=Europe/Rome \
linkitaly/govway

I servizi e le interfacce web di GovWay sono accessibili sia su protocollo HTTP, che su protocollo AJP sulle porte 808* e 8009 rispettivamente (nella sezione 'Informazioni di Base' vengono fornite maggiori informazioni a riguardo):

$ docker run \
 -e GOVWAY_DB_TYPE=hsql \
 -e GOVWAY_POP_DB_SKIP=false \
 -e TZ=Europe/Rome \
 -p 8080:8080 \
 -p 8081:8081 \
 -p 8082:8082 \
 -p 8009:8009 \
linkitaly/govway

Per maggiori informazioni sulle console fare riferimento alla documentazione del progetto GovWay⁠.

I files, interni all'immagine, utilizzati da GovWay sono:

• le properties di configurazione, posizionati nella directory /etc/govway;
• i file di log, posizionati nella directory /var/log/govway;
• il database HSQL situato in /opt/hsqldb-2.7.4/hsqldb/database.

Si possono rendere persistenti i file sopra indicati montando un volume per ogni directory indicata:

$ mkdir ~/govway_conf
$ mkdir ~/govway_log
$ mkdir ~/govway_db
$ docker run \
 -e GOVWAY_DB_TYPE=hsql \
 -e GOVWAY_DEFAULT_ENTITY_NAME=Ente \
 -e GOVWAY_POP_DB_SKIP=false \
 -e TZ=Europe/Rome \
 -p 8080:8080 \
 -p 8081:8081 \
 -p 8082:8082 \
 -p 8009:8009 \
 -v ~/govway_conf:/etc/govway \
 -v ~/govway_log:/var/log/govway \
 -v ~/govway_db:/opt/hsqldb-2.7.4/hsqldb/database \
linkitaly/govway

⁠Avviare una delle immagini orchestrate

Utilizzando docker-compose come esempio di ambiente orchestrato, è possibile utilizzare un docker-compose.yml simile al seguente per database postgresql (nella dir ~/postgresql/jdbc-driver deve essere presente il driver jdbc):

version: '2'
services:
  govway:
    container_name: govway
    image: linkitaly/govway:3.4.3
    ports:
        - 8080:8080
        - 8081:8081
        - 8082:8082
        - 8009:8009
    volumes:
        - ~/govway_conf:/etc/govway
        - ~/govway_log:/var/log/govway
        - ~/postgresql/jdbc-driver:/tmp/jdbc-driver
    environment:
        - TZ=Europe/Rome
        - GOVWAY_DB_TYPE=postgresql
        - GOVWAY_DEFAULT_ENTITY_NAME=Ente
        - GOVWAY_DS_JDBC_LIBS=/tmp/jdbc-driver
        - GOVWAY_DB_SERVER=postgres_hostname:5432
        - GOVWAY_DB_NAME=govwaydb
        - GOVWAY_DB_USER=govway
        - GOVWAY_DB_PASSWORD=govway
        - GOVWAY_POP_DB_SKIP=true

Un esempio di docker-compose per oracle è invece il seguente (nella dir ~/oracle11g/jdbc-driver deve essere presente il driver jdbc):

version: '2'
services:
  govway:
    container_name: govway
    image: linkitaly/govway:3.4.3
    ports:
        - 8080:8080
        - 8081:8081
        - 8082:8082
        - 8009:8009
    volumes:
        - ~/govway_conf:/etc/govway
        - ~/govway_log:/var/log/govway
        - ~/oracle11g/jdbc-driver:/tmp/jdbc-driver
    environment:
        - TZ=Europe/Rome
        - GOVWAY_DB_TYPE=oracle
        - GOVWAY_DEFAULT_ENTITY_NAME=Ente
        - GOVWAY_DS_JDBC_LIBS=/tmp/jdbc-driver
        - GOVWAY_ORACLE_JDBC_URL_TYPE=SERVICENAME
        - GOVWAY_DB_SERVER=oracle_hostname:1521
        - GOVWAY_DB_NAME=govwaydb
        - GOVWAY_DB_USER=govway
        - GOVWAY_DB_PASSWORD=govway
        - GOVWAY_POP_DB_SKIP=true

Un esempio di docker-compose per SQL Server è invece il seguente (nella dir ~/sqlserver/jdbc-driver deve essere presente il driver jdbc):

version: '2'
services:
  govway:
    container_name: govway
    image: linkitaly/govway:3.4.3
    ports:
        - 8080:8080
        - 8081:8081
        - 8082:8082
        - 8009:8009
    volumes:
        - ~/govway_conf:/etc/govway
        - ~/govway_log:/var/log/govway
        - ~/sqlserver/jdbc-driver:/tmp/jdbc-driver
        - ~/sqlserver/truststore.jks:/tmp/truststore.jks
    environment:
        - TZ=Europe/Rome
        - GOVWAY_DB_TYPE=sqlserver
        - GOVWAY_DEFAULT_ENTITY_NAME=Ente
        - GOVWAY_DS_JDBC_LIBS=/tmp/jdbc-driver
        - GOVWAY_SQLSERVER_TRUSTSTORE=/tmp/truststore.jks
        - GOVWAY_SQLSERVER_TRUSTSTORE_PASSWORD=changeit
        - GOVWAY_DB_SERVER=sqlserver_hostname:1433
        - GOVWAY_DB_NAME=govwaydb
        - GOVWAY_DB_USER=govway
        - GOVWAY_DB_PASSWORD=govway
        - GOVWAY_POP_DB_SKIP=true

Per maggiori informazioni sulla configurazione della cifratura a livello di trasporto per SQL Server (GOVWAY_SQLSERVER_ENCRYPT, GOVWAY_SQLSERVER_TRUSTSTORE, GOVWAY_SQLSERVER_TRUSTSTORE_PASSWORD), fare riferimento alla documentazione del progetto Govway-Docker⁠.

I containers vengono avviati con i seguenti comandi:

$ mkdir -p ~/govway_{conf,log}
$ chmod 777 ~/govway_{conf,log}
$ docker-compose up

⁠Informazioni di Base

⁠File interni all'immagine

I files, interni all'immagine, utilizzati da GovWay sono:

• le properties di configurazione, posizionati nella directory /etc/govway;
• i file di log, posizionati nella directory /var/log/govway;
• in una immagine standalone il database HSQL è situato in /opt/hsqldb-2.7.4/hsqldb/database.

si possono rendere queste location persistenti, montando dei volumi su queste directory come mostrato negli esempi delle sezioni precedenti.

⁠Servizi attivi

I servizi attivi all'interno dell'immagine sono in ascolto sia in protocollo AJP sulla porta 8009 sia in HTTP su 3 porte in modo da gestire il traffico su ogni porta, con un listener dedicato:

• 8080: Listener dedicato al traffico in erogazione (max-thread-pool default: 100)
• 8081: Listener dedicato al traffico in fruizione (max-thread-pool default: 100)
• 8082: Listener dedicato al traffico di gestione (max-thread-pool default: 20)

Tutte queste porte sono esposte dal container e per accedere ai servizi dall'esterno si devono pubblicare al momento dell'avvio del immagine. Le interfacce web di monitoraggio configurazione sono quindi disponibili sulle URL:

 http://<indirizzo IP>:8082/govwayConsole/
 http://<indirizzo IP>:8082/govwayMonitor/

L'account di default per l'interfaccia govwayConsole è:

• username: amministratore
• password: 123456

L'account di default per l'interfaccia govwayMonitor è:

• username: operatore
• password: 123456

Il contesto di accesso ai servizi dell'API gateway per le erogazioni di API:

 http://<indirizzo IP>:8080/govway/

Il contesto di accesso ai servizi dell'API gateway per le fruizioni di API:

 http://<indirizzo IP>:8081/govway/

⁠Script SQL di inizializzazione della BaseDati

All'avvio del container, sia in modalità standalone che con immagini orchestrate, vengono eseguite delle verifiche sul database per assicurarne la raggiungibilità ed il corretto popolamento; in caso venga riconosciuto un database non inizializzato vengono utilizzati gli scripts SQL interni per effettuare l'inizializzazione a meno che la variabile 'GOVWAY_POP_DB_SKIP' risulta abilitata.

Per esaminare gli script SQL di inizializzazione o utilizzarli manualmente è possibile recuperarli dall'immagine in una delle directory standard /opt/hsql, /opt/postgresql, /opt/mysql, /opt/mariadb, /opt/oracle o /opt/sqlserver. Ad esempio per estrarre gli script SQL per PostgreSQL è possibile utilizzare il comando:

CONTAINER_ID=$(docker run -d -e GOVWAY_DEFAULT_ENTITY_NAME=Ente -e GOVWAY_DB_TYPE=postgresql linkitaly/govway:3.4.3 initsql);
docker wait ${CONTAINER_ID};
docker cp ${CONTAINER_ID}:/opt/postgresql .;
docker rm ${CONTAINER_ID}

⁠Aggiornamento di Versione

Un upgrade richiede l'aggiornamento della base dati.

Serve inoltre una verifica dei diritti utente se si proviene da una versione precedente alla 3.3.16.b1, come descritto nella successiva sezione.

⁠Upgrade di una versione precedente alla v3.3.16.b1

Nel caso siano stati utilizzati dei volumi esterni è necessario gestire il cambio di utente che è avvenuto in seguito alla modifica del sistema operativo di base da Ubuntu 22 LTS (Jammy) a Alpine 3.21.3. Questo comporta aggiornare i diritti associati alle directory montate utilizzando l'id-utente '100' e l'id-gruppo '101' di tomcat; ad esempio:

  chown -R 100:101 ~/govway_conf
  chown -R 100:101 ~/govway_log
  chown -R 100:101 ~/govway_db

⁠Upgrade di una versione precedente alla v3.3.15 fino alla v3.3.16

Nel caso siano stati utilizzati dei volumi esterni è necessario gestire il cambio di utente che è avvenuto in seguito alla modifica di application server di base da wildfly 26.1.3 a tomcat 9.0.x. Questo comporta aggiornare i diritti associati alle directory montate utilizzando l'id-utente '999' di tomcat; ad esempio:

  chown -R 999:999 ~/govway_conf
  chown -R 999:999 ~/govway_log
  chown -R 999:999 ~/govway_db

⁠Ambiente orchestrato

Se è stato utilizzato un docker-compose su ambiente orchestrato (postgresql o oracle) o un'immagine standalone con database montato su un volume esterno, per effettuare l'upgrade è necessario seguire i seguenti step:

• fermare ed eliminare il container contenente la precedente versione;

• aggiornare la base dati come indicato in README.update⁠;

  • nel caso di un aggiornamento da una versione precedente alla 3.3.15, è necessario applicare i seguenti script SQL aggiuntivi sulla base dati, a causa della modifica dell'application server di base da WildFly a Tomcat:

    update registri set location='java:/comp/env/org.govway.datasource.console';
    update audit_appender_prop set value='java:/comp/env/org.govway.datasource.console' where name='datasource';
    

    Copy

• riferire la nuova versione all'interno del docker-compose;

• riavviare il docker-compose.

⁠Standalone

Nel caso di versione standalone in cui il database non sia stato montato su un volume esterno, è sufficiente avviare la nuova versione dell'immagine.

⁠Ambienti batch

La console di Monitoraggio mette a disposizione informazioni statistiche aggregate, elaborate su base periodica, relative alle transazioni gestite. Questi dati consentono un’analisi sintetica e continuativa dell’andamento del sistema.

In aggiunta, è previsto un campionamento specifico dedicato alla generazione di report in formato CSV, conformi agli standard previsti dalla Piattaforma Digitale Nazionale Dati (PDND), con relativa gestione della pubblicazione attraverso le API di Interoperabilità.

Sia i dati statistici che la pubblicazione dei report PDND vengono gestiti per default dal componente runtime dell'api gateway attraverso la schedulazione periodica di thread dedicati.

In ambienti di produzione è consigliato spostare l'attività di generazione delle statistiche su un componente dedicato in modo da non gravare il costo sui nodi run. La disattivazione della generazione delle statistiche sui nodi run deve essere effettuata nel file '/etc/govway/govway_local.properties' come segue:

# ================================================
# Generazione Report
...
# Tipo di campionamenti abilitati
org.openspcoop2.pdd.statistiche.generazione.baseOraria.enabled=false
org.openspcoop2.pdd.statistiche.generazione.baseGiornaliera.enabled=false
org.openspcoop2.pdd.statistiche.pdnd.tracciamento.generazione.enabled=false
org.openspcoop2.pdd.statistiche.pdnd.tracciamento.pubblicazione.enabled=false
...
# ================================================

Utilizzando docker-compose come esempio di ambiente orchestrato, è possibile utilizzare un docker-compose.yml simile al seguente per database postgresql (nella dir ~/postgresql/jdbc-driver deve essere presente il driver jdbc):

version: '2'
services:

  batch_stat_orarie:
    container_name: govway_batch_statistiche_orarie
    image: linkitaly/govway:3.4.3_batch
    volumes:
       - ~/govway_log:/var/log/govway
       - ~/postgresql/jdbc-driver:/tmp/jdbc-driver
    command:
      - orarie
    environment:
      - GOVWAY_DB_TYPE=postgresql
      - GOVWAY_DS_JDBC_LIBS=/tmp/jdbc-driver
      - GOVWAY_STAT_DB_SERVER=postgres_hostname:5432
      - GOVWAY_STAT_DB_NAME=govwaydb
      - GOVWAY_STAT_DB_USER=govway
      - GOVWAY_STAT_DB_PASSWORD=govway
      - GOVWAY_BATCH_USA_CRON=true
      - GOVWAY_BATCH_INTERVALLO_CRON=5
      - TZ=Europe/Rome

  batch_stat_giornaliere:
    container_name: govway_batch_statistiche_giornaliere
    image: linkitaly/govway:3.4.3_batch
    command:
      - giornaliere
    environment:
      - ... come esempio 'batch_stat_orarie' ...

  batch_generazione_report_pdnd:
    container_name: govway_batch_generazione_report_pdnd
    image: linkitaly/govway:3.4.3_batch
    command:
      - generaReportPDND
    environment:
      - ... come esempio 'batch_stat_orarie' ...

  batch_pubblicazione_report_pdnd:
    container_name: govway_batch_pubblicazione_report_pdnd
    image: linkitaly/govway:3.4.3_batch
    command:
      - pubblicaReportPDND
    environment:
      - ... come esempio 'batch_stat_orarie' ...

I containers vengono avviati con i seguenti comandi:

$ mkdir -p ~/govway_{conf,log}
$ chmod 777 ~/govway_{conf,log}
$ docker-compose up

⁠Versione Snapshot

⁠3.4.x

Ogni modifica dei sorgenti attuata sul branch '3.4.x' del progetto viene validata nell'ambiente di continuous integration⁠. Il processo produce un installer della versione snapshot⁠ scaricabile dall'ambiente di CI.

Vengono inoltre fornite le seguenti immagini per le versioni snapshot (Dockerfile)⁠:

• master4
• master4_batch

⁠3.3.x

Ogni modifica dei sorgenti attuata sul master del progetto viene validata nell'ambiente di continuous integration⁠. Il processo produce un installer della versione snapshot⁠ scaricabile dall'ambiente di CI.

Vengono inoltre fornite le seguenti immagini per le versioni snapshot (Dockerfile)⁠:

• master
• master_batch