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

Algumas equipes não conseguem enviar seu tráfego para a nuvem. Talvez você esteja atrás de um firewall corporativo que bloqueia chamadas de saída para serviços de terceiros. Talvez uma regra de conformidade diga que os dados de solicitação e resposta devem permanecer em máquinas que você controla. Talvez todo o ambiente seja isolado (air-gapped) e nada saia da intranet. Em qualquer um desses casos, uma URL de mock hospedada na infraestrutura de outra pessoa é inviável, mesmo quando os próprios dados de mock são falsos.

O Apidog lida com isso através de um runner auto-hospedado. Em vez de suas requisições irem para o mock na nuvem do Apidog, você implanta um pequeno programa em um servidor que você possui, e esse programa retorna as respostas de mock de dentro da sua própria rede. O design reside no seu projeto Apidog como sempre; apenas o serviço de mock se move para o seu hardware. Este guia explica o que é o runner, quando escolhê-lo em vez do mock na nuvem, como configurá-lo a partir da documentação, e uma distinção que confunde as pessoas: o runner não é a CLI. Se você quer uma visão mais ampla do porquê as equipes executam mocks em suas próprias máquinas, o guia sobre servidores de mock de API auto-hospedados cobre o caso geral, e a Iniciativa OpenAPI explica a especificação a partir da qual esses mocks são gerados. Quer acompanhar? Baixe o Apidog primeiro.

O que é o runner auto-hospedado

O Apidog Self-hosted Runner é um programa automatizado que você hospeda em um servidor autônomo. Ele é oficialmente chamado de General Runner e executa três tarefas: ele executa testes automatizados agendados, importa documentos de API e retorna respostas de mock. Essa terceira tarefa é o foco deste artigo.

Aqui está a ideia chave. Uma vez que você implanta um General Runner e configura seu Server Host, um novo ambiente chamado Runner Mock aparece automaticamente em seu projeto. Qualquer solicitação que você enviar através desse ambiente obtém sua resposta de mock do seu runner auto-hospedado, em vez do mock na nuvem do Apidog. O mesmo design de mock, os mesmos dados gerados, uma máquina diferente fazendo o serviço. Seu tráfego nunca sai da sua rede.

Esta é a alternativa auto-hospedada ao mock na nuvem. Se sua equipe pode acessar a internet e não tem nenhuma regra contra isso, o mock na nuvem do Apidog é mais simples porque não há nada a ser implantado. Opte pelo runner quando uma destas condições for verdadeira:

• O tráfego de saída para hosts externos é bloqueado ou fortemente auditado.
• Uma política de conformidade exige que os dados de solicitação permaneçam na infraestrutura interna.
• O ambiente é isolado (air-gapped) e não consegue alcançar um endpoint na nuvem de forma alguma.
• Você quer a latência do mock medida na sua própria LAN, não através da internet pública.

Se nenhuma dessas condições se aplicar, o host Docker extra é uma sobrecarga desnecessária. Seja honesto consigo mesmo sobre em qual situação você se encontra antes de provisionar um servidor.

Uma observação sobre planos e permissões. A documentação do Apidog não especifica uma distinção explícita entre gratuito e pago para o General Runner ou para o mock auto-hospedado, e não lista valores de preços para ele, então este guia não inventará nenhum. O que a configuração exige é permissão de administrador de equipe ou projeto, porque a implantação de um runner ocorre dentro de Recursos da Equipe, e apenas administradores podem abrir essas configurações. Se você não consegue ver o painel de Recursos, essa é a razão.

O que você precisa antes de começar

O runner é fornecido como um contêiner Docker, então o servidor que o hospeda precisa ter o Docker instalado. A documentação pede uma versão mínima de 20.10.0 e recomenda 20.10.13 ou mais recente. Verifique o que você tem:

docker --version

Você também precisa de um lugar para executá-lo: uma máquina Linux, macOS ou Windows que tanto os clientes Apidog da sua equipe quanto o serviço Apidog possam acessar. Em uma intranet, isso geralmente significa um servidor interno com um IP ou nome de host estável. Essa é a lista completa de pré-requisitos: Docker, um host e direitos de administrador na equipe. Todo o resto você configura dentro do próprio Apidog.

Implantar o General Runner

O comando de implantação é gerado para você de dentro do Apidog e contém um token, para que você não precise escrevê-lo manualmente. Veja o fluxo.

Gerar o comando

Abra a página inicial do Apidog, selecione sua equipe, clique em Recursos na barra lateral direita e escolha Implantar General Runner. Um pop-up aparecerá onde você configurará algumas coisas:

• Sistema Operacional do Servidor: Linux, macOS ou Windows, para que o comando gerado corresponda ao seu host.
• Imagem Docker: escolha General, Slim ou Custom. O General vem com Node.js 18, Java 21, Python 3 e PHP 8 pré-instalados. O Slim vem apenas com Node.js 18, para uma imagem menor. O Custom permite que você forneça seu próprio Dockerfile quando precisar de runtimes extras para scripts de teste.
• Porta Exposta: definida com o parâmetro -p, por exemplo -p 80:4524, que mapeia a porta 80 do host para a porta interna do runner.
• Diretório de Dados Montado: definido com o parâmetro -v, para que os dados do runner persistam no host após reinícios.

Quando terminar, copie o comando gerado. Isso é importante: o comando é exibido apenas uma vez, por motivos de segurança de dados, porque ele incorpora seu token. Se você o perder, deverá gerar um novo em vez de recuperar o antigo. Capture-o imediatamente.

Executá-lo no servidor

Cole o comando no terminal do seu servidor. A instalação começa automaticamente e puxa a imagem. Um comando finalizado se parece aproximadamente com este (o seu será diferente e incluirá o token real):

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

Confirme se o contêiner está ativo:

docker ps

Você deve ver o contêiner do runner listado com seu mapeamento de porta. Um cliente Docker como o Docker Desktop mostra a mesma coisa se você preferir usar uma interface gráfica.

Confirmar registro

De volta ao Apidog, vá para Recursos da Equipe e abra General Runner. Clique no botão de atualização. O runner deve agora aparecer como implantado com o status de Iniciado. Se ele não aparecer de imediato, o botão de atualização é a sua solução; aguarde um momento e clique novamente.

O status do runner tem três estados que vale a pena conhecer:

• Iniciado (Started): ativado, comunicando-se com o Apidog, processando tarefas. Este é o estado desejado.
• Parado (Stopped): alguém o parou manualmente no Apidog. Ele permanece implantado, mas não processará tarefas.
• Offline: perdeu a conexão com o Apidog, então não pode processar nada. Verifique o contêiner e o caminho da rede.

Ativar Runner Mock

A implantação do runner fornece o agente. Mais um passo direciona seu tráfego de mock para ele.

Em Recursos da Equipe, abra General Runner e localize o campo Server Host. Insira o endereço onde seu runner pode ser acessado. Em uma configuração HTTP simples, é o host e a porta que você expôs, como http://127.0.0.1:80 para um teste local ou http://runner.internal.example.com:80 para um host de intranet compartilhado. Atrás de um proxy com terminação TLS, parece https://runner.example.com:443. Mais sobre HTTPS em breve.

Uma vez que o Server Host é configurado, o Apidog configura automaticamente o ambiente Runner Mock para o seu projeto. Verifique: abra o projeto, vá para Gerenciamento de Ambiente e confirme que Runner Mock agora aparece na lista de ambientes. Você não o criou manualmente; configurar o Server Host foi o que o fez aparecer.

Enviar uma solicitação através do mock auto-hospedado

Agora, use-o. Digamos que você tenha um endpoint GET /orders/{orderId} em um projeto para uma API interna de gerenciamento de pedidos. Abra esse endpoint e, no menu suspenso de ambiente na parte superior, selecione Runner Mock em vez do ambiente da nuvem. Envie a solicitação.

A resposta vem do seu runner. Como o Apidog gera dados de mock a partir do seu esquema, um esquema Order bem definido retorna valores realistas em vez de espaços reservados vazios:

curl http://runner.internal.example.com:80/orders/10583

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

Esse JSON nunca tocou a internet pública. O runner o construiu a partir do esquema do seu endpoint e o serviu de dentro da sua rede. A geração consciente de campos, como o valor customerEmail acima, vem do Apidog lendo os tipos e nomes de campo do seu esquema, o mesmo motor abordado no artigo complementar sobre geração automática de dados de mock realistas com smart mock. Se você deseja controlar exatamente o que uma determinada solicitação retorna, você adiciona uma expectativa de mock no endpoint, e o runner serve essa expectativa da mesma forma que o mock na nuvem faria. A mecânica de construir boas respostas de mock é a mesma, seja o servidor do Apidog ou o seu; apenas o host muda. Os conceitos gerais por trás do mocking de API se aplicam inalterados.

HTTPS, montagens de dados e outros detalhes do mundo real

Uma execução de teste em http://127.0.0.1 é fácil. Uma implantação em intranet compartilhada possui alguns pontos críticos que vale a pena conhecer antes de implementá-la para uma equipe.

HTTPS precisa de um proxy reverso

O runner não possui suporte embutido a certificados HTTPS e não realiza provisionamento automático de certificados. Ele não buscará ou gerenciará um certificado TLS para você. Se você precisar de https://, termine o TLS em um proxy reverso na frente do runner, por exemplo, o Nginx segurando seu certificado, e então aponte o Server Host para a URL HTTPS do proxy. Sem um proxy, use http://host:port. Não defina Server Host como https:// e espere que o runner responda ao TLS diretamente; ele não consegue.

Um bloco Nginx mínimo que serve como front-end para um runner na porta 4524 se parece com isto:

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;
    }
}

Então o Server Host se torna https://runner.example.com:443. O guia da MDN sobre HTTPS é um bom lembrete se a terminação TLS for algo novo para sua equipe.

Montagens de arquivo são específicas de caminho

Se seus mocks ou testes precisarem de arquivos extras, o runner os espera em caminhos fixos dentro do contêiner, então monte-os lá:

• Programas externos devem ir para /app/external-programs/.
• A configuração de conexão de banco de dados deve ir para /app/database/database-connections.json.
• Os certificados de cliente SSL devem ir para /app/ssl/ssl-client-cert-list.json.

Conecte-os através de suas montagens -v para que sobrevivam a reinícios.

Comportamento de reimplantação e atualização

Quando uma nova versão do runner é lançada, você verá uma opção de Atualização (Upgrade), e em Mais Ações (More Actions) você pode Reimplantar (Redeploy). Ambos param o contêiner em execução enquanto o novo é iniciado. A parte tranquilizadora: as tarefas agendadas existentes no cliente Apidog não são afetadas por uma reimplantação ou atualização, então você só estará interrompendo o serviço ativo pelo momento em que o contêiner reinicia, sem perder a configuração.

Automatize o fluxo de trabalho com a CLI do Apidog

Aqui está a distinção que evita confusão: o runner é um agente de longa duração que pode servir mocks e executar tarefas agendadas, enquanto a CLI do Apidog é um executor de testes único para CI. São ferramentas diferentes. A CLI não pode servir, iniciar ou hospedar um servidor de mock. Não existe apidog run mock e não existe apidog mock serve. O apidog run da CLI executa cenários de teste, pastas de cenários de teste e suítes de teste, e seu grupo de comandos mock apenas realiza operações CRUD em expectativas de mock como dados. O serviço de mock é trabalho do runner, nunca da CLI.

Assim, os dois se encaixam da seguinte forma. A CLI e agentes de codificação de IA, como Cursor, Claude Code e Codex, podem criar e atualizar os endpoints e esquemas em seu projeto, o que mantém sua saída de mock precisa à medida que a especificação evolui. Uma vez que o mock auto-hospedado tenha desbloqueado o trabalho de frontend, os cenários de teste do mesmo projeto são executados sem interface (headless) em CI com um único comando, validando o backend real contra o próprio contrato que o mock descreveu:

apidog run -t <scenario_id> -e <env_id> -r html,cli

Esse único comando executa seus cenários contra o backend ativo e gera um relatório HTML mais um relatório CLI. A instalação é npm install -g apidog-cli no Node.js v16 ou superior; o guia de instalação da CLI do Apidog cobre apidog login e a configuração de token. Para que esse teste ocorra a cada push, integre-o ao seu pipeline com o guia de CI/CD da CLI do Apidog. O artigo sobre mocking de APIs pela CLI explica exatamente por que o terminal gerencia definições de mock, mas não as hospeda.

FAQ

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

Provavelmente não. O mock na nuvem não exige nada implantado e é o caminho mais simples. Escolha o runner quando o tráfego de saída for bloqueado ou auditado, uma regra de conformidade mantiver os dados na infraestrutura interna, ou o ambiente for isolado (air-gapped). Se você está comparando a abordagem hospedada com a gerenciada primeiro, o passo a passo do mock na nuvem do Apidog é o complemento natural a este guia.

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 como dados com seu grupo de comandos mock. O serviço de tráfego de mock é feito pelo General Runner ou pelo mock na nuvem, nunca pela CLI. Se você esperava digitar um comando no terminal e ter um mock em execução em uma porta, essa é a tarefa do runner, configurada através da GUI conforme descrito acima.

O runner suporta HTTPS por conta própria?

Ele não vem com certificados nem os provisiona automaticamente. Coloque um proxy reverso como o Nginx na frente para terminar o TLS, e então aponte o Server Host para a URL https:// do proxy. Sem um proxy, use http://host:port.

Por que meu runner não aparece depois que executei o comando?

Abra Recursos da Equipe, vá para General Runner e clique no botão de atualização. O registro pode demorar um pouco. Se ainda assim não aparecer, confirme se o contêiner está em execução com docker ps e se o host é acessível a partir do Apidog. Um status de Offline significa que a conexão caiu; Iniciado (Started) é o que você deseja.

Várias equipes podem compartilhar um único runner para serviço de mock global?

Um runner é registrado na equipe onde você o implantou, e seu ambiente Runner Mock aparece por projeto. Se você gerencia equipes distribuídas que compartilham ambientes de mock, os padrões no guia sobre compartilhamento de ambientes de mock entre equipes globais o ajudarão a decidir quantos runners configurar e onde.

Conclusão

O mocking auto-hospedado com o General Runner mantém seus dados de solicitação na infraestrutura que você controla, enquanto o design do seu mock permanece onde sempre esteve, no seu projeto Apidog. Você implanta um contêiner Docker, configura o Server Host e o ambiente Runner Mock faz o resto. Opte por ele quando a nuvem estiver fora dos limites, e use o mock na nuvem quando não estiver. Pronto para executar mocks em sua própria rede? Baixe o Apidog, implante um runner e sirva sua primeira resposta de Runner Mock sem que um único pacote saia da sua intranet.