Documento 6 di 13

Requisiti e architettura

Browser, server, rete, componenti, tecnologie.

Per chi: IT

Per chi usa Orafila

Cosa	Requisito
Browser	Chrome o Edge 111 e successivi, Firefox 111 e successivi, Safari 16.4 e successivi (versioni dal 2023 in poi), con JavaScript e cookie attivi
Dispositivi	Computer, tablet e telefono: le pagine si adattano allo schermo
Verifica in due passaggi	Un telefono con un'app di autenticazione (Google Authenticator, Microsoft Authenticator o simili)
Installazioni locali	Nessuna: Orafila si usa dal browser
Rete	Accesso all'indirizzo HTTPS dell'installazione (per esempio `https://psa.vostraazienda.it`)

Per chi installa il server

Cosa	Requisito
Sistema operativo	Ubuntu Server 24.04 LTS (anche 22.04), 64 bit, processori x86-64 (amd64) o Arm (arm64)
Processore	1 vCPU per una demo, 2 o più consigliate
Memoria	2 GB o più consigliati. Con meno di 3,5 GB di RAM lo script di preparazione crea da solo 2 GB di memoria di scorta su disco (swap); la costruzione dell'applicazione richiede almeno 768 MB di RAM e 2,8 GB tra RAM e swap. 1 GB con swap basta per una demo
Disco	25 GB per una demo, 50 GB consigliati (immagini, database, backup locali); l'avvio libera da solo la cache quando restano meno di 4 GB
Indirizzo pubblico	Un IPv4 pubblico e un nome a dominio (record DNS di tipo A verso il server) per il certificato HTTPS
Porte in ingresso	TCP 80 e 443, UDP 443 (HTTPS e HTTP/3); TCP 22 per l'amministrazione via SSH, possibilmente solo dal vostro IP
Porte in uscita	HTTPS 443 (certificati, aggiornamenti, AI, Fatture in Cloud, archivio dei backup); IMAP 993 (o 143 con STARTTLS); SMTP 465 o 587, oppure 2525 se il fornitore blocca le porte di posta
Software	Docker Engine con il plugin compose, age, rclone: li installa lo script di preparazione. curl e OpenSSL, che scaricano e verificano il pacchetto, sono già in Ubuntu
Accesso al pacchetto	L'indirizzo HTTPS dei rilasci di Orafila e, se il fornitore le usa, le credenziali di accesso del server (servono anche per gli aggiornamenti)

Fornitori già provati con guide passo per passo: Oracle Cloud (VM Always Free Arm, regioni Milano o Francoforte) e DigitalOcean (Droplet, regioni Amsterdam o Francoforte). Qualunque altro VPS Ubuntu, per esempio in Unione Europea (Aruba, OVHcloud, Hetzner...), funziona allo stesso modo: cambiano solo la creazione del server e il firewall del fornitore.

Con un database esterno (facoltativo)

Se il database deve stare fuori dal server (database gestito dal fornitore cloud o server PostgreSQL dell'azienda):

PostgreSQL 15 o successivo con TLS, nella stessa regione del server;
un database dedicato a Orafila, raggiungibile solo dall'IP del server;
il certificato dell'autorità (CA) del fornitore in formato PEM;
un amministratore del database con i permessi di creare ruoli e database (CREATEROLE, CREATEDB; con BYPASSRLS funzionano anche i backup di Orafila);
almeno 25 connessioni disponibili.

Architettura

                  ┌──────────── server Ubuntu con Docker ────────────────┐
Browser ──HTTPS──►│ Caddy (HTTPS) ──► App Orafila ──────┐               │
                  │                                      ├─► PostgreSQL  │
Caselle IMAP/SMTP◄┼─► Processo della posta ──────────────┘ (rete interna)│
                  │ Migrazioni (all'avvio) · Strumenti (a richiesta)     │
                  └──────────────────────────────────────────────────────┘
Ogni notte: backup cifrato ──► archivio compatibile S3, fuori dal server
In uscita, se attivi: fornitori AI · Fatture in Cloud (SDI)

Componente	Cosa fa
Caddy	Riceve le visite sulle porte 80 e 443, ottiene e rinnova da solo il certificato HTTPS (Let's Encrypt), inoltra all'app
App	L'applicazione web (pagine, azioni, PDF, esportazioni, endpoint per le email e per il controllo di salute)
Processo della posta	Legge le caselle IMAP delle code ogni minuto, invia le email in coda via SMTP con nuovi tentativi, chiede all'AI lo smistamento dei nuovi ticket
PostgreSQL 16	Il database, su una rete interna senza accesso a internet e senza porte pubbliche
Migrazioni	Aggiornano lo schema del database a ogni avvio, poi si fermano; app e processo della posta partono solo dopo
Strumenti dell'operatore	Attivazione delle aziende, indirizzi delle code, dati di esempio: comandi lanciati a richiesta

Una sola immagine Docker per app, processo della posta, migrazioni e strumenti, costruita sul server dal codice sorgente.
Reti separate: il database è solo sulla rete interna; l'app e il processo della posta hanno accesso a internet in uscita, che usano per AI, posta e Fatture in Cloud.
Controlli di salute: l'app risponde su /api/health; il processo della posta segnala ogni 15 secondi che è vivo; Docker riavvia da solo i servizi che si fermano.
Multi-azienda: una sola installazione serve più aziende, separate dal database (vedi Sicurezza e privacy).

Tecnologie

Livello	Tecnologia
Linguaggio	TypeScript in modalità rigorosa, su Node.js 22
Web	Next.js 16 (App Router) e React 19, rendering sul server
Database	PostgreSQL (16 nel pacchetto, 15 o successivo supportato) con Row-Level Security
Accesso ai dati	postgres.js con query parametrizzate, schema in SQL puro con migrazioni numerate
Posta	IMAP (imapflow), SMTP (nodemailer), lettura dei messaggi (mailparser)
PDF	pdf-lib, in JavaScript puro: nessun browser né servizio esterno sul server
AI	SDK ufficiale di Anthropic; API di OpenAI e Google Gemini
Fattura elettronica	API v2 di Fatture in Cloud
HTTPS	Caddy 2 con Let's Encrypt
Backup	pg_dump, cifratura age, copia con rclone su archivi compatibili S3
Contenitori	Docker Engine e Docker Compose

Dimensionamento

Una sola installazione serve più aziende. Per un'azienda pilota o una demo basta un server da 2 GB di RAM; con molte aziende o molti utenti contemporanei si aumentano memoria e processori dello stesso server (i limiti di memoria dei servizi sono: database 2 GB, app 2 GB, processo della posta 1 GB, Caddy 256 MB). Con un database esterno il carico del database passa al suo server.