Como usar o ngrok no Rails em 2025

Este artigo foi atualizado em agosto de 2025

Há muitas ocasiões durante o desenvolvimento em que um servidor localhost simplesmente não é suficiente. É nessas horas que podemos usar uma ferramenta bem legal chamada ngrok. O ngrok cria túneis. Esses túneis conectam seu código local a um site público, sem a necessidade de nenhuma configuração complicada. O principal caso de uso para desenvolvedores da Vonage é ao utilizar uma API que depende de webhooks para enviar informações automatizadas. Por exemplo, se você estiver criando recursos de mensagens, como respostas sugeridas por RCS com Ruby on Rails, o ngrok facilita os testes locais, expondo seus endpoints de webhooks à internet pública.

O caso de uso que nos interessa neste artigo é utilizar o ngrok com o Ruby on Rails ao desenvolver um projeto e permitir que outros usuários acessem-no pelo navegador. Isso permite a simulação mais realista possível. Além disso, é muito legal compartilhar algo com os amigos, mesmo que você nunca o implemente publicamente.

Você pode ler mais sobre isso em Testes com o ngrok nas ferramentas do nosso portal para desenvolvedores.

Instalando o ngrok

Conforme consta na documentação do ngrok, a instalação completa do ngrok envolve três etapas: instalar o agente do ngrok, criar um Account e, em seguida, conectar o agente ao seu Account. E, para o Rails, temos mais uma etapa: adicionar o ngrok ao seu ambiente de desenvolvimento.

Instalação do agente

No macOS, use o HomeBrew:

brew install ngrok

No Linux, use o Apt:

curl -sSL https://ngrok-agent.s3.amazonaws.com/ngrok.asc \
  | sudo tee /etc/apt/trusted.gpg.d/ngrok.asc >/dev/null \
  && echo "deb https://ngrok-agent.s3.amazonaws.com buster main" \
  | sudo tee /etc/apt/sources.list.d/ngrok.list \
  && sudo apt update \
  && sudo apt install ngrok

No Windows, use Chocolatey:

choco install ngrok

Extrair o agente

No Linux ou no Mac OS X, você pode descompactar o ngrok a partir de um terminal com o seguinte comando. No Windows, basta clicar duas vezes no arquivo ngrok.zip para descompactá-lo.

unzip /path/to/ngrok.zip

Criando um Account

Se você ainda não tem um Account, cadastre-se no painel do ngrok. Se você já tiver um account, faça login. De qualquer forma, com seu account gratuito, você precisará obter seu authtoken para a próxima etapa.

As contas gratuitas do ngrok geram URLs temporárias e aleatórias. Para subdomínios personalizados ou permanentes, é necessária uma conta paga.

Como vincular seu agente à sua Account:

Aqui, precisaremos do authtoken da etapa anterior. O authtoken é o que o agente usa para fazer login na sua Account ao criar um túnel.

Execute a seguinte linha na linha de comando. Não se esqueça de substituir TOKEN pelo seu authtoken real.

ngrok config add-authtoken TOKEN

Executando o Ngrok

A melhor parte do ngrok é que ele tem o comando mais simples que já existiu. Basta uma única linha para indicar em qual porta ele deve escutar e servir o conteúdo. Em uma aplicação Rails, sabemos que o Puma adora a porta 3000!

ngrok http 3000

Adicionando o ngrok ao seu ambiente de desenvolvimento Rails

Na sua aplicação, você terá um arquivo config/environments/development.rb. Esse arquivo informa ao Rails como configurar o ambiente de desenvolvimento.

Aqui, precisaremos adicionar uma linha:

config.hosts << "\[ngrok url]"

ngrok terminal output showing active tunnel forwarding localhost:3000 to a public ngrok URL.

Por exemplo, no caso acima, ao executar o ngrok, eu acrescentaria:

Rails.application.configure do
  config.hosts << "XXXX.ngrok.app"

É importante que essa linha seja adicionada dentro do Rails.application.configure do bloco.

Agora podemos executar nosso servidor Rails:

rails s

E agora nosso aplicativo já está funcionando, e você pode convidar amigos para experimentá-lo enviando a eles a URL do ngrok.

Se você estiver usando variáveis de ambiente para gerenciar configurações como a URL do ngrok ou a configuração de host do Rails, confira nosso guia sobre trabalhar com variáveis de ambiente em Ruby

Avançado: Expressão regular para lidar com URLs dinâmicas do ngrok

Se você estiver usando um account gratuito do ngrok, a URL mudará com frequência. Você pode usar a expressão regular a seguir para definir a configuração do host uma vez e nunca mais precisar atualizá-la.

Rails.application.configure do
  config.hosts << /.*\.ngrok-free\.app$/

Erros comuns

Esses são alguns erros comuns que eu cometo; por mais que eu tente, eles parecem sempre se repetir.

• Mantendo o “https” no arquivo config.hosts

• Deixar um espaço no arquivo config.hosts

• Esquecer de reiniciar o servidor do Rails após adicionar ou atualizar o arquivo config.hosts no ambiente de desenvolvimento

• Incluindo o arquivo config.hosts fora do bloco “Rails.application.configure do”

Participe da conversa

Agora que você já está pronto, pode testar fluxos de trabalho baseados em webhooks, como o envio de mensagens SMS com Ruby on Railsou qualquer recurso que dependa de callbacks externos para o seu servidor local.

Compartilhe conosco suas ideias sobre ferramentas! Venha participar da conversa na nossa Slack da Comunidade Vonage ou envie-nos uma mensagem no Twitter.