O Apidog Self-hosted Runner pode ser entendido como um programa automatizado que pode ser hospedado em um servidor independente. Ele pode executar tarefas dentro do Apidog, como testes automatizados agendados, importações agendadas de documentos de API e retorno de resultados de respostas mock.Preparação#
A máquina host (servidor ou PC local) deve ter o Docker instalado. A versão mínima exigida do Docker é 20.10.0; a versão 20.10.13 é recomendada.
Início rápido#
Esta seção orientará você sobre como implantar o General Runner em seu servidor.1. Implantar o General Runner#
Acesse a página Apidog Home, selecione a equipe desejada e clique em Resources à direita. Em seguida, clique em Deploy General Runner para começar.2. Obter o comando de implantação do Runner#
Ao clicar em Deploy General Runner, copie o comando de implantação do General Runner na janela pop-up. Você pode personalizar o comando conforme necessário, com suporte a sistema operacional de servidor personalizado, portas expostas, montagem de diretório de dados e muito mais. Veja abaixo uma explicação detalhada dessas configurações:Sistema operacional do servidor: especifica o sistema operacional para o contêiner Docker. Isso inclui Linux, macOS e Windows. Selecionar o sistema operacional correto é essencial para garantir que o contêiner Docker opere adequadamente.
Imagem Docker: há três versões disponíveis: General, Slim e Custom. Se o seu "script personalizado" precisar chamar programas externos, escolha a imagem apropriada para instalação com base no ambiente necessário:General: contém todos os recursos do Runner e vem pré-instalada com os seguintes ambientes de linguagem: Node.js 18, Java 21, Python 3 e PHP 8.
Slim: contém todos os recursos do Runner, mas pré-instala apenas o Node.js 18.
Custom: contém todos os recursos do Runner e oferece suporte a ambientes de linguagem personalizados para programas externos. Você pode criar seu próprio Dockerfile para adicionar ou remover ambientes conforme necessário.
Porta exposta: por padrão, os contêineres Docker não expõem portas internas para acesso externo. Usando o parâmetro -p, você pode mapear uma porta interna do contêiner para uma porta na máquina host, permitindo acesso externo aos serviços fornecidos pelo contêiner. Por exemplo, -p 80:4524 mapeia a porta interna 4524 do contêiner para a porta 80 na máquina host.
Montar diretório de dados: o parâmetro -v permite montar diretórios da máquina host no contêiner, possibilitando que o contêiner acesse e manipule arquivos no host (por exemplo, configurações de banco de dados ou programas externos). Por exemplo, -v "/opt/runner":/opt/runner monta o diretório /opt/runner do host no diretório /opt/runner do contêiner.
O comando de implantação contém informações de token e será exibido apenas uma vez por motivos de segurança dos dados. Um novo comando será gerado sempre que você clicar em Deploy General Runner.Salve o comando localmente, pois você poderá usá-lo em futuras atualizações do Runner.
3. Implantar o Runner no servidor#
Cole o comando de implantação copiado no terminal do servidor, e a instalação do Runner será iniciada automaticamente.Você pode modificar as propriedades de implantação do Runner por meio de variáveis de ambiente para corresponder melhor aos seus cenários reais de uso. Leia ambiente de implantação do runner para obter mais informações. 4. Visualizar o status do Runner no servidor#
Você pode visualizar o status de execução do contêiner por meio do cliente Docker.Você também pode usar o comando docker ps no terminal para visualizar o status de execução do contêiner.5. Visualizar o General Runner implantado no Apidog#
Depois de confirmar que o contêiner do Runner no servidor foi implantado e habilitado, retorne ao Apidog. Você poderá ver que o Runner foi implantado e conectado ao Apidog em Team Resources → General Runner.Se o General Runner tiver sido implantado com sucesso no servidor, mas não for exibido no cliente Apidog, clique no botão de atualizaç ão no lado direito de "General Runner" para atualizar a página e verificar novamente.
| Status | Descrição |
|---|
| Iniciado | O Runner está habilitado normalmente no contêiner no servidor, mantém comunicação com o Apidog e pode processar tarefas relacionadas emitidas pelo Apidog. |
| Parado | O Runner foi parado manualmente no Apidog, mas continua sendo executado normalmente no contêiner no servidor e mantém a comunicação. Ele não processará tarefas emitidas pelo Apidog, e novas tarefas não poderão especificar um Runner parado para execução. Você pode habilitá-lo manualmente no Apidog para restaurar o Runner ao estado iniciado. |
| Offline | O Runner está desconectado do Apidog e não pode processar tarefas. Isso pode ocorrer devido à parada do contêiner do Runner no servidor ou a problemas de comunicação entre o servidor e o Apidog. Para restaurar o Runner, certifique-se de que o contêiner do Runner esteja em execução e de que não haja problemas de comunicação com o Apidog, permitindo que o Runner retorne ao estado iniciado. |
Você pode implantar vários General Runners em uma equipe. Ao criar tarefas que exigem Runners auto-hospedados, os membros da equipe podem escolher entre os Runners disponíveis.Salvando arquivos no Runner#
Ao usar o Runner para executar tarefas como requisições de endpoint, cenários de teste e tarefas agendadas, determinados arquivos locais podem ser necessários para dar suporte à execução da tarefa. Exemplos incluem:Chamar outras linguagens de programação em scripts personalizados
Usar conexões de banco de dados em Pré/Pós-processadores
Usar certificado SSL ao enviar uma requisição
| Conteúdo de uso | Caminho do diretório especificado (ou nome do arquivo) | Exemplo de comando Docker |
|---|
| Outras linguagens de programação | /app/external-programs/ | -v /Users/xxx/runner/packages/api-test/external-programs:/app/externalPrograms |
| Arquivo de configuração de conexão com banco de dados | /app/database/database-connections.json | -v /Users/xxx/runner/packages/api-test/database/database-connections.json:/app/database/database-connections.json |
| Arquivo de lista de certificados SSL | /app/ssl/ssl-client-cert-list.json | -v /Users/xxx/runner/packages/api-test/ssl/ssl-client-cert-list.json:/app/ssl/ssl-client-cert-list.json |
Você pode consultar esta página para ver como exportar o arquivo de configuração do cliente Apidog. Atualizando e reimplantando o Runner#
Atualizando o Runner#
Quando uma nova versão do Runner for lançada, um ícone de atualização aparecerá na interface do usuário do Runner para desktop. Clique no ícone para instalar a versão mais recente fornecida pelo Apidog.Clicar em Upgrade solicitará que você pare o contêiner do Runner em execução no momento. Observe que, uma vez que o contêiner seja parado, tarefas agendadas e quaisquer tarefas enviadas a este Runner pelo cliente não serão mais executadas.Depois que você confirmar a atualização, o Apidog interromperá automaticamente o contêiner atual do Runner e fornecerá um comando para implantar a nova versão. Siga as etapas iniciais de implantação para reimplantar o Runner. Depois que a implantação for bem-sucedida, você estará usando a versão mais recente. Observação: as tarefas agendadas existentes no cliente permanecerão inalteradas e não precisarão ser reatribuídas.Reimplantando o Runner#
Se o Runner encontrar um problema e você não conseguir encontrar uma solução na seção de Perguntas e Respostas, ou se as instruções não ajudarem, considere reimplantar o Runner. Para fazer isso, acesse a seção More Actions do Runner específico e clique em Redeploy.O processo de reimplantação é o mesmo que o de atualização acima. Observação: a reimplantação também interromperá o contêiner do Runner.Perguntas e respostas#
Use o comando docker ps para localizar o Runner problemático.
Use os comandos a seguir para visualizar os logs:
Etapa 1: reúna informações para diagnosticar o problema:
Procure padrões de erro ou detalhes operacionais
Abra as ferramentas de desenvolvedor (Alt+7+8), envie um cenário de teste para o Runner problemático e registre os detalhes do endpoint
Revise os logs do Runner para procurar mensagens de erro ou pistas
Se você conseguir identificar o problema e ele não for causado por um bug do Apidog, corrija-o por conta própria
Se você não conseguir identificar o problema, entre em contato com a comunidade Apidog para obter mais assistência
Etapa 1: verifique a conclusão da tarefa:
Verifique se um relatório de teste da tarefa agendada está disponível no cliente Apidog
Revise os logs do Runner em busca de problemas
Certifique-se de que as configurações de notificação estejam salvas na tarefa agendada
Verifique novamente se as condições e os destinatários estão configurados corretamente
Tente acionar a tarefa manualmente para confirmar se as notificações são enviadas corretamente
Há duas causas possíveis para esse erro:
O comando de implantação foi gerado novamente: se você gerou o comando, fechou o pop-up e clicou novamente, um novo token pode invalidar o anterior. Para corrigir isso:Alterne para outra equipe no canto superior esquerdo e, em seguida, retorne à equipe onde a implantação do Runner é necessária
Gere novamente o comando de implantação, copie-o e execute-o. Certifique-se de não clicar para gerar novamente até que o processo seja concluído.
Erro de dados de ID com a variável teamId: este é um bug conhecido que foi corrigido na versão mais recente. Se o problema persistir:Alterne para outra equipe no canto superior esquerdo e, em seguida, retorne à equipe onde a implantação do Runner é necessária
Gere novamente o comando de implantação, copie-o e execute-o. Certifique-se de não clicar para gerar novamente até que o processo seja concluído.
