SecureAnyCloud
Deployment guide

MockServer

Overview

MockServer is an open source tool for mocking and virtualizing the HTTP and HTTPS services your application depends on. You configure expectations through its control API. An expectation is a request matcher paired with a mock response, a forward or a callback. You then point your 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. It ships a live web dashboard for inspecting requests and the expectations that matched them.

MockServer's control API and dashboard are unauthenticated by default. This SecureAnyCloud image installs the pinned official MockServer 7.4.0 runnable jar (OpenJDK 21) under systemd and locks it down, so it is secure by default.

What you get:

  • 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) that protects the control and expectation API, the dashboard and all mock endpoints. The password is unique to each VM and is generated on first boot
  • A single systemd service pair (mockserver.service and 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
  • Zero expectations out of the box. First boot verifies the gate and then resets, so you start from a clean slate
  • 24/7 SecureAnyCloud support

nginx does all customer-facing work on port 80, behind the Basic Auth gate. The control and expectation API, the dashboard and every mock endpoint you configure are reachable only through that authenticated gate.

Prerequisites

You need an active Azure subscription, an SSH key pair, and a VNet with a subnet in the target region.

Standard_B2s (2 vCPU / 4 GiB RAM) is a comfortable starting size. For higher request volume, size up the JVM heap (JAVA_OPTS in the systemd unit) and the VM.

Configure the network security group (NSG) to allow inbound 22/tcp from your management network and 80/tcp for the control API, dashboard and mock endpoints, all behind Basic Auth. Also allow 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 SecureAnyCloud, and select Create.

On the Basics tab, 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 select Review + create and Create.

Step 2 - Deploy from the Azure CLI

Accept the Marketplace terms once per subscription, create the VM, then open port 80.

# Accept the Marketplace terms once per subscription (required before the first CLI deploy)
az vm image terms accept --urn sac1647283583153:mockserver-ubuntu-24-04:default:latest
az vm create \
  --resource-group <your-rg> \
  --name mockserver \
  --image sac1647283583153:mockserver-ubuntu-24-04:default:latest \
  --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

Connect over SSH with the key you supplied at deployment.

ssh azureuser@<vm-public-ip>

Step 4 - Confirm the services are running

Check that both services are active:

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.

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. 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. Store the password somewhere safe.

The password is stored on disk only as a bcrypt hash in /etc/nginx/.mockserver.htpasswd, so no plaintext password ships in the image.

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. Nobody reaches MockServer without the password.

The commands below read the per-VM password from the credentials file and test three cases: an unauthenticated request 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 confirm 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 example below 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.

You can match on method, path, query string, headers, cookies or body. You can respond with a static body, a templated or JavaScript-generated body, a delay, a forward or a callback. See the MockServer expectations documentation for details. To clear all expectations, call 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. It shows 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. The full feature set is in the tabs across the top (Mock, Observe, Verify, Resilience, Inspect).

Step 10 - Watch the live dashboard

Open Observe -> Dashboard for the live view. It has three panels:

  • Active Expectations lists every mock currently configured, with its method and path. Examples include mocks named users-get, products-list and orders-create.
  • Received Requests lists every request MockServer handled.
  • 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 and 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, then sudo systemctl reload nginx.
  • Expectations are in memory. MockServer holds expectations and recorded requests in the JVM's memory, and they are cleared on a 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 run sudo systemctl daemon-reload && sudo systemctl restart mockserver. See the MockServer initializer docs for details.
  • 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 terminating on :443, for example with certbot and your own domain.
  • JVM sizing. The default heap is -Xms256m -Xmx512m (JAVA_OPTS in /etc/systemd/system/mockserver.service). For higher request volume, increase it and the VM size, then run sudo systemctl daemon-reload && sudo systemctl restart mockserver.
  • Logs. journalctl -u mockserver shows recent MockServer output. To raise verbosity, change -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

SecureAnyCloud provides 24/7 expert support for this image. Contact sales@secureanycloud.com.

Deploy on Azure

Launch MockServer on Ubuntu 24.04 LTS on Azure with 24/7 support from SecureAnyCloud.

View this image

Need Help?

Our support team is available 24/7.

sales@secureanycloud.com

Deploy on Azure