MockServer HTTP/HTTPS Mock and Proxy on Ubuntu 24.04 on Azure User Guide

Overview

MockServer is an open source tool for mocking and virtualizing the HTTP and HTTPS services your application depends on. You configure expectations (a request matcher paired with a mock response, a forward, or a callback) through its control API, then point systems under test at MockServer so they receive deterministic mocked responses instead of calling real dependencies that may be slow, costly, rate limited or not yet built. MockServer can also run as a forward or reverse proxy to record and replay real traffic, and it ships a live web dashboard for inspecting requests and the expectations that matched them.

The cloudimg image installs the pinned official MockServer 7.4.0 runnable jar (OpenJDK 21) running under systemd, then locks it down for a marketplace appliance. MockServer's control API and dashboard are unauthenticated by default, so this image is secure by default: MockServer itself is bound to loopback only (127.0.0.1:1080), and nginx does all customer-facing work on port 80 behind a per-VM HTTP Basic Auth gate whose password (user admin) is generated uniquely on the first boot of every VM. The control/expectation API, the dashboard, and every mock endpoint you configure are all reachable only through that authenticated gate; an unauthenticated /healthz endpoint on port 80 supports Azure Load Balancer probes. Backed by 24/7 cloudimg support.

What is included:

• MockServer 7.4.0 installed as the official runnable jar, running as the mockserver systemd service under OpenJDK 21
• MockServer bound to loopback only (127.0.0.1:1080), with nginx fronting port 80 as the only way in
• Per-VM HTTP Basic Auth (user admin) protecting the control/expectation API, the dashboard, and all mock endpoints, with a unique password generated on first boot
• A single systemd service pair (mockserver.service + nginx.service), enabled and active
• The live MockServer web dashboard at /mockserver/dashboard, behind the same per-VM gate
• An unauthenticated /healthz endpoint on :80 for Azure Load Balancer health probes
• The image ships with zero expectations (first boot proves the gate then resets), so you start from a clean slate
• 24/7 cloudimg support

Prerequisites

An active Azure subscription, an SSH key pair, and a VNet + subnet in the target region. Standard_B2s (2 vCPU / 4 GiB RAM) is a comfortable starting point; size up the JVM heap (JAVA_OPTS in the systemd unit) and the VM for higher request volume. NSG inbound: allow 22/tcp from your management network and 80/tcp for the control API, dashboard and mock endpoints (all behind Basic Auth), plus 443/tcp if you add TLS. MockServer serves plain HTTP; for production use, terminate TLS in front of it with your own domain and restrict access to trusted application subnets.

Step 1 - Deploy from the Azure Marketplace

Sign in to the Azure Portal, choose Create a resource, search the Marketplace for MockServer by cloudimg, and select Create. On Basics pick your subscription, resource group, region and size; under Administrator account choose SSH public key and paste your key; under Inbound port rules allow SSH (22) and HTTP (80). Then Review + create -> Create.

Step 2 - Deploy from the Azure CLI

az vm create \
  --resource-group <your-rg> \
  --name mockserver \
  --image <marketplace-image-urn> \
  --size Standard_B2s \
  --admin-username azureuser \
  --ssh-key-values ~/.ssh/id_ed25519.pub \
  --vnet-name <your-vnet> --subnet <your-subnet> \
  --public-ip-sku Standard

az vm open-port --resource-group <your-rg> --name mockserver --port 80 --priority 1010

Step 3 - Connect to your VM

ssh azureuser@<vm-public-ip>

Step 4 - Confirm the services are running

systemctl is-active mockserver.service nginx.service

Both report active. MockServer serves its control API, dashboard and all mock endpoints on the loopback address 127.0.0.1:1080 only; nginx fronts port 80 with the per-VM HTTP Basic Auth gate. You can confirm the loopback binding with sudo ss -tlnp | grep 1080 - MockServer listens only on 127.0.0.1:1080, never on a public interface.

Step 5 - Retrieve your dashboard password

nginx protects the MockServer control API and dashboard with HTTP Basic Auth. The username is admin and a unique password is generated on the first boot of your VM and written to a root-only file:

sudo cat /root/mockserver-credentials.txt

This file contains MOCKSERVER_USERNAME, MOCKSERVER_PASSWORD, the MOCKSERVER_URL to open in a browser, and MOCKSERVER_DASHBOARD_URL. The password is stored on disk only as a bcrypt hash in /etc/nginx/.mockserver.htpasswd, so no plaintext password ships in the image. Store the password somewhere safe.

Step 6 - Confirm the health endpoint

nginx serves an unauthenticated health endpoint for load balancers and probes:

curl -s http://localhost/healthz

It returns ok. This endpoint never requires authentication, so it is safe for an Azure Load Balancer health probe.

Step 7 - Confirm authentication on the control plane

Because a password is set on first boot, an unauthenticated request to the dashboard or control API returns HTTP 401, so nobody reaches MockServer without the password. The following reads the per-VM password from the credentials file and proves the round-trip - unauthenticated is rejected, a wrong password is rejected, and the correct password authenticates the control API:

PW=$(sudo grep '^MOCKSERVER_PASSWORD=' /root/mockserver-credentials.txt | cut -d= -f2-)
echo "unauth  : $(curl -s -o /dev/null -w '%{http_code}' http://127.0.0.1/mockserver/dashboard)"
echo "wrongpw : $(curl -s -o /dev/null -w '%{http_code}' -u admin:wrong-pw http://127.0.0.1/mockserver/dashboard)"
echo "authed  : $(curl -s -o /dev/null -w '%{http_code}' -u admin:$PW -X PUT http://127.0.0.1/mockserver/status)"

It prints unauth : 401, wrongpw : 401, authed : 200. Only the per-VM password reaches MockServer, because MockServer itself is bound to loopback and nginx port 80 is the only way in.

Step 8 - Create a mock expectation and prove it serves

An expectation tells MockServer: when a request matches this, respond with that. Create one with PUT /mockserver/expectation (through the authenticated gate), then call the mocked path to see the response. The following mocks GET /api/users/1 to return a JSON body:

PW=$(sudo grep '^MOCKSERVER_PASSWORD=' /root/mockserver-credentials.txt | cut -d= -f2-)

curl -s -o /dev/null -w 'PUT /mockserver/expectation -> %{http_code}\n' -u admin:$PW \
  -X PUT http://127.0.0.1/mockserver/expectation \
  -H 'Content-Type: application/json' \
  -d '{"httpRequest":{"method":"GET","path":"/api/users/1"},
       "httpResponse":{"statusCode":200,
                       "headers":{"Content-Type":["application/json"]},
                       "body":{"id":1,"name":"Ada Lovelace","email":"ada@example.com"}}}'

curl -s -u admin:$PW http://127.0.0.1/api/users/1

The PUT returns 201, and the GET returns the mocked JSON body - {"id":1,"name":"Ada Lovelace","email":"ada@example.com"}. Your systems under test now point at this VM's port 80 (with the Basic Auth credentials) and receive deterministic mocked responses. Match on method, path, query string, headers, cookies or body, and respond with a static body, a templated/JavaScript-generated body, a delay, a forward, or a callback - see the MockServer expectations documentation. To clear all expectations, PUT /mockserver/reset.

Step 9 - Sign in to the dashboard

Browse to http://<vm-public-ip>/mockserver/dashboard. Your browser prompts for a username and password: enter admin and the password from Step 5. The MockServer web interface opens on its overview, showing what MockServer can do - build mock responses, sit in front of a real API as a debugging proxy, set breakpoints on in-flight requests, and run chaos and performance testing - with the full feature set in the tabs across the top (Mock, Observe, Verify, Resilience, Inspect).

Step 10 - Watch the live dashboard

Open Observe -> Dashboard for the live view. The Active Expectations panel lists every mock currently configured (here the three seeded above - users-get, products-list, orders-create - with their methods and paths), the Received Requests panel lists every request MockServer handled, and Log Messages shows how each request was matched and what response was returned. All three panels update in real time as requests flow through MockServer, so you can watch your system under test hit the mocks live.

Step 11 - Inspect a mock definition

Expand any entry in the Active Expectations panel to see its full definition - the httpRequest matcher, the httpResponse it returns, its priority and time-to-live. This is the fastest way to confirm exactly how a mock is configured and to debug why a request did or did not match it.

Maintenance

• Password: the dashboard/API password is set on first boot and stored as a bcrypt entry in /etc/nginx/.mockserver.htpasswd. To change it, run sudo htpasswd -B /etc/nginx/.mockserver.htpasswd admin and then sudo systemctl reload nginx.
• Expectations are in-memory: MockServer holds expectations and recorded requests in the JVM's memory; they are cleared on mockserver service restart or VM reboot. To ship a fixed set of mocks that survive restarts, point MockServer at an initialization JSON file by setting Environment=MOCKSERVER_INITIALIZATION_JSON_PATH=/var/lib/mockserver/initializer.json in /etc/systemd/system/mockserver.service, then sudo systemctl daemon-reload && sudo systemctl restart mockserver (see the MockServer initializer docs).
• Reset: PUT /mockserver/reset (with the Basic Auth credentials) clears all expectations and recorded requests without restarting the service.
• Loopback binding: MockServer is bound to 127.0.0.1:1080 in /etc/systemd/system/mockserver.service (-Dmockserver.localBoundIP=127.0.0.1), so nginx is the only path in. Keep it that way - do not change the bind address to a public interface, or you expose the unauthenticated control plane.
• Restrict access: MockServer serves plain HTTP on port 80. For production, restrict access to trusted IP ranges in your Network Security Group, and front it with TLS (for example certbot with your own domain) terminating on :443.
• JVM sizing: the default heap is -Xms256m -Xmx512m (JAVA_OPTS in /etc/systemd/system/mockserver.service). Increase it and the VM size for higher request volume, then sudo systemctl daemon-reload && sudo systemctl restart mockserver.
• Logs: journalctl -u mockserver shows recent MockServer output; raise verbosity by changing -logLevel WARN to INFO or DEBUG in the systemd unit.
• Security patches: unattended-upgrades remains enabled so the OS continues to receive security updates automatically.

Support

cloudimg provides 24/7 expert support for this image. Contact support@cloudimg.co.uk.