Installation


Mockoon Pro is distributed as an official Docker image on Docker Hub (mockoon/pro). It requires a single persistent storage directory and a base domain name with wildcard DNS support for deployed mock instances.

 Prerequisites

  • Docker or OCI container engine (Docker Engine, Podman, containerd).
  • Persistent storage volume: A local volume or network persistent volume (minimum 1GB recommended) mounted to /data.
  • Domain & DNS records:
    • A base domain pointing to your server (e.g. mockoon.company.com, replace with your own domain).
    • A wildcard DNS record pointing to the same server (e.g. *.mockoon.company.com) to support deployed mock subdomains.
  • TLS Certificate (for production): A wildcard TLS certificate covering both the base domain (mockoon.company.com) and its subdomains (*.mockoon.company.com).

 Deployment methods

 Docker

You can run Mockoon Pro with a standard docker run command:

Copy
docker run -d \ --name mockoon-pro \ -p 5020:5020 \ -e MOCKOON_DOMAIN=mockoon.company.com \ -e MOCKOON_SERVER_ID=mockoon-node-1 \ -e NODE_ENV=production \ -e PORT=5020 \ -v mockoon-data:/data \ mockoon/pro:latest

 Docker Compose

For VM and standalone server deployments, Docker Compose paired with a reverse proxy like Caddy provides a complete, turnkey stack with automated HTTPS certificate provisioning for both your base domain and dynamic mock subdomains.

 Docker Compose with Caddy (Automated HTTPS)

This setup uses Caddy with On-Demand TLS. Caddy automatically provisions and renews TLS certificates via Let's Encrypt / ZeroSSL on port 80 for the main dashboard and every mock subdomain created by your team, with zero DNS API credentials required.

  1. Create a docker-compose.yml file:
Copy
services: caddy: image: caddy:2-alpine container_name: mockoon-proxy restart: unless-stopped ports: - '80:80' - '443:443' volumes: - ./Caddyfile:/etc/caddy/Caddyfile:ro - caddy_data:/data - caddy_config:/config depends_on: - mockoon-pro mockoon-pro: image: mockoon/pro:latest container_name: mockoon-pro restart: unless-stopped environment: - NODE_ENV=production - PORT=5020 - MOCKOON_DOMAIN=mockoon.company.com - MOCKOON_SERVER_ID=mockoon-pro-prod - MOCKOON_STORAGE_DIR=/data/ - USE_HTTPS=true volumes: - mockoon-pro-data:/data volumes: caddy_data: caddy_config: mockoon-pro-data:
  1. Create a Caddyfile in the same directory:
Copy
{ on_demand_tls { # Internal permission check to prevent certificate issuance abuse ask http://127.0.0.1:8080/check-domain } } # Internal check endpoint to validate subdomains :8080 { @allowed `{query.domain}.endsWith('.mockoon.company.com') || {query.domain} == 'mockoon.company.com'` respond @allowed 200 respond 400 } # Main dashboard & API https://mockoon.company.com { reverse_proxy mockoon-pro:5020 } # Dynamic mock subdomains (On-demand TLS) https://*.mockoon.company.com { tls { on_demand } @subdomains host *.mockoon.company.com handle @subdomains { reverse_proxy mockoon-pro:5020 } }

 Standalone Docker Compose (No Reverse Proxy)

If you already terminate TLS at an external load balancer or firewall:

Copy
services: mockoon-pro: image: mockoon/pro:latest container_name: mockoon-pro restart: unless-stopped ports: - '5020:5020' environment: - NODE_ENV=production - PORT=5020 - MOCKOON_DOMAIN=mockoon.company.com - MOCKOON_SERVER_ID=mockoon-pro-prod - MOCKOON_STORAGE_DIR=/data/ volumes: - mockoon-pro-data:/data volumes: mockoon-pro-data:

 Kubernetes & OpenShift

Mockoon Pro is compatible with Kubernetes and OpenShift environments:

  • Volume permissions: The container is pre-configured with root group (GID 0) permissions (chgrp 0 /data && chmod g+rwX /data) to seamlessly support OpenShift's arbitrary non-root UID security context constraints (SCC).
  • Persistent Volume Claim: Mount a ReadWriteOnce (RWO) PVC to /data.
  • Ingress / Route: Configure your Ingress Controller or OpenShift Route to route both the main domain (mockoon.company.com) and wildcard subdomains (*.mockoon.company.com) to container port 5020.
Copy
apiVersion: apps/v1 kind: Deployment metadata: name: mockoon-pro spec: replicas: 1 strategy: type: Recreate # SQLite on an RWO volume: never run two pods at once selector: matchLabels: app: mockoon-pro template: metadata: labels: app: mockoon-pro spec: containers: - name: mockoon-pro image: mockoon/pro:latest ports: - containerPort: 5020 env: - name: NODE_ENV value: 'production' - name: PORT value: '5020' - name: MOCKOON_DOMAIN value: 'mockoon.company.com' - name: MOCKOON_SERVER_ID value: 'mockoon-k8s-1' - name: MOCKOON_STORAGE_DIR value: '/data/' volumeMounts: - name: mockoon-storage mountPath: /data volumes: - name: mockoon-storage persistentVolumeClaim: claimName: mockoon-pro-data-pvc

 Environment variables

The application is configured through environment variables passed to the container:

VariableRequiredDefaultDescription
MOCKOON_DOMAINOptionallocalhostBase domain for routing (e.g. mockoon.company.com). If omitted, defaults to localhost.
PORTOptional5020Port on which the HTTP server listens inside the container.
NODE_ENVOptionalproductionNode.js environment mode: production or development.
MOCKOON_STORAGE_DIROptional/data/Path to the directory where SQLite database files and mock environment JSON files are stored. Must be an absolute path inside the container.
MOCKOON_SERVER_IDRequiredmockoon-pro-testUnique identifier for the server node (lowercase letters, digits and hyphens only), used for deployment instances tracking and logging. Set your own value.
USE_HTTPSOptionalAuto-inferredForce true (HTTPS/WSS) or false (HTTP/WS). Automatically inferred as false for localhost and true for custom production domains. Informs the application that traffic is served over HTTPS (behind reverse proxy or Direct TLS).
MOCKOON_TLS_CERT_PATHOptionalNonePath to the server certificate/bundle when using Direct TLS. Direct TLS is only activated if this and MOCKOON_TLS_KEY_PATH are set.
MOCKOON_TLS_KEY_PATHOptionalNonePath to the server private key when using Direct TLS.
MOCKOON_TLS_CA_PATHOptionalNonePath to the CA certificate when using Direct TLS.

 DNS & wildcard routing

Mockoon Pro serves multiple interfaces from your base domain:

  • Dashboard & API: https://mockoon.company.com
  • Embedded Web App: https://mockoon.company.com/app
  • Synchronization Gateway (WebSocket): wss://mockoon.company.com
  • Deployed Mock Instances: https://{subdomain}.mockoon.company.com

Configure two DNS records:

  1. A / CNAME Record: mockoon.company.com pointing to your reverse proxy / ingress IP.
  2. Wildcard Record: *.mockoon.company.com pointing to the same reverse proxy / ingress IP.

 TLS options

Traffic must be served over HTTPS to support both the dashboard (mockoon.company.com) and mock instances (*.mockoon.company.com). Choose one of the following setups:

Using a wildcard certificate (covering mockoon.company.com and *.mockoon.company.com) is the recommended production setup:

  • Privacy: A single wildcard certificate covers all dynamic mock subdomains without exposing individual mock subdomain names in public Certificate Transparency (CT) logs.
  • Obtain the certificate via your DNS provider, internal corporate CA, or Certbot with a DNS-01 challenge (_acme-challenge), then mount it into your reverse proxy:

 Caddy

Copy
https://mockoon.company.com, https://*.mockoon.company.com { tls /etc/ssl/certs/fullchain.pem /etc/ssl/certs/privkey.pem reverse_proxy mockoon-pro:5020 }

Mount your certificates into the Caddy container in docker-compose.yml:

Copy
volumes: - ./Caddyfile:/etc/caddy/Caddyfile:ro - ./certs:/etc/ssl/certs:ro

 Nginx

Copy
server { listen 443 ssl http2; server_name mockoon.company.com *.mockoon.company.com; ssl_certificate /etc/ssl/certs/mockoon-wildcard.crt; ssl_certificate_key /etc/ssl/private/mockoon-wildcard.key; location / { proxy_pass http://127.0.0.1:5020; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; # WebSocket support for Real-time Synchronization proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection "upgrade"; } }

 Option 2: Reverse proxy with On-Demand TLS

Using Caddy with On-Demand TLS is an alternative setup for standalone VM deployments (AWS EC2, Azure VM, GCP Compute Engine, Linux VPS) when DNS-01 validation is unavailable:

  • Caddy automatically requests and renews Let's Encrypt / ZeroSSL TLS certificates on port 80/443 when a new mock subdomain is accessed.
  • Requires no DNS API tokens or manual certificate renewals.

 Option 3: Cluster Ingress (Kubernetes & OpenShift)

 OpenShift Wildcard Routes

OpenShift's native HAProxy router supports wildcard subdomain routes out of the box:

Copy
apiVersion: route.openshift.io/v1 kind: Route metadata: name: mockoon-wildcard spec: host: mockoon.company.com wildcardPolicy: Subdomain to: kind: Service name: mockoon-pro-service tls: termination: edge

 Kubernetes Ingress + cert-manager

On Kubernetes, cert-manager can automatically issue and renew a wildcard certificate using DNS-01 challenges and attach it to your Ingress controller:

Copy
apiVersion: networking.k8s.io/v1 kind: Ingress metadata: name: mockoon-ingress annotations: cert-manager.io/cluster-issuer: letsencrypt-dns01 spec: tls: - hosts: - 'mockoon.company.com' - '*.mockoon.company.com' secretName: mockoon-tls-secret rules: - host: 'mockoon.company.com' http: paths: - path: / pathType: Prefix backend: service: name: mockoon-pro-service port: number: 5020

 Option 4: Direct TLS termination

To have the Mockoon container serve TLS directly without a reverse proxy, set USE_HTTPS=true, NODE_ENV=production, and mount your certificate files:

Copy
docker run -d \ --name mockoon-pro \ -p 443:443 \ -e NODE_ENV=production \ -e PORT=443 \ -e USE_HTTPS=true \ -e MOCKOON_DOMAIN=mockoon.company.com \ -e MOCKOON_SERVER_ID=mockoon-prod \ -e MOCKOON_TLS_CERT_PATH=/certs/fullchain.pem \ -e MOCKOON_TLS_KEY_PATH=/certs/privkey.pem \ -v mockoon-data:/data \ -v /path/to/certs:/certs:ro \ mockoon/pro:latest

 Updating Mockoon Pro

Updating Mockoon Pro is seamless because all persistent data (the SQLite database, settings, user accounts, license information, and synchronized mock environments) resides on the mounted /data storage volume.

When a new version or patch is released, follow the instructions below matching your deployment setup.

Before applying updates, stop the container (the SQLite database runs in WAL mode, so a live copy may be inconsistent) and archive the /data volume:

Copy
docker stop mockoon-pro docker run --rm \ -v mockoon-data:/data:ro \ -v "$(pwd)":/backup \ alpine tar -czf /backup/mockoon-data-backup.tar.gz -C /data .

 2. Update the container

 With Docker Compose

  1. (Optional) Update the image tag: If you pinned a specific version tag in your docker-compose.yml (e.g. mockoon/pro:9.10.0), update it to the target version. If you are tracking latest, you can leave it as is.
  2. Pull the latest image:
    Copy
    docker compose pull
  3. Recreate and restart the service:
    Copy
    docker compose up -d
    Docker Compose will detect the updated image, stop the old container, and start the new one with zero data loss.
  4. Verify startup logs:
    Copy
    docker compose logs -f mockoon-pro
  5. Clean up old dangling images (optional):
    Copy
    docker image prune -f

 With Standalone Docker

  1. Pull the new image:
    Copy
    docker pull mockoon/pro:latest
  2. Stop and remove the old container:
    Copy
    docker stop mockoon-pro docker rm mockoon-pro
  3. Start the new container using your original volume mount and environment parameters:
    Copy
    docker run -d \ --name mockoon-pro \ -p 5020:5020 \ -e NODE_ENV=production \ -e PORT=5020 \ -e MOCKOON_DOMAIN=mockoon.company.com \ -e MOCKOON_SERVER_ID=mockoon-node-1 \ -v mockoon-data:/data \ mockoon/pro:latest

 With Kubernetes / OpenShift

Because latest is a moving tag, set imagePullPolicy: Always on the container and restart the rollout to pull the new image:

Copy
kubectl rollout restart deployment/mockoon-pro

Or pin an exact version tag in your Helm values / Kubernetes manifest and apply:

Copy
kubectl apply -f deployment.yaml

 Automated migrations

When the updated container starts up, any required SQLite database migrations and internal state upgrades are automatically executed. No manual migration scripts or database intervention are needed.

Check the list of migrations for each version to understand the changes applied during the upgrade.