Migrate from WireMock Cloud to self-hosted WireMock

Migrate from WireMock Cloud to self-hosted WireMock: what moves and what does not

If your WireMock Cloud renewal is under review, or a hosting or data residency rule means mock definitions cannot sit in a vendor's cloud, the move to self-hosted WireMock is mostly export, re-hosting and rewiring. The open-source engine is the easier part. Expect four pieces of work: export the mock definitions, run the engine as a standalone process or container in your own infrastructure, point CI and test environments at the new endpoint, and decide how each Cloud-only feature will be replaced. Platform or test engineering usually owns this work, with a security reviewer checking where mock stubs and any sample credentials are stored.

Export is where most of the uncertainty sits. The topic notes that exporting definitions as WireMock OSS JSON is an Enterprise feature, so confirm with WireMock whether your current agreement includes that export and which file format you will receive before you plan around it. Inventory every mock API, including its request matching rules, response templates and dependencies on request headers or bodies. Load a small sample into a standalone WireMock instance in a non-production environment, send the same requests to Cloud and to your instance, and compare the responses. Record every mapping that needs manual edits. Stateful scenarios and chaos rules are the parts most likely to need redesign, because they depend on hosted behavior you may not reproduce exactly.

Decide early how each Cloud-only feature will be covered. For stateful mocking, decide whether scenario state can be modeled with the open-source features or whether the affected tests should be rewritten. For chaos rules, decide whether fault injection in your own pipeline is enough or whether a separate tool is needed. To rewire CI, replace the Cloud base URL and API key in pipeline variables with the address of your containerized instance, and keep the Cloud mocks running until the new pipeline has passed several consecutive runs. The main risks are silent drift in matching rules, test code that still calls Cloud URLs, and unclear ownership of the hosted instance after go-live. Ask any implementation partner to document the export check and the feature mapping in writing before work starts.

Which WireMock Cloud capabilities map to open-source WireMock and which need rework

This table maps the main WireMock Cloud capabilities to what open-source WireMock provides when you host it yourself. Read the status column first: clean rows move with exported mappings, needs rework rows change in configuration or process, and gap rows need a decision before cutover. Confirm stateful and chaos behavior against the open-source engine and its extensions in a test environment before you retire any Cloud mocks.

Capability	Open-source WireMock equivalent	Status	Migration note
Mock stubs and request matching	Request matchers and response stubs stored as WireMock JSON mappings	Clean	Export mappings as WireMock OSS JSON, which is an Enterprise feature. Confirm your plan includes it.
Response templating	Templated responses in the open-source templating engine	Needs rework	Test every template helper used in Cloud mappings against the version you deploy.
Hosted mock APIs	Standalone JAR or container you run in your own network	Needs rework	Move hosting, DNS, TLS and access control to your infrastructure. Update base URLs in test configs.
Stateful mocking	Scenario-based state in open-source WireMock, plus any extensions you add	Needs rework	Confirm whether Cloud state behavior has an equivalent. Rebuild it as scenarios or an extension if not.
Chaos rules	Fault and delay settings in open-source WireMock, plus any extensions	Gap	Confirm which Cloud chaos rules the open-source engine reproduces. Plan a substitute for any that it does not.
OpenAPI sync	Specs kept in your repository and loaded by your own pipeline	Needs rework	Replace hosted sync with a CI step that validates or regenerates mappings from the spec file.
SSO and team access	Not provided by open-source WireMock	Gap	Move sign-in to your identity provider. Control edits through repository permissions and review.
Shared team workspaces	Mapping files versioned in Git and shared through your CI environments	Needs rework	Store mappings in Git with review. Agree ownership of each mock API before cutover.

Exporting mock definitions as WireMock OSS JSON

Moving mocks out of WireMock Cloud starts with knowing exactly what you have. The export path, the artifacts behind each mock and the integrations that call Cloud URLs each need a separate pass before you cut over. Work through these cards in order so nothing that tests depend on is left behind.

Confirm export tier and licence first

Exporting definitions as WireMock OSS JSON is an Enterprise feature, so check whether your current plan includes it before you plan the work. Ask WireMock to confirm the current tier, the licence terms that apply to exported files and whether you may run the open-source engine in your own CI and test environments. Get the answer in writing, because it decides whether export is a self-service step or a request you need to raise with the vendor.

Inventory stub mappings and files

List every stub mapping, its request matcher, response definition and priority, and the files that hold response bodies. Stubs that reference bodies by file name need those files exported alongside the mapping JSON, or the mock will return errors after the move. Note any mappings created through the Cloud interface only, since they may not appear in a standard export.

Capture environment variables and OpenAPI sources

Record every value a mock depends on, such as base URLs, feature toggles and fixture identifiers, and where each one is read. Also identify which mocks were generated or synced from an OpenAPI file, because you will need that source file in your repository to regenerate or update them. Without it, the self-hosted mocks become a frozen copy that drifts from the real contract.

Store definitions in version control

Commit exported mappings, body files and OpenAPI sources to a Git repository with a clear folder layout per mock API, and review changes through pull requests like any other test asset. Keep environment-specific values out of committed files and inject them at run time. This turns the mock library into a reviewable artifact that your own engineers control, instead of a set of records in a hosted console.

Rebuild CI jobs that call Cloud URLs

Search your pipelines, test scripts and client configuration for hostnames that point at WireMock Cloud. Each job that calls a Cloud URL must switch to a WireMock instance you run, usually reached through a service name inside the pipeline network. Test each changed job against the new endpoint before removing the old one, since a silent fallback to a missing host can make failures look like passing tests.

Replace Cloud API keys and user access

Find every Cloud API key that CI, developers or scripts use, and plan a replacement for each one. Self-hosted WireMock does not need those keys to serve mocks, so the work is to remove the secrets from pipeline variables and confirm nothing still authenticates to the hosted service. Also list users who reached Cloud through SSO group membership, because their access ends with the subscription, and confirm the access model you will use for the self-hosted instance.

Migration sequence from inventory to decommission

This sequence moves WireMock Cloud mock APIs to WireMock you host without breaking the tests that depend on them. Each step produces a artifact you can check before moving to the next, so the cutover and the decommission are decisions made on evidence.

Inventory mock APIs and their consumers
Start by listing every mock API in your WireMock Cloud account, along with its base path, the stubs and scenarios it contains, and which test suites, pipelines, services or developers call it. Export the list from the Cloud console and confirm it against your CI configuration, because a mock that no pipeline calls is a candidate for retirement rather than migration. Record the owner and the environment variables that point each consumer at the mock URL. The output is an inventory list with one row per mock API, marked as migrate, retire or review, and signed off by the team that owns each consumer.
Export and convert definitions to OSS JSON
Export each mock API's stub definitions in the WireMock JSON format. Confirm first that your plan includes the export, since the supplied facts list it as an Enterprise feature, and ask WireMock to confirm the exact export path for your account. Store the converted mappings and any response body files in a Git repository, with one folder per mock API. Load them into a local standalone WireMock instance and send the requests from the inventory to check that each stub matches and returns the same status, headers and body. The output is a tested definitions repository and a short log of any stubs that failed to convert.
Pilot one non-critical mock API
Choose one low-risk mock API with few consumers and run it twice: once as a standalone WireMock process on a developer machine or test host, and once in a WireMock container built from the same definitions repository. Point a single test suite at each one and compare results with the Cloud version. Check that request matching, response templating and any priority rules behave the same, and note any Cloud-only features the pilot depends on. The output is a pilot result that records pass or fail for each run, the container image tag you tested, and a list of differences that must be resolved before wider use.
Run Cloud and self-hosted mocks in parallel
For every remaining mock API, deploy the self-hosted version next to the Cloud version and run the same test suites against both. Have the pipeline call both endpoints in the same job, so any drift in responses shows up in the same build. Treat any difference in status codes, payload shape or latency-sensitive behavior as a blocking defect until the owning team accepts it. Keep a record of each run so the team can see stable results over time, not one good build. The output is a parallel run report per mock API that shows matching results across the agreed number of runs.
Resolve Cloud-only features before cutover
Review each mock API for features that have no direct equivalent in open-source WireMock, such as the hosted stateful mocking and chaos rules described in the Cloud documentation. For each one, decide whether to reimplement it with open-source WireMock extensions or standalone scripting, move the scenario into the test code, or drop it with the owning team's agreement. Confirm the exact feature set with WireMock before deciding, because the Cloud-only list can change. The output is a decision record that names each Cloud-only feature, the chosen replacement, and the owner who accepted the change.
Cut over CI and environment variables
Change each consumer's environment variables and pipeline configuration so they point to the self-hosted WireMock endpoints, and start the containers from the tested definitions repository in your CI runners or Kubernetes cluster. Make the change in a controlled release, one consumer group at a time, and keep the Cloud URLs in a separate variable set so you can switch back. Run the full suites after each change and confirm that the build results match the parallel run. The output is a cutover checklist with each consumer, the variable changed, the commit that changed it, and the successful run that proves it.
Retain a rollback window then decommission Cloud
Keep the WireMock Cloud mock APIs active but unused for an agreed rollback period, and keep the Cloud URLs in your configuration so you can revert quickly. Confirm the length of that period with your own change process, since no duration is set here. When no consumer has called a Cloud mock during the window, export a final copy of the definitions, remove the API keys and users that no longer need access, and cancel or downgrade the subscription only after finance and procurement confirm the terms. The output is a decommission record that lists the final export location, the removed credentials, the cancellation date and the owner who approved it.

Running WireMock Cloud and self-hosted WireMock side by side

Run WireMock Cloud and self-hosted WireMock in parallel for a defined set of test suites, and keep Cloud as the reference until the self-hosted instance agrees with it. Start with suites that rely on static stubs and simple request matching, since those move with the least change. Point one suite at the self-hosted instance through a single configuration value, such as a base URL held in an environment variable, so the switch can be reversed without editing test code. On each run, capture responses from both targets and compare status codes, headers and bodies, excluding fields that legitimately vary such as timestamps or generated identifiers. Keep Cloud as the fallback until the suites pass on repeated CI runs, and write that threshold down before you begin.

Stateful scenarios need the most care. Cloud state may persist between runs or be reset by your own setup code, while self-hosted WireMock holds scenario state in the running process. Confirm how your current Cloud project resets scenarios, then have each test suite reset state explicitly at its start, for example by calling the reset endpoint of the admin API in a setup hook, so a failed run cannot leak state into the next one. Also review the request journal on the self-hosted instance. Comparing the journal with the Cloud request logs is how you find a call that arrived in a different order or with a different payload. Verify each scenario's behavior in your own environment before relying on it.

Chaos and fault injection need an explicit plan, because Cloud-only chaos rules may not have a direct equivalent in open-source WireMock. WireMock can return some faults and delays in individual stub definitions, so simple cases may be re-created there. Anything beyond that, such as network-level behavior, random failure rates or rules managed from a shared console, should move into test code, a fault proxy placed in front of the mock, or the test harness itself. Record each Cloud chaos rule your suites use, assign it to one of those mechanisms, and run the affected tests against both targets. Treat the open-source behavior as unverified until a test shows the same failure reaching the client, and confirm each mapping against the WireMock version you deploy.

What drives cost and duration in a WireMock migration

This table lists the factors that change the effort of moving mocks from WireMock Cloud to self-hosted WireMock, with the one-time and recurring costs each one affects. Read each row as a question to answer about your own estimate before requesting a quote, because the largest driver is usually the number of mock APIs and their dependencies.

Driver	Why it changes cost or effort	How to keep it down
Number of mock APIs and stubs	Each mock API needs export, review and conversion, so effort grows with the inventory and with stubs that carry hand-written logic.	Inventory every mock API first, retire unused ones, and group similar stubs into shared mappings.
Stateful and chaos features	Stateful scenarios and chaos rules configured in Cloud may not map one-to-one to open-source WireMock, so they need redesign and new tests.	List each stateful scenario and chaos rule, then confirm with WireMock which ones the open-source engine supports before scoping.
OpenAPI sync dependence	If Cloud keeps mocks in step with OpenAPI specifications automatically, you must replace that sync with a pipeline step you own.	Decide whether specs are generated in CI or stored in Git, and automate the regeneration of stubs from them.
CI pipelines and environments	Each pipeline, test environment and branch that calls a Cloud mock URL needs its endpoint, credentials and startup steps changed.	Count pipelines and environments early, and switch them in waves with a rollback path for each.
Enterprise export tier	Exporting definitions as WireMock OSS JSON is an Enterprise feature, so the license tier you hold determines whether export is available without another purchase.	Ask the vendor in writing whether your current plan includes this export before you start the migration.
Hosting and container readiness	Running WireMock standalone or in containers requires a host, image management, networking and monitoring that your platform team may not yet provide.	Confirm an existing container platform and deployment pattern, or reuse the one already used for other test services.
Security review of self-hosted endpoints	Self-hosted mock endpoints need access control, network placement and review, which adds approvals and testing time.	Reuse your standard review checklist for internal test services and document how the endpoints are reached.
Team skills	Teams used to a managed UI may need training on JSON mappings, container operations and CI configuration.	Run a pilot with the team that owns the most mock APIs and record the steps as internal runbooks.
Recurring platform operations	Hosting, patching, upgrades and on-call for the mock platform continue after cutover, and the Cloud subscription no longer covers them.	Set an owner, a patch cadence and an upgrade process before cutover so operations are assigned, not assumed.

What usually goes wrong when moving mock APIs and how to prevent it

Moving mocks from WireMock Cloud to self-hosted WireMock rarely fails in one dramatic step. The problems tend to be quiet: a partial export, a scenario that resolves differently, a rule that never arrived, or a Cloud URL left in a pipeline. Each risk below has a check you can run before cutover and after handover.

Exports missing response files

A definition export can contain the mapping while leaving out the response bodies, binary files or templates that the mapping points to. The stubs then load, match requests and return empty or wrong responses, which looks like a passing test until someone reads the payload. Before cutover, diff the exported mappings and __files folders against the Cloud inventory, then replay a sample of real requests and compare response bodies byte for byte.

Stateful scenarios behaving differently

Scenario state lives in the running server, so a scenario that depended on Cloud-side sequencing or reset behavior may advance differently in a standalone instance. Tests that run in parallel can also share state that was previously isolated per project. Identify every scenario in the export, write a test that walks each state transition in order, and confirm that a reset call returns the scenario to its start state.

Chaos rules silently dropped

Fault injection and latency settings configured in WireMock Cloud may not be part of the open-source definition format, so they can disappear without an error. Tests then pass because the failure never happens, which weakens resilience coverage. List every chaos rule in the Cloud project, decide whether each one is reproduced with a proxy, a delay in the test client or a fault in a separate tool, and add a test that fails when the expected fault does not occur.

CI jobs still calling Cloud URLs

Pipelines, environment files and test fixtures often hard-code the Cloud mock host, so a cutover can leave some jobs calling the old endpoint while others call the new one. The result is intermittent failures that depend on which runner picked up the job. Search repositories and CI variables for the Cloud hostname, move the base URL into a single environment variable, and run a cutover window where the old endpoint is removed from every pipeline before it is switched off.

Credentials copied into repositories

Teams moving quickly often paste API keys, Cloud tokens or basic-auth passwords into exported files, Docker Compose definitions or test code so the new instance works immediately. Those values then persist in Git history where they are hard to remove. Keep credentials in the CI secret store or the container runtime's secret mechanism, scan the export and the repository for token patterns before the first commit, and rotate any value that was ever exposed.

No owner after handover

A self-hosted mock server needs someone to patch the image, watch its availability, restore its mappings and decide when a stub is outdated. When the engineer who built it moves on, the instance keeps running with stale definitions and no one accountable for them. Name an owning team in the service catalog, document the image version, the mapping source of truth and the restore procedure, and agree on who reviews stub changes against the API contract.

How the migration differs by team size and starting point

Illustrative scenario: a small team with a handful of mock APIs used by one or two services and a single CI pipeline. The migration is mostly a matter of exporting the definitions, running WireMock in a container, and pointing the existing tests at the new host. The main effort is confirming that each mock behaves the same way, since there are few places for drift to hide.

Export first: Confirm which mock APIs are actually called by tests and export only those as WireMock OSS JSON, which requires an Enterprise-plan export feature to be checked with the vendor before you rely on it.
Run one container: A single standalone WireMock instance in a container is usually enough, so decide the hosting location and image tag before writing any pipeline changes.
Replace the hosted URL: Change the base URL in test configuration in one place so rollback means reverting one variable.
Document what Cloud did: Write down any response templating or per-user behavior that the team relied on, because it must be reproduced by hand.

Before starting, ask the vendor which export formats and plan tiers apply to your account, and list every test that calls a mock.

How much effort does a WireMock Cloud migration take and what does it need from us?

How much effort does moving WireMock Cloud mocks to self-hosted WireMock involve?

The effort depends mainly on how many mock APIs you have, how many of them use Cloud-only features, and how many test suites and pipelines call them. A small set of stateless stubs is mostly an export, a container image and a CI change. Stateful scenarios, chaos rules and mocks wired to OpenAPI sync need more analysis and retesting, because each one has to be rebuilt or replaced in open-source WireMock and verified. Ask any provider to inventory your mock APIs by feature before quoting, and to state which ones they expect to rework.

How long does a WireMock Cloud to self-hosted WireMock migration take?

Duration follows the same drivers as effort: inventory size, feature usage, the number of consuming teams and how many environments must be cut over. Cutover timing also depends on change windows and how quickly your test owners can confirm results. No duration applies to every estate, so ask for a timeline in the written scope, with milestones for export, containerization, CI integration, parallel running and retirement of the Cloud workspace. Confirm with WireMock how long you retain access to your Cloud account during a parallel run.

Can our in-house team migrate WireMock Cloud mocks without outside help?

Often yes for simple estates. Teams that already run Java or container-based test services and manage their own CI can handle stateless stubs with the open-source documentation. The harder parts are reproducing stateful behavior, replacing chaos rules, and building reliable pipeline steps that other teams will depend on. Consider whether your engineers have time for the retesting. If they do not, a fixed-scope engagement with a written list of deliverables lets you hand over the work without committing to ongoing support.

What does a WireMock migration need from our staff?

Three groups of people are usually needed:

Test owners, who list the mock APIs their suites depend on, confirm expected responses and sign off on parity testing.
CI administrators, who set up container images, environment variables and pipeline stages in your runners.
A security reviewer, who checks how mock definitions containing tokens or internal hostnames are stored, and who controls access to the self-hosted instance.

Agree on named people and their time before work starts, since delays usually come from waiting for sign-off rather than from technical work.

Do we need the Enterprise tier to export our WireMock Cloud mocks?

Export depends on your plan, and WireMock documents the export feature as an Enterprise capability for producing WireMock OSS JSON mappings. If you are not on that tier, you may need to request exports through WireMock, change plans for the migration window, or recreate the stubs from your own sources of truth such as OpenAPI specifications or test code. Confirm with WireMock in writing which tier includes export, whether the exported JSON loads into standalone and containerized WireMock without edits, and what the cost of any tier change is.

What happens to stateful mocking and chaos rules after we leave WireMock Cloud?

Stateful scenarios and chaos rules are the features most likely to need redesign. Open-source WireMock supports scenario-based state in its engine, but the Cloud features for managing them, along with chaos configuration and hosted sync, may not map one-to-one. Inventory every scenario and fault rule, then test each against the self-hosted engine. Ask WireMock which Cloud behaviors have open-source equivalents, which need custom code, and which have no equivalent. Budget test time for those items separately from the simple stubs.

What should we ask for in a migration quote?

Ask for a written scope that lists the mock APIs in and out of scope, the export method, the containerized runtime, the CI integration steps, the parity tests and the cutover plan. Require a feature-by-feature mapping for stateful and chaos behavior, a named list of client-side changes, a rollback plan and a retirement plan for the Cloud workspace. Confirm which deliverables are one-time and which recur, such as image upgrades or support. DeployOpen plans and implements self-hosted platforms in your own infrastructure and provides fixed-scope engagements agreed in writing, with ongoing support available as a retainer.

How DeployOpen scopes, runs and supports the migration

DeployOpen plans, implements, integrates, hardens, documents and supports self-hosted open-source platforms inside your own infrastructure. For a move from WireMock Cloud to WireMock you host, we start from a written scope that names which mock APIs, environments and CI pipelines are in and out, then build and hand the setup over with documentation your team can run.

How we scope

We inventory the mock APIs, stubs and environments you currently run in WireMock Cloud before any work starts.
We record which definitions can be exported as WireMock OSS JSON and which depend on Cloud-only features.
Engagements are fixed-scope, with deliverables and timelines agreed in writing before work begins.

How we build

We deploy WireMock standalone or in containers inside your cloud accounts, data centers or air-gapped networks.
We wire the mock runtime into your CI pipelines so test jobs call your own instance instead of a hosted endpoint.
We test each migrated mock against the consumers that depend on it and record the results for your review.

How we hand over

We deliver configuration, runbooks and a map showing where each Cloud feature was replaced or retired.
We document the stateful mocking and chaos behavior that needs redesign, so your team can decide how to rebuild it.
We walk your engineers through running, updating and rolling back the self-hosted mock service.

How we support

Ongoing support, upgrades and continuous testing are available as retainers after handover.
We can help you keep the self-hosted WireMock version and container images current under your change process.
Ask any provider to confirm how support, upgrades and access to your environment are handled in the written scope.

Migrate from WireMock Cloud to self-hosted WireMock