1 of 46

Installazione e manutenzione

Gestione della piattaforma

In questo documento sono descritte le attività operative per l'installazione e la manutenzione dei servizi della piattaforma, svolte dal personale di Opencity Labs per l'ambiente SaaS. Le stesse operazioni possono essere svolte da partner tecnici - con il supporto di Opencity Labs - sulle proprie installazioni on-premise.

Il documento è orientato a sistemisti, platform engineers, SRE e tecnici addetti alla manutenzione della piattaforma in produzione.

La piattaforma Opencity Italia è composta da due componenti integrate tra loro:

il sito istituzionale: un CMS che implementa il Design della Pubblica Amministrazione e basato su modelli di sito ufficiali di Designers Italia (Comuni, Asl, Musei)
i servizi digitali e l'area personale: un'area interattiva con cui i cittadini possono usufruire di servizi di richiesta a istanza, pagare dovuti PagoPA, prenotare appuntamenti.

Architettura

L'architettura del CMS è di tipo monolitico, mentre quella che implementa i servizi digitali è organizzata a microservizi, sebbene l'originale monolite in symfony abbia ancora rilevanti responsabilità

Architettura generale

In questo e nei diagrammi che seguono è stato seguito il Modello C4 per la rappresentazione dei diagrammi architetturali.

Sito istituazionale

L'architettura del CMS è una classica architettura monolitica con un core in PHP e una persistenza principale (PostgreSQL) a cui si affiancano un motore di ricerca (Solr) e un layer di cache http (Varnish)

Container diagram

Servizi digitali e area personale

L'architettura ha subito varie trasformazioni nel tempo e non può dirsi ancora definitiva, ma alcune caratteristiche sono ormai consolidate:

la decomposizione in microservizi con storage indipendenti e API ReST
il sistema di scambio di messaggi basato su Kafka per rendere asincrone le interazioni tra i microservizi

Vista dettagliata di Services Core

Questa parte del sistema ha la maggior parte delle responsabilità relative alle pratiche al sistema di appuntamenti. E' costitutito da un core in symfony e da alcuni servizi al contorno che svolgono funzioni specifiche.

Kafka API, è una istanza del server open-source Vector fornisce una interfaccia HTTP per Kafka
Gotenberg è un tool opensource che la piattaforma utilizza per la creazione dei PDF
Form Server è la nostra implementazione del server open-source Form.io, di cui usiamo nel core le librerie Javascript per il rendering delle form.
Form Builder è una Single-Page-App in angular che include la libreria di Form.io per la creazione delle form. E' un servizio dedicato agli amministratori della piattaforma per la gestione di una libreria di componenti condivisi e riusabili dagli Enti nella creazione dei loro moduli: anagrafiche, definizione di immobili, autoveicoli etc...

Vista di dettaglio del sotto-sistema dei Pagamenti

TBD

Vista di dettaglio del sotto-sistema dei Documenti

TBD

Vista di dettaglio del sotto-sistema degli Analytics

Installazione

La distribuzione dei servizi della piattaforma avviene mediante immagini docker, non ci sono requisiti particolari in merito all'orchestratore utilizzato (docker swarm, kubernetes, nomad, mesos).

Installazione ambiente di Test / Sviluppo

Per una installazione di test su singolo nodo si consiglia di usare il service compose presente nei due repository principali:

dal repo dei sito istituzionale e leggere con attenzione il .
dal core dei servizi digitali e leggere con attenzione il .

Installazione ambiente di Produzione

Per un ambiente di produzione è indispensabile predisporre un ambiente con adeguati livelli di ridondanza e dimensionamento dei singoli servizi in base alla propria infrastruttura e ai propri requisiti in termini di affidabilità e livelli di servizio da garantire.

Non c'e' una ricetta valida a priori per dimensionare il sistema, si consiglia di partire da una configurazione con 2 repliche di ogni servizio stateless e un dimensionamento molto largo (es: 1GB di ram, 1 vCPU) e poi monitorare il proprio sistema per stabilire i requisiti di ogni singolo container: si potrà verificare facilmente che molti microservizi richiedono pochi Mb di ram.

Elenco dei servizi necessari

Ogni servizio si basa su una immagine docker specifica e necessita di adeguate configurazioni. Le configurazioni e i valori di default delle stesse sono documentate nei singoli repository dei microservizi.

Al fine di dare una corretta configurazione dei vari servizi vengono indicate inoltre:

la dipendenza dalle persistenze usate dalla piattaforma
la necessità di pubblicare un endpoint per quel servizio pubblicamente raggiungibile

Sito istituzionale

Servizio

Descrizione

Docker Image

Pubblico

Servizi digitali e Area Personale

File di esempio

Prima di procedere all’avvio dei microservizi si devono compiere alcune operazioni:

Creazione del file delle istanze

Va creato un file instances.yml sull'ambiente che ospiterà la piattaforma, questo file dovrà poi essere condiviso con i servizi che ne hanno bisogno (vedi file di esempio di distribuzione).

Il file è così formato:

Andrà creato un blocco istanza per ogni ente che si vorrà ospitare sulla piattaforma

Creazione dei database

Singole istanze degli enti (Symfony core)

Il tipo di multi-tenancy implementata in OpenCity Area personale è di singolo stack applicativo con database dedicato per tenant.

Per poter effettuare un’installazione dell’infrastruttura abbiamo quindi bisogno di un singolo database per tenant con le seguenti caratteristiche.

Postgres >= 11 con estensione postgis >= 3

Permessi

Per ridurre i rischi dovuti a errori o a compromissione delle credenziali vengono usati due utenti differenti:

un utente oc_manager che viene utilizzato per creare i database ed eseguire operazione di struttura (creazione, modifica e cancellazione di tabelle, viste, colonne ecc ecc)
un utente oc_user che viene utilizzato dall’applicativo per effettuare operazioni sui dati

Attualmente nella nostra infrastruttura la creazione del database avviene con l'utente oc_manager, a partire da un template preimpostato con i privilegi necessari.

Creazione del template

Come utente postgres si crea il database impostando i privilegi di default che verranno assegnati a tutti gli oggetti creati in seguito.

A postgres verranno dati privilegi ampi, mentre a oc_user verranno dati privilegi minimali:

In seguito la proprietà del database viene assegnata ad oc_manager

Per creare database come utente postgres gli viene dato il ruolo oc_manager

Creazione di un nuovo database

Per creare il database e impostarne subito come owner l'utente corretto, si esegue come utente postgres

Sistema di protocollazione (registry)

Il sistema di protocollazione ha invece bisogno di un singolo database con le seguenti caratteristiche:

Postgres >= 11

Creazione di un nuovo utente

Tuning di alcuni parametri di connessione (questi comandi sono opzionali ma suggeriti da django)

Creo il database e lo assegno all'utente

Configurazione dei proxy di pagamento

Per garantire una corretta comunicazione tra l'area personale e i proxy di pagamento è necessaria configurare appropriatamente gli endpoint sul proxy di riferimento.

Configurazione dei CORS

Il requisito di base affinchè questi endpoint siano correttamente funzionanti è che siano correttamente racchiuse all'interno di un middleware che gestisca i CORS in maniera adeguata. In particolare questo middleware dovrà essere configurato come segue:

Di seguito un esempio di configurazione del middleware:

Endpoint interni (non necessita di CORS)

L'unico endpoint interno in questo caso è quello per richiedere l'aggiornamento dello stato di un pagamento. Per garantire quindi che questo venga chiamato solo ed esclusivamente dal microservizio di polling, è necessario che questo venga configurato come endpoint raggiungibile solo internamente alla rete di docker. Di seguito un esempio:

Endpoint pubblici

Gli endpoint pubblici sono:

Pagamento online (/online-payment/{payment_id})
Download dell'avviso cartaceo (/offline-payment/{payment_id})
Download della ricevuta telematica (/receipt/{payment_id})
Ritorno alla area personale (detta anche landing url) (/landing/{payment_id})
Form schema per la configurazione del tenant (/tenants/schema)
Form schema per la configurazione del servizio (/services/schema)
Documentazione Swagger delle API (/docs, facoltativo)
Status (/status, facoltativo)
Metriche di monitoraggio (/metrics, facoltativo)

Di seguito un esempio di configurazione degli endpoint

Endpoint protetti

Gli endpoint protetti da autenticazione sono:

Inserimento, recupero, modifica e cancellazione della configurazione del tenant (/tenants/{id})
Inserimento, recupero, modifica e cancellazione della configurazione del servizio (/services/{id})

Di seguito un esempio di configurazione degli endpoint:

Primo avvio e configurazione

Una volta scelto il tipo di distribuzione, creato il file delle istanze e creati i database si potrà effettuare il deploy dei servizi che compongono la piattaforma.

Al primo avvio verranno svolte alcune operazioni in automatico:

Esecuzione delle migrazioni su tutti i database delle istanze specificate nel file instances.yml
Esecuzione delle migrazioni sul database del registry
Creazione dei topics di kafka necessari
Creazione degli stream e delle tabelle sul servizio ksqldb-server

Una volta eseguite queste azioni automatiche dovranno essere finalizzate le configruazioni degli ambienti da parte dell'utente.

Configurazione dell'utente admin per il registry

Entrare nel servizio registry ed eseguire il seguente comando:

/app/venv/bin/python3.9 manage.py createsuperuser

Verrà avviata una procedura guidata per la creazione dell'utente admin per il registry

Installazione dei componenti base nel form server

L'installazione dei componenti base nel formserver può essere fatta in automatico tramite l'esecuzione del formserver-init (Per maggiori info guardare i file di distribuzione)

Queste operazioni possono essere eseguite anche manualmente, effettuato una post alle api del form server:

I componenti da creare sono:

address, birth-info, fiscal-code, full-name, gender, iban, minor-personal-data, personal-data-contacts, personal-data-light, personal-data-minimal, personal-data, residency

Variabili ambiente

Di seguito la lista delle variabili d'ambiente che possono essere configurare nel microservizio core della piattaforma

Integrazioni terze parti

Configurazione tenants

Il sistema è multitenant-multiple-databases, i tenant configurati sono nel file app/instances_${APP_ENV}.yml

E' possibile sovrascrivere il file dei tenant con alcune variabili d'ambiente:

Abilitazione features

Mediante specifiche variabili d'ambiente è possibile abilitare o disabilitare features.

FEATURE_NOME=true

Feature disponibili:

Browser outdated, si abilita tramite la variabile d'ambiente FEATURE_NEW_OUTDATED_BROWSER: sostituisce il vecchio plugin browser outdated per la verifica di browser obsoleti. Migliora la scelta di browser compatibili tramite la versione minima configurata. Supporta browser mobile con callback specifiche per Web - Android - IOS.
Interfaccia di dettaglio pratica per il cittadino, si abilita tramite la variabile d'ambiente FEATURE_APPLICATION_DETAIL: sostituisce l'interfaccia di dettaglio ad uso del cittadino, migliorandone la user experience. Consente inoltre lo scambio di messaggi tra operatore e cittadino.
Calendari con appuntamenti a intervalli dinamici, si abilita tramite la variabile d'ambiente FEATURE_CALENDAR_TYPE: aggiunge la possibilità di modificare la tipologia di appuntamenti di un calendario aggiungendo la possibilità di gestire prenotazioni ad intervalli variabili
Interfaccia per operatori e admin, si abilita tramite la variabile d'ambiente FEATURE_ANALYTICS: abilita la pagina operatori/analytics mostrando dati statistici della stanza.
Identificativo univoco del servizio, si abilita/disabilita tramite la variabile d'ambiente FEATURE_SERVICE_IDENTIFIER: Consente all'amministratore di definire ed editare per ogni servizio un identificativo univoco.
Orari di apertura sovrapposti, si abilita/disabilita tramite la variabile d'ambiente FEATURE_OVERLAPPED_OPENING_HOURS: Consente all'amministratore di creare un calendario dove si possono aggiungere più orari di apertura nella stessa fascia oraria. Sovrascribile a livello di tenant.
Gestione dovuti, mediante variabile d'ambiente FEATURE_DUE_AMOUNT. Sovrascribile a livello di tenant con feature_due_amount.
Abilitazione dell'integrazione con la PDND, mediante variabile d'ambiente FEATURE_PDND. Sovrascribile a livello di tenant con feature_pdnd.
Abilitazione della personalizzazione dei template dei pdf per ente e servizio mediante variabile d'ambiente FEATURE_CUSTOM_TEMPLATES. Sovrascribile a livello di tenant con feature_custom_templates.
Abilitazione dell'interfaccia di configurazione dei pagamenti multipli (Supportata solo su alcuni proxy di pagamento è attualmente ancora in sviluppo) FEATURE_MULTIPLE_PAYMENTS. Sovrascribile a livello di tenant con feature_multiple_payments.
Abilitazione del backoffice lato operatore per la moderazione delle segnalazioni FEATURE_INEFFICIENCIES_BACKOFFICE. Sovrascribile a livello di tenant con feature_inefficiencies_backoffice.
Abilitazione della sezione lato amministratore per l'assegnazione automatica delle pratiche in base al valore di un campo espresso in fase di compilazione della pratica FEATURE_AUTOMATIC_APPLICATIONS_ASSIGNMENT. Sovrascribile a livello di tenant con feature_automatic_applications_assignment
Abilitazione della visualizzazione e gestione da parte degli operatori del Livello di priorità delle pratiche. FEATURE_APPLICATIONS_PRIORITY. Sovrascribile a livello di tenant con feature_applications_priority
Abilitazione di 2 nuovi workflow per la gestione delle pratica Silezio assenso e Silenzio diniego FEATURE_TACIT_OUTCOME. Sovrascribile a livello di tenant con feature_tacit_outcome

Abilitazione protocolli

Nel file di configurazione config/packages/app.yaml è possibile configurare i protocolli disponibili all'amministratore nella configurazione del servizio. Per configurare un protocollo è sufficiente aggiungere una voce alla lista dei protocolli disponibili register_providers

  <key>:
    name: <name>
    url: <protocol_provider_url>
    handler: <handler>
    headers:
      - '<header-name>=<header_value>'
    enabled: <true|false>

dove:

Aggiornamenti

Gli aggiornamenti sono pubblicati ad ogni release sul repository ufficiale della piattaforma e in forma di changelog.

Le modifiche elencate in modo dettagliato nel presente nel repository principale sono sintetizzate con un linguaggio più amichevole in un , dove viene pubblicato un post per ogni release.

La maggior parte delle operazioni di aggiornamento riguardano la struttura dei database e ogni sistema che ne fa uso si occupa in autonomia di effettuare i cambiamenti mediante un proprio sistema di migrazioni.

L'aggiornamento della piattaforma consiste per questo motivo nell'aggiornamento della versione dei microservizi, nelle pagine dedicate alle sono disponibili le singole versioni rilasciate con l'elenco di tutte le versioni di tutti i microservizi.

In qualche caso è possibile che ci siano operazioni che non siamo riusciti a gestire in modo automatico, per questo motivo prima di applicare aggiornamenti consultare sempre il file dove vengono elencate operazioni preliminari o da eseguire subito dopo l'upgrade.

Se non diversamente specificato è necessario eseguire l'aggiornamento in due step:

aggiornamento del microservizio app-manager, che esegue le migrazioni del core
aggiornamento di tutti gli altri microservizi

Monitoraggio

La maggior parte dei microservizi offre la possibilità di essere sottoposto a monitoraggio con vari tools:

i microservizi espongono un path /metricsche espone metriche in
mediante una variabile di ambiente è possibile abilitare l'integrazione con uno strumento per la gestione aggregata e analitica degli errori applicativi, disponibile sia come servizio cloud, sia come che si può installare sulla propria infrastruttura

Backup

Integrazioni

In questa sezione sono elencate tutte le integrazioni dell'area personale con sistemi di autenticazione, pagamenti e protocollo esterni.

Autenticazioni

La piattaforma è integrata con sistemi di autenticazione sviluppati sia da OpenCity Labs che da diversi partner ed enti locali. In questa pagina si descrivono i vari metodi di autenticazione e le configurazioni per abilitarli.

Legenda

Agid / Cie Ministero

SPID L1/L2

CNS

CIE L1

CIE L2

CIE L3

eIDAS

Questo metodo di autenticazione sfrutta l'utilizzo del micro servizio OpenLogin nel quale può essere configurato il singolo tenant. Il micro servizio si interfaccia direttamente con i sistemi di autenticazione Agid tramite SAML per quanto riguarda Spid Utilizzai invece il nuovo sistema di federazione Oidc con il ministero degli interni per quanto riguarda CIE La piattaforma comunica con il micro servizio tramite client Oauth 2