Installazione

Questo documento spiega come Orafila viene messo in funzione: le modalità di erogazione, l'installazione su un server con il pacchetto Docker, il database esterno facoltativo, l'avvio di prova su un computer e i riferimenti di configurazione.

Le guide passo per passo con le schermate dei fornitori cloud, pensate anche per chi non fa il sistemista, sono nel pacchetto:

• Rilascio su Oracle Cloud (VM gratuita Always Free, adatta a demo e pilota);
• Rilascio su DigitalOcean (Droplet a pagamento, adatto anche ai clienti in produzione);
• Database esterno.

1. Modalità di erogazione

In entrambi i casi l'applicazione è la stessa e ogni azienda ha i suoi dati separati dal database. Nel servizio gestito l'azienda parte dal passo 8 di questo documento e poi da Avvio e configurazione.

2. Prima di iniziare

• Un server Ubuntu 24.04 (o 22.04) con i requisiti di Requisiti e architettura, raggiungibile via SSH con una chiave.
• Un nome a dominio di cui potete modificare il DNS (per esempio psa.vostraazienda.it) e un'email per la registrazione dei certificati HTTPS.
• L'indirizzo dei rilasci di Orafila e, se il fornitore di Orafila le usa, le credenziali di accesso del server (Client ID e Client Secret): li manda il fornitore (passo 4).
• Un gestore di password dove salvare le chiavi generate dall'installazione. È indispensabile.
• Facoltativi: una chiave API di Anthropic, OpenAI o Google per l'AI; un bucket compatibile S3 per la copia dei backup; un account su un servizio di controllo esterno (per esempio Healthchecks.io e un servizio di uptime).

Da qui in poi i comandi che iniziano con deploy/ si scrivono sul server, dalla cartella orafila.

3. Creare il server e il DNS

1. Create il server presso il fornitore scelto, preferibilmente in una regione dell'Unione Europea. Le guide Oracle e DigitalOcean descrivono ogni schermata.
2. Nel firewall del fornitore aprite in ingresso TCP 80, TCP 443 e UDP 443 da tutti, e TCP 22 (SSH) possibilmente solo dal vostro indirizzo IP.
3. Nel DNS del dominio create un record A con il nome scelto (per esempio psa) verso l'IP pubblico del server. Prima di andare avanti il nome deve rispondere con l'IP giusto (nslookup psa.vostraazienda.it).

4. Scaricare il pacchetto

Orafila si scarica con l'installatore: prende l'ultima versione dal server dei rilasci, ne controlla la firma digitale (la prova che il pacchetto viene dal fornitore di Orafila e che nessuno l'ha alterato) e crea la cartella orafila. Al posto di https://rilasci.orafila.com usate l'indirizzo dei rilasci che vi ha dato il fornitore:

cd ~
curl -fsSLO https://rilasci.orafila.com/install.sh
bash install.sh
cd orafila

Se il fornitore vi ha mandato l'impronta dell'installatore, prima di bash install.sh controllate che sha256sum install.sh stampi la stessa. Se il server dei rilasci è protetto, l'installatore chiede Client ID e Client Secret e li salva in deploy/.env: servono anche per gli aggiornamenti. Non serve sudo e nulla cambia fuori dalla cartella orafila. Se l'installatore segnala che la firma non corrisponde, non andate avanti e avvisate il fornitore di Orafila.

5. Preparare il server

sudo deploy/setup-host.sh

Lo script (da 5 a 15 minuti, si può rilanciare senza danni):

• riconosce il fornitore (Oracle Cloud, DigitalOcean o altro Ubuntu);
• crea 2 GB di swap sui server con meno di 3,5 GB di RAM;
• aggiorna Ubuntu e attiva gli aggiornamenti di sicurezza automatici;
• installa Docker (dal repository ufficiale di Docker), git, age e rclone;
• apre le porte 80 e 443 nel firewall interno del server, se lo blocca;
• controlla se le porte SMTP in uscita sono bloccate (465, 587) e propone la porta 2525.

Su un utente diverso da root (per esempio ubuntu su Oracle) uscite e rientrate con SSH perché il gruppo docker valga anche per voi; docker ps deve rispondere senza errori.

6. Configurare e salvare le chiavi

deploy/nova.sh init --domain psa.vostraazienda.it --email it@vostraazienda.it

Lo script crea deploy/.env (leggibile solo dal vostro utente), genera tutte le password e i segreti e crea la chiave per cifrare i backup in deploy/secrets/backup.agekey. Rilanciato, non cambia mai i valori già presenti.

Subito dopo, salvate nel gestore di password:

cat deploy/secrets/backup.agekey          # tutto il contenuto, righe con # comprese
grep '^APP_ENCRYPTION_KEY=' deploy/.env
cat deploy/.env                            # consigliato: tutta la configurazione

• Senza la chiave privata dei backup i backup non si possono aprire.
• Senza APP_ENCRYPTION_KEY, dopo un ripristino la verifica in due passaggi e le password delle caselle di posta non si possono più leggere.
• Aggiornate la copia ogni volta che modificate deploy/.env. Non mandate mai queste chiavi per email o in chat.

AI (facoltativa): per attivarla scrivete in deploy/.env la chiave di almeno un fornitore (ANTHROPIC_API_KEY=, OPENAI_API_KEY= o GEMINI_API_KEY=, senza spazi dopo =). Conviene impostare anche un limite di spesa nella console del fornitore. Si può fare anche dopo: ogni modifica a deploy/.env si applica con deploy/nova.sh up.

7. Avviare

deploy/nova.sh up

Lo script controlla la memoria, costruisce l'immagine (la prima volta 10-15 minuti), avvia il database, applica le migrazioni dello schema, poi avvia l'app, il processo della posta e Caddy, e aspetta che l'app risponda.

Verifiche:

• deploy/nova.sh status: app, worker e db healthy, caddy running, migrate exited (normale: ha finito).
• https://psa.vostraazienda.it mostra il lucchetto e la pagina di accesso (Codice azienda, Email, Password).
• https://psa.vostraazienda.it/api/health risponde {"status":"ok"}.

Se il certificato HTTPS non arriva: aspettate 2-3 minuti; controllate il DNS e le porte 80/443 (anche con sudo deploy/setup-host.sh --firewall-only); leggete deploy/nova.sh logs caddy (certificate obtained successfully vuol dire che è a posto). Dopo la correzione deploy/nova.sh up fa ripartire subito la richiesta. Troppi tentativi falliti di fila fanno bloccare Let's Encrypt per circa un'ora.

8. Attivare la prima azienda

Ogni azienda ha un codice azienda da 3 a 40 caratteri tra lettere minuscole, cifre e trattini:

deploy/nova.sh tenant-create --name "Rossi Software Srl" --slug rossi \
  --admin-email anna.rossi@rossisoftware.it --admin-name "Anna Rossi"

Il comando crea l'azienda, i sette ruoli predefiniti, la coda Assistenza (prefisso dei ticket TCK) e l'invito per il primo amministratore, e stampa il link di invito (https://psa.vostraazienda.it/invite/...), valido 7 giorni e una sola volta. Mandatelo all'amministratore con un canale sicuro: Orafila non lo invia per email.

Opzioni utili:

L'amministratore apre il link, sceglie la password (almeno 12 caratteri), accede con codice azienda, email e password e attiva la verifica in due passaggi. Da lì prosegue con Avvio e configurazione.

Dati di esempio (facoltativi, per una demo o per la formazione): deploy/nova.sh sample-data --slug rossi riempie tutte le schermate con dati inventati e riconoscibili (codici ESEMPIO-..., indirizzi @esempio.example, due anni di storia); deploy/nova.sh sample-data --slug rossi --remove li toglie senza toccare i dati reali. Toglieteli prima di lavorare con i clienti veri.

9. Configurare i backup

1. Create un bucket privato compatibile S3 (Oracle Object Storage, DigitalOcean Spaces o altro) e una chiave di accesso limitata a quel bucket. Su Oracle aggiungete una regola di conservazione che impedisce di cancellare i file per 29 giorni.
2. Compilate in deploy/.env BACKUP_RCLONE_REMOTE e le righe RCLONE_CONFIG_... del vostro archivio (il modello deploy/env.example ha i blocchi già pronti per Oracle e DigitalOcean).
3. Primo backup di prova: deploy/nova.sh backup (crea il backup, lo verifica decifrandolo, lo copia nel bucket). deploy/nova.sh backups elenca i backup locali e remoti.
4. Backup automatico ogni notte alle 02:30: deploy/nova.sh install-timer (controllo con systemctl list-timers nova-backup.timer).
5. Consigliato: un controllo su Healthchecks.io (periodo 1 giorno, tolleranza 2 ore) con l'indirizzo in BACKUP_PING_URL: se il backup di una notte non arriva o fallisce, arriva un'email.

10. Controllo esterno e prova di ripristino

• Create un controllo di disponibilità (uptime) HTTPS su https://psa.vostraazienda.it/api/health ogni 5 minuti, con avviso via email: il server non può avvisarvi se è spento.
• Provate subito il ripristino, non il giorno del bisogno: deploy/nova.sh restore nova-AAAAMMGGTHHMMSSZ.dump.age --yes (fa prima un backup di sicurezza). La ricostruzione completa su un server nuovo (pacchetto, deploy/.env e chiavi dal gestore di password, ripristino dal bucket) è descritta nelle guide dei fornitori. Vedi anche Gestione e manutenzione.

11. Database esterno (facoltativo)

Di solito PostgreSQL gira in un contenitore sullo stesso server. Per un database gestito (alta disponibilità, backup e ripristino a un momento preciso del fornitore) o un server PostgreSQL dell'azienda:

1. Dopo deploy/nova.sh init, copiate il certificato CA del fornitore in deploy/db-ca.crt.
2. Compilate in deploy/.env:

   NOVA_DB_HOST=nome-del-server-del-database
   NOVA_DB_PORT=5432            # 25060 su DigitalOcean
   NOVA_DB_NAME=nova
   NOVA_DB_SSLMODE=verify-full  # oppure verify-ca; altri valori sono rifiutati
   NOVA_DB_CA_FILE=./db-ca.crt  # vuoto = autorità pubbliche, solo con verify-full
   

3. deploy/nova.sh db-setup: chiede le credenziali di un amministratore del database (non le salva) e crea i ruoli nova_owner, nova_app, nova_app_user, il database e, se il fornitore lo permette, nova_backup per i backup. Le password arrivano al database come verificatori SCRAM, mai in chiaro.
4. deploy/nova.sh up: controlla il collegamento, ferma il database interno (il suo volume resta) e applica le migrazioni sul database esterno.

Da quel momento backup, ripristino, aggiornamenti e strumenti lavorano sul database esterno. Per spostare i dati di un'installazione già avviata si fa un backup prima di compilare NOVA_DB_HOST, poi db-setup, restore e up. Tutti i dettagli, i problemi frequenti e la lista di sicurezza sono nella guida Database esterno.

12. Avvio di prova su un computer (senza Docker)

Per una valutazione tecnica o per lo sviluppo, su Linux o macOS con Node.js 22.18 o successivo e PostgreSQL 15 o successivo:

cd orafila
npm install
cp .env.example .env.local                  # poi compilate le variabili (vedi sotto)
sudo -u postgres scripts/setup-dev-db.sh    # ruoli nova_owner, nova_app, nova_app_user e database nova_dev
npm run db:migrate
npm run db:seed                             # dati dimostrativi: aziende "demo" e "altra"
npm run build && npm start                  # in un altro terminale: npm run mail:worker

Accesso dimostrativo su http://localhost:3000: azienda demo, email responsabile@demo.example (amministratore), password Demo-Orafila-2026!; altri ruoli con commerciale@, amministrazione@, magazzino@, marco.galli@ (tecnico), tutti @demo.example. Queste credenziali sono pubbliche e valgono solo per la prova in locale: non usate mai db:seed su un'installazione reale.

13. Riferimento: configurazione del server (deploy/.env)

Formato: una riga CHIAVE=valore, senza spazi intorno a =, commenti su righe proprie; un valore con $ va tra apici singoli.

Per un'installazione senza il pacchetto (avvio in locale o altra piattaforma) l'app legge: DATABASE_URL (ruolo applicativo, soggetto all'isolamento), ADMIN_DATABASE_URL (proprietario, solo per migrazioni e strumenti), APP_ENCRYPTION_KEY, INBOUND_EMAIL_SECRET, APP_BASE_URL (indirizzo pubblico per i link di invito), TRUST_PROXY=1 solo dietro un proxy che imposta X-Forwarded-For, le chiavi AI e, con un database con TLS, ?sslmode=verify-full&sslrootcert=/percorso/ca.crt nell'indirizzo più NOVA_DB_REQUIRE_VERIFIED_TLS=1.

14. Riferimento: comandi di deploy/nova.sh

Mai usare docker compose down -v, docker volume rm o docker system prune --volumes: cancellano il database.