HUB
Sign inSign up

fantasticmock/fantastic-mock

By fantasticmock

•Updated 3 days ago

Self-hosted mock server for HTTP and Kafka: record real APIs, generate mocks, edit in a browser

Image
Networking
Developer tools
0

249

fantasticmock/fantastic-mock repository overview

⁠Fantastic Mock

Fantastic Mock is a self-hosted mock server for HTTP and Kafka, extensible with protocol plugins (WebSocket, gRPC, FIX and more). It records the APIs you depend on, turns that traffic into editable mock templates, and replays requests to check every change. A browser workspace edits templates, inspects traffic and shows a live dashboard.

Free to use, with no account or license key. Website and downloads: https://fantasticmock.com⁠

⁠Quick start

docker run -d --name fantastic-mock -p 127.0.0.1:8080:8080 -v fantastic-mock:/data fantasticmock/fantastic-mock

Open the workspace at http://localhost:8080/__admin/⁠ and send mock traffic to the same port (http://localhost:8080/⁠). The documentation is built in: open it from the question-mark menu in the workspace header.

The workspace has no sign-in. Anyone who can reach the port can read and change your mocks. The command above publishes the port on this machine only (127.0.0.1:); publish it more widely only on a network you trust.

⁠Your data: /data

The server works in /data, and everything it writes goes there: templates (mock-templates/), traffic logs (logs/), Java plugins (plugins-src/, plugins-lib/), protocol plugins (protocol-plugins/), data sources, settings changed in the workspace and error.log. Mount a volume or a folder on /data, or it is lost with the container.

To keep templates in a folder you can put under version control:

docker run -d --name fantastic-mock -p 127.0.0.1:8080:8080 \
  -v "$PWD/mocks:/data" --user "$(id -u)" fantasticmock/fantastic-mock

On Linux, --user "$(id -u)" runs the server as you, so it can write to your folder.

⁠Configuration

Any setting can be given as an argument after the image name, as an environment variable, or in /data/config/application.yml, which is read at startup:

docker run -d -p 127.0.0.1:8080:8080 -v fantastic-mock:/data fantasticmock/fantastic-mock \
  --fantasticmock.mode=proxy-on-miss --fantasticmock.proxy-base-url=https://api.example.com

Environment variables follow Spring Boot's naming: upper case, dots become underscores and dashes are dropped, so fantasticmock.mode is FANTASTICMOCK_MODE.

⁠More ports and protocol plugins

Port 8080 serves HTTP mocks and the workspace. Every other listener (an extra HTTP endpoint, a WebSocket, gRPC or FIX plugin) has a port of its own, and Docker only forwards the ports you publish when the container starts. Choose them up front and publish each one.

For example, the gRPC plugin from https://fantasticmock.com⁠:

  1. Unzip it into protocol-plugins/ in your data folder, giving protocol-plugins/grpc/.

  2. Add an instance to config/application.yml in the data folder. Listen on 0.0.0.0: the plugins' own examples use 127.0.0.1, which inside a container cannot be reached from outside.

    fantasticmock:
      protocols:
        instances:
          grpc-demo:
            protocol: grpc
            enabled: true
            settings:
              host: 0.0.0.0
              port: 9091
              descriptor-file: protocol-plugins/grpc/examples/hello.protoset
    
  3. Publish its port too:

    docker run -d -p 127.0.0.1:8080:8080 -p 127.0.0.1:9091:9091 \
      -v "$PWD/mocks:/data" --user "$(id -u)" fantasticmock/fantastic-mock
    

Paths in plugin settings are relative to /data. Each plugin zip has a README with its settings and example templates.

⁠Java plugins

Handlers, variable generators and template functions are .java files in plugins-src/, with the JARs they need in plugins-lib/. The image carries a full Java runtime with the compiler, so the server compiles and loads them itself.

⁠Memory and JVM options

The heap may take three quarters of the container's memory limit. Give the container at least 1 GB (--memory 1g) and more for heavy traffic or large logs. Pass other JVM options in JAVA_TOOL_OPTIONS:

docker run -e JAVA_TOOL_OPTIONS="-XX:+HeapDumpOnOutOfMemoryError -XX:HeapDumpPath=/data" ...

⁠Health, metrics and diagnostics

  • Health: /actuator/health (with /actuator/health/liveness and /actuator/health/readiness for Kubernetes probes)
  • Prometheus metrics: /actuator/prometheus
  • JDK tools are in the image: docker exec fantastic-mock jcmd 1 Thread.print

⁠Tags

  • latest: the newest release
  • 1.0: the newest 1.0.x release
  • 1.0.6 and so on: one release

Images are built for linux/amd64 and linux/arm64, and rebuilt weekly on patched base images.

Tag summary

Content type

Image

Digest

sha256:dc6fcf643…

Size

158.7 MB

Last updated

3 days ago

docker pull fantasticmock/fantastic-mock