Esegui il deploy di un'applicazione Node.js su Plesk
Pubblica un'applicazione Node.js da Plesk: struttura delle cartelle, file di avvio, dipendenze npm, variabili di ambiente, registri e risoluzione degli errori più comuni.
In questa pagina
I tuoi valori
Inseriscili una volta: i comandi della guida si aggiornano.
Questa guida spiega come pubblicare un'applicazione Node.js sul tuo dominio da Plesk, installarne le dipendenze, configurarla e verificare che risponda correttamente.
Prerequisiti
- Un accesso al tuo pannello Plesk (vedi Connetti all'interfaccia Plesk).
- Un dominio collegato al tuo hosting e che punti a quest'ultimo.
- Il codice della tua applicazione, con il relativo file
package.json. - Un modo per caricare i file: il gestore di file di Plesk, un account FTP o un repository Git.
- Se la tua applicazione usa un database MySQL o MariaDB, un database creato in Plesk.
Questa guida usa httpdocs, la cartella abituale del dominio principale. Per un dominio aggiuntivo la cartella può essere diversa: controlla la Root del documento in Hosting e DNS > Hosting.
Come funziona
Su Plesk per Linux, la tua applicazione non viene avviata con npm start né con un gestore di processi come PM2. È l'application server Phusion Passenger ad avviare il file indicato in Plesk e a passargli le richieste ricevute dal server web.
Questo comporta tre conseguenze pratiche:
- La porta viene gestita per te. Passenger ignora il numero passato a
listen()e collega autonomamente il tuo server HTTP. Non devi aprire alcuna porta né aggiungerla all'indirizzo del sito. - Il file di avvio deve chiamare
listen(), direttamente o caricando il file che lo fa. - Il processo può arrestarsi in caso di inattività e riavviarsi alla richiesta successiva. Non affidare quindi un'operazione ricorrente a un timer interno (
setInterval): usa piuttosto le Attività pianificate di Plesk.
Occorre distinguere due cartelle:
| Impostazione Plesk | Ruolo | Esempio |
|---|---|---|
| Directory principale applicazione (Application Root) | Cartella che contiene l'intero progetto: package.json, codice, node_modules |
/httpdocs |
| Root del documento (Document Root) | Sottocartella dei file pubblici, serviti direttamente dal server web | /httpdocs/public |
La root del documento deve trovarsi obbligatoriamente all'interno della cartella dell'applicazione. Solo il suo contenuto è accessibile direttamente dal web: i file .env, il codice e node_modules restano così fuori portata, a patto di non inserirli mai in public.
Passaggio 1: prepara l'applicazione
Ecco la struttura usata in questa guida:
httpdocs/
├── app.js
├── package.json
├── package-lock.json
└── public/
└── logo.pngSe vuoi prima convalidare la configurazione, questo file app.js minimo non richiede alcuna dipendenza:
const http = require('node:http');
const server = http.createServer((req, res) => {
res.writeHead(200, { 'Content-Type': 'text/plain; charset=utf-8' });
res.end('Applicazione Node.js online\n');
});
server.listen(process.env.PORT || 3000);Con Express il principio non cambia:
const express = require('express');
const app = express();
app.get('/', (req, res) => {
res.send('Applicazione Node.js online');
});
app.listen(process.env.PORT || 3000);Mantenere process.env.PORT || 3000 consente allo stesso codice di funzionare anche sul tuo computer.
Controlla anche il file package.json: contiene l'elenco delle dipendenze, e gli script che eseguirai da Plesk devono comparire nella sezione scripts.
{
"name": "mia-applicazione",
"version": "1.0.0",
"private": true,
"main": "app.js",
"scripts": {
"build": "echo \"Nessuna compilazione necessaria\""
},
"dependencies": {
"express": "^5.0.0"
}
}Passaggio 2: carica i file
Carica il progetto in httpdocs, senza la cartella node_modules: le dipendenze verranno installate sul server al passaggio 4.
Il metodo più semplice per un primo caricamento:
- Crea un archivio
.zipdel progetto sul tuo computer. - In Plesk, apri File (il gestore di file), poi la cartella
httpdocs. - Carica l'archivio.
- Selezionalo, clicca su Estrai file, poi elimina l'archivio.
- Crea la cartella
publicse non esiste: Plesk ne ha bisogno come root del documento, anche se resta vuota.
Passaggio 3: configura Node.js in Plesk
-
Vai su Siti web e domini e individua il tuo dominio.
-
Clicca su Node.js. Se sul dominio non è ancora configurato un sito, passa da Crea sito web > Node.js.
-
Compila le impostazioni:
Impostazione Valore da indicare Versione di Node.js La versione richiesta dalla tua applicazione, o quella più vicina alla versione usata in sviluppo Gestione pacchetti npmoYarn, in base al tuo progetto. In genere Plesk propone la scelta giustaRoot del documento /httpdocs/publicModalità applicazione Produzione ( production) quando il sito è pronto, Sviluppo (development) durante la messa a punto. Questo valore alimentaNODE_ENVDirectory principale applicazione /httpdocsFile di avvio applicazione app.js, o il file che avvia effettivamente il tuo server -
Conferma con OK se questo pulsante è presente.
Passaggio 4: attiva l'applicazione e installa le dipendenze
Sempre nella pagina Node.js del dominio:
- Clicca su Abilita Node.js.
- Clicca su Installa NPM (o Installa Yarn). Questo pulsante compare solo se
package.jsonsi trova nella cartella dell'applicazione. - Se il tuo progetto deve essere compilato (TypeScript, front-end, ecc.), clicca su Esegui script, inserisci il nome dello script, ad esempio
build, poi conferma. - Clicca su Riavvia app per caricare l'ultima versione.
Passaggio 5: definisci le variabili di ambiente
Chiavi API, password e altre impostazioni sensibili non devono comparire nel codice.
- Nella pagina Node.js, individua Variabili di ambiente personalizzate.
- Clicca su specifica, poi su Aggiungi variabile.
- Inserisci il nome e il valore, ad esempio
DATABASE_HOSTelocalhost. - Conferma, poi clicca su Riavvia app.
Node.js non carica automaticamente un file .env. Se la tua applicazione ne usa uno, deve leggerlo da sé, ad esempio con il pacchetto dotenv.
Passaggio 6: verifica il risultato
Apri https://tuo-dominio.com/ nel browser. Con l'esempio di questa guida, la pagina mostra Applicazione Node.js online.
Puoi anche controllare la risposta dal tuo computer:
curl -i https://tuo-dominio.com/La prima riga deve indicare il codice 200. La prima richiesta può essere più lenta, il tempo necessario all'avvio dell'applicazione.
Per consultare i messaggi dell'applicazione, apri Registri dal tuo dominio, espandi Tutti i registri e lascia selezionata solo la voce Node.js.
Aggiorna l'applicazione
- Carica i file modificati.
- Se
package.jsonè cambiato, clicca di nuovo su Installa NPM. - Se necessario, esegui di nuovo lo script di compilazione.
- Clicca su Riavvia app.
Per automatizzare questi aggiornamenti, consulta Esegui il deploy da GitHub o GitLab con Plesk.
Risoluzione dei problemi
«Web application could not be started» o «We're sorry, but something went wrong»
L'applicazione si è bloccata all'avvio. Apri i Registri per leggere l'errore esatto, poi verifica:
- che il File di avvio applicazione esista nella Directory principale applicazione;
- che le dipendenze siano state installate;
- che la versione di Node.js corrisponda a quella richiesta dal progetto;
- che tutte le variabili di ambiente necessarie siano definite.
«The file does not exist» nella pagina Node.js
Plesk non trova il file di avvio. Controlla la Directory principale applicazione e il nome del file, rispettando maiuscole e minuscole.
Error: Cannot find module 'express'
Le dipendenze mancano. Clicca su Installa NPM, verifica che il modulo compaia in dependencies e non solo in devDependencies, poi riavvia l'applicazione.
ERR_REQUIRE_ESM o «require() of ES Module not supported»
Passenger carica il file di avvio con require(), operazione che può non riuscire quando il progetto usa i moduli ES ("type": "module" in package.json). Crea nella cartella dell'applicazione un piccolo file passenger.cjs:
import('./app.js').catch((error) => {
console.error(error);
process.exit(1);
});Indica poi passenger.cjs come File di avvio applicazione e riavvia.
L'applicazione non si avvia e alla fine va in timeout
Probabilmente il file di avvio non chiama mai listen(). Succede spesso con i progetti creati da express-generator, in cui il server viene avviato da bin/www e non da app.js. Indica quindi il file corretto oppure sposta la chiamata a listen().
Errore relativo a più server HTTP
Passenger si collega al primo server che chiama listen() e segnala un errore se l'applicazione ne crea più di uno. Indica esplicitamente il server da usare:
if (typeof PhusionPassenger !== 'undefined') {
PhusionPassenger.configure({ autoInstall: false });
}
const port = typeof PhusionPassenger !== 'undefined' ? 'passenger' : 3000;
server.listen(port);Viene visualizzata la pagina predefinita di Plesk o un errore 403
Verifica che Node.js sia abilitato per questo dominio e che la Root del documento punti a /httpdocs/public. Un vecchio file index.html presente in questa cartella verrebbe servito al posto della tua applicazione: eliminalo o rinominalo.
Immagini o fogli di stile restituiscono un errore 404
I file statici devono trovarsi nella Root del documento. Un URL /logo.png corrisponde al file public/logo.png, senza public nell'indirizzo.
Le tue modifiche non vengono applicate
Node.js mantiene il codice in memoria. Clicca su Riavvia app dopo ogni caricamento di file o modifica di una variabile.
Installa NPM non riesce
Leggi il messaggio visualizzato: indica il pacchetto interessato. Verifica che la Versione di Node.js rispetti il campo engines delle tue dipendenze e che package-lock.json sia aggiornato. Se l'errore parla di memoria insufficiente o della compilazione di un modulo nativo, contatta il supporto dalla tua area clienti allegando il messaggio.