Node.js: Prime operazioni

Scoprite come distribuire rapidamente e in sicurezza un servizio Node.js su Stackhero

👋 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!

La distribuzione del vostro servizio Node.js su Stackhero è pensata per essere rapida, efficiente e affidabile. In questa guida vi illustreremo i passaggi essenziali per mettere online la vostra applicazione in pochi minuti, mantenendo sempre la sicurezza e le prestazioni come priorità.

Avviare un servizio Node.js

Per iniziare, creiamo un servizio Node.js su Stackhero. Questo costituirà la base per il deployment della vostra applicazione e vi darà accesso a tutti i vantaggi dell'hosting cloud di Stackhero.

Prerequisiti

Prima di iniziare, assicuratevi di avere a disposizione i seguenti strumenti:

Git: Potete scaricarlo da https://git-scm.com/downloads.
Utenti Windows: Per un'esperienza più fluida, è consigliabile utilizzare Windows Terminal, disponibile su Microsoft Store.

Configurare il servizio

Il principale passaggio di configurazione consiste nell'aggiornare la vostra chiave pubblica SSH. Questa chiave consente a Stackhero di accedere in modo sicuro al vostro repository di codice.

Per trovare la vostra chiave pubblica, potete eseguire uno di questi comandi nel terminale:

cat ~/.ssh/id_rsa.pub

oppure

cat ~/.ssh/id_ed25519.pub

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

Una volta ottenuta la chiave pubblica, accedete alla dashboard di Stackhero, selezionate il vostro servizio Node.js, andate nella sezione di configurazione e incollate la chiave nel campo dedicato.

Tip: Se desiderate che la vostra chiave pubblica SSH sia disponibile per tutti i servizi futuri, potete impostarla a livello globale. Accedete alla dashboard di Stackhero, cliccate sulla vostra immagine profilo (in alto a destra), andate su "Il tuo profilo" e incollate lì la vostra chiave pubblica SSH.

Clonare l'esempio

Per facilitarvi l'avvio, mettiamo a disposizione un'applicazione Node.js di esempio che mostra come funziona il deployment su Stackhero. Potete clonare il repository con questi comandi:

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

Configurare il repository remoto

Distribuire la vostra applicazione tramite Git su Stackhero è semplice. Nella pagina principale del vostro servizio troverete un comando per aggiungere un remote Git, che potrebbe essere simile a questo:

git remote add stackhero ssh://stackhero@<XXXXXX>.stackhero-network.com:222/project.git

Potete copiare e incollare questo comando nel terminale per configurare il remote.

Distribuire la vostra applicazione Node.js

Per effettuare il deployment, è sufficiente eseguire il push del vostro codice su Stackhero con:

git push stackhero main

Al primo push vi verrà chiesto di confermare l'impronta digitale della chiave. Digitate semplicemente "yes" per continuare.

In pochi istanti la vostra applicazione sarà online. Potete verificarne lo stato visitando l'URL visualizzato nella dashboard di Stackhero (ad esempio, https://<XXXXXX>.stackhero-network.com).

Ecco fatto, la vostra applicazione è ora distribuita.

Se dovete apportare modifiche, aggiornate il file app.js, effettuate il commit e fate il push delle modifiche:

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

Distribuire un'applicazione esistente

Se avete già un'applicazione Node.js, potete aggiungere il remote Stackhero come descritto sopra e distribuire il vostro codice con:

git push stackhero main

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

Se riscontrate questo 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.

Significa che il vostro repository locale non è sincronizzato con quello remoto. Potete forzare il push con:

git push -f stackhero main

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

Se vedete il seguente messaggio durante il push:

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

Questo di solito significa che il branch main non esiste. Provate a fare il push del branch master invece:

git push stackhero master

Gestire l'errore "Everything up-to-date" durante il push

Se Git vi comunica "Everything up-to-date" ma le vostre modifiche non vengono distribuite, potrebbe essere perché avete dimenticato di effettuare il commit. Provate a eseguire:

git add -A .
git commit -m "Il vostro messaggio di commit"
git push stackhero main

Se non avete modifiche ma volete comunque forzare un deployment, potete eseguire un commit vuoto:

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

Distribuire un branch diverso da main

Se desiderate distribuire un branch diverso da main, ad esempio production, potete farlo con:

git push stackhero production:main

Distribuire un tag

Se utilizzate i tag e volete distribuire un tag specifico (ad esempio, v1.0), potete eseguire:

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

Il ^{} garantisce che venga pushato il commit associato al tag.

Effettuare il rollback o distribuire uno specifico commit

Se dovete distribuire uno specifico commit, prima trovate l'hash del commit con git log. Poi distribuitelo con:

git push -f stackhero <HASH>:main

Distribuire su più ambienti

Potrebbe essere utile separare gli ambienti di produzione e staging. Per rinominare il remote attuale da stackhero a stackhero-staging, potete eseguire:

git remote rename stackhero stackhero-staging

Successivamente, create un nuovo servizio Node.js nella dashboard di Stackhero e aggiungetelo come stackhero-production:

git remote add stackhero-production ssh://stackhero@<XXXXXX>.stackhero-network.com:222/project.git

A questo punto potete distribuire su ciascun ambiente con:

git push stackhero-production main

oppure

git push stackhero-staging main

Salvare la password della chiave privata SSH nel portachiavi di macOS

Su macOS, potrebbe esservi richiesta la password della chiave SSH a ogni push. Per maggiore comodità e sicurezza, potete salvarla nel portachiavi di macOS eseguendo:

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

Questo comando salva la password della chiave, così non vi verrà più richiesta durante i futuri deployment.

Gestire i secrets

Quando lavorate con ambienti di staging e produzione, è fondamentale gestire in modo sicuro i secrets come token o password. Invece di memorizzare i secrets nel repository, utilizzate le variabili d'ambiente per una maggiore sicurezza.

Potete aggiungere variabili d'ambiente dalla dashboard di Stackhero e accedervi nel vostro codice Node.js. Ad esempio, se definite una variabile chiamata mySecret, potete accedervi così nella vostra app:

process.env.mySecret

Aprire altre porte di rete

Se la vostra applicazione necessita di utilizzare protocolli diversi da HTTP, potete aprire porte TCP o UDP aggiuntive. Potete farlo direttamente dalla dashboard di Stackhero specificando la porta di ingresso pubblica, la porta di destinazione sul vostro servizio Node.js e il protocollo (TCP o UDP).

Archiviare file

Per archiviare file degli utenti, come foto, è consigliabile utilizzare una soluzione di object storage. Questo vi permette di condividere i file tra più servizi e istanze, mantenendo separati codice e dati. Consigliamo MinIO come soluzione veloce, semplice e potente, compatibile con il protocollo Amazon S3.

Se preferite uno storage locale, potete utilizzare lo storage persistente disponibile con la vostra istanza Node.js. Questo storage si trova nella cartella /persistent/storage/.

ATTENZIONE: Conservate sempre i dati all'interno della cartella /persistent/storage/.

I dati memorizzati al di fuori di questa cartella potrebbero andare persi in caso di riavvio dell'istanza o di push del codice.

Arresto graduale (graceful shutdown)

Quando distribuite una nuova versione della vostra applicazione, la versione precedente riceve un segnale di terminazione prima di essere arrestata. Questo consente all'app di chiudere correttamente le connessioni al database e interrompere altri servizi in modo ordinato.

Il segnale di terminazione SIGTERM viene inviato alla vostra applicazione. Potete gestirlo nel vostro codice in questo modo:

process.on('SIGTERM', () => {
  // Questo log appare nella dashboard di Stackhero nella scheda "logs"
  console.info('SIGTERM signal received.');

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

Utilizzare tutti i core CPU disponibili

Per impostazione predefinita, Node.js utilizza un solo core e un solo thread. Per sfruttare tutti i core CPU disponibili, potete utilizzare l'API cluster di Node.js. La documentazione ufficiale è disponibile qui: https://nodejs.org/api/cluster.html.

Ecco un esempio semplice 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 dei worker
  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`);
}