Reference

Migrating from v1

Mocko v2 ships a supervised migration that copies a v1 installation's mocks and flags into v2 on the same Redis. The two versions run side by side during the transition, v1 stays untouched until you explicitly purge it, and rollback is always possible in between.

How it works

v1 and v2 store their data under different key namespaces inside the same Redis, so the safe path is: point your v2 install at the Redis v1 already uses, copy the data across namespaces with the migration operation, verify, and only then decommission v1.

1. Point v2 at the v1 Redis

Deploy v2 in Redis mode against the existing v1 Redis, keeping the same key prefix v1 used. On Helm, that means disabling the chart's bundled Redis and configuring the external one:

persistence:
  redis:
    enabled: true
    internal:
      enabled: false
    url: "redis://my-existing-redis:6379"

control:
  v1Migration:
    enabled: true

v1 Helm installs used the release name as the key prefix, so have your old release name at hand: it is the source prefix the migration will ask for. Outside Helm, it is whatever REDIS_PREFIX v1 ran with.

2. Enable the migration operations

The migration UI is hidden by default. Setting control.v1Migration.enabled: true (or MOCKO_V1_MIGRATION_ENABLED=true on a self-managed control panel) reveals two extra operations on the Management page: Migrate from V1 and Purge V1 data. Turn the setting back off once you are done.

3. Run the migration

Start Migrate from V1and enter the v1 prefix. Like every operation, it scans first and reports what it found, for example "12 mocks and 3,400 flags will be migrated", before anything is written. On execute it copies all flags (values and remaining TTLs) and then all mocks, with live progress, and the migrated mocks are served by v2 the moment the run completes.

The migration is one-time and requires an empty v2 workspace: it refuses to run if v2 already has mocks.
A scan that finds nothing usually means a wrong source prefix; cancel and check the prefix against your v1 configuration.
v1 keeps running unmodified throughout, so you can compare the two side by side before switching traffic.

4. Fix templates that need it

v1 bodies used Handlebars; v2 uses Bigodon. The syntax is largely compatible, and mocks whose templates do not parse as Bigodon are still migrated: they get an Invalid template badge in the mocks list and return 500 if hit, and the badge clears on the first successful save. The usual edits are ../field to $parent.field, {{this}} to {{$this}}, and unescaping triple-stash.

If you use an AI coding agent, install the Mocko skill and ask it to translate the flagged templates:

$npx skills@latest add mocko-app/skills/mocko

5. Purge v1 data

Purge V1 dataappears only after a successful migration run. It deletes the old v1 keys (only Mocko's known key patterns, never a blanket wipe of the prefix) after a confirmation that shows the migration date.

Anything v1 wrote after the migration date is lost on purge. Purge only once v1 is decommissioned and nothing writes to it anymore.

Behavior details

An interrupted migration can be re-run and completes cleanly; flag collisions are overwritten by the v1 value during migration.
v1 installs on a different Redis than the one v2 will use: migrate on the old Redis first, then move the database with standard Redis tooling.
The operations API and UI reject both operations while the v1-migration setting is off, so leaving it disabled day to day costs nothing.