Certaines équipes ne peuvent pas envoyer leur trafic vers le cloud. Peut-être êtes-vous derrière un pare-feu d'entreprise qui bloque les appels sortants vers des services tiers. Peut-être qu'une règle de conformité stipule que les données de requête et de réponse doivent rester sur les machines que vous contrôlez. Peut-être que l'environnement entier est en air-gap et que rien ne quitte l'intranet. Dans tous ces cas, une URL de maquette hébergée sur l'infrastructure de quelqu'un d'autre est un non-sens, même lorsque les données de maquette elles-mêmes sont fausses.
Apidog gère cela avec un runner auto-hébergé. Au lieu que vos requêtes aillent vers le service de maquette cloud d'Apidog, vous déployez un petit programme sur un serveur que vous possédez, et ce programme renvoie les réponses de maquette depuis votre propre réseau. La conception réside dans votre projet Apidog comme toujours ; seul le service se déplace sur votre matériel. Ce guide explique ce qu'est le runner, quand le choisir plutôt que la maquette cloud, comment le configurer à partir de la documentation, et une distinction qui déroute les gens : le runner n'est pas l'interface de ligne de commande (CLI). Si vous voulez une vue d'ensemble plus large des raisons pour lesquelles les équipes exécutent des maquettes sur leurs propres machines, le guide sur les serveurs de maquettes d'API auto-hébergés couvre le cas général, et l'Initiative OpenAPI explique la spécification à partir de laquelle ces maquettes sont générées. Vous voulez suivre ? Téléchargez Apidog d'abord.
Qu'est-ce que le runner auto-hébergé ?
Le runner auto-hébergé d'Apidog est un programme automatisé que vous hébergez sur un serveur autonome. Il est officiellement appelé "General Runner" (Runner Général), et il a trois fonctions : il exécute des tests automatisés planifiés, il importe des documents d'API, et il renvoie des réponses de maquette. Cette troisième fonction est l'objet de cet article.
Voici l'idée clé. Une fois que vous avez déployé un Runner Général et défini son hôte de serveur, un nouvel environnement appelé Runner Mock apparaît automatiquement dans votre projet. Toute requête que vous envoyez via cet environnement obtient sa réponse de maquette de votre runner auto-hébergé au lieu de la maquette cloud d'Apidog. Même conception de maquette, mêmes données générées, machine différente pour le service. Votre trafic ne quitte jamais votre réseau.
C'est l'alternative auto-hébergée à la maquette cloud. Si votre équipe peut atteindre Internet et n'a aucune règle contre cela, la maquette cloud Apidog est plus simple car il n'y a rien à déployer. Choisissez le runner lorsque l'une de ces conditions est vraie :
- Le trafic sortant vers des hôtes externes est bloqué ou fortement audité.
- Une politique de conformité exige que les données de requête restent sur l'infrastructure interne.
- L'environnement est en air-gap et ne peut pas du tout atteindre un point de terminaison cloud.
- Vous souhaitez que la latence de la maquette soit mesurée sur votre propre réseau local, et non sur l'internet public.
Si aucune de ces conditions ne s'applique, l'hôte Docker supplémentaire est une surcharge dont vous n'avez pas besoin. Soyez honnête avec vous-même quant au camp dans lequel vous vous trouvez avant de provisionner un serveur.
Une remarque sur les plans et les autorisations. La documentation Apidog ne mentionne pas de barrière explicite gratuit/payant pour le Runner Général ou pour la maquette auto-hébergée, et elle ne liste aucun chiffre de prix pour cela, donc ce guide n'en inventera pas. Ce que la configuration exige, ce sont des autorisations d'administrateur d'équipe ou de projet, car le déploiement d'un runner se fait dans les Ressources d'équipe, et seuls les administrateurs peuvent ouvrir ces paramètres. Si vous ne pouvez pas voir le panneau Ressources, c'est la raison.
Ce dont vous avez besoin avant de commencer
Le runner est livré sous forme de conteneur Docker, donc le serveur qui l'héberge doit avoir Docker installé. La documentation requiert une version minimale de 20.10.0, et recommande la version 20.10.13 ou plus récente. Vérifiez ce que vous avez :
docker --version
Vous avez également besoin d'un endroit pour l'exécuter : une machine Linux, macOS ou Windows que les clients Apidog de votre équipe et le service Apidog peuvent tous deux atteindre. Sur un intranet, cela signifie généralement un serveur interne avec une IP ou un nom d'hôte stable. C'est toute la liste des prérequis : Docker, un hôte et des droits d'administrateur sur l'équipe. Tout le reste est configuré dans Apidog lui-même.
Déployer le Runner Général
La commande de déploiement est générée pour vous depuis Apidog, et elle contient un jeton, vous n'avez donc pas à l'écrire manuellement. Voici le flux.
Générer la commande
Ouvrez Apidog Home, sélectionnez votre équipe, puis cliquez sur Ressources dans la barre latérale droite et choisissez Déployer le Runner Général. Une fenêtre contextuelle apparaît où vous définissez quelques éléments :
- Système d'exploitation du serveur : Linux, macOS ou Windows, pour que la commande générée corresponde à votre hôte.
- Image Docker : choisissez Général, Slim ou Personnalisé. Général est livré avec Node.js 18, Java 21, Python 3 et PHP 8 préinstallés. Slim n'est livré qu'avec Node.js 18, pour une image plus petite. Personnalisé vous permet de fournir votre propre Dockerfile lorsque vous avez besoin de runtimes supplémentaires pour les scripts de test.
- Port exposé : défini avec le paramètre
-p, par exemple-p 80:4524, qui mappe le port hôte 80 au port interne du runner. - Répertoire de données monté : défini avec le paramètre
-v, afin que les données du runner persistent sur l'hôte après les redémarrages.
Lorsque vous avez terminé, copiez la commande générée. C'est important : la commande n'est affichée qu'une seule fois, pour des raisons de sécurité des données, car elle intègre votre jeton. Si vous le perdez, vous en générez un nouveau plutôt que de récupérer l'ancien. Capturez-le immédiatement.
L'exécuter sur le serveur
Collez la commande dans le terminal de votre serveur. L'installation démarre seule et télécharge l'image. Une commande terminée ressemble à peu près à ceci (la vôtre sera différente et inclura le vrai jeton) :
docker run -d \
--name apidog-runner \
-p 80:4524 \
-v /opt/apidog-runner/data:/app/data \
apidog/runner:latest \
--token <YOUR_GENERATED_TOKEN>
Confirmez que le conteneur est opérationnel :
docker ps
Vous devriez voir le conteneur du runner listé avec son mappage de ports. Un client Docker comme Docker Desktop affiche la même chose si vous préférez une interface utilisateur.
Confirmer son enregistrement
De retour dans Apidog, allez dans Ressources d'équipe et ouvrez Runner Général. Cliquez sur le bouton d'actualisation. Le runner devrait maintenant apparaître comme déployé avec un statut Démarré. S'il n'apparaît pas au début, le bouton d'actualisation est votre solution ; donnez-lui un instant et cliquez à nouveau.
Le statut du runner a trois états à connaître :
- Démarré : activé, communique avec Apidog, gère les tâches. C'est l'état souhaité.
- Arrêté : quelqu'un l'a arrêté manuellement dans Apidog. Il reste déployé mais ne traitera pas les tâches.
- Hors ligne : il a perdu sa connexion avec Apidog, il ne peut donc rien traiter. Vérifiez le conteneur et le chemin réseau.
Activer le Runner Mock
Le déploiement du runner vous donne l'agent. Une étape supplémentaire dirige votre trafic de maquette vers lui.
Dans les Ressources d'équipe, ouvrez le Runner Général et trouvez le champ Hôte du serveur. Entrez l'adresse où votre runner est accessible. Pour une configuration HTTP simple, c'est l'hôte et le port que vous avez exposés, comme http://127.0.0.1:80 pour un test local ou http://runner.internal.example.com:80 pour un hôte intranet partagé. Derrière un proxy de terminaison TLS, cela ressemble à https://runner.example.com:443. Plus d'informations sur HTTPS dans un instant.
Une fois que l'Hôte du serveur est défini, Apidog configure automatiquement l'environnement Runner Mock pour votre projet. Vérifiez-le : ouvrez le projet, allez dans Gestion de l'environnement, et confirmez que Runner Mock apparaît maintenant dans la liste des environnements. Vous ne l'avez pas créé manuellement ; c'est la définition de l'Hôte du serveur qui l'a fait apparaître.
Envoyer une requête via la maquette auto-hébergée
Maintenant, utilisez-le. Supposons que vous ayez un point de terminaison GET /orders/{orderId} dans un projet pour une API de gestion des commandes interne. Ouvrez ce point de terminaison, puis dans le menu déroulant de l'environnement en haut, sélectionnez Runner Mock au lieu de l'environnement cloud. Envoyez la requête.
La réponse provient de votre runner. Parce qu'Apidog génère des données de maquette à partir de votre schéma, un schéma Order bien défini renvoie des valeurs réalistes plutôt que des espaces réservés vides :
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"
}
Ce JSON n'a jamais touché l'internet public. Le runner l'a construit à partir du schéma de votre point de terminaison et l'a servi depuis votre réseau. La génération sensible aux champs comme la valeur customerEmail ci-dessus provient d'Apidog lisant les types et les noms de champs de votre schéma, le même moteur couvert dans l'article complémentaire sur la génération automatique de données de maquette réalistes avec la maquette intelligente. Si vous voulez contrôler exactement ce qu'une requête donnée renvoie, vous ajoutez une attente de maquette sur le point de terminaison, et le runner sert cette attente de la même manière que la maquette cloud le ferait. La mécanique de construction de bonnes réponses de maquette est la même, que le serveur soit celui d'Apidog ou le vôtre ; seul l'hôte change. Les concepts généraux derrière la maquette d'API s'appliquent inchangés.
HTTPS, montages de données et autres détails concrets
Un test sur http://127.0.0.1 est facile. Un déploiement intranet partagé présente quelques difficultés à connaître avant de le déployer en équipe.
HTTPS nécessite un proxy inverse
Le runner n'a pas de support intégré pour les certificats HTTPS et ne fournit pas de provisionnement automatique de certificats. Il ne récupérera ni ne gérera un certificat TLS pour vous. Si vous avez besoin de https://, terminez TLS sur un proxy inverse devant le runner, par exemple Nginx détenant votre certificat, puis pointez l'Hôte du serveur vers l'URL HTTPS du proxy. Sans proxy, tenez-vous-en à http://hôte:port. Ne définissez pas l'Hôte du serveur sur https:// en vous attendant à ce que le runner réponde directement à TLS ; il ne peut pas.
Un bloc Nginx minimal qui se trouve devant un runner sur le port 4524 ressemble à ceci :
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;
}
}
Alors l'Hôte du serveur devient https://runner.example.com:443. Le guide MDN sur HTTPS est un bon rappel si la terminaison TLS est nouvelle pour votre équipe.
Les montages de fichiers sont spécifiques au chemin
Si vos maquettes ou tests nécessitent des fichiers supplémentaires, le runner les attend à des chemins fixes à l'intérieur du conteneur, alors montez-les là :
- Les programmes externes vont dans
/app/external-programs/. - La configuration de connexion à la base de données va dans
/app/database/database-connections.json. - Les certificats clients SSL vont dans
/app/ssl/ssl-client-cert-list.json.
Connectez-les via vos montages -v afin qu'ils survivent aux redémarrages.
Comportement de redéploiement et de mise à niveau
Lorsqu'une nouvelle version du runner est publiée, vous verrez une option Mettre à niveau, et sous Plus d'actions, vous pourrez Redéployer. Les deux arrêtent le conteneur en cours d'exécution pendant que le nouveau démarre. Le point rassurant : les tâches planifiées existantes dans le client Apidog ne sont pas affectées par un redéploiement ou une mise à niveau, vous n'interrompez donc le service en direct que le temps que le conteneur redémarre, sans perdre la configuration.
Automatiser le flux de travail avec l'interface CLI d'Apidog
Voici la distinction qui évite la confusion : le runner est un agent de longue durée qui peut servir des maquettes et exécuter des tâches planifiées, tandis que l'interface CLI d'Apidog est un exécutant de tests ponctuel pour la CI. Ce sont des outils différents. La CLI ne peut pas servir, démarrer ou héberger un serveur de maquette. Il n'y a pas de apidog run mock ni de apidog mock serve. Le apidog run de la CLI exécute des scénarios de test, des dossiers de scénarios de test et des suites de tests, et son groupe de commandes mock ne fait que des opérations CRUD sur les attentes de maquette en tant que données. Le service de maquette est le travail du runner, jamais celui de la CLI.
Ainsi, les deux s'assemblent comme ceci. La CLI et les agents de codage IA tels que Cursor, Claude Code et Codex peuvent créer et mettre à jour les points de terminaison et les schémas dans votre projet, ce qui maintient la précision de votre sortie de maquette à mesure que la spécification évolue. Une fois que la maquette auto-hébergée a débloqué le travail frontal, les scénarios de test du même projet s'exécutent sans interface graphique dans la CI avec une seule commande, validant le backend réel par rapport au contrat même que la maquette a décrit :
apidog run -t <scenario_id> -e <env_id> -r html,cli
Cette commande unique exécute vos scénarios par rapport au backend en direct et génère un rapport HTML et CLI. L'installation est npm install -g apidog-cli sur Node.js v16 ou ultérieur ; le guide d'installation de la CLI Apidog couvre apidog login et la configuration du jeton. Pour que ce test s'exécute à chaque push, intégrez-le à votre pipeline avec le guide CI/CD de la CLI Apidog. L'article sur la simulation d'API depuis la CLI explique précisément pourquoi le terminal gère les définitions de maquettes mais ne les héberge pas.
FAQ
Ai-je besoin du runner auto-hébergé si mon équipe peut atteindre Internet ?
Probablement pas. La maquette cloud ne nécessite aucun déploiement et est la voie la plus simple. Choisissez le runner lorsque le trafic sortant est bloqué ou audité, qu'une règle de conformité maintient les données sur l'infrastructure interne, ou que l'environnement est en air-gap. Si vous comparez d'abord l'approche hébergée à l'approche gérée, la présentation de la maquette cloud Apidog est le complément naturel de ce guide.
La CLI d'Apidog peut-elle démarrer un serveur de maquette auto-hébergé ?
Non. La CLI exécute des tests avec apidog run et gère les attentes de maquette en tant que données avec son groupe de commandes mock. Le service de trafic de maquette est effectué par le Runner Général ou par la maquette cloud, jamais par la CLI. Si vous espériez taper une commande de terminal et obtenir une maquette en cours d'exécution sur un port, c'est le travail du runner, configuré via l'interface graphique comme décrit ci-dessus.
Le runner prend-il en charge HTTPS seul ?
Il ne fournit pas de certificats et ne les provisionne pas automatiquement. Placez un proxy inverse comme Nginx devant pour terminer TLS, puis pointez l'Hôte du serveur vers l'URL https:// du proxy. Sans proxy, utilisez http://hôte:port.
Pourquoi mon runner n'apparaît-il pas après avoir exécuté la commande ?
Ouvrez les Ressources d'équipe, allez dans Runner Général et cliquez sur le bouton d'actualisation. L'enregistrement peut prendre un instant. Si le runner n'apparaît toujours pas, confirmez que le conteneur est en cours d'exécution avec docker ps et que l'hôte est accessible depuis Apidog. Un statut Hors ligne signifie que la connexion a été perdue ; Démarré est ce que vous voulez.
Plusieurs équipes peuvent-elles partager un seul runner pour le service de maquette global ?
Un runner s'enregistre auprès de l'équipe où vous l'avez déployé, et son environnement Runner Mock apparaît par projet. Si vous gérez des équipes distribuées qui partagent des environnements de maquette, les modèles du guide sur le partage d'environnements de maquette entre équipes globales vous aideront à décider combien de runners mettre en place et où.
En résumé
La simulation auto-hébergée avec le Runner Général maintient vos données de requête sur l'infrastructure que vous contrôlez, tandis que votre conception de maquette reste là où elle a toujours été, dans votre projet Apidog. Vous déployez un conteneur Docker, définissez l'Hôte du serveur, et l'environnement Runner Mock fait le reste. Utilisez-le lorsque le cloud est inaccessible, et restez avec la maquette cloud quand il ne l'est pas. Prêt à exécuter des maquettes sur votre propre réseau ? Téléchargez Apidog, déployez un runner et servez votre première réponse de Runner Mock sans qu'aucun paquet ne quitte votre intranet.