DEV Community

Cover image for Como Rodar um Servidor Mock Auto-Hospedado na Sua Intranet com Apidog
Lucas
Lucas

Posted on • Originally published at apidog.com

Como Rodar um Servidor Mock Auto-Hospedado na Sua Intranet com Apidog

Algumas equipes não podem enviar tráfego para a nuvem. Você pode estar atrás de um firewall corporativo que bloqueia chamadas de saída para serviços de terceiros, sob regras de conformidade que exigem que dados de solicitação e resposta permaneçam em máquinas controladas pela empresa, ou em um ambiente isolado (air-gapped). Nesses cenários, uma URL de mock hospedada por terceiros não é uma opção, mesmo quando os dados de mock são fictícios.

Experimente o Apidog hoje

O Apidog resolve esse caso com um runner auto-hospedado. Em vez de direcionar requisições para o mock em nuvem do Apidog, você executa um programa em um servidor da sua rede. Esse programa retorna respostas de mock localmente. O design da API, os esquemas e as expectativas continuam no projeto Apidog; apenas o serviço que responde aos mocks é executado na sua infraestrutura.

Este guia mostra quando usar o runner, como implantá-lo e como ativar o ambiente Runner Mock. Para uma visão mais ampla, consulte o guia sobre servidores de mock de API auto-hospedados e a Iniciativa OpenAPI, especificação usada como base para gerar mocks.

O que é o runner auto-hospedado

O Apidog Self-hosted Runner — também chamado de General Runner — é um programa executado em um servidor autônomo. Ele pode:

  1. Executar testes automatizados agendados.
  2. Importar documentos de API.
  3. Retornar respostas de mock.

Neste artigo, o foco é o terceiro item: servir mocks dentro da sua rede.

Diagrama do runner auto-hospedado

Depois de implantar o General Runner e configurar o Server Host, o Apidog cria automaticamente um ambiente chamado Runner Mock no projeto. As requisições enviadas por esse ambiente recebem respostas do runner auto-hospedado, e não do mock em nuvem.

O design do mock permanece o mesmo. O que muda é o host que processa e responde às requisições.

Use o runner quando uma ou mais condições forem verdadeiras:

  • O tráfego de saída para hosts externos é bloqueado ou auditado.
  • Políticas de conformidade exigem que os dados permaneçam na infraestrutura interna.
  • O ambiente é isolado (air-gapped).
  • Você precisa que a latência do mock permaneça dentro da LAN.

Se sua equipe pode acessar a internet e não há restrições de tráfego, o mock em nuvem do Apidog é mais simples, pois não exige infraestrutura adicional.

A documentação não especifica diferenças explícitas de plano ou preço para o General Runner. Para implantá-lo, você precisa ser administrador da equipe ou do projeto, já que a configuração fica em Recursos da Equipe.

Pré-requisitos

Antes de iniciar, prepare:

  • Docker 20.10.0 ou superior.
  • Um host Linux, macOS ou Windows.
  • Um IP ou hostname estável para o runner em ambientes compartilhados.
  • Permissão de administrador no Apidog.

Verifique a versão do Docker:

docker --version
Enter fullscreen mode Exit fullscreen mode

A documentação recomenda Docker 20.10.13 ou mais recente.

Implantar o General Runner

O Apidog gera o comando de implantação com um token incluído. Você não precisa montar esse token manualmente.

1. Gerar o comando no Apidog

No Apidog:

  1. Abra a página inicial.
  2. Selecione sua equipe.
  3. Na barra lateral direita, abra Recursos.
  4. Selecione Implantar General Runner.

No modal de configuração, defina:

  • Sistema Operacional do Servidor: Linux, macOS ou Windows.
  • Imagem Docker:
    • General: inclui Node.js 18, Java 21, Python 3 e PHP 8.
    • Slim: inclui somente Node.js 18.
    • Custom: permite usar seu próprio Dockerfile para runtimes adicionais.
  • Porta Exposta: configurada com -p.
  • Diretório de Dados Montado: configurado com -v, para persistir dados após reinicializações.

Exemplo de mapeamento de portas:

-p 80:4524
Enter fullscreen mode Exit fullscreen mode

Nesse caso, a porta 80 do host aponta para a porta 4524 do runner.

Copie e armazene o comando assim que ele for exibido. O token faz parte do comando e, por segurança, ele é mostrado apenas uma vez. Se você o perder, gere um novo comando.

2. Executar o contêiner

Cole o comando gerado no terminal do servidor. Um exemplo aproximado é:

docker run -d \
  --name apidog-runner \
  -p 80:4524 \
  -v /opt/apidog-runner/data:/app/data \
  apidog/runner:latest \
  --token <SEU_TOKEN_GERADO>
Enter fullscreen mode Exit fullscreen mode

Seu comando real terá o token gerado pelo Apidog.

Confirme que o contêiner iniciou:

docker ps
Enter fullscreen mode Exit fullscreen mode

Você deve ver o contêiner do runner e o mapeamento de portas configurado.

3. Confirmar o registro

Volte ao Apidog:

  1. Abra Recursos da Equipe.
  2. Entre em General Runner.
  3. Clique em atualizar.

O runner deve aparecer como implantado com o status Iniciado.

Estados importantes:

Status Significado
Iniciado (Started) O runner está conectado ao Apidog e processando tarefas.
Parado (Stopped) O runner foi interrompido manualmente e não processa tarefas.
Offline O runner perdeu conexão com o Apidog. Verifique o contêiner e a rede.

Se o runner não aparecer imediatamente, aguarde alguns segundos e atualize novamente.

Ativar o Runner Mock

Implantar o contêiner não redireciona automaticamente o tráfego de mock. Você precisa configurar o endereço público ou interno pelo qual o runner será acessado.

Em Recursos da Equipe > General Runner, localize o campo Server Host.

Use o endereço que os clientes precisam alcançar, por exemplo:

http://127.0.0.1:80
Enter fullscreen mode Exit fullscreen mode

Para testes locais.

http://runner.internal.example.com:80
Enter fullscreen mode Exit fullscreen mode

Para um host de intranet compartilhado.

https://runner.example.com:443
Enter fullscreen mode Exit fullscreen mode

Quando houver um proxy reverso com terminação TLS.

Depois de salvar o Server Host, o Apidog cria automaticamente o ambiente Runner Mock.

Para confirmar:

  1. Abra o projeto.
  2. Vá para Gerenciamento de Ambiente.
  3. Verifique se Runner Mock aparece na lista.

Você não precisa criar esse ambiente manualmente.

Enviar uma requisição para o mock auto-hospedado

Suponha que seu projeto tenha o endpoint:

GET /orders/{orderId}
Enter fullscreen mode Exit fullscreen mode

No Apidog:

  1. Abra o endpoint.
  2. No seletor de ambiente, escolha Runner Mock.
  3. Envie a requisição.

Você também pode testar diretamente pelo terminal:

curl http://runner.internal.example.com:80/orders/10583
Enter fullscreen mode Exit fullscreen mode

Com um esquema Order bem definido, a resposta pode ser semelhante a:

{
  "orderId": 10583,
  "customerEmail": "amelia.turner@example.com",
  "status": "shipped",
  "total": 148.5,
  "currency": "USD",
  "createdAt": "2026-07-14T09:32:11Z"
}
Enter fullscreen mode Exit fullscreen mode

A resposta é gerada pelo runner dentro da sua rede. O Apidog usa os tipos e nomes de campos definidos no esquema para gerar dados coerentes, como customerEmail, valores numéricos e datas.

Para entender esse comportamento em mais detalhes, consulte o artigo sobre geração automática de dados de mock realistas com smart mock.

Se precisar controlar a resposta com precisão, crie uma expectativa de mock no endpoint. O runner servirá essa expectativa da mesma maneira que o mock em nuvem. Os princípios de mocking de API continuam os mesmos; apenas o host de execução muda.

HTTPS, persistência e detalhes de produção

Use um proxy reverso para HTTPS

O runner não possui gerenciamento embutido de certificados HTTPS. Ele não provisiona nem administra certificados TLS.

Para expor o runner com https://, coloque um proxy reverso na frente do contêiner, como o Nginx.

Exemplo mínimo:

server {
    listen 443 ssl;
    server_name runner.example.com;

    ssl_certificate     /etc/ssl/certs/runner.example.com.pem;
    ssl_certificate_key /etc/ssl/private/runner.example.com.key;

    location / {
        proxy_pass http://127.0.0.1:4524;
        proxy_set_header Host $host;
    }
}
Enter fullscreen mode Exit fullscreen mode

Com essa configuração:

  • O Nginx recebe conexões HTTPS na porta 443.
  • O Nginx termina o TLS.
  • O Nginx encaminha as requisições para o runner na porta 4524.

Então, configure o Server Host como:

https://runner.example.com:443
Enter fullscreen mode Exit fullscreen mode

Sem um proxy reverso, use HTTP:

http://host:port
Enter fullscreen mode Exit fullscreen mode

Não configure uma URL https:// diretamente no Server Host se o runner estiver servindo apenas HTTP. Consulte também o guia da MDN sobre HTTPS.

Montar arquivos em caminhos esperados

Se mocks ou testes precisarem de arquivos extras, monte-os nos caminhos esperados pelo contêiner:

Tipo de arquivo Caminho no contêiner
Programas externos /app/external-programs/
Configuração de banco de dados /app/database/database-connections.json
Certificados SSL de cliente /app/ssl/ssl-client-cert-list.json

Exemplo de montagem de um diretório local:

-v /opt/apidog-runner/external-programs:/app/external-programs
Enter fullscreen mode Exit fullscreen mode

Use volumes Docker para garantir que esses dados sobrevivam a reinicializações e reimplantações.

Atualizar ou reimplantar

Quando houver uma nova versão do runner, o Apidog exibirá a opção Atualização (Upgrade). Em Mais Ações, também existe Reimplantar (Redeploy).

Ambas as operações interrompem temporariamente o contêiner enquanto uma nova instância é iniciada. As tarefas agendadas configuradas no Apidog permanecem intactas; a interrupção afeta apenas o período de reinicialização do serviço.

Runner e CLI: ferramentas diferentes

O General Runner e a CLI do Apidog têm finalidades diferentes:

Ferramenta Finalidade
General Runner Serviço de longa duração para mocks auto-hospedados, tarefas agendadas e importações.
Apidog CLI Execução pontual de testes em pipelines de CI/CD.

A CLI não inicia nem hospeda um servidor de mock. Não existem comandos como:

apidog run mock
Enter fullscreen mode Exit fullscreen mode

ou:

apidog mock serve
Enter fullscreen mode Exit fullscreen mode

O comando apidog run executa cenários, pastas de cenários e suítes de teste. Já o grupo de comandos mock gerencia expectativas de mock como dados, mas não serve tráfego HTTP.

Use a CLI para validar o backend real contra o contrato da API:

apidog run -t <scenario_id> -e <env_id> -r html,cli
Enter fullscreen mode Exit fullscreen mode

Esse comando executa cenários de teste e gera relatórios HTML e CLI.

Para instalar a CLI:

npm install -g apidog-cli
Enter fullscreen mode Exit fullscreen mode

Ela requer Node.js 16 ou superior. Consulte o guia de instalação da CLI do Apidog para configurar apidog login e tokens.

Para executar testes a cada push, integre a CLI ao pipeline usando o guia de CI/CD da CLI do Apidog.

O artigo sobre mocking de APIs pela CLI explica por que a CLI administra definições de mock, mas não hospeda o servidor.

FAQ

Preciso do runner auto-hospedado se a equipe pode acessar a internet?

Provavelmente não. O mock em nuvem não exige infraestrutura adicional e é a alternativa mais simples.

Use o runner quando:

  • O tráfego externo estiver bloqueado ou auditado.
  • Regras de conformidade exigirem que os dados permaneçam internamente.
  • O ambiente for air-gapped.
  • A latência precisar permanecer dentro da rede local.

Para comparar as abordagens, consulte o guia de mock na nuvem do Apidog.

A CLI do Apidog pode iniciar um servidor de mock auto-hospedado?

Não. A CLI executa testes com apidog run e gerencia expectativas de mock por meio dos comandos mock.

O serviço de mock é executado pelo General Runner ou pelo mock em nuvem, nunca pela CLI.

O runner suporta HTTPS diretamente?

Não. Ele não inclui certificados nem os provisiona automaticamente.

Use um proxy reverso, como Nginx, para terminar TLS e configure o Server Host com a URL HTTPS do proxy.

Por que o runner não aparece após executar o comando?

Siga esta sequência:

docker ps
Enter fullscreen mode Exit fullscreen mode
  1. Confirme que o contêiner está em execução.
  2. Abra Recursos da Equipe > General Runner.
  3. Clique em atualizar.
  4. Verifique a conectividade de rede entre o runner e o Apidog.

O status desejado é Iniciado. Se aparecer Offline, a conexão foi perdida.

Várias equipes podem compartilhar um único runner?

O runner é registrado na equipe em que foi implantado, e o ambiente Runner Mock é criado por projeto.

Se você administra equipes distribuídas, consulte o guia sobre compartilhamento de ambientes de mock entre equipes globais para decidir quantos runners implantar e onde posicioná-los.

Conclusão

O General Runner permite manter tráfego e respostas de mock dentro da infraestrutura que você controla. O fluxo é direto:

  1. Implante o contêiner Docker.
  2. Confirme que o runner está iniciado.
  3. Configure o Server Host.
  4. Selecione o ambiente Runner Mock no projeto.
  5. Envie requisições para o mock dentro da sua rede.

Use o runner quando a nuvem estiver fora dos limites. Caso contrário, o mock em nuvem continua sendo a opção com menor custo operacional.

Pronto para executar mocks na sua própria rede? Baixe o Apidog, implante um runner e sirva a primeira resposta de Runner Mock sem enviar tráfego pela internet pública.

Top comments (0)