Installare ERPNext su Ubuntu 22.04: guida passo passo

Installare ERPNext su Ubuntu 22.04 senza improvvisare

ERPNext su Ubuntu 22.04 si installa in modo pulito solo se si tiene separato il piano applicativo da quello di sistema: utente dedicato, servizi controllati da systemd, database locale, Redis locale e Nginx come reverse proxy. La scelta più sensata in produzione è evitare installazioni “creative” dentro l’utente root o dentro ambienti già sovraccarichi di stack web non coerenti. Qui la logica è semplice: prima si prepara il sistema, poi si crea il bench, poi si verifica che i servizi rispondano davvero, non solo che il comando di installazione sia finito senza errori.

La versione di Ubuntu conta perché 22.04 porta con sé una combinazione abbastanza stabile di kernel, systemd e librerie, ma non basta per ERPNext: servono versioni compatibili di Python, Node.js, MariaDB, Redis e strumenti di build. Il punto critico non è “far partire qualcosa”, ma evitare che il primo aggiornamento rompa dipendenze o permessi. Per questo conviene lavorare con una sequenza rigida e verificabile, usando sempre comandi che permettano di capire dove si ferma il processo.

Prerequisiti reali: cosa deve esserci prima di iniziare

Assumo un server Ubuntu 22.04 aggiornato, accesso sudo e un hostname già definito. ERPNext non è un’app da installare su un nodo già carico di altri servizi critici senza valutare conflitti su porte, RAM e policy di aggiornamento. Se il server è piccolo, il collo di bottiglia iniziale è quasi sempre la memoria: durante build e migrazioni il sistema può andare in swap o terminare processi. Su macchine da test, almeno 4 GB di RAM sono il minimo pratico; in produzione, meglio ragionare su margine extra e monitoraggio.

Prima di toccare i pacchetti, conviene verificare stato base e aggiornare l’indice. Questo passaggio non risolve i problemi di ERPNext, ma riduce il rumore quando qualcosa va storto.

sudo apt update
sudo apt -y upgrade
sudo reboot

Dopo il reboot, controlla che il sistema sia davvero tornato su e che non ci siano errori di boot o filesystem. Un check veloce è utile prima di iniziare a installare dipendenze pesanti.

systemctl --failed
free -h
df -h
uname -a

Se `systemctl --failed` mostra unità in errore, fermati: una base instabile rende impossibile distinguere un problema del sistema da un problema dell’applicazione. Se `df -h` mostra partizioni quasi piene, libera spazio prima di procedere; build, log e cache di npm/pip consumano più spazio di quanto molti prevedano.

Pacchetti di sistema e dipendenze: la base che evita errori ambigui

ERPNext dipende da librerie e strumenti che vanno installati in modo coerente. La sequenza sotto è quella che in genere evita la maggior parte degli errori di compilazione e runtime. Non serve inventarsi varianti finché non c’è un vincolo preciso di ambiente.

sudo apt install -y \
  git curl build-essential python3-dev python3-setuptools python3-venv \
  software-properties-common mariadb-server mariadb-client redis-server \
  nginx xvfb fontconfig libfontconfig1 libxrender1 libxext6 \
  libjpeg-dev liblcms2-dev libblas-dev libatlas-base-dev \
  wkhtmltopdf

Su Ubuntu 22.04 il pacchetto `wkhtmltopdf` dai repository standard può non essere quello più adatto a tutti i casi d’uso, perché la resa dei PDF in ERPNext dipende da una build compatibile con le librerie grafiche presenti. Se i report PDF risultano vuoti o con rendering errato, il problema spesso è lì. In quel caso va verificata la versione installata con `wkhtmltopdf --version` e, se necessario, sostituita con una build coerente con la piattaforma. Non è un dettaglio estetico: fatture, preventivi e stampe amministrative dipendono da questo componente.

Verifica subito i servizi database e cache, perché più avanti li userai come prerequisito per il bench.

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

Se uno dei due non parte, non andare avanti a tentativi. Leggi i log con `journalctl -u mariadb -n 100 --no-pager` o `journalctl -u redis-server -n 100 --no-pager` e risolvi prima il problema di base. Installare ERPNext sopra un database rotto produce solo diagnosi confuse.

MariaDB: impostazione corretta prima dell’installazione di ERPNext

ERPNext usa MariaDB come backend principale e una configurazione troppo “default” può creare problemi già durante la fase di migrazione. La cosa da fare è impostare alcuni parametri che riducono gli errori su charset, dimensione dei campi e compatibilità SQL. Il punto non è ottimizzare al millimetro, ma evitare errori noti al primo bootstrap.

Apri il file di configurazione di MariaDB, in genere ` /etc/mysql/mariadb.conf.d/50-server.cnf`, e verifica che la sezione `mysqld` includa impostazioni compatibili. Se hai già un database in uso, fai prima un backup del file.

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

Inserisci o verifica almeno questi parametri sotto `[mysqld]`.

character-set-server = utf8mb4
collation-server = utf8mb4_unicode_ci
innodb-file-format = Barracuda
innodb-file-per-table = 1
innodb-large-prefix = 1

Dopo la modifica riavvia il servizio e verifica che non ci siano errori di sintassi o di startup.

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

Se vuoi fare un controllo più concreto, entra nella shell MySQL e verifica charset e versioni. Qui l’obiettivo è confermare che non stai lavorando con valori incompatibili.

sudo mysql -e "SHOW VARIABLES LIKE 'character_set_server'; SHOW VARIABLES LIKE 'collation_server'; SELECT VERSION();"

Un errore frequente è lasciare attiva una configurazione vecchia con SQL mode troppo restrittiva o con charset non coerente. Se durante le migrazioni compaiono errori su campi `varchar` o su indici troppo lunghi, la causa è spesso qui. Meglio sistemarlo prima, non dopo il primo fallimento.

Utente dedicato, Node.js e bench: il cuore dell’installazione

ERPNext viene gestito bene quando vive sotto un utente non privilegiato, tipicamente `frappe`. Questo riduce il rischio operativo e rende più semplice controllare permessi e aggiornamenti. L’installazione si appoggia al tool `bench`, che orchestra app Frappe, ERPNext, asset statici, processi e migrazioni. Il punto importante è non mischiare più ambienti Python o più versioni di Node senza un motivo preciso.

Crea l’utente e preparati a usarlo come contesto operativo.

sudo adduser frappe
sudo usermod -aG sudo frappe
su - frappe

Installa Node.js in una versione compatibile con la release di ERPNext che intendi usare. La compatibilità cambia nel tempo, quindi il punto serio è verificare la matrice ufficiale della versione che stai deployando. Se questo dato manca, non inventare: chiudilo consultando la documentazione del ramo specifico prima di procedere. In assenza di un vincolo noto, un setup recente e stabile di Node LTS è la scelta più prudente, ma va confermata rispetto alla release target.

Installa anche `yarn` se richiesto dal ramo che stai usando. In molti casi il flusso attuale si regge su `npm` e `yarn` per il build degli asset. Se il comando di build fallisce con errori sulle dipendenze frontend, non è raro che la causa sia una versione non allineata di Node o un cache corrotto.

A questo punto installa `bench` e inizializza il workspace. Il percorso classico è dentro la home dell’utente dedicato, in una directory separata per il sito o per i siti gestiti.

python3 -m venv env
source env/bin/activate
pip install --upgrade pip
pip install frappe-bench
bench --version

Crea il bench e inizializza il progetto. Il nome del sito va scelto con criterio, perché finirà in configurazioni, path e spesso nel certificato TLS.

bench init frappe-bench --frappe-branch version-14

Il branch può cambiare in base alla versione che vuoi installare. Qui il controllo da fare è semplice: il branch di Frappe e quello di ERPNext devono essere compatibili tra loro. Un mismatch qui produce errori più avanti, spesso durante `bench migrate` o `bench build`. Se hai un dubbio sulla versione, fermati e verifica la tabella di compatibilità del ramo che stai usando.

Creazione del sito, installazione di ERPNext e provisioning iniziale

Una volta creato il bench, si passa al sito vero e proprio. Questa fase è quella in cui molti confondono “installazione del framework” con “installazione dell’applicazione”. In realtà sono due passaggi distinti: prima il sito, poi l’app ERPNext dentro il sito.

cd frappe-bench
bench new-site erp.example.local

Il comando chiederà la password di MariaDB e la password dell’utente `Administrator` del sito. Qui non usare credenziali deboli e soprattutto non lasciare segreti in chiaro dentro file condivisi. Se stai documentando il processo, redigi i valori sensibili e conserva le password in un vault o in un password manager, non in note operative sparse.

Dopo la creazione del sito, installa ERPNext come app.

bench get-app erpnext --branch version-14
bench --site erp.example.local install-app erpnext

Se il download o l’installazione falliscono, controlla subito tre cose: connettività al repository, branch compatibile e stato del database. Non è raro che un errore riportato come generico sia in realtà un problema di permessi nella directory del bench o un conflitto di dipendenze Python. In quel caso il controllo utile è `ls -ld ~/frappe-bench`, `whoami` e l’output completo di `bench` nella parte finale del log.

Per una prima verifica funzionale, avvia il server di sviluppo solo come test locale, non come soluzione definitiva.

bench start

Se il processo si avvia e i log mostrano worker, socket e web server interni attivi, il core è coerente. Se invece vedi errori su Redis, database o build asset, fermati e correggi la causa prima di passare a Nginx e systemd. Il vantaggio di questo passaggio è che isola la parte applicativa dal layer web esterno.

Nginx e systemd: portare ERPNext fuori dalla shell

Una volta validato il bench, il passo corretto è renderlo un servizio gestito dal sistema. In pratica si usano i comandi di setup del bench per generare unità systemd e configurazione Nginx. Questo evita di tenere processi aperti in una shell manuale e rende possibile restart, logging e avvio automatico al boot.

sudo bench setup production frappe

Il comando crea o aggiorna i servizi necessari. Dopo l’esecuzione, controlla che le unità siano attive e che Nginx abbia caricato la configurazione senza errori. I log da leggere sono quelli del sistema, non solo quelli dell’app.

systemctl status nginx --no-pager
systemctl status supervisor --no-pager
journalctl -u nginx -n 50 --no-pager

Se usi `supervisor` o il meccanismo di process management previsto dal bench, verifica che i processi ERPNext siano presenti e stabili. L’errore classico qui è credere che il sito sia online perché Nginx risponde, mentre dietro i worker Python sono in crash loop. La risposta HTTP da sola non basta: serve anche il controllo dei processi applicativi.

Per il reverse proxy, controlla che il server block punti al socket corretto e che il dominio sia coerente con il nome del sito. Un mismatch tra hostname e configurazione genera errori apparentemente casuali, soprattutto se ci sono più siti sullo stesso host. La verifica minima è aprire il file generato in ` /etc/nginx/sites-enabled/` e confrontare `server_name`, upstream e path ai socket.

sudo nginx -t
sudo systemctl reload nginx

TLS, dominio e accesso: la parte che spesso viene lasciata a metà

ERPNext va esposto con HTTPS. Se il sito resta in HTTP, il rischio non è solo di sicurezza: alcune integrazioni, login e redirect si comportano male. Se il dominio è pubblico, il certificato va emesso dopo aver confermato che il DNS punta all’IP corretto e che la porta 80/443 è raggiungibile. Se il dominio è interno o in fase di test, puoi usare un certificato temporaneo o un reverse proxy interno, ma la logica resta la stessa: prima DNS, poi web server, poi TLS.

Se usi Let’s Encrypt, verifica che il record A o AAAA sia corretto e che non ci siano proxy o CDN che bloccano la validazione. Il check più rapido è un `dig` o `nslookup` da una macchina esterna alla rete del server.

dig erp.example.com A +short
curl -I http://erp.example.com

Se `curl -I` non restituisce un redirect coerente verso HTTPS o mostra un errore di connessione, il problema non è ERPNext ma il layer di front-end. In quel caso controlla Nginx e firewall prima di toccare l’applicazione.

Quando il certificato è pronto, verifica la catena e il rinnovo automatico. Un’installazione buona ma senza rinnovo è solo un problema rimandato.

sudo certbot certificates
sudo systemctl status certbot.timer --no-pager

Verifiche finali: capire se il sistema è davvero sano

Il controllo finale non è “la home si apre”, ma una piccola batteria di prove che copre front-end, backend e database. Solo così distingui un deploy riuscito da un’installazione che sembra viva ma si rompe al primo click.

1. Apri il sito via browser e verifica che il login mostri la pagina corretta, non una pagina bianca o un errore 502.
2. Esegui `curl -I https://erp.example.com` e conferma uno status 200 o 302 coerente con il redirect previsto.
3. Controlla i log applicativi in `~/frappe-bench/logs/` e quelli di Nginx per cercare errori immediati su asset, socket o permessi.
4. Verifica che `bench --site erp.example.local console` apra la shell interattiva senza errori di connessione al database.

cd ~/frappe-bench
bench --site erp.example.local console

Se la console si apre, il database è raggiungibile e il sito è registrato correttamente. Se fallisce, il problema è quasi sempre in MariaDB, credenziali del sito o path del bench. In quel caso la risoluzione passa dalla lettura del log specifico, non dal riavvio casuale dei servizi.

Un altro controllo utile è il consumo di risorse dopo il primo avvio. ERPNext può andare bene su un server medio, ma se memoria e CPU restano costantemente alte già a sistema fermo, significa che qualcosa non è dimensionato o che un worker è in loop. Con `htop`, `top`, `free -h` e `journalctl` puoi capire rapidamente se sei di fronte a saturazione, crash ripetuti o semplicemente picchi normali di bootstrap.

Errori tipici e come leggerli senza perdere tempo

Tre errori si vedono spesso. Il primo è il 502 da Nginx: in quel caso il problema è quasi sempre a valle, cioè processi ERPNext non attivi, socket errato o worker in crash. Il secondo è il fallimento delle migrazioni: qui guardi prima compatibilità versioni, poi schema database, poi permessi. Il terzo è l’assenza di asset o pagine rotte dopo il login: spesso è un build frontend incompleto o una cache non allineata.

Quando manca un dato, non si deve inventare. Se non sai quale versione di ERPNext installare, chiudi il gap leggendo il branch target nel repository o nella documentazione della release. Se non sai perché un comando fallisce, chiudi il gap con il log completo di `bench`, `journalctl` o del browser console. Questo approccio fa risparmiare ore rispetto al classico “provo un altro restart”.

In un’installazione fatta bene, la differenza la fanno i dettagli: compatibilità tra branch, charset del database, permessi dell’utente dedicato, processi gestiti dal sistema e TLS corretto. ERPNext non è difficile da installare, ma è facile da installare male. Se segui una sequenza controllata e verifichi ogni layer, arrivi a un ambiente che si mantiene meglio nel tempo e si rompe meno al primo aggiornamento.