Come installare PM2 su Ubuntu 20.04

Installare PM2 su Ubuntu 20.04 senza complicarsi la vita

PM2 è il gestore di processi che si usa quando un’app Node.js deve restare in piedi anche dopo un crash, un logout SSH o un reboot. Su Ubuntu 20.04 la procedura è lineare, ma il punto non è solo installare il pacchetto: bisogna anche farlo partire con l’utente giusto, registrare il servizio di avvio e verificare che il riavvio della macchina non rompa nulla.

© TrgtKLS • Tech, Sicurezza e Strumenti & guide per Webmaster — https://trgtkls.it — tutti i diritti riservati.

Qui sotto trovi una procedura pratica, con comandi verificabili e con un criterio semplice: prima installi, poi fai girare un processo di prova, poi abiliti l’autostart, infine controlli i log e il comportamento dopo reboot. Se salti uno di questi passaggi, stai solo rimandando il problema.

Prerequisiti minimi

Assumo un server Ubuntu 20.04 aggiornato, accesso con un utente non root che abbia sudo e una versione di Node.js già disponibile. PM2 non installa Node al posto tuo: se Node manca o è troppo vecchio, l’installazione di PM2 non risolve il problema a monte.

Verifica subito la situazione di base:

node -v
npm -v
whoami
uname -a

Se node -v fallisce, installa prima Node.js con il metodo che usi normalmente in produzione: repository ufficiale, NodeSource, o una gestione versioni come nvm. Qui non serve fare evangelismo sul metodo, serve avere una runtime coerente e aggiornata.

Installazione globale di PM2

La strada più comune è l’installazione globale con npm. È la scelta più semplice se vuoi un setup standard e se il server è dedicato a una o poche app Node.

sudo npm install -g pm2

Subito dopo controlla che il binario sia raggiungibile e che la versione sia leggibile dal tuo utente:

pm2 -v
which pm2

Se pm2 non viene trovato ma l’installazione è riuscita, il problema è quasi sempre nel PATH o nel fatto che hai installato con un utente diverso da quello con cui stai operando. In quel caso non forzare soluzioni creative: allinea l’utente di esecuzione oppure reinstalla in modo coerente con l’ambiente scelto.

Avviare una prima applicazione con PM2

Prima di configurare l’autostart, conviene avviare un processo reale. Se hai già un’app Node, usa quella. Se vuoi solo testare PM2, puoi creare un file minimale e controllare che il ciclo start-monitoring-fallback funzioni.

Esempio con una semplice app Express:

mkdir -p ~/pm2-demo
cd ~/pm2-demo
npm init -y
npm install express

Crea app.js:

const express = require('express');
const app = express();
const port = 3000; app.get('/', (req, res) => { res.send('PM2 OK');
}); app.listen(port, () => { console.log(`App in ascolto sulla porta ${port}`);
});

Avviala con PM2:

pm2 start app.js --name demo-app

Verifica lo stato:

pm2 list
pm2 show demo-app

Il risultato atteso è un processo in stato online, con restart pari a zero o quasi, e senza errori nel campo log. Se il processo flappa, non è PM2 il colpevole automatico: di solito l’app esce subito per un errore di codice, una porta già occupata o una dipendenza mancante.

Leggere i log prima di toccare altro

La parte utile di PM2 è che non ti lascia cieco. I log sono il primo posto da guardare quando qualcosa non parte o si riavvia in loop.

pm2 logs demo-app

Se vuoi vedere solo l’output recente, usa il dump dei log associati al processo oppure vai direttamente ai file sotto la directory di runtime di PM2, in genere ~/.pm2/logs/. I nomi tipici sono del tipo demo-app-out.log e demo-app-error.log.

Un errore comune è confondere il fatto che PM2 stia “gestendo” il processo con il fatto che l’app sia sana. PM2 può riavviare un binario rotto all’infinito: il supervisore funziona, il servizio no. Se vedi molte ripartenze, il problema è nell’app o nella configurazione di runtime, non nel demone.

Abilitare l’avvio automatico al reboot

Questo è il passaggio che molti lasciano a metà. PM2, da solo, non basta: devi registrare il suo startup script per systemd, così il server riporta in vita i processi dopo il boot.

Genera lo script di avvio con l’utente corretto:

pm2 startup systemd

Il comando stampa una riga da eseguire con sudo. Non copiarla a memoria: esegui esattamente quella che PM2 propone, perché include il percorso corretto del tuo binario e il nome dell’utente. Un esempio tipico è questo:

sudo env PATH=$PATH:/usr/bin pm2 startup systemd -u nomeutente --hp /home/nomeutente

Dopo aver creato lo startup script, salva la lista dei processi attivi. Senza questo passaggio, al reboot il sistema sa come avviare PM2, ma non sa quali processi ripristinare.

pm2 save

Qui il criterio è semplice: pm2 save scrive lo stato nella dump list di PM2, in genere sotto ~/.pm2/dump.pm2. Se quel file manca o è corrotto, il restore non farà quello che ti aspetti.

Verificare che systemd stia facendo il suo lavoro

Dopo aver generato lo startup script, controlla il servizio systemd creato da PM2 e il suo stato attuale.

systemctl status pm2-nomeutente

Il nome del servizio dipende dall’utente scelto. Se non ricordi il nome, elenca i servizi:

systemctl list-units --type=service | grep pm2

Se il servizio è attivo ma i processi non tornano su, guarda i log di systemd:

journalctl -u pm2-nomeutente -n 50 --no-pager

Un errore frequente è aver eseguito pm2 startup come un utente e pm2 save come un altro. In quel caso il servizio parte, ma non trova la lista dei processi giusta. L’allineamento tra utente operativo e home directory è fondamentale.

Usare un file ecosystem quando l’app cresce

Per una sola app puoi cavartela con un comando diretto. Quando le variabili aumentano, conviene passare a un file ecosystem.config.js. È il modo più pulito per tenere insieme nome processo, script di avvio, variabili d’ambiente, numero di istanze e policy di restart.

module.exports = { apps: [{ name: 'demo-app', script: 'app.js', instances: 1, autorestart: true, watch: false, env: { NODE_ENV: 'production', PORT: 3000 } }]
};

Avvio con ecosystem:

pm2 start ecosystem.config.js

Se cambi il file, ricarica senza perdere il controllo dello stato:

pm2 reload ecosystem.config.js

Per ambienti di produzione, l’ecosystem evita il classico caos da parametri sparsi in shell history o script improvvisati. È anche più facile da versionare in Git e da revisionare in coppia quando c’è un change controllato.

Comandi utili da tenere a portata di mano

Questi sono i comandi che di fatto usi ogni giorno quando PM2 è già in servizio:

pm2 list
pm2 monit
pm2 restart demo-app
pm2 stop demo-app
pm2 delete demo-app
pm2 save
pm2 resurrect

pm2 monit è utile quando vuoi un colpo d’occhio su CPU, memoria e comportamento dei processi. Non sostituisce metriche serie, ma ti dice subito se hai un consumo anomalo o un processo che si sta impiccando da solo.

pm2 resurrect è il comando che ripristina la lista salvata. Se dopo un reboot non trovi nulla, è uno dei primi test da lanciare manualmente per capire se il problema è nello startup script o nella dump list.

Problemi tipici e come riconoscerli in fretta

Ci sono quattro casi che si ripetono spesso. Il primo è la porta già occupata: l’app tenta di ascoltare su una porta in uso e PM2 la riavvia senza successo. Il secondo è una variabile d’ambiente mancante: la tua app parte in shell, ma non nel contesto che pensavi. Il terzo è l’utente sbagliato: i file di PM2 finiscono in una home diversa da quella che il servizio systemd usa. Il quarto è il mismatch tra versione di Node e dipendenze native.

Per falsificare rapidamente queste ipotesi puoi usare una sequenza breve:

ss -ltnp | grep 3000
pm2 logs demo-app --lines 50
node -v
pm2 show demo-app

Se la porta è libera ma l’app non resta su, leggi gli errori dell’applicazione. Se l’app parte manualmente ma non via PM2, quasi sempre c’è una differenza di ambiente. Se parte con sudo ma non da utente normale, hai un problema di permessi o di path che va sistemato, non aggirato.

Disinstallazione pulita e ritorno indietro

Se devi tornare indietro, fallo in modo esplicito. Prima rimuovi i processi gestiti, poi il servizio di startup, poi il pacchetto globale. Non cancellare a caso la home di PM2 se non hai verificato che non ci siano altri processi o dump utili.

pm2 delete all
pm2 unstartup systemd
sudo npm uninstall -g pm2

Se vuoi ripulire anche i dati locali, controlla prima cosa c’è sotto ~/.pm2/. In ambienti condivisi o server con più operatori, quella directory può contenere informazioni utili per il ripristino o per l’analisi post-incidente.

Una nota operativa finale: PM2 è un ottimo supervisore, non una soluzione completa di orchestrazione. Su un singolo server è perfetto per tenere in vita servizi Node e per fare restart controllati; se però stai iniziando a gestire scaling, deploy distribuiti, health check complessi e rollout multi-nodo, stai entrando in un terreno dove serve qualcosa di più strutturato. PM2 resta utile, ma non deve diventare il pezzo che regge tutta l’architettura da solo.