🌐 ngrok · Expor servidores locais à Internet

📡 O que é o ngrok?

O ngrok é uma ferramenta multiplataforma que cria túneis seguros entre o seu computador local e a Internet pública. Permite expor servidores web, APIs, SSH ou qualquer serviço TCP/IP que esteja em execução na sua máquina (ex: localhost:3000, localhost:80, porta 22) através de um endereço público https://*.ngrok-free.app.

🎯 Para que serve?
• Demonstrar projetos web a clientes sem precisar de servidor em produção.
• Testar webhooks (pagamentos, notificações) em ambiente de desenvolvimento.
• Partilhar um servidor local com colegas ou fazer testes remotos.
• Expor temporariamente uma API, base de dados ou ambiente de desenvolvimento.
• Trabalhar com bots de WhatsApp, Telegram ou plataformas que exigem HTTPS público.

🔐 Como funciona?
O ngrok estabelece uma ligação segura entre o agente (no seu PC) e a cloud da ngrok. A cloud atribui um subdomínio aleatório (ex: abc123.ngrok-free.app) ou um domínio personalizado (planos pagos) e encaminha todo o tráfego HTTPS/HTTP diretamente para o serviço local que definiu.

📋 Pré‑requisitos

Windows 10/11 ou Ubuntu 20.04/22.04/24.04 (recomenda-se versão LTS).
Acesso à Internet para descarregar o binário e autenticar.
Um servidor/serviço local já em execução (ex: Apache, Nginx, Node.js, Flask, SSH).
Conta gratuita em ngrok.com (recomendada para maior tempo de túnel e subdomínios fixos).

⚠️ Aviso de segurança: Qualquer pessoa com o URL público pode aceder ao seu serviço local. Não exponha ambientes com dados sensíveis ou sem autenticação adequada. Use sempre HTTPS e, se possível, autenticação básica.

🪟 Instalação no Windows

⬇️ Descarregar o executável

Aceda a https://ngrok.com/download
Escolha a versão para Windows (ngrok-vX-stable-windows-amd64.zip)
Faça o download e extraia o ficheiro ngrok.exe para uma pasta, por exemplo: C:\ngrok
            

📂 Adicionar ao PATH (opcional, mas recomendado)

Abra o "Menu Iniciar" e procure "Variáveis de Ambiente"
Clique em "Variáveis de Ambiente..." → na secção "Variáveis do sistema", selecione "Path" → "Editar..."
Adicione o caminho da pasta onde está o ngrok.exe (ex: C:\ngrok)
Clique em OK e reinicie o PowerShell/CMD.
            

✅ Verificar instalação

PS C:\> ngrok --version
ngrok version 3.x.x
            

✔️ Se aparecer a versão, o ngrok está pronto.

🐧 Instalação no Ubuntu (Linux)

⬇️ Método oficial (recomendado)

# Descarregar o pacote .deb mais recente
wget https://binaries.ngrok.com/ngrok-v3-stable-linux-amd64.deb

# Instalar com dpkg
sudo dpkg -i ngrok-v3-stable-linux-amd64.deb

# (opcional) remover o ficheiro após instalação
rm ngrok-v3-stable-linux-amd64.deb
            

📦 Alternativa via Snap (Ubuntu)

sudo snap install ngrok

✅ Verificar instalação

ngrok --version
ngrok version 3.x.x
            

💡 Dica: O binário é instalado globalmente (geralmente em /usr/bin/ngrok), pode ser executado a partir de qualquer diretório.

🔑 Autenticar o ngrok (necessário para túneis)

Para utilizar o ngrok, precisa de associar o agente à sua conta (gratuita ou paga).

📧 Obter o token de autenticação

Crie uma conta em https://dashboard.ngrok.com/signup
Após login, aceda a https://dashboard.ngrok.com/get-started/your-authtoken
Copie o token (uma sequência longa)
            

⚙️ Configurar o token (Windows e Ubuntu)

ngrok config add-authtoken SEU_TOKEN_AQUI

✔️ O token é guardado em ~/.ngrok3/ngrok.yml (Linux) ou %USERPROFILE%\.ngrok3\ngrok.yml (Windows).

🔁 Se preferir configurar manualmente, crie o ficheiro de configuração com:
ngrok config edit e adicione:

version: "2"
authtoken: SEU_TOKEN_AQUI

🚀 Utilizar ngrok (exemplos práticos)

🌐 Expor um servidor web na porta 80

ngrok http 80

O ngrok irá gerar um URL do tipo https://xxxx.ngrok-free.app. Qualquer pessoa com esse link acede ao seu servidor local.

🧪 Expor um servidor Node.js/React (porta 3000)

ngrok http 3000

🐍 Expor uma aplicação Flask/Django (porta 5000)

ngrok http 5000

🔒 Expor SSH (porta 22) – útil para acesso remoto

ngrok tcp 22

Receberá um endereço como 0.tcp.ngrok.io:12345.

📌 Expor com subdomínio fixo (plano gratuito permite reservar domínios estáticos)

ngrok http --domain=meusubdominio.ngrok-free.app 80

📄 Guardar pedidos HTTP para inspeção (web interface)

ngrok http 80 --inspect

Acede à interface de inspeção em http://127.0.0.1:4040 para ver detalhes de cada requisição.

✅ Após iniciar o túnel, o terminal mostra informações como:
- URL público (Forwarding)
- Web Interface (localhost:4040)
- Estatísticas de tráfego

🛠️ Comandos avançados e resolução de erros

📋 Listar túneis ativos

ngrok tunnel list

🛑 Parar túneis e terminar o agente

# No terminal onde o ngrok está a correr, pressione Ctrl + C
# Ou, em Windows PowerShell (Admin):
taskkill /F /IM ngrok.exe

# Em Ubuntu / Linux:
pkill ngrok
            

🔁 Parar um túnel específico mantendo o agente

ngrok tunnel stop

📁 Configuração persistente (ficheiro YAML)

# Editar ficheiro de configuração
ngrok config edit

# Exemplo de conteúdo (Windows: %USERPROFILE%\.ngrok3\ngrok.yml)
version: "2"
authtoken: SEU_TOKEN
tunnels:
  web:
    proto: http
    addr: 80
  ssh:
    proto: tcp
    addr: 22
            

🧪 Testar túnel com configuração guardada

ngrok start web
ngrok start ssh
ngrok start --all
            

⚠️ Erros comuns e soluções

Erro	Causa	Solução
`ERR_NGROK_334` endpoint already online	Um túnel com o mesmo subdomínio já está ativo noutra sessão	1. Parar o túnel anterior (`Ctrl+C` no terminal onde corre) 2. Usar `taskkill /F /IM ngrok.exe` (Windows) 3. Usar `--subdomain` diferente
`Failed to start tunnel` authentication failed	Token ausente ou inválido	Executar `ngrok config add-authtoken` com o token correto
`address already in use`	A porta local já está ocupada	Verifique se o serviço local está em execução e noutra porta
`session rate limit`	Plano gratuito tem limites de conexões por minuto	Aguarde alguns segundos ou faça upgrade para plano pago

❗ Importante no Windows: Se o comando ngrok service stop retornar Acesso negado, execute o PowerShell/CMD como administrador ou utilize taskkill /F /IM ngrok.exe.

🔍 Interface de Inspeção (localhost:4040)
Enquanto o túnel estiver ativo, aceda a http://127.0.0.1:4040 para:
• Ver todas as requisições feitas ao URL público (headers, corpo, método).
• Reenviar pedidos (Replay).
• Analisar erros e latência.
• Configurar túneis e autenticação básica.

📊 Uso em produção vs desenvolvimento

# Adicionar autenticação básica ao túnel (protege o URL público)
ngrok http 80 --basic-auth="utilizador:password"

# Limitar IPs (apenas planos pagos)
ngrok http 80 --allow-cidr="192.168.1.0/24"
            

🎉 Com estes comandos e conceitos, consegue expor qualquer serviço local de forma rápida e segura. O ngrok é uma ferramenta indispensável para developers, consultores e equipas remotas.