Node.js: Iniziare

Scopri come distribuire un servizio Node.js su Stackhero rapidamente e in modo sicuro

👋 Benvenuti nella documentazione di Stackhero!

Stackhero offre una soluzione Node.js cloud pronta all'uso che fornisce numerosi vantaggi, tra cui:

  • Distribuisci la tua applicazione in pochi secondi con un semplice git push.
  • Usa il tuo nome di dominio e beneficia della configurazione automatica dei certificati HTTPS per una sicurezza potenziata.
  • Goditi la tranquillità con backup automatici, aggiornamenti con un clic, e una tariffazione semplice, trasparente e prevedibile.
  • Ottieni prestazioni ottimali e una sicurezza robusta grazie a una VM privata e dedicata.

Risparmia tempo e semplificati la vita: bastano solo 5 minuti per provare la soluzione di hosting cloud Node.js di Stackhero!

Distribuire un servizio Node.js su Stackhero è rapido, efficiente e affidabile. Questa guida ti accompagna attraverso i passaggi essenziali per distribuire la tua app in pochi secondi garantendo al contempo sicurezza e prestazioni di alto livello.

Avviare un servizio Node.js

Inizia creando un servizio Node.js su Stackhero. Questo passaggio costituisce la base per il deployment della tua applicazione e ti prepara a esplorare tutti i vantaggi della soluzione di cloud hosting di Stackhero.

Prerequisiti

Prima di distribuire su Stackhero, assicurati di avere installato i seguenti strumenti:

  1. Git. Puoi scaricarlo da https://git-scm.com/downloads.
  2. Per gli utenti Windows, suggeriamo di utilizzare Windows Terminal disponibile tramite il Microsoft Store per una migliore esperienza.

Configura il tuo servizio

L'unica configurazione necessaria è l'aggiornamento della tua chiave pubblica SSH. Questa chiave consente a Stackhero di accedere in modo sicuro al tuo repository di codice.

Per individuare la tua chiave pubblica, esegui uno di questi comandi:

cat ~/.ssh/id_rsa.pub

oppure

cat ~/.ssh/id_ed25519.pub

Se non hai ancora una coppia di chiavi SSH, puoi generarne una eseguendo ssh-keygen su Linux o macOS o ssh-keygen.exe su Windows.

Dopo aver recuperato la tua chiave pubblica, accedi al dashboard di Stackhero, seleziona il tuo servizio Node.js, vai alla sua configurazione e incolla la tua chiave.

Suggerimento: Puoi impostare la tua chiave pubblica SSH a livello globale in modo che tutti i futuri servizi la includano automaticamente. Per farlo, vai al dashboard di Stackhero, clicca sulla tua immagine del profilo (situata in alto a destra), vai su 'Il tuo profilo' e incolla la tua chiave pubblica SSH.

Clona l'esempio

È fornita un'applicazione Node.js di esempio per illustrare il processo di deployment su Stackhero. Puoi clonare il repository con i seguenti comandi:

git clone https://github.com/stackhero-io/nodejsGettingStarted.git stackhero-nodejs-getting-started
cd stackhero-nodejs-getting-started

Configura il server del repository remoto

Distribuire la tua applicazione tramite git è veloce, affidabile e semplice su Stackhero. Nella pagina principale del tuo servizio, troverai un comando per aggiungere un repository remoto git. Potrebbe apparire così:

git remote add stackhero ssh://stackhero@XXXXX.stackhero-network.com:222/project.git

Basta copiare e incollare il comando nel tuo terminale.

Distribuisci la tua applicazione Node.js

Invia il tuo codice a Stackhero utilizzando il seguente comando:

git push stackhero main

La prima volta che invii, ti verrà chiesto di aggiungere l'impronta digitale della chiave. Digita "yes" per continuare.

Dopo pochi istanti, la tua applicazione sarà online. Puoi verificarne lo stato visitando l'URL del sito fornito sul dashboard di Stackhero (ad esempio, https://XXXXX.stackhero-network.com).

Ecco fatto. La tua applicazione è ora distribuita!

Se apporti modifiche al file app.js, basta confermare e inviare le tue modifiche:

git add -A .
git commit -m "Update app.js"
git push stackhero main

Distribuire un'applicazione esistente

Per le applicazioni esistenti, aggiungi il repository remoto come descritto in precedenza sotto Configura il server del repository remoto. Quindi, distribuisci le tue modifiche con:

git push stackhero main

Gestire l'errore "failed to push some refs to '[...]'"

Se incontri il seguente errore:

error: failed to push some refs to '[...]'
hint: Updates were rejected because the remote contains work that you do
hint: not have locally. This is usually caused by another repository pushing
hint: to the same ref. You may want to first integrate the remote changes
(e.g., 'git pull ...') before pushing again.
hint: See the 'Note about fast-forwards' in 'git push --help' for details.

Questo errore indica che il tuo repository locale non è sincronizzato con il repository remoto. In questo caso, puoi forzare l'invio eseguendo:

git push -f stackhero main

Gestire l'errore "src refspec main does not match any"

Se vedi questo errore quando esegui git push stackhero main:

error: src refspec main does not match any
error: failed to push some refs to 'ssh://<XXXXXX>.stackhero-network.com:222/project.git'

Indica che il branch main non esiste. Potresti provare a inviare il branch master invece:

git push stackhero master

Gestire l'errore "Everything up-to-date" quando si invia

Se git risponde con "Everything up-to-date" ma le tue modifiche non sono distribuite, potrebbe essere perché hai dimenticato di confermare le tue modifiche. In tal caso, esegui:

git add -A .
git commit -m "Your commit message"
git push stackhero main

Se non sono state apportate modifiche ma desideri comunque forzare un deployment, puoi forzare un commit vuoto:

git commit --allow-empty -m "Force update"
git push stackhero main

Distribuire un branch diverso da main

Se desideri distribuire un branch diverso da main, come production, puoi utilizzare il seguente comando:

git push stackhero production:main

Distribuire un tag

Se lavori con i tag e desideri distribuire un tag specifico (ad esempio, v1.0), esegui:

git push stackhero 'v1.0^{}:main'

Qui, ^{} garantisce che il commit associato al tag venga inviato.

Ripristinare o distribuire un commit specifico

Se hai bisogno di distribuire un commit specifico, identifica prima l'hash del commit utilizzando git log. Quindi distribuiscilo con:

git push -f stackhero <HASH>:main

Distribuire su più ambienti

Puoi configurare più servizi Node.js per diversi ambienti, come produzione e staging. Per rinominare il repository remoto attuale da stackhero a stackhero-staging, esegui:

git remote rename stackhero stackhero-staging

Successivamente, crea un nuovo servizio Node.js nel dashboard di Stackhero e aggiungilo come stackhero-production:

git remote add stackhero-production ssh://stackhero@XXXXX.stackhero-network.com:222/project.git

Distribuisci in produzione o staging utilizzando i rispettivi comandi:

git push stackhero-production main

oppure

git push stackhero-staging main

Salvare la password della chiave privata SSH nel portachiavi di macOS

Su macOS, potresti essere invitato a inserire la password della tua chiave SSH ogni volta che invii il tuo codice. Per maggiore comodità e sicurezza (senza rimuovere la password della chiave), puoi salvarla nel portachiavi di macOS eseguendo:

/usr/bin/ssh-add --apple-use-keychain ~/.ssh/id_rsa

Questo comando salva la password della tua chiave nel portachiavi in modo che non ti venga più richiesta durante i futuri deployment.

Gestire i segreti

Per gli ambienti di staging e produzione, gestire in modo sicuro i segreti come token o password è essenziale. Invece di memorizzare questi segreti direttamente nel tuo repository, utilizza variabili d'ambiente per una sicurezza migliorata.

Puoi aggiungere variabili d'ambiente tramite il dashboard di Stackhero e accedervi nel tuo codice Node.js. Ad esempio, se definisci una variabile chiamata mySecret, puoi accedervi nella tua app come segue:

process.env.mySecret

Aprire altre porte di rete

Se la tua applicazione non utilizza HTTP, potresti dover aprire porte TCP e UDP aggiuntive tramite il dashboard di Stackhero. Specifica semplicemente la porta di ingresso pubblica, la porta di destinazione sul tuo servizio Node.js e il protocollo (TCP o UDP) per garantire una connettività adeguata.

Memorizzare i file

Per memorizzare file come foto degli utenti, è meglio utilizzare una soluzione di object storage. Questo approccio consente la condivisione di file tra più servizi e istanze mantenendo il tuo codice separato dai tuoi dati. Raccomandiamo MinIO come soluzione semplice, veloce e potente compatibile con il protocollo Amazon S3.

Se preferisci lo storage locale, puoi utilizzare lo storage persistente disponibile con la tua istanza Node.js. Questo storage si trova in /persistent/storage/.

ATTENZIONE: Non memorizzare mai dati al di fuori della cartella /persistent/storage/!

I dati memorizzati al di fuori di questa cartella potrebbero essere persi se la tua istanza si riavvia o se invii modifiche al codice.

Arresto graduale

Quando distribuisci una nuova versione della tua app, la vecchia versione riceve un segnale di terminazione in anticipo. Questo le fornisce il tempo per chiudere con grazia le connessioni al database e fermare altri servizi.

Il segnale di terminazione SIGTERM viene emesso. Puoi catturare questo segnale nel tuo codice come segue:

process.on('SIGTERM', () => {
  // Questo log appare sul dashboard di Stackhero nella scheda 'logs'
  console.info('😯 Segnale SIGTERM ricevuto.');

  // Chiudi qui le connessioni al database o altri servizi
  // ...
});

Esegui il tuo codice su più core CPU

Per impostazione predefinita, Node.js viene eseguito su un singolo core utilizzando un solo thread. Per sfruttare appieno tutti i core CPU disponibili, considera l'uso dell'API cluster di Node.js. Puoi consultare la documentazione ufficiale qui: https://nodejs.org/api/cluster.html.

Di seguito è riportato un semplice esempio che crea un server HTTP utilizzando tutte le CPU disponibili:

const cluster = require('cluster');
const http = require('http');
const cpusCount = require('os').cpus().length;

if (cluster.isMaster) {
  console.log(`Master ${process.pid} is running`);

  // Fork workers
  for (let i = 0; i < cpusCount; i++) {
    cluster.fork();
  }

  cluster.on('exit', (worker, code, signal) => {
    console.log(`Worker ${worker.process.pid} died`);
  });
} else {
  // I worker condividono qualsiasi connessione TCP; in questo caso, un server HTTP
  http.createServer((req, res) => {
    res.writeHead(200);
    res.end('hello world\n');
  }).listen(8000);

  console.log(`Worker ${process.pid} started`);
}

Other articles for Node.js