DEV Community

Cover image for Cómo ejecutar un servidor mock autohospedado en tu intranet con Apidog
Roobia
Roobia

Posted on • Originally published at apidog.com

Cómo ejecutar un servidor mock autohospedado en tu intranet con Apidog

Algunos equipos no pueden enviar tráfico a la nube: un firewall corporativo puede bloquear llamadas salientes, una política de cumplimiento puede exigir que las solicitudes y respuestas permanezcan en infraestructura propia, o el entorno puede estar completamente aislado de la red (air-gapped). En esos casos, una URL de simulación alojada por un tercero no es aceptable, incluso si los datos simulados son falsos.

Prueba Apidog hoy

Apidog resuelve este escenario con un ejecutor autoalojado (self-hosted runner). Despliegas un programa pequeño en un servidor de tu red y ese programa devuelve respuestas simuladas internamente. El diseño de la simulación sigue estando en tu proyecto de Apidog; únicamente el servicio se ejecuta en tu infraestructura.

Esta guía explica cuándo usarlo, cómo desplegarlo y cómo enviar tráfico a través de él. Para más contexto, consulta la guía sobre servidores de simulación de API autoalojados y la documentación de la OpenAPI Initiative.

Qué es el ejecutor autoalojado

El ejecutor autoalojado de Apidog, denominado oficialmente General Runner, es un programa que alojas en un servidor independiente.

Puede:

  1. Ejecutar pruebas automatizadas programadas.
  2. Importar documentos de API.
  3. Servir respuestas simuladas.

Este artículo se centra en el tercer caso.

Diagrama del General Runner de Apidog

Después de desplegar un General Runner y configurar su Server Host, Apidog crea automáticamente un entorno llamado Runner Mock en tu proyecto.

Las solicitudes enviadas mediante ese entorno se resuelven desde tu ejecutor autoalojado, no desde la simulación en la nube de Apidog:

  • Mismo diseño de simulación.
  • Mismos esquemas y expectativas.
  • Mismos datos generados.
  • Diferente servidor que entrega la respuesta.

Usa el ejecutor autoalojado si se cumple alguna de estas condiciones:

  • El tráfico saliente hacia hosts externos está bloqueado o auditado.
  • Una política de cumplimiento exige que los datos permanezcan en la infraestructura interna.
  • El entorno no tiene acceso a Internet.
  • Necesitas medir la latencia dentro de tu LAN.

Si tu equipo puede usar servicios externos sin restricciones, la simulación en la nube de Apidog suele ser más simple porque no requiere administrar un host Docker adicional.

Necesitas permisos de administrador de equipo o proyecto para desplegar un ejecutor, ya que la configuración está disponible en Recursos del Equipo.

Requisitos previos

Antes de empezar, prepara lo siguiente:

  • Docker 20.10.0 o superior. Se recomienda Docker 20.10.13 o posterior.
  • Un servidor Linux, macOS o Windows.
  • Una IP o un nombre de host estable para el servidor, especialmente si varios desarrolladores lo usarán.
  • Permisos de administrador en Apidog.

Comprueba la versión de Docker:

docker --version
Enter fullscreen mode Exit fullscreen mode

El servidor debe ser accesible tanto por los clientes de Apidog de tu equipo como por la plataforma de Apidog.

Desplegar el General Runner

1. Generar el comando de despliegue

En Apidog:

  1. Abre Apidog Home.
  2. Selecciona tu equipo.
  3. Abre Recursos en la barra lateral derecha.
  4. Selecciona Desplegar General Runner.

En la ventana de configuración, define:

  • Sistema Operativo del Servidor: Linux, macOS o Windows.
  • Imagen Docker:
    • General: incluye Node.js 18, Java 21, Python 3 y PHP 8.
    • Slim: incluye Node.js 18 y tiene un tamaño menor.
    • Custom: permite proporcionar un Dockerfile propio para tiempos de ejecución adicionales.
  • Puerto Expuesto: se configura mediante -p, por ejemplo -p 80:4524.
  • Directorio de Datos Montado: se configura mediante -v para persistir los datos entre reinicios.

Apidog genera el comando con un token integrado. Cópialo inmediatamente: se muestra una sola vez por motivos de seguridad. Si lo pierdes, genera un token nuevo.

2. Ejecutar el contenedor

Pega el comando generado en la terminal de tu servidor. Un ejemplo aproximado es:

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

El comando real puede variar según el sistema operativo, la imagen y las rutas que hayas seleccionado.

Comprueba que el contenedor está activo:

docker ps
Enter fullscreen mode Exit fullscreen mode

Debes ver el contenedor del ejecutor y su mapeo de puertos.

3. Confirmar el registro en Apidog

Vuelve a Apidog:

  1. Abre Recursos del Equipo.
  2. Entra en General Runner.
  3. Pulsa actualizar.

El ejecutor debe aparecer como desplegado y con estado Iniciado.

Estados relevantes:

Estado Significado Acción recomendada
Iniciado El ejecutor está habilitado y procesando tareas. No requiere acción.
Detenido Fue detenido manualmente desde Apidog. Inícialo desde la configuración.
Sin conexión Perdió la conexión con Apidog. Revisa el contenedor y la conectividad de red.

Activar la simulación mediante el ejecutor

Desplegar el contenedor no redirige automáticamente las solicitudes. Debes configurar el host que Apidog utilizará para enviar el tráfico de simulación.

En Recursos del Equipo > General Runner, busca el campo Server Host e introduce la dirección pública o interna del ejecutor.

Ejemplos:

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

Para una prueba local.

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

Para un host compartido en una intranet.

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

Para un host detrás de un proxy inverso con TLS.

Cuando guardes el valor de Server Host, Apidog creará el entorno Runner Mock para el proyecto.

Verifícalo:

  1. Abre el proyecto.
  2. Ve a Gestión de Entornos.
  3. Confirma que aparece Runner Mock.

No necesitas crear este entorno manualmente.

Enviar una solicitud mediante Runner Mock

Supongamos que tu proyecto define este endpoint:

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

Para probarlo:

  1. Abre el endpoint en Apidog.
  2. En el selector de entorno, elige Runner Mock.
  3. Envía la solicitud.

También puedes comprobar el endpoint desde la red interna:

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

Una respuesta simulada basada en un esquema Order podría ser:

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

La respuesta se genera y se sirve dentro de tu red. Apidog usa el esquema del endpoint para producir valores coherentes con los tipos y nombres de los campos.

Para controlar una respuesta concreta, añade una expectativa de simulación al endpoint. El General Runner servirá esa expectativa igual que lo haría la simulación en la nube. Consulta también la guía de generación automática de datos simulados realistas con simulación inteligente y los conceptos generales de simulación de API.

HTTPS, persistencia y despliegues reales

Configurar HTTPS con un proxy inverso

El ejecutor no gestiona certificados HTTPS ni aprovisiona TLS automáticamente. Si necesitas una URL https://, coloca un proxy inverso delante del ejecutor.

Por ejemplo, puedes usar Nginx para terminar TLS y reenviar el tráfico al puerto interno 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

Después, configura el Server Host de Apidog así:

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

Sin proxy inverso, utiliza una URL HTTP:

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

Consulta la guía de MDN sobre HTTPS si necesitas repasar la terminación TLS.

Montar archivos en las rutas esperadas

Si tus pruebas o simulaciones necesitan archivos adicionales, móntalos en las rutas internas que espera el contenedor:

Recurso Ruta dentro del contenedor
Programas externos /app/external-programs/
Configuración de conexiones de base de datos /app/database/database-connections.json
Certificados SSL de cliente /app/ssl/ssl-client-cert-list.json

Usa montajes Docker con -v para que estos archivos sobrevivan a reinicios o redespliegues.

Ejemplo:

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

Actualizar o redesplegar

Cuando exista una versión nueva del ejecutor, Apidog mostrará una opción para Actualizar. También puedes usar Más Acciones > Redesplegar.

Ambas operaciones detienen temporalmente el contenedor mientras se inicia la nueva versión. Las tareas programadas existentes en Apidog no pierden su configuración; solo el servicio en vivo se interrumpe durante el reinicio del contenedor.

Automatizar pruebas con la CLI de Apidog

El General Runner y la CLI de Apidog tienen funciones distintas:

Herramienta Uso principal
General Runner Servir simulaciones autoalojadas y ejecutar tareas programadas.
CLI de Apidog Ejecutar pruebas en CI y administrar expectativas de simulación como datos.

La CLI no inicia ni aloja un servidor de simulación. No existe un comando como:

apidog run mock
Enter fullscreen mode Exit fullscreen mode

Ni:

apidog mock serve
Enter fullscreen mode Exit fullscreen mode

El comando apidog run ejecuta escenarios, carpetas de escenarios y suites de prueba. El grupo de comandos mock realiza operaciones CRUD sobre expectativas de simulación, pero no sirve tráfico HTTP.

Una integración típica es:

  1. Mantener endpoints y esquemas actualizados en Apidog.
  2. Usar Runner Mock para desbloquear el desarrollo frontend dentro de la red privada.
  3. Ejecutar pruebas de contrato contra el backend real en CI.

Ejemplo:

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

Este comando ejecuta el escenario de prueba contra el entorno seleccionado y genera informes HTML y CLI.

Instala la CLI con Node.js 16 o posterior:

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

Consulta la guía de instalación de la CLI de Apidog para configurar apidog login y tokens. Para integrarla en cada push, sigue la guía CI/CD de la CLI de Apidog.

La guía de simulación de API desde la CLI explica por qué la terminal administra definiciones de simulación, pero no las aloja.

Preguntas frecuentes

¿Necesito el ejecutor autoalojado si mi equipo tiene acceso a Internet?

Probablemente no. La simulación en la nube es más simple porque no requiere desplegar infraestructura. Usa el ejecutor cuando el tráfico saliente esté bloqueado, auditado, sujeto a requisitos de cumplimiento o cuando el entorno esté aislado de la red.

Para comparar ambos enfoques, consulta el tutorial de simulación en la nube de Apidog.

¿Puede la CLI de Apidog iniciar un servidor de simulación autoalojado?

No. La CLI ejecuta pruebas con apidog run y administra expectativas de simulación con los comandos mock. El servicio HTTP de simulación lo proporciona el General Runner o la simulación en la nube.

¿El ejecutor soporta HTTPS directamente?

No. Debes colocar un proxy inverso, como Nginx, delante del ejecutor para terminar TLS. Después, configura el Server Host con la URL HTTPS del proxy.

¿Por qué el ejecutor no aparece después de ejecutar el comando?

Sigue esta comprobación:

docker ps
Enter fullscreen mode Exit fullscreen mode

Si el contenedor está activo:

  1. Abre Recursos del Equipo > General Runner.
  2. Pulsa actualizar.
  3. Espera unos segundos y vuelve a actualizar.

Si el estado es Sin conexión, revisa la conectividad entre el host del ejecutor y Apidog.

¿Varios equipos pueden compartir un ejecutor?

Un ejecutor se registra en el equipo donde fue desplegado y genera el entorno Runner Mock por proyecto. Si trabajas con equipos distribuidos, consulta la guía sobre compartir entornos de simulación entre equipos globales para decidir cuántos ejecutores necesitas y dónde desplegarlos.

Conclusión

El General Runner permite servir simulaciones desde la infraestructura que controlas:

  1. Despliega el contenedor Docker.
  2. Configura el Server Host.
  3. Selecciona el entorno Runner Mock en tu proyecto.
  4. Envía solicitudes sin sacar el tráfico de tu intranet.

Usa la simulación autoalojada cuando la nube no sea una opción. Si no tienes restricciones de red o cumplimiento, la simulación en la nube sigue siendo la alternativa más directa.

¿Listo para probarlo? Descarga Apidog, despliega un General Runner y sirve tu primera respuesta simulada dentro de tu red.

Top comments (0)