🌐 Guía Completa de ngrok para Desarrollo Local
🚀 ¿Qué es ngrok?
ngrok es una herramienta que expone servidores locales a internet de forma segura, creando un túnel HTTPS hacia tu máquina local. Es perfecto para:
- ✅ Testing de APIs locales desde dispositivos móviles
- ✅ Demostraciones en vivo
- ✅ Desarrollo frontend/backend separado
- ✅ Webhooks locales
- ✅ Acceso remoto temporal
📥 Instalación
Windows
# Descargar ngrok curl -o ngrok.zip https://bin.equinox.io/c/bNyj1mQVY4c/ngrok-v3-stable-windows-amd64.zip # Extraer powershell -Command "Expand-Archive -Path ngrok.zip -DestinationPath . -Force" # Verificar instalación .\ngrok.exe version
macOS
# Con Homebrew brew install ngrok/ngrok/ngrok # Manual curl -o ngrok.zip https://bin.equinox.io/c/bNyj1mQVY4c/ngrok-v3-stable-darwin-amd64.zip unzip ngrok.zip sudo mv ngrok /usr/local/bin/
Linux
# Con snap sudo snap install ngrok # Manual curl -o ngrok.zip https://bin.equinox.io/c/bNyj1mQVY4c/ngrok-v3-stable-linux-amd64.zip unzip ngrok.zip sudo mv ngrok /usr/local/bin/
⚙️ Configuración Inicial
1. Crear cuenta en ngrok
- Ve a https://ngrok.com
- Crea una cuenta gratuita
- Copia tu authtoken del dashboard
2. Configurar autenticación
# Windows .\ngrok.exe config add-authtoken TU_TOKEN_AQUI # macOS/Linux ngrok config add-authtoken TU_TOKEN_AQUI
3. Verificar configuración
ngrok version
🛠️ Comandos Básicos
Exponer un puerto local
# Exponer puerto 3000 ngrok http 3000 # Exponer puerto específico con nombre ngrok http 8080 --name="mi-api" # Exponer con subdominio personalizado (plan pago) ngrok http 3000 --subdomain=mi-app
Exponer múltiples puertos
# Terminal 1 ngrok http 3000 # Terminal 2 ngrok http 8080
Exponer con configuración personalizada
# Con archivo de configuración ngrok http 3000 --config=./ngrok.yml # Con headers personalizados ngrok http 3000 --host-header=localhost:3000
🔍 Gestión de Túneles
Ver túneles activos
Método 1: Interfaz Web
# Abrir ngrok en el navegador ngrok http 3000 # Luego ve a: http://localhost:4040
Método 2: API REST
# Ver todos los túneles curl http://localhost:4040/api/tunnels # Ver información específica curl http://localhost:4040/api/tunnels/nombre-del-tunel
Método 3: PowerShell (Windows)
# Obtener información de túneles $tunnels = Invoke-RestMethod -Uri 'http://localhost:4040/api/tunnels' $tunnels.tunnels | Select-Object name, public_url, proto
Cerrar túneles
Método 1: Interfaz Web
- Ve a
http://localhost:4040 - Haz clic en el botón "Stop" del túnel
Método 2: API REST
# Cerrar túnel específico curl -X DELETE http://localhost:4040/api/tunnels/nombre-del-tunel
Método 3: Terminal
# Presionar Ctrl+C en la terminal donde está corriendo ngrok
Método 4: PowerShell (Windows)
# Cerrar todos los túneles $tunnels = Invoke-RestMethod -Uri 'http://localhost:4040/api/tunnels' foreach ($tunnel in $tunnels.tunnels) { Invoke-RestMethod -Uri "http://localhost:4040/api/tunnels/$($tunnel.name)" -Method DELETE }
📱 Configuración con NexusGO
1. Configurar túnel para tu API
# Si tu API corre en puerto 57608 ngrok http 57608
2. Obtener URL pública
# La salida será algo como: # Forwarding https://abc123.ngrok.io -> http://localhost:57608
3. Actualizar configuración de la app
Editar app/src/develop/res/xml/remote_config_defaults.xml:
<entry> <key>api_url</key> <value>https://abc123.ngrok.io/</value> </entry>
4. Compilar con flavor develop
./gradlew assembleDevelopDebug
5. Instalar en dispositivo
./gradlew installDevelopDebug
🔧 Configuración Avanzada
Archivo de configuración ngrok.yml
# ~/.ngrok2/ngrok.yml o ngrok.yml version: "2" authtoken: TU_TOKEN_AQUI tunnels: web: proto: http addr: 3000 subdomain: mi-app-web api: proto: http addr: 8080 subdomain: mi-app-api db: proto: tcp addr: 5432
Usar configuración personalizada
ngrok start --all --config=ngrok.yml
🚨 Troubleshooting
Problemas Comunes
1. "tunnel session failed"
# Verificar authtoken ngrok config check # Reconfigurar token ngrok config add-authtoken TU_TOKEN_AQUI
2. "bind: address already in use"
# Verificar puertos en uso netstat -ano | findstr :4040 # Cambiar puerto de ngrok ngrok http 3000 --web-addr=localhost:4041
3. "failed to start tunnel"
# Verificar que el puerto local esté activo netstat -ano | findstr :3000 # Verificar firewall # Windows: Permitir ngrok.exe en Windows Firewall
4. "ngrok not found"
# Agregar ngrok al PATH # Windows: Agregar carpeta de ngrok al PATH del sistema # macOS/Linux: sudo mv ngrok /usr/local/bin/
Comandos de Diagnóstico
# Verificar configuración ngrok config check # Ver logs detallados ngrok http 3000 --log=stdout # Verificar conectividad ngrok version
📊 Monitoreo y Logs
Interfaz Web de ngrok
- URL:
http://localhost:4040 - Funciones:
- Ver túneles activos
- Monitorear tráfico
- Ver requests/responses
- Cerrar túneles
Logs en tiempo real
# Ver logs detallados ngrok http 3000 --log=stdout --log-level=debug
Métricas de uso
# Ver estadísticas curl http://localhost:4040/api/requests/http
🎯 Casos de Uso con NexusGO
Desarrollo Frontend/Backend
# Terminal 1: API Backend ngrok http 57608 --name="nexus-api" # Terminal 2: Frontend (si aplica) ngrok http 3000 --name="nexus-frontend"
Testing en Dispositivos Móviles
# Exponer API local ngrok http 57608 # Usar URL pública en la app móvil # https://abc123.ngrok.io/GetExcursionMasterData?
Demostraciones
# Túnel con subdominio personalizado (plan pago) ngrok http 57608 --subdomain=demo-nexus # URL: https://demo-nexus.ngrok.io
🔒 Seguridad
Buenas Prácticas
- ✅ Usar HTTPS (automático con ngrok)
- ✅ No exponer servicios sensibles
- ✅ Cerrar túneles cuando no se usen
- ✅ Usar authtoken válido
- ✅ Monitorear tráfico en la interfaz web
Limitaciones del Plan Gratuito
- 🔸 1 túnel simultáneo
- 🔸 URLs aleatorias
- 🔸 Límite de conexiones
- 🔸 Sin subdominios personalizados
📚 Recursos Adicionales
- Documentación oficial: https://ngrok.com/docs
- Dashboard: https://dashboard.ngrok.com
- API Reference: https://ngrok.com/docs/api
- Comunidad: https://github.com/inconshreveable/ngrok
🎉 ¡Listo para usar!
Con esta guía puedes:
- ✅ Instalar y configurar ngrok
- ✅ Exponer tu API local
- ✅ Configurar NexusGO para usar ngrok
- ✅ Gestionar túneles activos
- ✅ Solucionar problemas comunes
¡Happy coding! 🚀
Loading