Docker: Node.js

Cómo usar y desplegar una aplicación Node.js con Docker

👋 ¡Bienvenido a la documentación de Stackhero!

Stackhero ofrece una solución Docker cloud CaaS (Containers as a Service) lista para usar que proporciona una serie de beneficios, incluyendo:

  • Despliega fácilmente tus contenedores en producción con solo un docker-compose up.
  • Nombre de dominio personalizable asegurado con HTTPS (por ejemplo, https://api.tu-empresa.com, https://www.tu-empresa.com, https://backoffice.tu-empresa.com).
  • Rendimiento óptimo y seguridad robusta gracias a una VM privada y dedicada.
  • Actualizaciones sin esfuerzo con solo un clic.

Ahorra tiempo y simplifica tu vida: ¡solo toma 5 minutos probar la solución de alojamiento en la nube Docker CaaS de Stackhero y desplegar tus contenedores en producción!

Esta guía ofrece una base sólida para desarrollar una aplicación Node.js y desplegarla en producción de manera rápida y sencilla.

No se requiere conocimiento previo de Docker. Todo está configurado para garantizar una experiencia fluida; solo necesita tener Docker instalado en su ordenador.

Esta documentación está diseñada tanto para principiantes como para usuarios experimentados que desean desplegar una aplicación Node.js utilizando tecnologías modernas y escalables sin complicaciones innecesarias.

Las características clave de esta solución incluyen:

  • 💪 Configuración fácil con un mínimo esfuerzo
  • 🐳 Utiliza Docker para entornos de desarrollo y producción
  • 🔄 Recarga automática de Node.js al cambiar el código usando nodemon
  • 🚀 Despliegue en producción con un solo comando
  • 🔒 Gestión de certificados TLS para un cifrado HTTPS seguro
  • 🚧 Soporte para plataformas de staging y preproducción
  • 🧱 Arquitectura modular y escalable

Primeros pasos

Si Docker aún no está instalado en su ordenador, puede descargarlo desde el sitio oficial de Docker. Para verificar que Docker funciona correctamente, abra un terminal y ejecute docker version. Debería ver la información de la versión sin errores.

Después de instalar Docker, clone el siguiente repositorio de boilerplate:

git clone https://github.com/stackhero-io/nodejsWithDockerGettingStarted/
cd nodejsWithDockerGettingStarted

Luego, inicie la plataforma de desarrollo ejecutando make development-start o vea todos los comandos disponibles con make help.

Plataforma de desarrollo

Para iniciar la plataforma de desarrollo, ejecute:

make development-start

Este comando construye la imagen de Docker, la ejecuta y lanza el script dev definido en my-app/package.json (lo que equivale a ejecutar npm run dev).

En este ejemplo, se crea una simple API REST usando Express. Puede ver la API navegando a http://localhost:5000. La página debería mostrar "Hello World".

A continuación, abra el archivo my-app/src/app.js en su IDE preferido y modifique la siguiente línea:

res.send('Hello World');

Cámbiela a:

res.send('Updated!');

Guarde el archivo. El código de Node.js se recargará automáticamente y al actualizar http://localhost:5000 se reflejará la respuesta actualizada de la API.

¡Felicidades, ahora tiene una plataforma de desarrollo completamente operativa!

Instalar paquetes

Si necesita instalar paquetes adicionales, puede ejecutar make development-shell para acceder al shell del contenedor. Una vez dentro, use NPM con npm install <package> o Yarn con yarn add <package> para instalar los paquetes deseados.

Usar un proyecto Node.js existente

Si tiene un proyecto Node.js existente que desea integrar con Docker, siga estos pasos:

  1. Cree un nuevo directorio llamado my-app dentro de su proyecto.

  2. Mueva todos sus archivos de proyecto al directorio my-app, excluyendo los archivos .gitignore y .git.

  3. Copie docker, secrets y Makefile del boilerplate en el directorio raíz de su proyecto.

  4. Edite el archivo .gitignore en su proyecto y añada las siguientes líneas:

    node_modules/
secrets/*.production
secrets/*.staging

Puerto abierto

Este boilerplate asume que su aplicación escucha en el puerto 5000. Si prefiere otro puerto, puede editar el archivo docker/docker-compose.development.yml y luego reiniciar el entorno con make development-start.

Elegir una versión específica de Node.js

Si desea especificar una versión diferente de Node.js, siga estos pasos:

  1. Abra el archivo docker/my-app.dockerfile, que define la imagen de Docker para su aplicación.
  2. Localice la primera línea que dice FROM node:<version>-alpine.
  3. Reemplace <version> con la versión de Node.js que elija. Se recomienda usar la versión de Soporte a Largo Plazo (LTS). Puede verificar la última versión LTS en el sitio de Node.js. Por ejemplo, para usar la última versión LTS (actualmente 22), actualice la línea a FROM node:22-alpine. Si prefiere un número de versión específico, puede usar algo como FROM node:22.13.0-alpine.
  4. Guarde sus cambios en el Dockerfile.

Variables de entorno

Establezca las variables de entorno para la plataforma de desarrollo en el archivo secrets/my-app.development.

Para producción, use el archivo secrets/my-app.production.

¡No cometa el archivo secrets/my-app.production en su repositorio Git! Este archivo contiene información sensible y está ignorado por defecto en el .gitignore del boilerplate para evitar compartirlo accidentalmente.

Almacenar archivos locales

Si su aplicación Node.js necesita almacenar archivos (por ejemplo, cargas de usuarios), considere usar un servicio de almacenamiento de objetos como MinIO. Un servicio de almacenamiento de objetos ayuda a su aplicación a escalar sin problemas mientras reduce posibles problemas.

Si prefiere almacenar archivos localmente, asegúrese de usar siempre un volumen de Docker. Almacenar archivos directamente en un contenedor puede llevar a una pérdida de datos. Este boilerplate proporciona un volumen montado en /persistent para almacenar archivos de manera segura.

Nunca almacene datos persistentes fuera del directorio /persistent a menos que haya creado volúmenes personalizados y esté seguro de la configuración. ¡Almacenar archivos fuera de /persistent resultará en pérdida de datos!

Añadir un entorno de staging

Puede modificar fácilmente este boilerplate para añadir un entorno de staging. Para hacerlo:

  1. Cree una copia de docker/docker-compose.production.yml y nómbrela docker/docker-compose.staging.yml. Este archivo define los contenedores y la configuración para su entorno de staging.
  2. Cree el archivo de secretos secrets/my-app.staging que contenga cualquier información sensible requerida para staging, como contraseñas de bases de datos o claves API.
  3. En el Makefile, localice la sección etiquetada "Staging platform" y descoméntela.

Finalmente, ejecute make help para ver los nuevos comandos de staging que ahora están disponibles.

Plataforma de producción

Si aún no tiene un servicio Stackhero for Docker, puede crear uno fácilmente desde su panel de Stackhero. Se activará en aproximadamente 2 minutos.

Si es nuevo en Stackhero, puede probar el alojamiento en la nube de contenedores Docker gratis durante un mes.

Preparar su primer despliegue en producción

Antes de desplegar su aplicación en producción, necesita preparar algunos archivos de configuración:

  1. Copie secrets/global.production.example a secrets/global.production.
  2. Edite secrets/global.production y reemplace <XXXXXX>.stackhero-network.com con el nombre de host de su servicio Docker desde su panel de Stackhero.
  3. Copie secrets/my-app.production.example a secrets/my-app.production.
  4. Edite secrets/my-app.production e inserte sus credenciales.
  5. Actualice docker/docker-compose.production.yml reemplazando <XXXXXX>.stackhero-network.com con el nombre de host de su servicio Docker.

Desplegar en producción

Desplegar en producción es sencillo: ejecute:

make production-deploy

Este comando crea un contenedor Docker, transfiere los datos de su proyecto y los envía a su servicio Docker en producción. Abra su navegador y navegue al nombre de host de su servicio Docker (por ejemplo, https://<XXXXXX>.stackhero-network.com). Debería ver su API REST responder "Hello World".

También puede usar make production, que despliega sus contenedores y muestra logs en tiempo real.

Mostrar logs

Para monitorear su entorno de producción o solucionar problemas, puede ver sus logs usando estos comandos:

  • Para transmitir logs en vivo, ejecute: make production-logs-live
  • Para recuperar todos los logs almacenados, ejecute: make production-logs
  • Para recuperar logs de un día específico (reemplace YYYY-MM-DD con la fecha deseada), ejecute: make production-logs | grep "YYYY-MM-DD"

Personalizar nombres de dominio

Si desea usar un nombre de dominio diferente a https://<XXXXXX>.stackhero-network.com, Stackhero for Docker integra Traefik para simplificar la gestión de dominios. Traefik maneja el enrutamiento HTTP y el cifrado TLS (HTTPS) por usted.

Aquí hay un par de ejemplos para personalizar sus nombres de dominio:

  • Para servir api.my-company.com a través de su contenedor my-app en el puerto 5000 con cifrado TLS, actualice el archivo docker/docker-compose.production.yml reemplazando la sección labels con:

        labels:
      - "traefik.enable=true" # Habilitar Traefik para enrutar el tráfico a este contenedor
      - "traefik.http.routers.my-app.rule=Host(`api.my-company.com`)" # Definir el host
      - "traefik.http.routers.my-app.tls.certresolver=letsencrypt" # Usar letsencrypt para certificados TLS
      - "traefik.http.services.my-app.loadbalancer.server.port=5000" # Especificar el puerto 5000

  • Para servir my-company.com a través de su contenedor my-app en el puerto 5000 y redirigir todas las solicitudes de www.my-company.com a my-company.com, actualice la sección labels en el mismo archivo con:

        labels:
      - "traefik.enable=true"
      - "traefik.http.routers.my-app.rule=Host(`my-company.com`) || Host(`www.my-company.com`)" # Incluir ambos dominios
      - "traefik.http.routers.my-app.tls.certresolver=letsencrypt"
      - "traefik.http.services.my-app.loadbalancer.server.port=5000" # Especificar el puerto 5000

      # Redirigir www.my-company.com a my-company.com:
      - "traefik.http.routers.my-app.middlewares=redirect-www"
      - "traefik.http.middlewares.redirect-www.redirectregex.regex=^https://www.my-company.com/(.*)"
      - "traefik.http.middlewares.redirect-www.redirectregex.replacement=https://my-company.com/$${1}"
      - "traefik.http.middlewares.redirect-www.redirectregex.permanent=true"

No olvide configurar el DNS para my-company.com y www.my-company.com para que cada uno apunte como un CNAME a su servicio Docker en https://<XXXXXX>.stackhero-network.com.

Other articles for Docker