DEV Community

Cover image for Comment exécuter un serveur de mock auto-hébergé sur votre Intranet avec Apidog
Antoine Laurent
Antoine Laurent

Posted on • Originally published at apidog.com

Comment exécuter un serveur de mock auto-hébergé sur votre Intranet avec Apidog

Certaines équipes ne peuvent pas envoyer leur trafic vers le cloud : pare-feu sortant, exigences de conformité, réseau air-gap ou politique imposant que les données de requête et de réponse restent sur l’infrastructure interne. Dans ce contexte, un serveur de maquettes hébergé par un tiers n’est pas adapté, même si les données de maquette sont fictives.

Essayez Apidog dès aujourd’hui

Apidog répond à ce besoin avec un runner auto-hébergé : vous déployez un programme sur un serveur que vous contrôlez, puis ce programme sert les réponses de maquette depuis votre réseau. La définition de l’API et des maquettes reste dans votre projet Apidog ; seul le trafic de service est déplacé sur votre infrastructure. Pour le contexte global, consultez le guide des serveurs de maquettes d’API auto-hébergés et la spécification de l’Initiative OpenAPI.

Qu’est-ce que le runner auto-hébergé ?

Le runner auto-hébergé d’Apidog, officiellement nommé General Runner (Runner Général), est un programme déployé sur votre propre serveur.

Il remplit trois fonctions :

  1. Exécuter des tests automatisés planifiés.
  2. Importer des documents d’API.
  3. Servir des réponses de maquette.

Cet article se concentre sur le troisième usage.

Schéma montrant comment un runner auto-hébergé sert des requêtes de maquette

Après le déploiement du Runner Général et la configuration de son hôte, Apidog crée automatiquement un environnement nommé Runner Mock dans le projet. Les requêtes envoyées avec cet environnement reçoivent une réponse depuis votre runner, au lieu du service de maquette cloud.

La définition de la maquette ne change pas. Seul le serveur qui répond change.

Quand choisir le runner plutôt que la maquette cloud ?

La maquette cloud d’Apidog est plus simple si votre équipe peut utiliser Internet sans restriction : aucun serveur ni conteneur à gérer.

Choisissez le runner auto-hébergé si :

  • les connexions sortantes vers des hôtes externes sont bloquées ou auditées ;
  • la conformité impose que les données de requête restent dans le réseau interne ;
  • l’environnement est air-gap ;
  • vous souhaitez mesurer la latence de maquette sur le LAN plutôt que sur Internet.

Le déploiement requiert des droits d’administrateur d’équipe ou de projet, car la configuration se fait dans les Ressources d’équipe.

Prérequis

Le runner est distribué sous forme de conteneur Docker.

Vérifiez votre version de Docker :

docker --version
Enter fullscreen mode Exit fullscreen mode

La documentation indique Docker 20.10.0 au minimum et recommande 20.10.13 ou une version plus récente.

Préparez également :

  • un hôte Linux, macOS ou Windows ;
  • une adresse IP ou un nom DNS stable pour le serveur ;
  • un chemin réseau accessible par les clients Apidog ;
  • des droits d’administrateur dans l’équipe Apidog.

La configuration fonctionnelle se fait ensuite dans Apidog.

Déployer le Runner Général

1. Générer la commande de déploiement

Dans Apidog :

  1. Ouvrez Apidog Home.
  2. Sélectionnez votre équipe.
  3. Ouvrez Ressources dans la barre latérale.
  4. Choisissez Déployer le Runner Général.

Dans la fenêtre de déploiement, configurez les éléments suivants :

  • Système d’exploitation du serveur : Linux, macOS ou Windows.
  • Image Docker :
    • Général : Node.js 18, Java 21, Python 3 et PHP 8 ;
    • Slim : Node.js 18 uniquement ;
    • Personnalisé : votre propre Dockerfile pour des runtimes supplémentaires.
  • Port exposé : par exemple -p 80:4524.
  • Répertoire de données monté : avec -v, afin de conserver les données après un redémarrage.

Copiez immédiatement la commande générée. Elle contient un jeton et n’est affichée qu’une seule fois.

2. Lancer le conteneur

Exécutez la commande fournie par Apidog sur votre serveur. Elle ressemble à ceci :

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

Utilisez toujours la commande générée par Apidog : votre jeton réel y est intégré.

Vérifiez que le conteneur est démarré :

docker ps
Enter fullscreen mode Exit fullscreen mode

Vous devez voir apidog-runner avec le mappage de port configuré.

3. Vérifier l’enregistrement dans Apidog

Retournez dans Ressources d’équipe > Runner Général, puis cliquez sur actualiser.

Le runner doit apparaître avec le statut Démarré.

Statut Signification Action
Démarré Le runner est connecté et traite les tâches. Aucune action requise.
Arrêté Le runner a été arrêté depuis Apidog. Redémarrez-le si nécessaire.
Hors ligne Le runner ne communique plus avec Apidog. Vérifiez Docker, le réseau et les règles de pare-feu.

Activer l’environnement Runner Mock

Déployer le conteneur ne suffit pas : vous devez indiquer à Apidog l’adresse à utiliser.

Dans Ressources d’équipe > Runner Général, renseignez le champ Hôte du serveur.

Exemples :

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

Avec un proxy TLS :

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

Après l’enregistrement de l’hôte :

  1. Ouvrez votre projet.
  2. Accédez à Gestion de l’environnement.
  3. Vérifiez que l’environnement Runner Mock apparaît dans la liste.

Cet environnement est créé automatiquement après la définition de l’Hôte du serveur.

Envoyer une requête vers la maquette auto-hébergée

Supposons une API interne avec l’opération suivante :

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

Dans Apidog :

  1. Ouvrez le point de terminaison.
  2. Sélectionnez Runner Mock dans le menu des environnements.
  3. Envoyez la requête.

Vous pouvez aussi tester directement le runner :

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

Exemple de réponse :

{
  "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

Le runner génère cette réponse à partir du schéma défini dans le projet. Des champs correctement typés et nommés, comme customerEmail, permettent de produire des valeurs plus réalistes.

Pour approfondir ce comportement, consultez le guide sur la génération automatique de données de maquette réalistes avec la maquette intelligente.

Si vous devez retourner une réponse précise pour une requête donnée, ajoutez une attente de maquette sur le point de terminaison. Le runner sert ces attentes comme le ferait la maquette cloud. Les principes généraux de la maquette d’API restent identiques : seul l’hôte de service diffère.

HTTPS, montages de données et exploitation

Terminer TLS avec un proxy inverse

Le runner ne gère pas directement les certificats HTTPS et ne provisionne pas de certificat TLS.

Pour exposer le runner en https://, placez un proxy inverse devant lui. Exemple Nginx pour un runner accessible localement sur le port 4524 :

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

Définissez ensuite l’Hôte du serveur dans Apidog :

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

Consultez la documentation Nginx et le rappel MDN sur HTTPS si votre équipe met en place la terminaison TLS pour la première fois.

Monter les fichiers aux chemins attendus

Si vos tests ou maquettes dépendent de fichiers additionnels, montez-les aux chemins prévus dans le conteneur :

Type de fichier Chemin dans le conteneur
Programmes externes /app/external-programs/
Connexions à une base de données /app/database/database-connections.json
Certificats clients SSL /app/ssl/ssl-client-cert-list.json

Utilisez des volumes Docker avec -v pour préserver ces données entre les redémarrages.

Mettre à niveau ou redéployer

Lorsqu’une nouvelle version du runner est disponible, Apidog propose une action Mettre à niveau. L’option Redéployer, disponible dans Plus d’actions, recrée également le conteneur.

Ces opérations interrompent temporairement le trafic pendant le redémarrage du conteneur, mais les tâches planifiées configurées dans Apidog restent conservées.

Utiliser la CLI Apidog dans la CI

Le runner et la CLI remplissent des rôles différents :

  • le Runner Général est un agent de longue durée qui sert les maquettes et exécute des tâches planifiées ;
  • la CLI Apidog exécute ponctuellement des tests dans un terminal ou une pipeline CI.

La CLI ne démarre pas de serveur de maquette. Il n’existe pas de commande telle que :

apidog run mock
Enter fullscreen mode Exit fullscreen mode

ou :

apidog mock serve
Enter fullscreen mode Exit fullscreen mode

La commande apidog run exécute des scénarios, dossiers de scénarios ou suites de tests. Le groupe de commandes mock gère les attentes de maquette comme des données, mais ne sert pas le trafic HTTP.

Une fois votre API décrite et votre maquette auto-hébergée disponible pour le frontend, exécutez les scénarios contre le backend réel depuis votre CI :

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

Cette commande exécute le scénario avec l’environnement fourni et génère des rapports HTML et CLI.

Installez la CLI avec Node.js 16 ou plus récent :

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

Pour l’authentification et la configuration du jeton, consultez le guide d’installation de la CLI Apidog. Pour l’intégrer à chaque push, suivez le guide CI/CD de la CLI Apidog.

Le guide sur la simulation d’API depuis la CLI détaille la différence entre gérer des définitions de maquette et héberger un service de maquette.

FAQ

Ai-je besoin d’un runner auto-hébergé si mon équipe peut atteindre Internet ?

Probablement pas. La maquette cloud évite la gestion d’un serveur et reste l’option la plus simple.

Utilisez un runner si les connexions sortantes sont bloquées ou auditées, si la conformité impose un réseau interne, ou si l’environnement est air-gap. Pour comparer, consultez la présentation de la maquette cloud Apidog.

La CLI Apidog peut-elle démarrer un serveur de maquette auto-hébergé ?

Non. La CLI exécute les tests avec apidog run et gère les attentes de maquette avec ses commandes mock. Le trafic de maquette est servi par le Runner Général ou par la maquette cloud.

Le runner prend-il en charge HTTPS seul ?

Non. Il ne fournit pas et ne provisionne pas automatiquement de certificats. Placez Nginx ou un autre proxy inverse devant le runner pour terminer TLS, puis configurez l’Hôte du serveur avec l’URL HTTPS du proxy.

Pourquoi mon runner n’apparaît-il pas après l’exécution de la commande ?

Procédez dans cet ordre :

docker ps
Enter fullscreen mode Exit fullscreen mode
  1. Vérifiez que le conteneur est démarré.
  2. Retournez dans Ressources d’équipe > Runner Général.
  3. Cliquez sur actualiser.
  4. Vérifiez que l’hôte et le chemin réseau sont accessibles.

Un délai d’enregistrement peut se produire. Le statut attendu est Démarré.

Plusieurs équipes peuvent-elles partager un seul runner ?

Un runner est enregistré auprès de l’équipe dans laquelle il a été déployé, et l’environnement Runner Mock apparaît par projet. Pour concevoir une stratégie de partage entre équipes, consultez le guide sur le partage d’environnements de maquette entre équipes globales.

En résumé

Le Runner Général permet de servir des maquettes API sans faire sortir le trafic de votre réseau :

  1. Déployez le conteneur Docker.
  2. Vérifiez son statut dans les Ressources d’équipe.
  3. Définissez l’Hôte du serveur.
  4. Sélectionnez l’environnement Runner Mock dans votre projet.
  5. Envoyez vos requêtes vers votre infrastructure interne.

Utilisez cette approche lorsque le cloud est inaccessible ou interdit. Sinon, privilégiez la maquette cloud pour réduire la charge opérationnelle.

Téléchargez Apidog , déployez un runner et servez votre première réponse de maquette depuis votre intranet.

Top comments (0)