Guía para Configurar el Servicio de Proxy Inverso Ngrok en ServBay

Ngrok es una potente herramienta de túneles seguros basada en tecnología de proxy inverso, capaz de atravesar firewalls y NAT, mapeando servicios que se ejecutan localmente a un dominio accesible públicamente. Esta guía detalla cómo integrar y configurar Ngrok en el entorno de desarrollo local ServBay, permitiendo el acceso a servicios web, APIs u otros servicios locales a través de Internet. Gracias a esto, se facilita la demostración remota, la colaboración en equipo o las pruebas de callbacks de servicios de terceros.

Principios Técnicos

El principio fundamental de Ngrok es establecer un túnel cifrado entre su ordenador local y los servidores de Ngrok. Cuando un usuario externo accede al dominio público asignado por Ngrok, la solicitud llega primero a los servidores de Ngrok y posteriormente es reenviada, a través del túnel seguro, al servicio correspondiente que se ejecuta en su entorno local de ServBay. Esto facilita exponer sus servicios al exterior aunque su máquina local no tenga IP pública o esté detrás de un firewall. En el caso de uso con ServBay, esto significa que puede compartir en tiempo real sitios web locales, APIs backend o cualquier servicio basado en HTTP/HTTPS para pruebas y demostraciones externas.

Preparativos

Antes de configurar Ngrok, asegúrese de lo siguiente:

1. ServBay instalado y en funcionamiento: Confirme que la aplicación ServBay está instalada correctamente y que los servicios web que desea exponer con Ngrok (por ejemplo, un sitio web) están configurados y funcionando en ServBay. Puede gestionar la configuración de sus sitios web locales desde el panel “Sitios” dentro de ServBay.
2. Cliente Ngrok instalado: Complete la instalación de la herramienta CLI de Ngrok mediante estos pasos:
   1. Visite la página oficial de descargas de Ngrok y obtenga el paquete correspondiente a su sistema operativo.
   2. Después de descargar, descomprima el archivo. Mueva o copie el ejecutable ngrok a un directorio incluido en su PATH del sistema (como /usr/local/bin en macOS) para poder ejecutar el comando ngrok desde cualquier terminal.

      # Ejemplo para macOS con arquitectura ARM64
      sudo unzip ~/Downloads/ngrok-v3-stable-darwin-arm64.zip -d /usr/local/bin

   3. Verifique la instalación comprobando si puede ejecutar ngrok version y se muestra el número de versión:

      ngrok version
      # Salida de ejemplo: ngrok version 3.5.0

3. Cuenta Ngrok (opcional pero recomendable): Disponer de una cuenta Ngrok (gratuita o de pago) facilita la gestión de túneles y permite acceder a funcionalidades avanzadas como dominios fijos. Regístrese en el sitio oficial de Ngrok y obtenga su token de autenticación (ngrok config add-authtoken <YOUR_AUTH_TOKEN>); esto elimina el límite temporal de los túneles y activa características adicionales.
4. Sitio local configurado: Al menos un sitio web local debe estar configurado en ServBay para exponer a través de Ngrok, usando un dominio local como servbay.local o yourproject.servbay.demo.

Configuración Práctica del Túnel

Explicación de Parámetros Clave

El comando estándar para mapear servicios es el siguiente:

ngrok http --domain=<NGROK_DOMAIN> <LOCAL_ENDPOINT> \
  --request-header-add='host: <VIRTUAL_HOST>'

Componente de Parámetro	Explicación de la Funcionalidad
http	Indica que se creará un túnel sobre el protocolo HTTP. Ngrok manejará solicitudes HTTP/HTTPS entrantes.
--domain <NGROK_DOMAIN>	Especifica el dominio fijo asignado por Ngrok (reemplace con su dominio real asignado o configurado en el Dashboard). En el plan gratuito normalmente no se usa—Ngrok asigna un subdominio aleatorio.
<LOCAL_ENDPOINT>	Dirección del servicio ServBay local. Para hosts virtuales en ServBay, suele ser el dominio local (p.ej. https://servbay.local) o bien http://localhost:puerto.
--request-header-add='host: <VIRTUAL_HOST>'	【Importante】 Sobreescribe la cabecera Host de la solicitud. ServBay utiliza típicamente el encabezado HTTP Host para distinguir distintos sitios locales (hosts virtuales). Con esto, modificamos el Host externo al dominio local configurado en ServBay (p.ej. servbay.local), asegurando el enrutamiento correctamente hacia el sitio.

Ejemplo de Configuración

Suponga que ha configurado un sitio local en ServBay con el dominio servbay.local y desea exponerlo públicamente mediante Ngrok. Si utiliza el plan gratuito de Ngrok, puede mapear directamente la dirección local:

# Mapear el sitio ServBay local servbay.local a un dominio aleatorio asignado por Ngrok
ngrok http https://servbay.local --request-header-add='host: servbay.local'

Si ha configurado un dominio fijo en el Dashboard de Ngrok, como your-servbay-demo.ngrok-free.app o un dominio personalizado (cuenta de pago), use la opción --domain:

# Mapear el sitio ServBay local servbay.local al dominio específico de Ngrok
ngrok http --domain=your-servbay-demo.ngrok-free.app https://servbay.local --request-header-add='host: servbay.local'

Al ejecutar estos comandos correctamente, el cliente Ngrok mostrará en el terminal el estado del túnel, la dirección pública asignada (como https://xxxx.ngrok-free.app o su dominio específico) y la consola de monitoreo en tiempo real (normalmente en http://127.0.0.1:4040).

Verificación del Servicio

Una vez que la configuración está completa y el túnel Ngrok funciona, siga estos pasos para verificar el acceso público:

1. Obtener la dirección pública: Localice la línea Forwarding en el terminal con el cliente Ngrok y apunte la URL pública que comienza por https://.
2. Acceso desde navegador: Desde cualquier dispositivo conectado a Internet, acceda mediante navegador a la URL pública obtenida en el paso anterior (por ejemplo, https://cunning-lacewing-fresh.ngrok-free.app o su dominio fijo).
3. Verificar resultados:
   • Confirme que el contenido de su sitio alojado en ServBay se carga correctamente en el navegador.
   • Compruebe que la barra de direcciones muestra la conexión segura HTTPS. Ngrok provee un certificado SSL válido para el túnel por defecto.
   • Puede visualizar los registros de solicitudes y estadísticas de tráfico en el terminal del cliente Ngrok o bien en la interfaz web local (http://127.0.0.1:4040) para asegurarse de que las solicitudes llegan y ServBay las gestiona correctamente.

Ilustración: Acceso exitoso al túnel creado por Ngrok desde un navegador web

Consejos Avanzados y Consideraciones

1. Gestión de dominios:
   • Con el plan gratuito, Ngrok suele asignar un subdominio aleatorio .ngrok-free.app y el túnel está limitado en tiempo de conexión.
   • Registre una cuenta y en el Dashboard de Ngrok podrá configurar un dominio fijo, evitando que cambie la URL pública cada vez que inicia el túnel.
   • Los planes de pago de Ngrok permiten enlazar su propio dominio, y ofrecen más ancho de banda, conexiones concurrentes y funcionalidades avanzadas.
2. Mapeo de múltiples servicios: Si necesita exponer múltiples servicios o puertos locales de ServBay, puede iniciar varios procesos de túnel Ngrok, o definirlos y gestionarlos usando el archivo de configuración de Ngrok (usualmente en ~/.config/ngrok/ngrok.yml). Ejemplo de mapeo de un sitio web de ServBay y otro servicio local:

   # Mapear servbay.local en ServBay (HTTPS 443 y enrutamiento por Host)
   ngrok http --domain=servbay-website.ngrok-free.app https://servbay.local --request-header-add='host: servbay.local'
   
   # En otra terminal o por configuración, mapear aplicación Node.js local en el puerto 3000
   ngrok http --domain=nodejs-api.ngrok-free.app http://localhost:3000

   Nota: Para hosts virtuales en ServBay, se recomienda mapear con https://[dominio-local] y --request-header-add, en vez de apuntar directamente a los puertos 80/443, ya que ServBay maneja todas las solicitudes para todos los hosts virtuales en esos puertos.
3. Comandos de diagnóstico:
   • ngrok config check: Verifica que la sintaxis del archivo de configuración de Ngrok (usualmente en ~/.config/ngrok/ngrok.yml) sea válida.
   • ngrok logs: Muestra en tiempo real los registros detallados del cliente Ngrok, útil para diagnosticar problemas de conexión o enrutamiento de solicitudes.
4. Seguridad: Exponer servicios locales a Internet implica riesgos. Asegúrese de compartir únicamente servicios seguros y mantenga el túnel activo solo cuando sea necesario. Los planes de pago de Ngrok incluyen características adicionales como listas blancas de IP y restricciones de acceso.

Solución de Problemas

Síntoma	Solución
Tiempo de conexión excedido o página que no carga	Verifique que el sitio objetivo de ServBay esté en funcionamiento y disponible mediante el dominio local (por ejemplo, acceda a https://servbay.local desde su propio navegador local). Asegúrese de que el servidor web en ServBay (como Caddy o Nginx) esté operativo y revise que el firewall local permita la conexión de Ngrok.
Error de certificado HTTPS (advertencia browser)	Ngrok proporciona certificados HTTPS válidos para los dominios públicos asignados. Si encuentra errores de certificado accediendo al dominio público de Ngrok, la causa suele estar en la configuración del túnel o en la red, no en ServBay. Confirme que accede a una URL https:// asignada por Ngrok. Si el error ocurre accediendo al dominio local de ServBay, revise la configuración SSL local.
Desconexión intermitente o ralentizaciones	Verifique la estabilidad de su conexión a Internet. Las fluctuaciones pueden interrumpir el túnel. Si es posible, utilice red cableada. Para máxima fiabilidad, valore los planes de pago de Ngrok, que ofrecen mejor infraestructura y mayor ancho de banda.
Se muestra la página por defecto de ServBay en vez del sitio deseado	Asegúrese de que la dirección <LOCAL_ENDPOINT> del comando ngrok http sea correcta y que el parámetro --request-header-add='host: <VIRTUAL_HOST>' establezca exactamente el mismo dominio local configurado en ServBay. Esto es clave para un enrutamiento adecuado hacia el sitio objetivo.

Preguntas Frecuentes (FAQ)

• P: ¿Se puede mapear el servicio de bases de datos de ServBay?

  R: Ngrok está orientado principalmente a túneles HTTP/HTTPS. Si bien tiene soporte para túneles TCP que permiten exponer bases de datos, esto se escapa de la presente guía y no se recomienda por motivos de seguridad. Para acceso remoto a bases de datos, considere túneles SSH u otras alternativas más seguras.

• P: ¿Cambia la URL pública de Ngrok cada vez que inicio el túnel?

  R: Con el plan gratuito, Ngrok asigna un subdominio .ngrok-free.app generalmente aleatorio. Para tener un dominio fijo, es necesario registrar una cuenta y configurarlo en el Dashboard o contratar un plan de pago.

• P: ¿Ngrok afecta el rendimiento de ServBay en mi máquina local?

  R: Ngrok añade cierta latencia porque las solicitudes pasan por sus servidores, pero para desarrollo, pruebas y demos esto suele ser insignificante. El rendimiento real de su servicio en ServBay depende principalmente de la capacidad de su máquina y la eficiencia de su aplicación.

Conclusión

Integrando Ngrok, los usuarios de ServBay pueden compartir de forma sencilla, segura y eficiente los proyectos web desarrollados localmente a través de Internet. La solución evita configuraciones de red complejas y resulta ideal para colaboración remota, demostraciones a clientes, integración y pruebas con servicios de terceros o dispositivos móviles. Ngrok proporciona monitoreo de tráfico en tiempo real y avanzadas opciones de seguridad (algunas solo bajo suscripción). Para aplicaciones críticas o cuando se requieren dominios fijos, se recomienda considerar un plan de pago de Ngrok para obtener una experiencia más estable y completa.