Crear y ejecutar un proyecto Koa.js con ServBay

ServBay es un entorno de desarrollo web local diseñado específicamente para macOS, que integra una variedad de paquetes comunes para desarrolladores, incluyendo el runtime de Node.js y diferentes bases de datos. En este artículo se muestra cómo aprovechar el entorno conveniente que ofrece ServBay para crear, ejecutar y gestionar rápidamente tus proyectos de Koa.js.

¿Qué es Koa.js?

Koa.js es el framework web de última generación para Node.js, desarrollado por el mismo equipo detrás de Express.js. Destaca por su sencillez, expresividad y un potente set de características, lo que lo convierte en una opción ideal para construir aplicaciones web y APIs. Koa.js saca provecho de las capacidades modernas de JavaScript, especialmente la sintaxis async/await, simplificando en gran medida la escritura de código asíncrono y middlewares, y facilitando su mantenimiento y claridad.

Características principales de Koa.js

• Basado en async/await: Su diseño está centrado en async/await, haciendo que el control del flujo asíncrono sea más intuitivo.
• Núcleo minimalista: Su librería central es muy ligera e incluye únicamente las funcionalidades básicas; se expande fácilmente mediante middlewares modulares.
• Middleware potente: Adopta una arquitectura de middlewares en cascada, que ofrece un flujo de procesamiento de peticiones claro y flexible.
• Enfoque en la web: Específicamente diseñado para aplicaciones web y APIs, sin añadir funcionalidades innecesarias.

Con Koa.js, los desarrolladores pueden construir servicios web eficientes y de alto rendimiento de forma sencilla y mantenible.

Configuración del entorno de desarrollo Koa.js con ServBay

ServBay provee un entorno listo para Node.js, integrando el runtime y servicios de bases de datos esenciales. Junto con la función de Sitio web (Website) de ServBay, puedes acceder fácilmente a tu proyecto local de Koa.js usando dominios personalizados y certificados SSL.

Requisitos previos

Antes de empezar, asegúrate de lo siguiente:

1. Instala ServBay: Accede al sitio oficial de ServBay para descargar e instalar la versión más reciente.
2. Instala el paquete de Node.js: Abre la aplicación ServBay, entra en la gestión de Paquetes (Packages) y comprueba que tienes instalada la versión de Node.js necesaria. Si no es así, selecciónala y haz clic en instalar.
3. Familiarízate con ServBay: Aprende cómo arrancar/detener servicios y cómo gestionar sitios web (Website) en ServBay.

Creando un proyecto Koa.js

Utilizaremos el directorio raíz recomendado por ServBay, /Applications/ServBay/www, para almacenar los archivos del proyecto.

1. Inicializa el directorio del proyecto

   Abre la aplicación Terminal y navega al directorio raíz de sitios de ServBay. Luego, crea una nueva carpeta para el proyecto (por ejemplo, servbay-koa-app), accede a ella e inicializa un proyecto nuevo de Node.js:

   cd /Applications/ServBay/www
   mkdir servbay-koa-app
   cd servbay-koa-app
   npm init -y

   El comando npm init -y generará rápidamente un archivo package.json predeterminado.

2. Instala Koa.js

   En el directorio raíz que creaste para el proyecto, instala Koa.js y (si utilizas TypeScript) sus definiciones de tipos:

   npm install koa
   # Si utilizas TypeScript, puedes instalar las definiciones de tipos
   # npm install @types/koa --save-dev

3. Crea el archivo de entrada de la aplicación

   Crea un archivo llamado app.js en la carpeta de tu proyecto y agrega un código básico de una aplicación Koa.js:

   const Koa = require('koa');
   const app = new Koa();
   
   // Middleware: registra información de la solicitud
   app.use(async (ctx, next) => {
     const start = Date.now();
     await next();
     const ms = Date.now() - start;
     console.log(`${ctx.method} ${ctx.url} - ${ms}ms`);
   });
   
   // Middleware: gestiona las peticiones a la ruta raíz
   app.use(async ctx => {
     ctx.body = '¡Hola desde ServBay Koa.js App!';
   });
   
   // Define el puerto, usando la variable de entorno PORT si existe
   const port = process.env.PORT || 3000;
   
   // Inicia el servidor HTTP
   app.listen(port, () => {
     console.log(`Servidor Koa.js ejecutándose en http://localhost:${port}`);
     console.log(`Ruta del proyecto: ${__dirname}`);
   });

   Este código crea una aplicación básica de Koa, con dos middlewares: uno que registra el tiempo y la ruta de cada petición, y otro que responde a la ruta / con el texto "¡Hola desde ServBay Koa.js App!". La aplicación escuchará en el puerto definido por la variable de entorno PORT o el puerto 3000 por defecto.

Entra en modo desarrollo

Durante el desarrollo, suele iniciarse el proceso local de Node.js para ejecutar la app y acceder a ella a través de la funcionalidad Sitio web (Website) de ServBay.

1. Ejecuta el servidor de desarrollo Koa.js

   Abre Terminal, ingresa al directorio del proyecto y ejecuta el archivo app.js con Node. Para evitar conflictos de puerto y facilitar la configuración de ServBay, puedes definir un puerto específico, por ejemplo 8585:

   cd /Applications/ServBay/www/servbay-koa-app
   PORT=8585 node app.js

   Verás en terminal un mensaje similar a Servidor Koa.js ejecutándose en http://localhost:8585, indicando que la aplicación está corriendo y escuchando en ese puerto. Deja abierta esa ventana para mantener el servidor activo.

2. Configura el proxy inverso en Sitio web de ServBay

   Para acceder al servidor Koa.js en localhost:8585 desde un dominio personalizado, debemos crear un nuevo Sitio web (Website) en ServBay configurado como proxy inverso:

   • Abre la aplicación de ServBay.
   • Dirígete al apartado Sitio web (Website).
   • Haz clic en el botón + en la esquina inferior izquierda para añadir un nuevo sitio.
   • Rellena los datos:
     • Nombre: ServBay Koa.js Dev Site
     • Dominio: servbay-koa-dev.servbay.demo (se recomienda el sufijo .servbay.demo, ServBay generará un certificado SSL automáticamente)
     • Tipo: selecciona Proxy inverso (Reverse Proxy)
     • Dirección IP: 127.0.0.1 (apunta al proceso de Node.js local)
     • Puerto: 8585 (el mismo que tu aplicación Koa.js)
     • Raíz de documentos (Document Root): este campo no es relevante para el proxy inverso; déjalo vacío o puedes poner la ruta del proyecto /Applications/ServBay/www/servbay-koa-app.
   • Haz clic en guardar.
   • Si ServBay solicita aplicar cambios, acepta para actualizar la configuración.

   Tras esto, ServBay actualizará el archivo hosts, asociando servbay-koa-dev.servbay.demo a 127.0.0.1, y mediante su servidor integrado (Caddy o Nginx) canalizará las peticiones de ese dominio al puerto 8585. Además, como pertenece al dominio .servbay.demo, ServBay User CA generará y confiará automáticamente un certificado SSL, así que podrás acceder de forma segura usando HTTPS.

   Si deseas detalles adicionales, consulta la documentación de ServBay sobre añadir un sitio de desarrollo Node.js (elige la versión en inglés).

3. Accede al sitio de desarrollo Koa.js

   Abre tu navegador y accede a https://servbay-koa-dev.servbay.demo.

   Si todo está correctamente configurado, deberías ver el mensaje "¡Hola desde ServBay Koa.js App!". Esto confirma que tu navegador accede a tu servidor de desarrollo Koa.js local a través del proxy de ServBay. Cada vez que modifiques app.js y reinicies el proceso de Node, los cambios aparecerán tras refrescar la página.

Despliegue de la versión de producción (simulación)

Cuando quieras simular un entorno de producción, puedes utilizar un puerto, variables de entorno o métodos de arranque distintos. La configuración de proxy en ServBay es igualmente válida para este contexto.

1. Ejecuta el servidor Koa.js en modo producción (simulado)

   En una nueva terminal (o tras detener el servidor de desarrollo), ejecuta el proyecto simulando el entorno de producción, por ejemplo usando el puerto 8586 y configurando la variable NODE_ENV:

   cd /Applications/ServBay/www/servbay-koa-app
   PORT=8586 NODE_ENV=production node app.js

   Esto levantará otra instancia de Koa.js, escuchando el puerto 8586 y simulando el modo de producción.

2. Configura un sitio web en ServBay para producción (simulado)

   Repite los pasos en ServBay, creando un nuevo sitio para el entorno simulado de producción:

   • Abre ServBay y ve al apartado Sitio web (Website).
   • Haz clic en el botón + para añadir un sitio nuevo.
   • Configura los campos así:
     • Nombre: ServBay Koa.js Prod Site
     • Dominio: servbay-koa-prod.servbay.demo (o tu propio dominio; si usas un dominio tuyo, puedes solicitar un certificado SSL gratuito con Let's Encrypt desde ServBay)
     • Tipo: selecciona Proxy inverso (Reverse Proxy)
     • Dirección IP: 127.0.0.1
     • Puerto: 8586 (el del servidor de producción Koa.js)
     • Raíz de documentos: vacío o la ruta del proyecto.
   • Guarda y aplica los cambios.

   Si utilizas un dominio .servbay.demo, seguirás usando el certificado de ServBay User CA. Si optas por tu dominio público, ServBay soporta certificados ACME/Let's Encrypt fácilmente. Más información en la documentación de ServBay sobre proteger tu sitio web con SSL.

3. Accede al sitio Koa.js de producción (simulada)

   Abre el navegador y ve a https://servbay-koa-prod.servbay.demo.

   La salida será idéntica a la del desarrollo, pero ahora las peticiones son canalizadas por ServBay hacia el proceso Node.js escuchando en el puerto 8586.

Conexión con bases de datos

ServBay integra sistemas de base de datos populares como MongoDB, Redis, MariaDB (compatible con MySQL) y PostgreSQL. Es sencillo conectarlas en tu proyecto Koa.js, ya que se ejecutan localmente y puedes acceder a ellas usando localhost con la configuración predeterminada.

A continuación, encontrarás ejemplos básicos usando los drivers de Node.js para las bases de datos incluidas. Asegúrate de que la base de datos correspondiente esté instalada y ejecutándose desde la sección Paquetes (Packages) de ServBay.

1. Conectando a MongoDB

   Instala el driver Node.js para MongoDB (por ejemplo mongoose o mongodb):

   cd /Applications/ServBay/www/servbay-koa-app
   npm install mongoose # o npm install mongodb

   Luego, añade este código en app.js u otro módulo:

   // Conectando a MongoDB usando Mongoose
   const mongoose = require('mongoose');
   
   // Por defecto, MongoDB en ServBay no requiere autenticación; base de datos personalizable
   mongoose.connect('mongodb://localhost:27017/servbay-koa-app', {
     useNewUrlParser: true,
     useUnifiedTopology: true
   })
   .then(() => console.log('Conectado a MongoDB'))
   .catch(err => console.error('Error al conectar a MongoDB:', err));
   
   // Nota: En apps reales, la conexión suele estar en la lógica de lanzamiento de la app
   // y escuchar en el puerto después del éxito en la conexión.

   El servicio MongoDB de ServBay escucha el puerto 27017 y, generalmente, permite conexiones sin credenciales. Solo especifica el nombre de la base de datos (si no existe, se creará automáticamente).

2. Conectando a Redis

   Instala la librería cliente de Redis:

   cd /Applications/ServBay/www/servbay-koa-app
   npm install redis

   Y conecta la app:

   // Conectando a Redis usando el cliente redis
   const redis = require('redis');
   
   // Crea el cliente Redis (por defecto en localhost:6379)
   const client = redis.createClient({
     url: 'redis://localhost:6379' // Puerto por defecto en ServBay
   });
   
   client.on('connect', () => {
     console.log('Conectado a Redis');
   });
   
   client.on('error', (err) => {
     console.error('Error de conexión a Redis:', err);
   });
   
   // Conecta el cliente
   client.connect();
   
   // Nota: Es recomendable esperar a la conexión antes de ejecutar operaciones,
   // por ejemplo, usando async/await junto con client.connect()

   Redis en ServBay escucha en el puerto 6379 y no requiere contraseña por defecto.

3. Conectando a MariaDB (o MySQL)

   MariaDB es un fork de MySQL y compatible a nivel de API; ServBay incluye el paquete oficial. Puedes usarlo como si fuera MySQL.

   Instala el driver correspondiente:

   cd /Applications/ServBay/www/servbay-koa-app
   npm install mariadb # o npm install mysql2 (alta compatibilidad, recomendado)

   Conectando con mariadb:

   // Conectando a MariaDB usando el cliente mariadb
   const mariadb = require('mariadb');
   
   // Por defecto, root:password son las credenciales en ServBay
   const pool = mariadb.createPool({
     host: 'localhost',
     user: 'root',
     password: 'password',
     database: 'servbay_koa_app', // Asegúrate de crear la base de datos previamente
     connectionLimit: 5
   });
   
   pool.getConnection()
     .then(conn => {
       console.log("Conectado a MariaDB");
       conn.release(); // Libera la conexión al pool
     })
     .catch(err => {
       console.error("Error de conexión a MariaDB:", err);
     });
   
   // Nota: Obtener conexiones del pool es una operación asíncrona

   Con mysql2 (recomendado):

   // Conectando a MariaDB/MySQL usando mysql2
   const mysql = require('mysql2/promise'); // Compatibilidad con promesas
   
   // Por defecto, root:password en ServBay
   const pool = mysql.createPool({
     host: 'localhost',
     user: 'root',
     password: 'password',
     database: 'servbay_koa_app', // Previamente creada
     waitForConnections: true,
     connectionLimit: 10,
     queueLimit: 0
   });
   
   pool.getConnection()
     .then(conn => {
       console.log("Conectado a MariaDB/MySQL usando mysql2");
       conn.release(); // Libera la conexión al pool
     })
     .catch(err => {
       console.error("Error de conexión a MariaDB/MySQL:", err);
     });
   
   // Nota: La contraseña predeterminada de root se puede revisar y cambiar desde el GUI de ServBay.
   // Se recomienda usar variables de entorno para las contraseñas y evitar hardcodearlas.

   El servicio MariaDB por defecto escucha en el puerto 3306. Encuentra o cambia las credenciales en el apartado administración de base de datos. Puede que necesites crear previamente la base de datos con un cliente como TablePlus, DBeaver, etc.

4. Conectando a PostgreSQL

   Instala el driver oficial Node.js:

   cd /Applications/ServBay/www/servbay-koa-app
   npm install pg

   Conexión básica:

   // Conectando a PostgreSQL usando el cliente pg
   const { Pool } = require('pg');
   
   // Por defecto, user:password en ServBay
   const pool = new Pool({
     user: 'user',
     host: 'localhost',
     database: 'servbay_koa_app', // Debe existir previamente
     password: 'password', // Contraseña por defecto en ServBay
     port: 5432, // Puerto PostgreSQL por defecto
   });
   
   pool.connect((err, client, done) => {
     if (err) {
       console.error('Error de conexión a PostgreSQL:', err);
       return;
     }
     console.log('Conectado a PostgreSQL');
     client.release(); // Libera el cliente al pool
   });
   
   // Nota: Puedes ver o cambiar la contraseña del usuario 'user' desde el GUI de ServBay.
   // Se recomienda no guardar passwords directamente en el código.

   PostgreSQL en ServBay escucha en el puerto 5432. Credenciales y datos pueden gestionarse desde el GUI. Recuerda crear la base servbay_koa_app previamente si no existe.

Gestión de bases de datos en ServBay

Además de conectar mediante código, puedes administrar las bases de datos de ServBay con herramientas gráficas. Las bases corren en 127.0.0.1/localhost y puedes usar los puertos y credenciales que ServBay muestra en la interfaz.

• Ver/modificar contraseñas: En la aplicación ServBay, encuentra el paquete de la base de datos, haz clic en el ícono de configuración y consulta o cambia las credenciales (usuario root de MariaDB, user de PostgreSQL, etc.).
• Crear bases de datos y usuarios: Usa clientes como TablePlus, DBeaver, pgAdmin, MongoDB Compass, etc., conectándote a las instancias locales, para crear bases, tablas, usuarios y administrar datos fácilmente por interfaz o comandos SQL.

Notas importantes

• Conflicto de puertos: Usa puertos (p.ej. 8585, 8586) que no estén ya en uso por otros programas.
• Estado de ServBay: Asegúrate de que ServBay, el paquete de Node.js y las bases de datos necesarias estén bien ejecutándose.
• Archivo hosts: ServBay lo gestiona automáticamente, pero si tienes problemas de resolución de dominios, revisa que existan los registros apropiados en /etc/hosts.
• Cortafuegos: Comprueba que el firewall de macOS o externos no bloquean el acceso de ServBay o los procesos de Node.js.
• Revisión de logs: Si surge algún inconveniente, revisa los logs de ServBay (en la pestaña correspondiente) y la salida del proceso Node.js en la terminal, te ayudarán en el diagnóstico.

Preguntas frecuentes (FAQ)

• ¿Por qué usar el proxy inverso de ServBay para acceder a mi proyecto Koa.js?

  Respuesta: El proxy inverso de los sitios web en ServBay ofrece varias ventajas:

  1. Simulación de entorno real: Acceder mediante tu propio dominio (como .servbay.demo o uno propio) se parece más al entorno de producción que usar localhost:PUERTO.
  2. Soporte SSL: ServBay puede crear y gestionar certificados SSL para sitios locales (usando ServBay User CA o Let's Encrypt), facilitando pruebas con HTTPS incluso en desarrollo.
  3. Gestión centralizada: Puedes administrar todos tus sitios y entornos de desarrollo desde la interfaz de ServBay de forma rápida y cómoda.
  4. Ocultamiento de puertos: El navegador accede mediante los puertos estándar 80/443, facilitando incluso el acceso externo si lo habilitas, y ServBay redirige internamente a los puertos altos del proceso Node.js.

• ¿Puedo acceder directamente a localhost:PUERTO sin proxy inverso?

  Respuesta: Sí, puedes. Si tu app Koa.js escucha en un puerto específico (por ejemplo, 3000 o el que configures), puedes acceder mediante http://localhost:PUERTO. Sin embargo, perderías ventajas como dominios personalizados, SSL automático y la gestión centralizada de logs y accesos de ServBay. Para una experiencia más cercana a producción, se recomienda usar el proxy inverso.

• ¿Cuál es la contraseña predeterminada de las bases de datos en ServBay y cómo cambiarla?

  Respuesta: Las contraseñas predeterminadas para las bases instaladas se pueden ver en la sección Base de datos de la app ServBay. Haz clic en el ícono de configuración junto a la base correspondiente (p.ej., MariaDB, PostgreSQL) para consultar o cambiar los usuarios y contraseñas. Por seguridad, se recomienda cambiar la contraseña predeterminada.

Resumen

Siguiendo esta guía has aprendido cómo montar un entorno Koa.js usando ServBay en macOS. Has creado una aplicación básica, configurado el proxy inverso de ServBay para acceder mediante dominio personalizado y HTTPS tanto en desarrollo como en simulación de producción, y comprendido cómo conectar con las bases de datos integradas.

ServBay brinda a los desarrolladores Node.js un entorno local integrado y fácil de gestionar, ayudándote a centrarte en el código sin complicaciones de configuración. Aprovecha la potencia de ServBay para potenciar y agilizar tu flujo de desarrollo.