SSD Nodes Learn Hosting plans →
Guide Matt ConnorDi Matt Connor

ERPNext su VPS con Docker: guida al self-hosting

Guida a ERPNext su VPS con Docker: dimensionamento, stack da undici container, TLS, email in uscita, versioni bloccate e ripristino dei backup verificato.

Cosa comporta questa configurazione

Gestire ERPNext in modalità self-hosted su un VPS è un'attività operativa, non un'installazione eseguibile con un solo comando. Lo stack Docker Compose ufficiale contiene undici container e gestisce il libro mastro e i dati dei clienti. Questo innalza il livello di attenzione richiesto per tutto ciò che segue: un backup non è un backup finché non ne hai verificato il ripristino, e un tag di immagine non fissato a una versione specifica può causare una migrazione dello schema.

Nel testo ricorrono alcuni nomi. ERPNext è l'applicazione gestionale. Frappe è il framework Python sottostante. Bench è lo strumento da riga di comando che gestisce i siti ed è già installato nei container. Un site è un tenant: un database MariaDB e una directory contenente i file caricati. Quasi tutti i comandi riportati qui vengono eseguiti bench all'interno del container backend, operando su un site specifico.

Questa guida usa il repository frappe_docker, che contiene la distribuzione gestita dal progetto. Tutti i comandi riportati di seguito sono stati verificati rispetto a quel repository nell'agosto 2026. Se Docker Compose è una novità, eseguire Docker Compose su un VPS tratta i prerequisiti dati per acquisiti da questa guida.

Di quanta capacità VPS ha bisogno ERPNext?

GraficoERPNext sizing starting points (guidance, not a measurement)
I dati alla base di questo grafico
[
  {
    "label": "Evaluation",
    "vcpu": 2,
    "ram_gb": 4,
    "disk_gb": 40
  },
  {
    "label": "Small production",
    "vcpu": 4,
    "ram_gb": 8,
    "disk_gb": 100
  },
  {
    "label": "Room to grow",
    "vcpu": 4,
    "ram_gb": 16,
    "disk_gb": 160
  }
]

Per la valutazione, iniziate con 2 vCPU e 4 GB di RAM. Questo è il livello di valutazione. Sono valori di partenza, non misurazioni ricavate da questa guida, e il numero effettivo dipende dal volume dei documenti. L'ultima riga non rappresenta affatto un requisito minimo pubblicato. Offre più margine di memoria, ma non garantisce che la memoria non si esaurisca mai.

Valutate con realismo i piani più piccoli. Un VPS da 1 GB o 2 GB lascia poco margine per dieci container a esecuzione prolungata, il buffer pool di MariaDB e un worker Python che genera un report. Quando la memoria è sotto pressione, il kernel out-of-memory killer può arrestare un container e docker inspect mostra quindi "OOMKilled": true con codice di uscita 137. Se un worker viene arrestato durante l'elaborazione, un documento inviato può rimanere con il relativo lavoro in background completato solo parzialmente.

Per un'azienda che usa ERPNext ogni giorno, iniziate a pianificare intorno a 8 GB di RAM, 4 vCPU e 100 GB di SSD, quindi testate il vostro carico di lavoro. La RAM si esaurisce per prima. Il disco cresce più rapidamente di quanto ci si aspetti, perché ogni allegato e ogni backup locale viene scritto sullo stesso volume del database.

Gli undici container e il ruolo di ciascuno

Esegui docker compose ps dopo che lo stack è attivo e dieci container sono in esecuzione. Un altro container, configurator, esegue il proprio lavoro una volta sola e poi termina. Da qui deriva il totale di undici container.

  • backend esegue l'applicazione Frappe tramite gunicorn. Qui si trova bench.
  • frontend è nginx. Serve gli asset statici e inoltra tutto il resto al backend.
  • queue-short e queue-long sono worker RQ (Redis Queue). Eseguono attività in background come l'invio di email, le importazioni e la generazione dei report.
  • scheduler avvia le attività basate sull'orario, inclusi i report pianificati e i documenti con ripetizione automatica.
  • websocket è il processo socket.io che gestisce gli aggiornamenti in tempo reale nel browser.
  • db è MariaDB.
  • redis-cache e redis-queue sono due istanze Redis separate: una per la cache e una per la coda dei job.
  • proxy è Traefik, aggiunto dall'override HTTPS. Gestisce le porte 80 e 443 e recupera i certificati.

Questa suddivisione è importante, perché indica quale log consultare. Un'email bloccata è un problema del worker della coda, quindi docker compose logs -f queue-short è il comando corretto. Una pagina che viene caricata ma non aggiorna mai il badge delle notifiche indica un problema websocket. Consultare i log di backend per uno di questi problemi fa solo perdere tempo.

Installare con i file Compose per la produzione, non con quelli dimostrativi

Il repository include pwd.yml e il README lo specifica chiaramente: "Questa configurazione è destinata solo a valutazioni di breve durata. Non sarà possibile installare applicazioni personalizzate in questa configurazione." Usatela per esaminare ERPNext per un pomeriggio. Non usatela per gestire l'infrastruttura IT di un'azienda.

sudo apt update && sudo apt install -y git
curl -fsSL https://get.docker.com | bash
git clone https://github.com/frappe/frappe_docker
cd frappe_docker
mkdir -p ~/gitops
cp example.env ~/gitops/erpnext.env

Aprite ~/gitops/erpnext.env e modificate quattro valori. ERPNEXT_VERSION fissa il tag dell'immagine. Nell'esempio, DB_PASSWORD è fornito come 123. SITES_RULE è la regola di routing di Traefik e LETSENCRYPT_EMAIL fornisce l'indirizzo email dell'account ACME. Let's Encrypt ha interrotto le email di notifica della scadenza il 4 giugno 2025, quindi monitorate separatamente la scadenza dei certificati.

ERPNEXT_VERSION=v16.32.1
DB_PASSWORD=<a long random password>
SITES_RULE=Host(`erp.example.com`)
LETSENCRYPT_EMAIL=ops@example.com

Ora generate un singolo file Compose, quindi avviatelo.

docker compose --project-name erpnext \
  --env-file ~/gitops/erpnext.env \
  -f compose.yaml \
  -f overrides/compose.mariadb.yaml \
  -f overrides/compose.redis.yaml \
  -f overrides/compose.https.yaml \
  config > ~/gitops/erpnext.yaml

docker compose --project-name erpnext -f ~/gitops/erpnext.yaml up -d
export COMPOSE_FILE="$HOME/gitops/erpnext.yaml"

config non avvia nulla. Unisce il file di base agli override e stampa il risultato con tutte le variabili già sostituite. Eseguite quindi il file generato. Questo passaggio aggiuntivo è utile: lo stack in esecuzione è contenuto in un unico file leggibile e non può cambiare mentre lo usate se qualcuno modifica il file env o aggiorna il repository. come vengono uniti più file Docker Compose illustra in dettaglio le regole degli override.

L'esportazione COMPOSE_FILE fa sì che i comandi seguenti usino il file generato. Ripetetela in ogni nuova shell; in cron, passate esplicitamente -f ~/gitops/erpnext.yaml.

Attendete l'avvio di db e la terminazione di configurator. Sono necessari alcuni secondi. Quindi create il sito.

docker compose --project-name erpnext exec backend \
  bench new-site --mariadb-user-host-login-scope=% \
  --db-root-password '<your DB_PASSWORD>' \
  --install-app erpnext \
  --admin-password '<a strong admin password>' \
  erp.example.com

Verificate il risultato:

docker compose --project-name erpnext ps
docker compose --project-name erpnext exec backend bench --site erp.example.com list-apps

list-apps dovrebbe stampare frappe e erpnext con le rispettive versioni. Un ps integro mostra dieci servizi nello stato running e nessun servizio nello stato restarting.

In questo passaggio si verificano spesso due problemi. --mariadb-user-host-login-scope=% assegna all'utente del database del nuovo sito un ambito host jolly, così l'utente può continuare ad autenticarsi quando Docker assegna al container dell'applicazione un indirizzo diverso. Senza questa opzione, Frappe associa l'utente all'host da cui avviene la connessione. Il container dell'applicazione raggiunge MariaDB attraverso la rete Docker, quindi si presenta come host remoto; un utente del database associato a localhost non può autenticarsi da tale host. Questa opzione modifica l'utente del database del sito, non l'account root. L'ambito % consente connessioni da qualsiasi host che possa raggiungere MariaDB. Mantenete quindi il database sulla rete Docker privata.

Il secondo problema riguarda il nome del sito. Per impostazione predefinita, il frontend sceglie quale sito pubblicare in base all'header HTTP Host. Di conseguenza, un sito creato come erpnext non è raggiungibile all'indirizzo erp.example.com, anche se entrambi esistono. Assegnate al sito il nome del dominio, come sopra, oppure impostate FRAPPE_SITE_NAME_HEADER nel file env con il nome del sito e generate nuovamente il file Compose.

HTTPS e condizioni necessarie

L'override compose.https.yaml esegue Traefik sulla porta 443, reindirizza la porta 80 verso di essa e richiede i certificati a Let's Encrypt. TLS (sicurezza del livello di trasporto) impedisce che una fattura e un cookie di sessione transitino in chiaro sulla rete.

Devono essere vere due condizioni, altrimenti il certificato non viene mai emesso. Il record DNS A per erp.example.com deve puntare già al VPS. Le porte 80 e 443 devono essere raggiungibili da Internet, perché Let's Encrypt verifica il controllo del nome tramite una challenge HTTP-01 sulla porta 80. Controlla anche il firewall di rete del provider e quello del server. Sono controlli distinti e il firewall del pannello è spesso quello che viene dimenticato.

I certificati vengono salvati nel volume cert-data in /letsencrypt/acme.json. Se il browser mostra un certificato predefinito invece del tuo, individua il nome del servizio proxy in docker compose --project-name erpnext ps e consulta i relativi log per trovare l'errore ACME (ambiente di gestione automatica dei certificati). Esegui altre applicazioni web sullo stesso server? una singola istanza Traefik davanti a più applicazioni Docker Compose mostra come condividere il proxy invece di contendersi la porta 443. La seconda applicazione su un server di questo tipo è spesso destinata ai clienti e un help desk Chatwoot self-hosted viene eseguito dietro lo stesso proxy, così le persone che gestiscono le fatture possono rispondere nello stesso posto alle email e alle chat dei clienti.

Posta in uscita, altrimenti le fatture non lasciano mai il server

Questo è il passaggio che la maggior parte delle guide su ERPNext omette, ma determina se il sistema è realmente utilizzabile. Senza una posta in uscita funzionante, nessuna fattura raggiunge il cliente, nessun messaggio per il ripristino della password viene recapitato e nessun report pianificato viene consegnato. Lo stack non include un server di posta.

Non provare a inviare la posta direttamente dal VPS sulla porta 25. Provider come AWS bloccano per impostazione predefinita la porta 25 in uscita, mentre un nuovo IP di invio con poca o nessuna reputazione aumenta il rischio di rifiuto o di inserimento nella cartella spam. Nessuno dei due risultati è inevitabile. Usa un relay autenticato sulla porta 587 e verifica prima le regole del provider per il traffico in uscita: DigitalOcean blocca per impostazione predefinita le porte 25, 465 e 587 sui Droplet.

Il percorso supportato è la schermata Email Account nell'interfaccia di ERPNext, che memorizza la password in forma crittografata. Puoi anche inserire le chiavi nella configurazione del sito:

docker compose --project-name erpnext exec backend \
  bench --site erp.example.com set-config mail_server smtp.example.com

docker compose --project-name erpnext exec backend \
  bench --site erp.example.com set-config mail_port 587 --parse

docker compose --project-name erpnext exec backend \
  bench --site erp.example.com set-config use_tls 1 --parse

docker compose --project-name erpnext exec backend \
  bench --site erp.example.com set-config mail_login 'erp@example.com'

docker compose --project-name erpnext exec backend \
  bench --site erp.example.com set-config auto_email_id 'erp@example.com'

--parse memorizza 587 come numero anziché come stringa "587". Rileggi il file e verifica che questi due valori non siano racchiusi tra virgolette:

docker compose --project-name erpnext exec backend \
  cat sites/erp.example.com/site_config.json

Per memorizzare la password in forma crittografata, configura insieme il server in uscita, il nome utente e la password nella schermata Email Account. Il relativo campo della password non imposta la chiave separata mail_password nella configurazione del sito.

Invia quindi un messaggio reale. Crea una Sales Invoice, inviala per posta elettronica a un indirizzo che controlli e monitora la coda durante l'operazione:

docker compose --project-name erpnext logs -f queue-short

La posta in uscita è un job in background. Per questo, un messaggio che non arriva normalmente compare come job non riuscito in quel log, anziché come errore nel browser. Pubblica inoltre i record SPF (sender policy framework) e DKIM (domainkeys identified mail) per il dominio di invio, quindi aggiungi una policy DMARC. Senza autenticazione, una fattura tecnicamente corretta rischia di essere rifiutata o inserita nella cartella spam. Se preferisci gestire internamente l'intero percorso, un server di posta Mailcow self-hosted ti fornisce un relay sotto il tuo controllo, su un server separato da quello di ERPNext.

Backup che si possono realmente ripristinare

Un dump del database, da solo, non è un backup di ERPNext. Gli allegati e i file privati si trovano nella directory dei siti, non in MariaDB. Se si ripristina soltanto il database, ogni ordine di acquisto caricato torna a essere un collegamento non valido.

docker compose --project-name erpnext exec backend \
  bench --site erp.example.com backup --with-files

Questo comando scrive quattro file in sites/erp.example.com/private/backups all’interno del volume sites:

  • un dump -database.sql.gz
  • un archivio -files.tar dei file pubblici
  • un archivio -private-files.tar dei file privati
  • una copia -site_config_backup.json della configurazione del sito

Il quarto file è quello che spesso viene eliminato, ma è anche quello che causa i problemi più gravi. Contiene encryption_key, la chiave che Frappe usa per cifrare le password memorizzate: credenziali degli account email, chiavi dei gateway di pagamento e tutti i secret delle integrazioni. Se si ripristina un database senza la chiave corrispondente, il sito si carica normalmente, ma l'invio delle email non funziona e mostra:

frappe.exceptions.ValidationError: Encryption key is invalid! Please check site_config.json

Conservare sempre insieme tutti e quattro i file.

Poi trasferirli fuori dal server. Un backup conservato nel volume non sopravvive alla perdita del server e bench lo elimina comunque: per impostazione predefinita, cancella da quella directory i backup più vecchi di 23 ore. Prima di Frappe 16.20.0 e 15.114.0, l'impostazione predefinita era di 24 ore; la chiave keep_backups_for_hours nella configurazione del sito consente di sostituirla.

docker compose --project-name erpnext cp \
  backend:/home/frappe/frappe-bench/sites/erp.example.com/private/backups \
  ~/erpnext-backups

Eseguire questo comando tramite cron, quindi inviare la directory in una posizione che non si amministra direttamente. backup restic cifrati su storage esterno è lo strumento appropriato, perché cifra i dati prima del caricamento e restic check verifica che il repository sia ancora leggibile. Un backup ERP è una copia dell'intero registro contabile, quindi deve essere cifrato a riposo e archiviato su hardware diverso da questo server.

Verifica il ripristino prima di averne bisogno

Un backup non verificato è solo un’ipotesi. Esegui il test su un secondo sito nello stesso server, mai sul sito in produzione.

docker compose --project-name erpnext exec backend \
  bench new-site --mariadb-user-host-login-scope=% \
  --db-root-password '<your DB_PASSWORD>' \
  --admin-password '<a strong admin password>' \
  restore-test.example.com

docker compose --project-name erpnext exec backend \
  bench --site restore-test.example.com --force restore \
  sites/erp.example.com/private/backups/<stamp>-erp_example_com-database.sql.gz \
  --with-public-files sites/erp.example.com/private/backups/<stamp>-erp_example_com-files.tar \
  --with-private-files sites/erp.example.com/private/backups/<stamp>-erp_example_com-private-files.tar \
  --db-root-password '<your DB_PASSWORD>'

Copia la chiave di crittografia dalla configurazione di cui hai eseguito il backup al sito ripristinato; in caso contrario, le relative integrazioni non funzioneranno:

docker compose --project-name erpnext exec backend \
  bench --site restore-test.example.com set-config encryption_key '<value from site_config_backup.json>'

Ora verifica il ripristino come farebbe un contabile. Apri il report dei crediti verso clienti e confronta il saldo finale con quello del sito in produzione. Apri una fattura di acquisto recente e scarica il relativo allegato. Un sito che visualizza la pagina di accesso non dimostra nulla.

Rimuovi il sito di test al termine:

docker compose --project-name erpnext exec backend \
  bench drop-site restore-test.example.com

Perché il version pinning è più importante per ERPNext

Su un sito statico, un tag dell'immagine non fissato significa un riavvio imprevisto. Su ERPNext significa una migrazione dello schema. bench migrate riscrive le tabelle del database e può riscrivere i dati dei documenti; non è possibile annullare l'operazione. Il rollback consiste in un ripristino da backup, non in un docker compose down.

Fissa quindi il tag. ERPNEXT_VERSION=v16.32.1 era la release fissata nel pwd.yml del repository stesso ad agosto 2026. Il 2026-11-16, sia pwd.yml sia example.env fissavano v16.55.0. Non riutilizzare nessuno dei due numeri senza averlo verificato. Le release correnti sono elencate nella pagina delle release di frappe/erpnext, mentre i tag delle immagini disponibili si trovano su Docker Hub. Leggi le note della versione a cui vuoi passare prima di procedere.

L'upgrade inizia con un backup e l'attivazione della modalità di manutenzione.

docker compose --project-name erpnext exec backend \
  bench --site erp.example.com backup --with-files

docker compose --project-name erpnext exec backend \
  bench --site erp.example.com set-maintenance-mode on

Modifica ERPNEXT_VERSION in ~/gitops/erpnext.env, quindi esegui il rendering, scarica l'immagine ed esegui la migrazione.

docker compose --project-name erpnext \
  --env-file ~/gitops/erpnext.env \
  -f compose.yaml \
  -f overrides/compose.mariadb.yaml \
  -f overrides/compose.redis.yaml \
  -f overrides/compose.https.yaml \
  config > ~/gitops/erpnext.yaml

docker compose --project-name erpnext -f ~/gitops/erpnext.yaml pull
docker compose --project-name erpnext -f ~/gitops/erpnext.yaml up -d

docker compose --project-name erpnext exec backend \
  bench --site erp.example.com migrate

docker compose --project-name erpnext exec backend \
  bench --site erp.example.com set-maintenance-mode off

La modalità di manutenzione è importante perché migrate modifica lo schema durante l'esecuzione. Se un utente invia un documento mentre una tabella è stata migrata solo parzialmente, potresti dover riparare manualmente i record.

Procedi una versione principale alla volta, eseguendo un backup tra un passaggio e l'altro. Prima di procedere, verifica le istruzioni di migrazione per ogni versione principale.

Il repository include anche overrides/compose.migrator.yaml, che aggiunge un container che esegue bench --site all migrate all'avvio quando esistono siti e MIGRATE_SITES è abilitato, come avviene per impostazione predefinita. È comodo. Significa però che un docker compose up con un tag modificato migra il database di produzione senza supervisione. Su un sistema aziendale, esegui migrate solo dopo aver preso consapevolmente questa decisione quella mattina.

Rafforzare la sicurezza di un server che contiene dati dei clienti

Cambiare la password dell'Administrator al primo accesso. Il file Compose di valutazione distribuisce admin come password, e questa abitudine può arrivare fino alla produzione.

Cambiare DB_PASSWORD rispetto a 123 in example.env. Questo valore finisce in chiaro nel ~/gitops/erpnext.yaml generato, quindi chmod 600 il file e tenerlo fuori da qualsiasi repository Git. Per una soluzione più sicura, overrides/compose.mariadb-secrets.yaml legge la password da un file secret Docker invece che da una variabile d'ambiente. gestione dei file env e dei secret in Docker Compose illustra i compromessi.

Pubblicare solo ciò che serve. Con l'override HTTPS, le uniche porte esposte sono 80 e 443. Non aggiungere un mapping ports al servizio db per facilitare la connessione di un client al database: in questo modo MariaDB viene esposto su Internet. Usare invece docker compose --project-name erpnext exec backend bench mariadb. Sul sistema host, consentire 22, 80 e 443, negare tutte le altre porte e controllare anche il firewall di rete separato del provider.

Abilitare l'autenticazione a due fattori nelle System Settings per ogni account con il ruolo System Manager. Questo ruolo può modificare le System Settings, quindi va trattato come un account amministrativo e non come una semplice comodità. Se si eseguono diverse applicazioni self-hosted, Authentik come provider self-hosted di single sign-on è preferibile all'aggiunta di un'altra password per ogni applicazione.

Applicare le patch al sistema host e riavviare il sistema per installare gli aggiornamenti del kernel. Prima di fare affidamento sul riavvio automatico dello stack, controllare nel file generato la presenza di una policy restart per ogni servizio, perché senza questa policy lo stack rimane arrestato dopo il riavvio. configurare l'avvio automatico di uno stack Docker Compose dopo un riavvio illustra la configurazione dal lato systemd.

Quando ERPNext non è più gestibile su un solo VPS

Un solo VPS può supportare una piccola azienda per molto tempo. I segnali che non è più sufficiente sono questi:

  • I job in background si accumulano, quindi le email e le importazioni arrivano con minuti o ore di ritardo.
  • docker inspect segnala container con "OOMKilled": true o codice di uscita 137.
  • I report che prima richiedevano due secondi ne richiedono trenta e MariaDB è il processo che utilizza la CPU.
  • I backup richiedono così tanto tempo che un'esecuzione si sovrappone a quella pianificata successiva.

Per prima cosa, assegna a MariaDB risorse che non debba condividere. Il database e i worker Python competono per la stessa memoria e il buffer pool è il componente che richiede più memoria. Un application server più grande aiuta meno di quanto ci si aspetti. eseguire il database in Docker o sull'host illustra questa scelta, mentre impostare i limiti di memoria in Docker Compose impedisce a un container di esaurire le risorse degli altri durante la modifica della configurazione.

Successivamente, aggiungi worker per le code invece di aumentare la capacità web. Le operazioni lente di ERPNext vengono eseguite in background: generazione dei report e importazioni in blocco. Più worker richiedono margine di CPU e memoria; aggiungere container a un VPS già saturo non aumenta la capacità.

FAQ

Quanta RAM richiede ERPNext su un VPS?

Per la valutazione, iniziare con 4 GB e 2 vCPU. Per un'azienda che lo usa ogni giorno, prevedere 8 GB, 4 vCPU e 100 GB di SSD. In caso di pressione sulla memoria, il kernel può arrestare i container tramite il meccanismo out-of-memory killer; docker inspect lo segnala come "OOMKilled": true con codice di uscita 137. Questi valori sono punti di partenza, non misurazioni. Monitorare quindi l'uso effettivo della memoria nel primo mese.

Posso eseguire pwd.yml in produzione?

No. Il README del progetto lo descrive come destinato esclusivamente a valutazioni di breve durata e specifica che non è possibile installarvi app personalizzate. Usare compose.yaml con gli override per MariaDB, Redis e HTTPS, generarli in un unico file con docker compose config ed eseguire quel file.

Perché il mio sito ERPNext non è raggiungibile subito dopo la creazione?

Per impostazione predefinita, il frontend sceglie quale sito servire in base all'header HTTP Host. Il nome del sito deve quindi corrispondere al dominio usato nel browser. Un sito creato come erpnext non viene servito su erp.example.com. Creare il sito usando il dominio come nome oppure impostare FRAPPE_SITE_NAME_HEADER nel file env sul nome del sito, generare di nuovo il file compose e riavviare lo stack.

Cosa deve contenere un backup di ERPNext?

Quattro file, conservati insieme: il dump -database.sql.gz, gli archivi -files.tar e -private-files.tar e la copia di configurazione -site_config_backup.json. L'esecuzione di bench --site erp.example.com backup --with-files produce tutti e quattro i file. La copia di configurazione contiene encryption_key. Un ripristino senza questo file rende quindi impossibile decrittografare le password delle integrazioni memorizzate; il problema si manifesta come Encryption key is invalid! Please check site_config.json.

Come posso aggiornare ERPNext senza danneggiare i dati?

Eseguire il backup con --with-files, attivare la modalità di manutenzione, modificare ERPNEXT_VERSION nel file env, generare di nuovo il file compose, eseguire il pull, avviare lo stack, quindi eseguire bench --site erp.example.com migrate e disattivare la modalità di manutenzione. Procedere una versione principale alla volta e leggere prima le note di rilascio, perché migrate riscrive lo schema e i dati dei documenti senza possibilità di annullamento. Per eseguire il rollback, ripristinare il backup creato all'inizio.

Questo articolo ti è stato utile?