Node.js: Primeros pasos

Aprenda cómo desplegar un servicio Node.js en Stackhero de forma rápida y segura

👋 ¡Bienvenido a la documentación de Stackhero!

Stackhero ofrece una solución nube de Node.js lista para usar que proporciona una serie de beneficios, incluyendo:

Despliegue su aplicación en segundos con un simple git push.

Use su propio nombre de dominio y benefíciese de la configuración automática de certificados HTTPS para una mayor seguridad.

Disfrute de la tranquilidad con copias de seguridad automáticas, actualizaciones con un clic, y precios sencillos, transparentes y predecibles.

Obtenga un rendimiento óptimo y una seguridad robusta gracias a una VM privada y dedicada.

Ahorre tiempo y simplifique su vida: ¡solo toma 5 minutos probar la solución de alojamiento en la nube de Node.js de Stackhero!

Desplegar su servicio Node.js en Stackhero está diseñado para ser rápido, eficiente y fiable. En esta guía, le mostraremos los pasos esenciales para poner su aplicación en marcha en solo unos minutos, manteniendo siempre la seguridad y el rendimiento como prioridades.

Iniciar un servicio Node.js

Para comenzar, vamos a crear un servicio Node.js en Stackhero. Esto será la base para el despliegue de su aplicación y le dará acceso a todas las ventajas del alojamiento en la nube de Stackhero.

Requisitos previos

Antes de empezar, asegúrese de tener las siguientes herramientas preparadas:

Git: Puede descargarlo desde https://git-scm.com/downloads.
Usuarios de Windows: Para una experiencia más fluida, es recomendable utilizar Windows Terminal, disponible en Microsoft Store.

Configurar su servicio

El paso principal de configuración es actualizar su clave pública SSH. Esta clave permite que Stackhero acceda de forma segura a su repositorio de código.

Para encontrar su clave pública, puede ejecutar uno de estos comandos en su terminal:

cat ~/.ssh/id_rsa.pub

cat ~/.ssh/id_ed25519.pub

Si aún no tiene un par de claves SSH, puede generarlo ejecutando ssh-keygen en Linux o macOS, o ssh-keygen.exe en Windows.

Una vez que tenga su clave pública, inicie sesión en el panel de Stackhero, seleccione su servicio Node.js, vaya a la sección de configuración y pegue su clave en el campo correspondiente.

Tip: Si desea que su clave pública SSH esté disponible para todos los servicios futuros, puede configurarla globalmente. Solo tiene que ir al panel de Stackhero, hacer clic en su foto de perfil (arriba a la derecha), acceder a "Su perfil" y pegar allí su clave pública SSH.

Clonar el ejemplo

Para ayudarle a empezar, proporcionamos una aplicación de ejemplo en Node.js que muestra cómo funciona el despliegue en Stackhero. Puede clonar el repositorio con estos comandos:

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

Configurar el repositorio remoto

Desplegar su aplicación mediante Git en Stackhero es sencillo. En la página principal de su servicio encontrará un comando para añadir un remoto de Git, que tendrá un aspecto similar a este:

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

Puede copiar y pegar este comando en su terminal para configurar el remoto.

Desplegar su aplicación Node.js

Para desplegar, simplemente suba su código a Stackhero con:

git push stackhero main

La primera vez que haga push, se le pedirá que confirme la huella digital de la clave. Escriba "yes" para continuar.

En unos instantes, su aplicación estará en línea. Puede comprobar su estado visitando la URL que aparece en su panel de Stackhero (por ejemplo, https://<XXXXXX>.stackhero-network.com).

Eso es todo, su aplicación ya está desplegada.

Si necesita realizar cambios, solo tiene que actualizar su archivo app.js, hacer commit y subir sus modificaciones:

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

Desplegar una aplicación existente

Si ya dispone de una aplicación Node.js, puede añadir el remoto de Stackhero como se ha descrito antes y desplegar su código con:

git push stackhero main

Gestionar el error "failed to push some refs to '[...]'"

Si se encuentra con este error:

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 que su repositorio local no está sincronizado con el remoto. Puede forzar el push con:

git push -f stackhero main

Gestionar el error "src refspec main does not match any"

Si ve lo siguiente al hacer push:

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

Esto suele indicar que la rama main no existe. Puede intentar subir la rama master en su lugar:

git push stackhero master

Gestionar el error "Everything up-to-date" al hacer push

Si Git le indica "Everything up-to-date" pero sus cambios no se han desplegado, puede que haya olvidado hacer commit. Pruebe a ejecutar:

git add -A .
git commit -m "Su mensaje de commit"
git push stackhero main

Si no ha realizado cambios pero igualmente quiere forzar un despliegue, puede hacer un commit vacío:

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

Desplegar una rama distinta de main

Si desea desplegar una rama diferente a main, como por ejemplo production, puede hacerlo con:

git push stackhero production:main

Desplegar una etiqueta (tag)

Si utiliza etiquetas y quiere desplegar una etiqueta específica (por ejemplo, v1.0), puede ejecutar:

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

El ^{} asegura que se suba el commit asociado a la etiqueta.

Revertir o desplegar un commit específico

Si necesita desplegar un commit concreto, primero localice el hash del commit usando git log. Después, despliegue con:

git push -f stackhero <HASH>:main

Desplegar en varios entornos

Puede que quiera separar los entornos de producción y preproducción (staging). Para renombrar el remoto actual de stackhero a stackhero-staging, ejecute:

git remote rename stackhero stackhero-staging

A continuación, cree un nuevo servicio Node.js en su panel de Stackhero y añádalo como stackhero-production:

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

Después podrá desplegar en cada entorno con:

git push stackhero-production main

git push stackhero-staging main

Guardar la contraseña de su clave privada SSH en el llavero de macOS

En macOS, es posible que se le solicite la contraseña de su clave SSH cada vez que suba código. Para mayor comodidad y seguridad, puede guardarla en el llavero de macOS ejecutando:

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

Este comando guarda la contraseña de su clave para que no se le vuelva a pedir en futuros despliegues.

Gestionar secretos

Cuando trabaje con entornos de preproducción y producción, es importante gestionar los secretos como tokens o contraseñas de forma segura. En lugar de almacenar los secretos en su repositorio, utilice variables de entorno para mayor seguridad.

Puede añadir variables de entorno en el panel de Stackhero y acceder a ellas en su código Node.js. Por ejemplo, si define una variable llamada mySecret, puede acceder a ella en su aplicación así:

process.env.mySecret

Abrir otros puertos de red

Si su aplicación necesita utilizar protocolos distintos a HTTP, puede abrir puertos TCP o UDP adicionales. Esto se configura directamente en el panel de Stackhero, especificando el puerto de entrada público, el puerto de destino en su servicio Node.js y el protocolo (TCP o UDP).

Almacenar archivos

Para almacenar archivos de usuario, como fotos, lo más recomendable es utilizar una solución de almacenamiento de objetos (object storage). Esto le permite compartir archivos entre varios servicios e instancias, y mantener su código separado de sus datos. Recomendamos MinIO como una solución rápida, sencilla y potente, compatible con el protocolo Amazon S3.

Si prefiere almacenamiento local, puede utilizar el almacenamiento persistente disponible en su instancia Node.js. Este almacenamiento se encuentra en /persistent/storage/.

PRECAUCIÓN: Guarde siempre los datos dentro de la carpeta /persistent/storage/.

Los datos almacenados fuera de esta carpeta pueden perderse si la instancia se reinicia o si sube cambios de código.

Apagado controlado (graceful shutdown)

Cuando despliega una nueva versión de su aplicación, la versión anterior recibe una señal de terminación antes de apagarse. Esto da tiempo a su aplicación para cerrar conexiones a bases de datos y detener otros servicios de forma controlada.

La señal de terminación SIGTERM se envía a su aplicación. Puede gestionarla en su código de la siguiente manera:

process.on('SIGTERM', () => {
  // Este log aparece en el panel de Stackhero en la pestaña "logs"
  console.info('SIGTERM signal received.');

  // Cierre aquí las conexiones a bases de datos u otros servicios
  // ...
});

Ejecutar su código en varios núcleos de CPU

Por defecto, Node.js utiliza un solo núcleo y un solo hilo. Para aprovechar todos los núcleos de CPU disponibles, puede utilizar la API cluster de Node.js. Puede consultar la documentación oficial aquí: https://nodejs.org/api/cluster.html.

Aquí tiene un ejemplo sencillo que crea un servidor HTTP utilizando todos los CPUs disponibles:

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 {
  // Los workers comparten cualquier conexión TCP, en este caso, un servidor HTTP
  http.createServer((req, res) => {
    res.writeHead(200);
    res.end('hello world\n');
  }).listen(8000);

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