Crear y ejecutar proyectos Koa.js con ServBay

ServBay es un entorno de desarrollo web local compatible con macOS y Windows, que integra una amplia selección de herramientas esenciales para desarrolladores, incluyendo el runtime de Node.js y múltiples sistemas de bases de datos. En este artículo te explicamos cómo aprovechar ServBay para crear, ejecutar y administrar tus proyectos Koa.js de forma práctica y eficiente.

¿Qué es Koa.js?

Koa.js es un framework web de próxima generación basado en Node.js y desarrollado por el equipo de Express.js. Destaca por su simplicidad, expresividad y conjunto de características potentes, siendo una opción ideal para construir aplicaciones web y APIs. Koa.js aprovecha las funcionalidades modernas de JavaScript, en especial la sintaxis async/await, lo que facilita la gestión de operaciones asíncronas y la escritura de middleware, haciendo que el código sea más claro y fácil de mantener.

Características principales de Koa.js

• Basado en async/await: Su diseño central gira en torno a async/await, permitiendo un control intuitivo del flujo asíncrono.
• Núcleo ligero: El núcleo de Koa es muy compacto y solo incluye las funcionalidades básicas, expandiéndose mediante middleware modular.
• Middleware potente: Utiliza un mecanismo de middleware en cascada que permite una gestión clara y flexible de las solicitudes.
• Enfoque web: Está orientado al desarrollo de aplicaciones web y APIs, sin ofrecer funcionalidades superfluas.

El uso de Koa.js permite a los desarrolladores construir servicios web eficientes y fácilmente mantenibles.

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

ServBay proporciona un entorno listo para usar para desarrolladores Node.js, integrando el runtime de Node.js y servicios de bases de datos habituales. Aprovechando la funcionalidad de Sitios Web (Website) de ServBay, puedes acceder fácilmente a tus proyectos Koa.js locales mediante dominios personalizados y certificados SSL.

Requisitos previos

Antes de comenzar, asegúrate de completar los siguientes pasos:

1. Instala ServBay: Visita el sitio oficial de ServBay para descargar e instalar la última versión.
2. Instala el paquete de Node.js: Abre la aplicación ServBay, accede al área de gestión de Paquetes (Packages) y verifica que tienes instalada la versión de Node.js que necesitas. Instala el paquete si aún no lo tienes.
3. Familiarízate con ServBay: Conoce el funcionamiento básico para iniciar/detener servicios y gestionar Sitios Web (Website).

Creación de 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 web de ServBay. Crea una nueva carpeta para tu proyecto (por ejemplo, servbay-koa-app), accede a ella e inicializa un proyecto de Node.js:

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

   El comando npm init -y creará automáticamente un archivo package.json por defecto.

2. Instalación de Koa.js

   Desde el directorio raíz de tu proyecto servbay-koa-app, instala Koa.js y sus tipos (si usas TypeScript):

   npm install koa
   # Si usas TypeScript, instala los tipos
   # npm install @types/koa --save-dev

3. Crea el archivo principal de la aplicación

   En el directorio principal servbay-koa-app, crea un archivo llamado app.js y añade el siguiente código de ejemplo para una aplicación Koa.js básica:

   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: maneja las solicitudes a la ruta raíz
   app.use(async ctx => {
     ctx.body = 'Hello from ServBay Koa.js App!';
   });
   
   // Definir puerto, usar la variable de entorno PORT si existe
   const port = process.env.PORT || 3000;
   
   // Iniciar el servidor HTTP
   app.listen(port, () => {
     console.log(`Koa.js server running on http://localhost:${port}`);
     console.log(`Project path: ${__dirname}`);
   });

   Este código define una aplicación Koa básica con dos middlewares: uno para registrar el tiempo y la ruta de cada solicitud, y otro para responder a la ruta raíz / mostrando "Hello from ServBay Koa.js App!". La aplicación escucha en el puerto definido por la variable de entorno PORT o el puerto 3000 por defecto.

Modo desarrollo

Durante el desarrollo, normalmente ejecutaremos el proceso local de Node.js para la app Koa.js y lo accederemos mediante la funcionalidad de Sitios Web (Website) de ServBay.

1. Ejecuta el servidor de desarrollo Koa.js

   Abre la Terminal, navega al directorio servbay-koa-app y ejecuta el archivo app.js usando node. Para evitar conflictos de puerto y facilitar la configuración en ServBay, se recomienda especificar un puerto, como el 8585:

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

   En la terminal aparecerá un mensaje como Koa.js server running on http://localhost:8585, indicando que el servidor está activo en el puerto 8585. Mantén esta ventana abierta para que la aplicación siga corriendo.

2. Configura el proxy inverso de Sitios Web (Website) en ServBay

   Para acceder a tu app Koa.js ejecutándose en localhost:8585 mediante un dominio propio, configura un Sitio Web (Website) con proxy inverso en ServBay:

   • Abre la aplicación ServBay.
   • Dirígete al apartado Sitios Web (Website).
   • Haz clic en el botón + para agregar un nuevo sitio web.
   • Configura los datos del sitio:
     • Nombre: ServBay Koa.js Dev Site
     • Dominio: servbay-koa-dev.servbay.demo (se recomienda terminar en .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 Node.js local)
     • Puerto: 8585 (el puerto de la app Koa.js)
     • Directorio raíz: para proxy inverso no aplica, déjalo vacío o pon la ruta /Applications/ServBay/www/servbay-koa-app.
   • Guarda la configuración.
   • Si ServBay solicita aplicar los cambios, haz clic en aplicar.

   Al finalizar, ServBay actualizará automáticamente tu archivo hosts local para apuntar servbay-koa-dev.servbay.demo a 127.0.0.1. Además, las peticiones a ese dominio se redirigirán internamente al puerto 8585 mediante Caddy o Nginx integrado. Usando dominio .servbay.demo, ServBay User CA genera y confía automáticamente el certificado SSL, permitiéndote acceder de forma segura vía HTTPS.

   Para más detalles, consulta la documentación de ServBay sobre cómo añadir un sitio de desarrollo Node.js (elige la documentación en inglés).

3. Accede al sitio web de desarrollo Koa.js

   Abre el navegador y visita https://servbay-koa-dev.servbay.demo.

   Si todo está configurado correctamente, verás "Hello from ServBay Koa.js App!" en la página. Esto significa que accedes a tu servidor Koa.js local usando el proxy inverso de ServBay, con dominio personalizado y HTTPS. Al editar app.js y reiniciar Node.js, verás los cambios tras refrescar el navegador.

Simulación de despliegue en producción

Para simular un entorno de producción, puedes usar diferentes puertos, variables de entorno o métodos de inicio. La configuración de proxy inverso en ServBay es igualmente válida para este escenario.

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

   En otra ventana de Terminal, detén el servidor de desarrollo y arranca la app usando el puerto 8586 y la variable NODE_ENV:

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

   Así se simula la ejecución en modo producción, escuchando en 8586.

2. Configura el proxy inverso para producción en ServBay

   Igualmente, crea un nuevo Sitio Web (Website) para la producción simulada:

   • Abre ServBay y ve al apartado Sitios Web (Website).
   • Haz clic en + para añadir el nuevo sitio.
   • Configura los siguientes datos:
     • Nombre: ServBay Koa.js Prod Site
     • Dominio: servbay-koa-prod.servbay.demo (o tu propio dominio; ServBay admite certificados SSL gratis vía ACME/Let's Encrypt)
     • Tipo: selecciona Proxy Inverso (Reverse Proxy)
     • Dirección IP: 127.0.0.1
     • Puerto: 8586 (el puerto de producción simulado)
     • Directorio raíz: vacío o la ruta del proyecto.
   • Guarda y aplica los cambios.

   Si usas .servbay.demo, seguirás contando con el certificado User CA. Para dominios públicos propios, ServBay soporta certificados SSL/TLS gratis mediante ACME (ejemplo, Let's Encrypt) para simular un entorno real de producción. Consulta la documentación sobre Cómo proteger tu sitio web con SSL.

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

   Abre el navegador y entra en https://servbay-koa-prod.servbay.demo.

   Deberías ver la misma salida que en el entorno de desarrollo, pero esta vez servida por el Node.js ejecutándose en el puerto 8586 atrás del proxy inverso de ServBay.

Conexión a bases de datos

ServBay integra varios sistemas de bases de datos populares: MongoDB, Redis, MariaDB (compatible con MySQL) y PostgreSQL. La conexión desde tus proyectos Koa.js es sencilla, ya que todas corren en local y se acceden habitualmente mediante localhost.

A continuación verás ejemplos para conectar, desde Node.js, a las bases integradas en ServBay. Antes de usarlos, asegúrate de haber instalado y abierto los servicios correspondientes en ServBay en el área Paquetes (Packages).

1. Conectar a MongoDB

   Primero instala el driver Node.js de MongoDB (mongoose o mongodb):

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

   Agrega el código de conexión en app.js u otro módulo:

   // Usar Mongoose para conectar a MongoDB
   const mongoose = require('mongoose');
   
   // Por defecto, MongoDB en ServBay no requiere autentificación, puedes elegir el nombre de la base
   mongoose.connect('mongodb://localhost:27017/servbay-koa-app', {
     useNewUrlParser: true,
     useUnifiedTopology: true
   })
   .then(() => console.log('Connected to MongoDB'))
   .catch(err => console.error('MongoDB connection error:', err));
   
   // Nota: En proyectos reales, el código de conexión suele ubicarse en la lógica de arranque de la app
   // y solo iniciar el servidor tras conectar exitosamente.

   MongoDB instalado en ServBay generalmente escucha en el puerto 27017 y no requiere usuario/contraseña por defecto. Elige el nombre de la base; si no existe, se crea automáticamente.

2. Conectar a Redis

   Instala la librería cliente de Redis para Node.js:

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

   Conecta al servidor Redis:

   // Usar el cliente de Redis para conectar
   const redis = require('redis');
   
   // Crear el cliente, conectando por defecto a localhost:6379
   const client = redis.createClient({
     url: 'redis://localhost:6379' // Puerto predeterminado Redis en ServBay
   });
   
   client.on('connect', () => {
     console.log('Connected to Redis');
   });
   
   client.on('error', (err) => {
     console.error('Redis connection error:', err);
   });
   
   // Conectar al servidor Redis
   client.connect();
   
   // Nota: En la práctica, conviene esperar la conexión antes de operar,
   // por ejemplo usando async/await y client.connect()

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

3. Conectar a MariaDB (MySQL compatible)

   MariaDB es un fork de MySQL, con API casi idéntica. ServBay lo provee como paquete, pudiendo usar la aplicación igual que MySQL.

   Instala el driver para Node.js:

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

   Usa el driver mariadb:

   // Usar el cliente mariadb para conectar
   const mariadb = require('mariadb');
   
   // El usuario root de MariaDB en ServBay tiene por defecto la contraseña 'password'
   const pool = mariadb.createPool({
     host: 'localhost',
     user: 'root',
     password: 'password',
     database: 'servbay_koa_app', // Asegúrate que existe la base, o cámbialo según tu caso
     connectionLimit: 5
   });
   
   pool.getConnection()
     .then(conn => {
       console.log("Connected to MariaDB");
       conn.release(); // Liberar la conexión al pool
     })
     .catch(err => {
       console.error("MariaDB connection error:", err);
     });
   
   // Nota: Obtener conexiones del pool es una operación asíncrona.

   Usando el driver mysql2 (recomendado):

   // Usar mysql2 para conectar a MariaDB/MySQL
   const mysql = require('mysql2/promise'); // Versión con promesas
   
   // El usuario root de MariaDB tiene como contraseña 'password' en ServBay
   const pool = mysql.createPool({
     host: 'localhost',
     user: 'root',
     password: 'password',
     database: 'servbay_koa_app', // Asegúrate que la base existe
     waitForConnections: true,
     connectionLimit: 10,
     queueLimit: 0
   });
   
   pool.getConnection()
     .then(conn => {
       console.log("Connected to MariaDB/MySQL using mysql2");
       conn.release(); // Liberar la conexión al pool
     })
     .catch(err => {
       console.error("MariaDB/MySQL connection error:", err);
     });
   
   // Nota: La contraseña de root se gestiona y puede consultarse o modificarse desde el área de configuración de bases de datos de ServBay.
   // Recomendamos no dejar contraseñas en el código en proyectos reales, usa variables de entorno y métodos seguros.

   MariaDB en ServBay escucha en el puerto 3306. Las credenciales pueden consultarse y cambiarse desde la interfaz de ServBay. Es probable que debas crear la base de datos servbay_koa_app manualmente usando ServBay, o bien clientes gráficos como TablePlus, DBeaver, etc.

4. Conectar a PostgreSQL

   Instala el driver de PostgreSQL para Node.js:

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

   Conexión al servidor PostgreSQL:

   // Usar pg para conectar a PostgreSQL
   const { Pool } = require('pg');
   
   // Usuario por defecto 'user', contraseña 'password' en ServBay
   const pool = new Pool({
     user: 'user', // Usuario predeterminado
     host: 'localhost',
     database: 'servbay_koa_app', // Asegúrate de crear la base
     password: 'password', // Contraseña predeterminada
     port: 5432, // Puerto por defecto en ServBay
   });
   
   pool.connect((err, client, done) => {
     if (err) {
       console.error('PostgreSQL connection error:', err);
       return;
     }
     console.log('Connected to PostgreSQL');
     client.release(); // Liberar la conexión al pool
   });
   
   // Nota: Las credenciales pueden consultarse y modificarse desde la sección de configuración de ServBay.
   // Evita dejar contraseñas en el código en proyectos reales.

   PostgreSQL en ServBay usa el puerto 5432. Las credenciales, así como la gestión de bases de datos, están accesibles desde la interfaz de ServBay; deberás crear la base de datos servbay_koa_app de forma manual.

Administración de bases de datos en ServBay

Además de conectar desde el código, puedes gestionar las bases provistas en ServBay usando herramientas gráficas. Los servicios de bases de datos suelen estar en 127.0.0.1 o localhost, con puertos y credenciales consultables desde la GUI de ServBay.

• Consulta/modifica contraseñas por defecto: Ve al paquete de la base deseada en la app ServBay, haz clic en su icono de configuración para ver o cambiar las credenciales de root (MariaDB) o user (PostgreSQL).
• Crea bases y usuarios: Usa clientes como TablePlus, DBeaver, pgAdmin, MongoDB Compass, etc., conecta a los servicios con los datos de ServBay y crea bases, usuarios y tablas mediante comandos SQL o la interfaz gráfica.

Consideraciones importantes

• Conflictos de puerto: Elige puertos para tu app Koa.js (8585, 8586, etc.) que no estén usados por otros programas.
• Estado de ServBay: Verifica que ServBay y los paquetes necesarios (Node.js y bases de datos) están en ejecución.
• Archivo hosts: ServBay gestiona el archivo /etc/hosts automáticamente, pero puedes revisar manualmente si tienes problemas de resolución de dominios.
• Firewall: Asegúrate de que el firewall de macOS o cualquiera de terceros no esté bloqueando conexiones de ServBay o Node.js.
• Revisión de logs: Ante problemas, consulta los logs de ServBay y la salida de Node.js en la terminal para diagnosticar.

Preguntas frecuentes (FAQ)

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

  Respuesta: El proxy inverso mediante el módulo de sitios de ServBay ofrece varias ventajas:

  1. Simulación realista: Usar dominios personalizados como .servbay.demo o un dominio propio es más parecido a cómo se accede en producción que mediante localhost:PORT.
  2. Soporte SSL: ServBay genera y configura automáticamente certificados SSL (User CA o Let's Encrypt), permitiendo probar HTTPS durante el desarrollo.
  3. Gestión centralizada: Administra todos tus sitios locales desde un solo lugar con rapidez y comodidad.
  4. Puertos estandarizados: Los navegadores y visitantes acceden por los puertos estándar (80/443) sin exposición directa a los puertos internos elevados en Node.js.

• Pregunta: ¿Puedo acceder sin proxy inverso vía localhost:PORT?

  Respuesta: Sí, puedes abrir directamente http://localhost:PORT en el navegador para tu Koa.js local, pero no aprovecharás las ventajas de ServBay: dominios personalizados, SSL automático, gestión de logs y otras facilidades para desarrollo y simulación de producción. El uso del proxy inverso es preferible para un entorno más realista.

• Pregunta: ¿Cuál es la contraseña por defecto de las bases en ServBay? ¿Cómo la cambio?

  Respuesta: Las contraseñas por defecto pueden consultarse desde la sección de Bases de Datos de ServBay. Haz clic en el icono de ajustes del paquete correspondiente (MariaDB, PostgreSQL, etc.), y verás las credenciales actuales. Ahí mismo puedes cambiarlas. Por seguridad, se recomienda cambiar la contraseña por defecto.

Conclusión

Siguiendo esta guía has aprendido cómo montar un entorno de desarrollo Koa.js en macOS usando ServBay. Hemos creado una aplicación básica con Koa.js y configurado el acceso mediante proxy inverso en ServBay, usando dominios personalizados y HTTPS, tanto en modo desarrollo como para simular producción. También has visto cómo conectar fácilmente con diferentes bases de datos integradas.

ServBay proporciona a los desarrolladores Node.js un entorno local integrado y gestionable, permitiéndote concentrarte en el desarrollo sin complicaciones de configuración. Aprovecha su potencia para mejorar tu productividad día a día.