Il progetto ha l'obiettivo di implementare una piattaforma open source per la raccolta di informazioni tramite form, utilizzando un modello di autenticazione "flessibile" (es. SPID, email, ...).
In questa prima versione il servizio, di tipo dispositivo, è rivolto a tutte le pubbliche amministrazioni che devono obbligatoriamente pubblicare le dichiarazioni di accessibilità per i propri siti web e applicazioni mobile.
Tali amministrazioni utilizzano la piattaforma per compilare le dichiarazioni, memorizzarle e riferire la pagina web ospitata su form.agid.gov.it tramite un link sul proprio sito web istituzionale.
Il servizio permette di autenticare i Responsabili per la Transizione Digitale delle amministrazioni che ne hanno indicato l'email all'interno dell'indice delle pubbliche amministrazioni.
L'utente che vuole autenticarsi seleziona la propria amministrazione da un menu a tendina e conferma di voler ricevere il codice di accesso (password) all'indirizzo dell'RTD indicato su IPA.
Viene quindi inviata un'email, a tale indirizzo, contenente il codice che l'utente inserirà nel form di login in modo da aprire una sessione autenticata della durata di 30 giorni; la data in cui la sessione decade è contenuta nel campo "expire" di un JSON Web Token che l'utente (browser) riceve se il codice inserito corrisponde a una password valida.
Il sistema memorizza:
- i dati (pubblici) ottenuti da IPA sulle singole amministrazioni, in modo da ricavare gli indirizzi degli RTD
- i dati (pubblici) immessi dall'utente durante la compilazione dei form (es. dichiarazione di accessibilità)
Non sono memorizzati dati privati, se non i codici di accesso (in Redis, con una durata temporanea di 30gg) corrispondenti agli indirizzi email degli RTD.
- generazione di form da file di configurazione YAML
- possibiltà di integrare facilmente logiche complesse (es. campi dipendenti dal valore di altri campi, valori computati, etc.)
- possibilità di memorizzare i dati senza attuare modifiche al database o al backend (utilizzando una base di dati schemaless)
- workflow: i contenuti possono assumere diversi stati (bozza, in revisione, pubblicato, archiviato)
- tutti i contenuti sono revisionati (viene creata una nuova revisione a ogni salvataggio); è possibile consultare le vecchie revisioni e compararle con l'ultima pubblicata
- il modello di autenticazione è flessibile: la comunicazione con il backend avviene tramite json web token
Il linguaggio di programmazione utilizzato è Typescript (v3.5.x), sia per il backend NodeJS che per il frontend ReactJS.
- NodeJS: il backend effettua l'autenticazione e trasmette i JWT al frontend che li utilizza per le chiamate alle API / GraphQL
- Apollo GraphQL: è il client utilizzato per l'interrogazione dei dati tramite GraphQL
- GatsbyJS: si tratta di un generatore di siti statici (o meglio, ibridi) che utilizza ReactJS come linguaggio di template e GraphQL per l'interrogazione dei dati
- Apollo GraphQL come client per l'interrogazione dei dati tramite GraphQL
Al netto delle dovute personalizzazioni, è possibile utilizzare il codice del frontend come tema GatsbyJS per produrre siti "ibridi" (pagine statiche e funzionalità dinamiche tramite API) conformi ai principi di designers.italia.it.
La piattaforma si compone di
- un backend NodeJS: implementa le funzionalità di autenticazione e generazione dei JWT da passare al frontend
- un frontend GatsbyJS: i file "statici" (HTML) sono serviti da un'istanza del webserver nginx
- dei task asincroni che leggendo da una coda redis processano i job da eseguire in background (es. per l'invio di email)
L'infrastruttura è attualmente dispiegata su una sola macchina utilizzando i due file docker compose:
- frontend: docker-compose.yml
- backend: docker-compose.yml
Le altre componenti consistono in
- Hasura: una piattaforma che realizza la pesistenza dei dati (GraphQL + PostgreSQL)
- Redis per il caching e le code di task asincroni
- Traefik come API gateway e per la generazione automatica dei certificati https
Le uniche porte aperte esternamente (internet) sono quelle che permettono il traffico attraverso il gateway Traefik ovvero 80 (HTTP) e 443 (HTTPS).
Gli host raggiungibili sono:
- https://form.agid.gov.it (il frontend statico)
- https://backend.form.agid.gov.it (il backend NodeJS)
- https://database.form.agid.gov.it (hasura GraphQL)
- https://gateway.form.agid.gov.it (la dashboard Traefik)
La generazione dei certificati HTTPS avviene in automatico tramite Let's Encrypt.
Il dispiegamento può avvenire su una macchina Linux dove sia installato docker.
Il repository del backend contiene un file rc.local con i comandi che devono essere lanciati sulla macchina che ospita l'installazione prima di avviare la piattaforma.
Si presuppone che al percorso /data sulla macchina host corrisponda una
partizione (directory) di dimensione adeguata (almeno 10GB) a ospitare i file
del layer di persistenza.
- installare git
- installare docker-compose
- installare hasura cli
- eseguire i seguenti comandi:
git clone https://github.com/AgID/agid-forms-backend
cd agid-forms-backend
cp env.example .env
# editare il file di configurazione del backend
# e impostare i valori delle variabili di configurazione.
docker-compose up -d hasura postgresql
cd database
hasura migrate apply
cd ..
docker-compose up -d
cd ..
git clone https://github.com/AgID/agid-forms-frontend
cp env.example .env
# editare il file di configurazione del frontend
# e impostare i valori delle variabili di configurazione.
cd agid-forms-frontend && docker-compose up -dUna volta lanciato docker-compose il frontend sarà raggiungibile con un browser all'indirizzo indicato nel file di configurazione (https://form.agid.gov.it).
TODO