Installare ERPNext 15 su Ubuntu 24.04 LTS passo passo

ERPNext 15 su Ubuntu 24.04 LTS funziona bene se l’installazione viene impostata con disciplina: utente dedicato, dipendenze corrette, database già dimensionato e servizi controllati prima di esporre il sito. Il punto non è solo “far partire Frappe”, ma evitare i classici problemi da ambiente incompleto: conflitti su Python, Redis non raggiungibile, MariaDB con parametri inadatti, Nginx configurato in fretta e certificati sistemati dopo.

Qui trovi un percorso lineare per una installazione pulita di ERPNext 15 su Ubuntu 24.04 LTS, con comandi ripetibili e verifiche pratiche a ogni passaggio. L’obiettivo è arrivare a un’istanza funzionante, con servizi supervisionati da systemd, reverse proxy Nginx e una base che si possa mantenere senza interventi fragili.

Scelta dell’architettura prima di installare

ERPNext non è un singolo demone: il front-end passa da Nginx, l’applicazione gira tramite bench/gunicorn, i job asincroni dipendono da Redis, il database è MariaDB. Se uno di questi pezzi è “quasi giusto”, l’installazione sembra avanzare ma poi si rompe in punti poco intuitivi. Su Ubuntu 24.04 conviene partire con una macchina pulita, senza stack web già invasivi, e con almeno 4 CPU, 8 GB di RAM e disco SSD; per ambienti con più utenti o più siti, meglio salire da subito.

La strada più robusta è usare il framework ufficiale Frappe Bench, non tentare installazioni manuali sparse tra venv, servizi custom e file copiati a mano. Bench standardizza la struttura dei siti, le app e i processi. In pratica riduce l’area di errore e rende anche il troubleshooting più veloce, perché sai dove cercare: directory `frappe-bench`, log di bench, servizio Nginx, servizio Redis, stato di MariaDB.

1. Aggiornare il sistema e preparare i pacchetti base

Parti sempre da sistema aggiornato. In produzione è un’abitudine banale, ma evita di mescolare dipendenze vecchie con componenti nuovi. Esegui gli aggiornamenti di base e installa gli strumenti che servono per compilare moduli, clonare repository e gestire servizi.

sudo apt update
sudo apt -y upgrade
sudo apt -y install git curl vim sudo software-properties-common build-essential python3-dev python3-venv python3-pip \
  libffi-dev libssl-dev libjpeg-dev zlib1g-dev liblcms2-dev libblas-dev liblapack-dev \
  libpq-dev pkg-config redis-server mariadb-server mariadb-client nginx supervisor

Dopo l’installazione, verifica che i servizi essenziali non siano in errore:

systemctl status mariadb --no-pager
systemctl status redis-server --no-pager
systemctl status nginx --no-pager

Se uno dei tre non è attivo, fermati qui. ERPNext non va “aggiustato sopra” a un database o a Redis già instabili.

2. Creare l’utente dedicato e separare i privilegi

Non installare ERPNext come root. La sessione di lavoro deve appartenere a un utente dedicato, ad esempio `frappe`, con sudo limitato alle operazioni amministrative. Questo riduce il rischio di permessi sbagliati in `sites/`, file di log e directory cache.

sudo adduser frappe
sudo usermod -aG sudo frappe

Accedi come `frappe` e verifica il contesto:

su - frappe
whoami
id

L’output atteso è `frappe` come utente attivo e il gruppo `sudo` presente tra i gruppi secondari. Se non c’è, correggi prima di andare avanti.

3. Configurare MariaDB per ERPNext 15

ERPNext è sensibile alla configurazione del database. Con MariaDB troppo “standard” puoi trovarti errori su indici, charset o limiti di pacchetti. Conviene impostare subito i parametri richiesti dal framework e usare `utf8mb4`.

Apri il file di configurazione di MariaDB, di solito ` /etc/mysql/mariadb.conf.d/50-server.cnf`, e controlla che nella sezione `[mysqld]` ci siano impostazioni coerenti con Frappe.

sudo cp /etc/mysql/mariadb.conf.d/50-server.cnf /etc/mysql/mariadb.conf.d/50-server.cnf.bak
sudo nano /etc/mysql/mariadb.conf.d/50-server.cnf

Aggiungi o verifica almeno queste direttive:

[mysqld]
character-set-server = utf8mb4
collation-server = utf8mb4_unicode_ci
innodb-file-format = Barracuda
innodb-file-per-table = 1
innodb-large-prefix = 1
max_connections = 100

Riavvia MariaDB e controlla lo stato:

sudo systemctl restart mariadb
sudo systemctl status mariadb --no-pager

Se il servizio non riparte, guarda il log con:

sudo journalctl -u mariadb -n 50 --no-pager

In questa fase il controllo utile è semplice: MariaDB deve essere attivo e rispondere a query locali. Se vuoi una verifica rapida, usa `mysqladmin ping`.

mysqladmin ping -u root -p

4. Installare Node.js, Yarn e i prerequisiti per il frontend

ERPNext 15 usa componenti frontend che richiedono Node.js e Yarn. Su Ubuntu 24.04 è meglio evitare versioni casuali prese dai repository terzi senza controllo. Usa una versione supportata dal progetto Frappe al momento dell’installazione; se il tuo standard interno impone una versione specifica, verifica sempre la compatibilità con la release di ERPNext che stai deployando.

Un approccio pratico è installare Node LTS e Yarn tramite repository ufficiali o tramite il meccanismo consigliato dalla documentazione corrente di Frappe. Se non hai una policy interna già definita, il punto da non saltare è la verifica finale delle versioni.

node -v
npm -v
yarn -v

Se il comando `yarn` non esiste o la versione di Node è fuori range, correggi subito. Molti errori durante `bench build` derivano da qui e non da ERPNext in sé.

5. Installare Bench e creare l’ambiente Frappe

Con l’utente `frappe` attivo, installa Bench e prepara la struttura del progetto. L’idea è avere una directory chiara, separata dal resto del sistema, in cui vivono app, siti, log e ambienti Python.

sudo -H pip3 install frappe-bench
bench --version

Crea il bench con la versione corretta del ramo Frappe per ERPNext 15. In pratica devi allineare il branch del framework al branch dell’app ERPNext. Se i branch non combaciano, l’istanza può installarsi ma poi fallire in migrazione o nel caricamento moduli.

bench init frappe-bench --frappe-branch version-15
cd frappe-bench

Verifica che la struttura sia presente:

ls -la
ls -la apps

Se `bench init` fallisce, il controllo da fare subito è la versione di Python, i pacchetti di compilazione e l’accesso in rete ai repository Git. Meglio correggere ora che dopo aver creato mezze directory.

6. Scaricare ERPNext 15 e collegarlo al bench

ERPNext va aggiunto come app separata dentro il bench. Anche qui il branch deve essere quello giusto per la major release 15.

bench get-app erpnext --branch version-15 https://github.com/frappe/erpnext
bench --site site1.local install-app erpnext

Prima di installare l’app sul sito, devi creare il sito Frappe. Il nome `site1.local` è un esempio: in un ambiente reale usa un FQDN coerente con DNS e certificati, oppure un hostname interno se stai ancora testando.

bench new-site site1.local

Durante la creazione del sito ti verrà richiesta la password root di MariaDB e la password dell’amministratore del sito. Non riutilizzare password deboli; se devi passare valori in automazione, usa variabili d’ambiente o vault, non testo in chiaro in uno script condiviso.

7. Installare l’app e fare la prima migrazione

Una volta creato il sito, installa ERPNext e lancia la migrazione iniziale. La migrazione costruisce tabelle, campi, configurazioni e parte dei dati di base. È il momento in cui emergono incompatibilità di versione, dipendenze mancanti o problemi di permessi.

bench --site site1.local install-app erpnext
bench --site site1.local migrate

Se la migrazione si ferma, non andare a tentativi. Guarda i log del sito e del processo bench. I punti utili sono `logs/`, il terminale da cui hai lanciato il comando e gli errori Python con traceback completo. La causa più comune, in questa fase, è una combinazione di branch errato, dipendenza mancante o database non conforme.

8. Avviare i servizi e impostare l’esposizione web

ERPNext in sviluppo può girare con `bench start`, ma per un server vero ti serve la modalità supervisionata. Bench può generare configurazioni per Nginx e Supervisor, così i processi restano gestiti dal sistema e ripartono con il boot.

sudo bench setup nginx
sudo bench setup supervisor
sudo ln -s /home/frappe/frappe-bench/config/nginx.conf /etc/nginx/conf.d/frappe-bench.conf
sudo nginx -t
sudo systemctl reload nginx
sudo supervisorctl status

Il test di Nginx deve restituire sintassi OK. Se `nginx -t` fallisce, non fare reload. Correggi prima il file generato o eventuali conflitti con altri virtual host già presenti sul server.

Per verificare che l’app risponda, usa un `curl` locale o remoto sul nome configurato nel sito:

curl -I http://site1.local

In un’installazione sana dovresti vedere un codice HTTP valido, tipicamente `200` o un redirect iniziale verso login o setup. Se ottieni `502`, il problema è quasi sempre nel backend bench/gunicorn o in un disallineamento tra Nginx e il socket applicativo.

9. SSL/TLS con Let’s Encrypt o certificato aziendale

Se il sito deve essere pubblico, il TLS non è un optional. Con ERPNext conviene attivarlo appena il virtual host è stabile, non dopo settimane di uso. Se usi Let’s Encrypt, assicurati che il DNS punti già al server e che la porta 80 sia raggiungibile per la challenge.

sudo bench setup lets-encrypt site1.local

Se invece hai un certificato aziendale, inserisci i file nel vhost Nginx generato da bench o in uno snippet dedicato, senza sovrascrivere a mano tutto il file se vuoi mantenere aggiornabile l’impianto. Dopo la modifica, valida sempre la sintassi e ricarica Nginx.

sudo nginx -t
sudo systemctl reload nginx

10. Hardening minimo e manutenzione operativa

Una volta online, l’installazione va trattata come servizio critico. Le misure minime non sono complicate: backup del database e dei file `sites/`, aggiornamenti controllati, accesso SSH solo per chi serve, e monitoraggio di spazio disco, RAM e stato dei servizi. ERPNext soffre molto più di altri stack quando il disco si riempie o Redis inizia a swapparsi.

Per un controllo rapido, tieni sott’occhio questi punti:

df -h
free -m
systemctl status mariadb redis-server nginx supervisor --no-pager

Programma backup coerenti con il volume dati. Al minimo: dump MariaDB, archivio della directory `sites/`, e copia delle app custom se ne usi. Se fai restore, testa il ripristino su una macchina separata: il backup non vale nulla se non sai reintegrarlo.

Errori tipici e come leggerli senza perdere tempo

Alcuni sintomi si ripetono quasi sempre. Un `502 Bad Gateway` davanti a Nginx indica che il reverse proxy non riesce a parlare con il backend: controlla `supervisorctl status`, i log di bench e l’esistenza del socket o del processo gunicorn. Una pagina bianca o un errore in login spesso punta a migrazione incompleta, cache corrotte o app non installata correttamente sul sito. Un errore SQL su charset o index length rimanda invece a MariaDB non allineato alle richieste di ERPNext.

Quando il problema non è immediato, il metodo migliore è ridurre il campo: verifica layer per layer, dall’esterno verso l’interno. DNS risolve? Nginx risponde? Il sito esiste in bench? MariaDB accetta connessioni? I log mostrano un traceback concreto? Questa sequenza ti evita di perdere ore a toccare parametri casuali.

Controllo finale dell’installazione

Prima di considerare chiusa l’installazione, esegui un giro di verifica minimale ma reale. Non basta vedere la home page: devi confermare che il sito sia attivo, che i processi siano vivi e che l’utente amministratore possa entrare senza errori di backend.

bench --site site1.local doctor
sudo supervisorctl status
sudo systemctl status nginx mariadb redis-server --no-pager

Se `bench doctor` segnala problemi, prendilo sul serio: spesso indica dipendenze assenti, servizi non raggiungibili o configurazioni incoerenti. L’obiettivo non è “far comparire il portale”, ma lasciare un’istanza mantenibile, ripetibile e pronta per il lavoro quotidiano.

Assunzione operativa: i comandi e i branch indicati vanno verificati contro la release corrente di Frappe/ERPNext che stai installando, perché il supporto delle versioni può cambiare; prima di intervenire su un server di produzione, prova sempre su una VM identica o su uno staging con lo stesso sistema operativo e gli stessi pacchetti.