Installation & Deployment Guide

Contents

1. Overview
2. Components and Ports
3. Running Binaries Directly
4. Running with Docker
5. Docker Compose Examples
6. Upgrading a Running Deployment
7. Environment Variables Reference
8. SQLite Standalone Mode
9. Mock Resolver
10. Runner Agent
11. Server Generator
12. TLS Configuration
13. Backup and Restore
14. Health Checks
15. Production Recommendations

Overview

What is Docker? Docker is a tool that packages applications into lightweight, portable containers so they run the same way on any machine. Using Docker for Mockarty simplifies deployment: you get a reproducible environment with all dependencies bundled, easy scaling with Docker Compose, and no need to install anything on the host besides Docker itself.

Mockarty is distributed in two ways:

1. Pre-built binaries — download from GitHub Releases and run as native processes
2. Official Docker images — pull from Docker Hub and run in containers

Official Docker Hub images:

All binaries and Docker images are self-contained and include embedded web UI assets, database migrations, and default configurations.

About URLs in examples: All examples use localhost:5770 as the default Mockarty address. If your instance runs on a remote server, replace localhost:5770 with its actual address (e.g. https://mockarty.company.com or http://192.168.1.50:5770). See Tips & Useful Features for details.

Components and Ports

Note: Port 5773 is an internal coordinator gRPC port used for resolver/runner node registration. It is not for general gRPC mock traffic.

Firewall checklist

Open the following ports to reach the admin node from clients and neighbouring services:

• 5770/tcp — HTTP: Web UI, REST API, mock traffic (stubs). Open to end users and SDK/CLI clients.
• 5771/tcp — HTTPS: same as above with TLS. Open to end users when HTTPS_ENABLED=true.
• 5772/tcp — MCP (Model Context Protocol). Open only to hosts running MCP-compatible AI assistants.
• 5773/tcp — Coordinator gRPC. Open only to resolver/runner nodes; keep it off the public internet.

Resolver nodes additionally expose 5780/tcp (mock traffic) and 6780/tcp (dashboard); runner agents expose 6770/tcp (dashboard). Open these only where the corresponding component is deployed.

Running Binaries Directly

1. Download

Download the appropriate binary for your platform from GitHub Releases.

2. Make executable (Linux/macOS)

chmod +x mockarty

3. Run the binary

The simplest way to start is with SQLite — no external database required:

DB_USE=sqlite ./mockarty

Mockarty will start on http://localhost:5770 with a SQLite database at ~/.mockarty/data.db.

Default admin credentials: admin / admin (change immediately after first login).

4. Run with PostgreSQL

export DB_USE=pg
export DB_DSN="postgres://mockarty:password@localhost:5432/mockarty?sslmode=disable"
export FIRST_ADMIN_PASSWORD=change_me

./mockarty

The admin node will start on http://localhost:5770.

5. Run with SQLite (no PostgreSQL needed)

export DB_USE=sqlite
export DB_DSN="/path/to/mockarty.db"
export FIRST_ADMIN_PASSWORD=change_me

./mockarty

If DB_DSN is empty with DB_USE=sqlite, the database defaults to ~/.mockarty/data.db.

Understanding Mock Resolution URLs

Mockarty uses a namespace-based URL routing system. All mock traffic goes through the /stubs/ prefix followed by the namespace name:

http://localhost:5770/stubs/{namespace}/{your-mock-route}

For example, if you create a mock with route /api/users in the sandbox namespace:

# Call your mock
curl http://localhost:5770/stubs/sandbox/api/users

# With query parameters
curl "http://localhost:5770/stubs/sandbox/api/users?page=1&limit=10"

# POST request
curl -X POST http://localhost:5770/stubs/sandbox/api/users \
  -H "Content-Type: application/json" \
  -d '{"name": "John"}'

The sandbox namespace is created automatically on first launch. You can create additional namespaces via the Admin Panel or Settings page.

Important: The /stubs/{namespace}/ prefix is required for all mock resolution requests. The Web UI, REST API, and management endpoints use different paths (e.g., /ui/, /mock/, /api/).

6. Run database migrations

Migrations are applied automatically on startup. To manage them manually:

# Apply all pending migrations
./mockarty --migrate up

# Apply N migrations
./mockarty --migrate up --migrate-steps N

# Rollback N migrations
./mockarty --migrate down --migrate-steps N

# Show current migration version
./mockarty --migrate version

# Dry run (print SQL without executing)
./mockarty --migrate up --migrate-dry-run

# Auto-fix dirty migration state
./mockarty --migrate up --migrate-fix-dirty

7. Run as a systemd service (Linux)

Create /etc/systemd/system/mockarty.service:

[Unit]
Description=Mockarty Mock Server
After=network.target postgresql.service

[Service]
Type=simple
User=mockarty
ExecStart=/opt/mockarty/mockarty
WorkingDirectory=/opt/mockarty
Environment=DB_USE=pg
Environment=DB_DSN=postgres://mockarty:password@localhost:5432/mockarty?sslmode=disable
Environment=FIRST_ADMIN_PASSWORD=change_me
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target

sudo systemctl enable mockarty
sudo systemctl start mockarty

Running with Docker

Warning: HTTP_BIND_ADDR — Inside Docker containers, you MUST set HTTP_BIND_ADDR=0.0.0.0. The default localhost makes the server unreachable from outside the container.

Warning: COOKIE_SECURE — When running without HTTPS (development), set COOKIE_SECURE=false to avoid authentication loops.

Using official Docker images

The quickest way to start is with the official Docker Hub images:

Admin Node

docker run -d \
  --name mockarty \
  -p 5770:5770 \
  -p 5771:5771 \
  -p 5772:5772 \
  -e HTTP_BIND_ADDR=0.0.0.0 \
  -e DB_USE=pg \
  -e DB_DSN="postgres://mockarty:password@postgres:5432/mockarty?sslmode=disable" \
  -e FIRST_ADMIN_PASSWORD=change_me \
  mockarty/mockarty:latest

With SQLite (no database server needed)

docker run -d \
  --name mockarty \
  -p 5770:5770 \
  -e HTTP_BIND_ADDR=0.0.0.0 \
  -e DB_USE=sqlite \
  -e DB_DSN="/data/mockarty.db" \
  -e FIRST_ADMIN_PASSWORD=change_me \
  -v mockarty-data:/data \
  mockarty/mockarty:latest

Building a custom Docker image from binary

If you cannot use Docker Hub (air-gapped environments), create a minimal image from the downloaded binary:

FROM alpine:3.20
RUN apk add --no-cache ca-certificates tzdata curl
COPY mockarty /usr/local/bin/mockarty
RUN chmod +x /usr/local/bin/mockarty
EXPOSE 5770 5771 5772 5773
HEALTHCHECK --interval=30s --timeout=5s --retries=3 \
  CMD curl -f http://localhost:5770/health/live || exit 1
ENTRYPOINT ["mockarty"]

Build and run:

docker build -t mockarty:latest -f Dockerfile.admin .
docker run -d \
  --name mockarty \
  -p 5770:5770 \
  -e HTTP_BIND_ADDR=0.0.0.0 \
  -e DB_USE=sqlite \
  -e FIRST_ADMIN_PASSWORD=change_me \
  mockarty:latest

Important: Use the linux/amd64 or linux/arm64 binary matching your Docker host architecture.

Docker Compose Examples

Minimal: Admin + PostgreSQL

services:
  postgres:
    image: postgres:17-alpine
    environment:
      POSTGRES_USER: mockarty
      POSTGRES_PASSWORD: change_me
      POSTGRES_DB: mockarty
    volumes:
      - pg-data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U mockarty"]
      interval: 5s
      retries: 10

  mockarty:
    image: mockarty/mockarty:latest
    ports:
      - "5770:5770"   # HTTP — Web UI, REST API, mock traffic
      - "5771:5771"   # HTTPS
      - "5772:5772"   # MCP
      - "5773:5773"   # gRPC coordinator (for resolver/runner nodes)
    environment:
      HTTP_BIND_ADDR: "0.0.0.0"
      DB_USE: pg
      DB_DSN: postgres://mockarty:change_me@postgres:5432/mockarty?sslmode=disable
      FIRST_ADMIN_PASSWORD: change_me
    depends_on:
      postgres:
        condition: service_healthy
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:5770/health/live"]
      interval: 10s
      timeout: 5s
      retries: 10

volumes:
  pg-data:

Minimal: Admin + SQLite (no database server)

services:
  mockarty:
    image: mockarty/mockarty:latest
    ports:
      - "5770:5770"
      - "5771:5771"
    environment:
      HTTP_BIND_ADDR: "0.0.0.0"
      DB_USE: sqlite
      DB_DSN: /data/mockarty.db
      FIRST_ADMIN_PASSWORD: change_me
    volumes:
      - mockarty-data:/data

volumes:
  mockarty-data:

Full: Admin + PostgreSQL + Redis + Resolver + Runner

Distributed deployment requires two-phase startup because resolver and runner nodes need integration tokens that are generated by the admin node.

Step 1: Start the admin node and database

Create docker-compose.yml:

services:
  postgres:
    image: postgres:16-alpine
    environment:
      POSTGRES_USER: mockarty
      POSTGRES_PASSWORD: change_me
      POSTGRES_DB: mockarty
    volumes:
      - pg-data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U mockarty"]
      interval: 5s
      retries: 10

  redis:
    image: redis:7-alpine
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 5s
      retries: 10

  mockarty:
    image: mockarty/mockarty:latest
    ports:
      - "5770:5770"
      - "5771:5771"
      - "5772:5772"
      - "5773:5773"   # gRPC coordinator (internal — expose only within compose network)
    environment:
      HTTP_BIND_ADDR: "0.0.0.0"
      DB_USE: pg
      DB_DSN: postgres://mockarty:change_me@postgres:5432/mockarty?sslmode=disable
      CACHE_TYPE: redis
      REPO_REDIS_HOST: redis
      REPO_REDIS_PORT: "6379"
      FIRST_ADMIN_PASSWORD: change_me
      RUNNER_GRPC_BIND_ADDR: "0.0.0.0"
    depends_on:
      postgres:
        condition: service_healthy
      redis:
        condition: service_healthy
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:5770/health/live"]
      interval: 10s
      timeout: 5s
      retries: 10

  resolver:
    image: mockarty/resolver:latest
    ports:
      - "5780:5780"
      - "6780:6780"
    environment:
      COORDINATOR_ADDR: mockarty:5773
      API_TOKEN: "${RESOLVER_API_TOKEN}"
      RESOLVER_NAME: "resolver-1"
      DB_DSN: postgres://mockarty:change_me@postgres:5432/mockarty?sslmode=disable
      HTTP_PORT: "5780"
    depends_on:
      mockarty:
        condition: service_healthy

  runner:
    image: mockarty/runner:latest
    environment:
      COORDINATOR_ADDR: mockarty:5773
      API_TOKEN: "${RUNNER_API_TOKEN}"
      RUNNER_NAME: "runner-1"
      SHARED: "true"
      CAPABILITIES: "api_test,performance"
    depends_on:
      mockarty:
        condition: service_healthy

volumes:
  pg-data:

Start only the admin node first:

docker compose up -d postgres redis mockarty

Wait for the admin node to become healthy, then log in to the Web UI at http://localhost:5770/ui/ and change the default password.

Step 2: Generate integration tokens and start resolver/runner

Generate tokens for the resolver and runner via the API:

# Log in and get a session cookie (replace password with your actual admin password)
# Or use an API token from Settings > API Tokens in the Web UI

# Create a resolver integration token
curl -X POST http://localhost:5770/api/v1/integrations \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"resolver-1","type":"mock_resolver"}'

# Create a runner integration token
curl -X POST http://localhost:5770/api/v1/integrations \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"runner-1","type":"test_runner"}'

Each response includes a token field (format: mki_...). Save the tokens immediately — they are shown only once.

Put the tokens in a .env file next to your docker-compose.yml:

RESOLVER_API_TOKEN=mki_your_resolver_token_here
RUNNER_API_TOKEN=mki_your_runner_token_here

Now start the full stack:

docker compose up -d

The resolver and runner nodes will authenticate with the admin node using the integration tokens and register themselves via the coordinator gRPC port (5773).

Important: If resolver or runner nodes start without valid tokens, they will fail to connect and restart in a loop. Always generate tokens before starting these components.

With Generated Servers

Generated servers produced by mockarty-server-generator are standalone services that call back to the Mockarty admin node for mock resolution:

services:
  mockarty:
    image: mockarty/mockarty:latest
    ports:
      - "5770:5770"
    environment:
      HTTP_BIND_ADDR: "0.0.0.0"
      DB_USE: pg
      DB_DSN: postgres://mockarty:change_me@postgres:5432/mockarty?sslmode=disable
      FIRST_ADMIN_PASSWORD: change_me

  # Generated MCP server (built from generated code)
  mcp-server:
    image: my-mcp-server:latest
    ports:
      - "8080:8080"   # Admin UI
      - "8910:8910"   # MCP SSE endpoint
    environment:
      HTTP_ADMIN_BASE_URL: http://mockarty:5770
      NAMESPACE: sandbox
      MCP_SSE_PORT: "8910"
    depends_on:
      - mockarty

  # Generated gRPC server (built from generated code)
  grpc-server:
    image: my-grpc-server:latest
    ports:
      - "4770:4770"   # gRPC
      - "8081:8080"   # Admin UI
    environment:
      HTTP_ADMIN_BASE_URL: http://mockarty:5770
      GRPC_PORT: "4770"
      NAMESPACE: sandbox
    depends_on:
      - mockarty

Note: Generated servers are built from the code produced by mockarty-server-generator. See the Code Generator Guide for details.

Upgrading a Running Deployment

Mockarty ships as a set of versioned Docker images on Docker Hub. The upgrade flow is the same regardless of whether you started with Compose or with Helm: change the image tag and let the orchestrator replace containers. Database migrations run automatically on admin-node startup, so no manual SQL is required.

Docker Hub image names

Each image is published with two tags: the exact version (e.g. mockarty/mockarty:0.0.4-beta) and latest. Pin an exact version in production — latest can move without warning.

Before you upgrade

1. Back up the database. On single-node setups run docker compose exec postgres pg_dump -U mockarty mockarty > backup.sql. On Helm-managed clusters use your existing Postgres backup workflow.
2. Read the release notes for the target version at https://mockarty.ru/downloads or on GitHub.
3. Verify health of the current deployment: curl -fsS http://<admin>/health/live.

Docker Compose upgrade

# 1. Pin the new version in your .env file (or export inline):
#    VERSION=0.0.4-beta

# 2. Pull the new images
docker compose -f docker-compose.minimal.yml pull

# 3. Recreate containers in-place (preserves volumes)
docker compose -f docker-compose.minimal.yml up -d

# 4. Watch logs until the admin node reports "migrations applied"
docker compose -f docker-compose.minimal.yml logs -f mockarty

For the distributed stack, upgrade in this order to avoid draining connections mid-migration:

docker compose -f docker-compose.distributed.yml pull
docker compose -f docker-compose.distributed.yml up -d --no-deps mockarty
docker compose -f docker-compose.distributed.yml up -d --no-deps mockarty-resolver
docker compose -f docker-compose.distributed.yml up -d --no-deps mockarty-runner

Helm / Kubernetes upgrade

# Option A — bump the chart-wide tag (simplest)
helm upgrade mockarty deploy/helm/mockarty \
  --namespace mockarty \
  --reuse-values \
  --set admin.image.tag=0.0.4-beta \
  --set resolver.image.tag=0.0.4-beta \
  --set runner.image.tag=0.0.4-beta \
  --set orchestrator.image.tag=0.0.4-beta

# Option B — keep your values.yaml authoritative
#   edit values.yaml → bump image.tag on each component
helm upgrade mockarty deploy/helm/mockarty --namespace mockarty -f values.yaml

Kubernetes rolls pods using RollingUpdate (maxSurge=1, maxUnavailable=0), so traffic to the resolver and runner stays uninterrupted. The admin StatefulSet is upgraded one pod at a time; a brief UI flicker during the admin roll is expected.

Rollback

# Docker Compose: pin the previous VERSION in .env and re-run up -d
VERSION=0.0.3 docker compose -f docker-compose.minimal.yml up -d

# Helm: roll the release back
helm rollback mockarty --namespace mockarty

Migration rollbacks (./mockarty --migrate down --migrate-steps N) are supported only for the last N migrations and should only be used if the newer version explicitly documents a down-migration path. When in doubt, restore from backup instead.

Environment Variables Reference

Core

HTTP Server

MCP Server

LLM / AI Assistant

AI Agent (ADK)

Database

Cache

Authentication

OAuth Providers

Recommended: Configure OAuth providers through the Admin Panel UI (Admin Panel > Identity Providers) for hot-reload support. The environment variables below are supported for backward compatibility and initial bootstrap only.

LDAP / Active Directory

LDAP/AD authentication is configured exclusively through the Admin Panel UI (Admin Panel > Identity Providers). Settings are stored in the database and hot-reloaded without a restart. There are no environment variables for LDAP — sign in as the bootstrap admin and complete the setup in the UI.

Email Notifications

Runner Coordinator

Chaos Engineering

Chaos engineering requires a PRO license and a connected Kubernetes cluster. See the Chaos Engineering guide for full details.

Contract Testing

Contract testing validates that mocks stay in sync with API specifications. See the Contract Testing guide for details.

Contract testing is enabled per-user in User Settings and does not require additional environment variables. Contract validation runs are configured via the UI or API.

License

License keys are entered through the Admin Panel UI: Administration → License. No environment variables are needed for license activation.

Security

Cluster

Event Bus

SQLite Standalone Mode

Mockarty supports SQLite for smaller deployments that don’t require PostgreSQL. SQLite mode is ideal for:

• Single-server deployments
• Development and testing environments
• Quick evaluations

# Direct binary
DB_USE=sqlite DB_DSN="/data/mockarty.db" ./mockarty

# Docker
docker run -d \
  --name mockarty \
  -p 5770:5770 \
  -e HTTP_BIND_ADDR=0.0.0.0 \
  -e DB_USE=sqlite \
  -e DB_DSN="/data/mockarty.db" \
  -e FIRST_ADMIN_PASSWORD=change_me \
  -v mockarty-data:/data \
  mockarty/mockarty:latest

SQLite uses WAL mode for concurrent reads with a single writer.

Limitations:

• No distributed resolver/runner support — resolver nodes require PostgreSQL via DB_DSN for shared database access, which is not possible with a single SQLite file
• Some dashboard statistics queries may return empty results on SQLite
• If DB_DSN is empty with DB_USE=sqlite, defaults to ~/.mockarty/data.db

Mock Resolver

For detailed setup instructions, see the Integrations Guide.

Resolver nodes handle mock resolution traffic, offloading the admin node. Route all mock traffic (HTTP, gRPC, etc.) to resolver nodes; admin UI and management API stay on the admin node.

Running directly

export COORDINATOR_ADDR=mockarty:5773
export API_TOKEN="mki_your_resolver_token"
export RESOLVER_NAME="resolver-1"
export DB_DSN="postgres://mockarty:password@localhost:5432/mockarty?sslmode=disable"
export HTTP_PORT=5780

./mockarty-resolver

Note: The resolver requires direct database access (DB_DSN) for reading mock definitions. It must use the same database as the admin node.

Running with Docker

resolver:
  image: mockarty/resolver:latest
  ports:
    - "5780:5780"   # Mock resolution traffic
    - "6780:6780"   # Dashboard UI
  environment:
    COORDINATOR_ADDR: mockarty:5773
    API_TOKEN: "mki_your_token"
    RESOLVER_NAME: "resolver-1"
    DB_DSN: postgres://mockarty:password@postgres:5432/mockarty?sslmode=disable
    HTTP_PORT: "5780"
  depends_on:
    - mockarty

Environment variables

Creating integration tokens

Create resolver tokens via the API (requires admin authentication):

curl -X POST http://localhost:5770/api/v1/integrations \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"resolver-1","type":"mock_resolver"}'

The response includes the token field (shown once, save it immediately). Token format: mki_*.

Tip: Get your YOUR_API_TOKEN from Settings > API Tokens in the Web UI after logging in as admin.

Runner Agent

For detailed setup instructions, see the Integrations Guide.

Runner agents execute performance tests and API test collections. They connect to the admin node via gRPC on port 5773.

Running directly

export COORDINATOR_ADDR=mockarty:5773
export API_TOKEN="mki_your_runner_token"
export RUNNER_NAME="runner-1"
export SHARED=true
export CAPABILITIES="api_test,performance"

./mockarty-runner

Running with Docker

runner:
  image: mockarty/runner:latest
  environment:
    COORDINATOR_ADDR: mockarty:5773
    API_TOKEN: "mki_your_runner_token"
    RUNNER_NAME: "runner-1"
    SHARED: "true"
    MAX_CONCURRENT_TASKS: "3"
    CAPABILITIES: "api_test,performance"
  depends_on:
    - mockarty

Environment variables

Creating integration tokens

curl -X POST http://localhost:5770/api/v1/integrations \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"runner-1","type":"test_runner"}'

The response includes the token field (shown once, save it immediately). Token format: mki_*.

Runner scope

• Shared runners (SHARED=true) — receive tasks from all namespaces
• Namespace runners (SHARED=false, NAMESPACE=sandbox) — only receive tasks from their namespace

Capabilities

Server Generator

The server generator can run as a CLI tool or as an orchestrator server.

Running the orchestrator

./mockarty-server-generator orchestrator \
  -api-token mk_your_token \
  -http-admin-base-url http://localhost:5770 \
  -port 8888

Running the orchestrator with Docker

server-generator:
  image: mockarty/generator:latest
  command: ["orchestrator", "-api-token", "mk_your_token", "-http-admin-base-url", "http://mockarty:5770", "-port", "8888"]
  ports:
    - "8888:8888"
  depends_on:
    - mockarty

For detailed server generator usage, see the Code Generator Guide.

TLS Configuration

Auto-generated certificates

By default, Mockarty generates self-signed TLS certificates on first start:

# Direct binary
HTTPS_ENABLED=true HTTPS_TLS_DIR=/opt/mockarty/tls ./mockarty

# Docker
docker run -d \
  -e HTTP_BIND_ADDR=0.0.0.0 \
  -e HTTPS_ENABLED=true \
  -e HTTPS_TLS_DIR=/app/tls \
  -v mockarty-tls:/app/tls \
  mockarty/mockarty:latest

Custom certificates

# Direct binary
HTTPS_ENABLED=true \
HTTPS_CERT_FILE=/path/to/server.crt \
HTTPS_KEY_FILE=/path/to/server.key \
./mockarty

# Docker
docker run -d \
  -e HTTP_BIND_ADDR=0.0.0.0 \
  -e HTTPS_ENABLED=true \
  -e HTTPS_CERT_FILE=/certs/server.crt \
  -e HTTPS_KEY_FILE=/certs/server.key \
  -v /path/to/certs:/certs:ro \
  mockarty/mockarty:latest

Coordinator gRPC TLS

For securing the coordinator gRPC channel between admin and resolver/runner nodes:

RUNNER_GRPC_TLS_ENABLED=true \
RUNNER_GRPC_TLS_CERT_FILE=/certs/grpc-server.crt \
RUNNER_GRPC_TLS_KEY_FILE=/certs/grpc-server.key \
RUNNER_GRPC_TLS_CLIENT_CA_CERT=/certs/ca.crt \
./mockarty

Backup and Restore

Mockarty includes a built-in backup system accessible from Admin Panel > Backup. It uses pg_dump/pg_restore for PostgreSQL and file copy for SQLite.

The official Docker image includes postgresql-client (pg_dump, pg_restore, psql), so backups work out of the box.

Key features:

• Scheduled backups — configurable via cron expression (default: daily at 2:00 AM)
• Manual backups — create on demand from the Admin Panel
• Multiple formats — custom (recommended), plain, tar, directory
• Compression — optional, reduces backup file size
• Retention policy — automatically delete old backups after N days
• Download / Restore — from the Admin Panel or via API

API examples:

# Create a backup
curl -X POST http://localhost:5770/api/v1/admin/backups/create \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"config_id": "your-config-id"}'

# Download a backup
curl http://localhost:5770/api/v1/admin/backups/download?path=backup_file.dump \
  -H "Authorization: Bearer $TOKEN" -o backup.dump

# Restore from uploaded file
curl -X POST http://localhost:5770/api/v1/admin/backups/restore-from-file \
  -H "Authorization: Bearer $TOKEN" -F "file=@backup.dump"

For Docker deployments, mount a persistent volume for backup storage:

docker run -v /host/path/data:/app/data mockarty/mockarty:latest

See the Administration Guide for detailed configuration.

Health Checks

All components expose health endpoints:

Example health check:

curl http://localhost:5770/health/live

Production Recommendations

1. Use PostgreSQL — SQLite is for development and small single-server deployments only
2. Set strong secrets — change FIRST_ADMIN_PASSWORD from defaults
3. Use a reverse proxy (nginx/Traefik) in front for TLS termination and routing
4. Use Redis with CACHE_TYPE=redis for better admin node performance at scale
5. Enable backups — mount a persistent volume for backup storage
6. Use resolver nodes for high-traffic mock resolution (separates mock traffic from admin UI)
7. Use runner agents for distributed test execution
8. Set COOKIE_SECURE=true — enabled by default, ensures cookies are only sent over HTTPS
9. Keep ALLOW_PROXY_TO_PRIVATE_IPS=false — default, prevents SSRF through proxy feature
10. Set HTTP_BIND_ADDR=0.0.0.0 in Docker/production to accept external connections (defaults to localhost)
11. Enable contract testing to validate that mocks stay in sync with API specifications. See the Contract Testing guide.
12. Use chaos engineering to test system resilience with controlled fault injection experiments. See the Chaos Engineering guide (PRO license required).

Kubernetes Deployment

For production Kubernetes environments, Mockarty provides Helm charts and a CRD-based operator that manages the full cluster lifecycle – scaling, upgrades, health checks, and token bootstrapping.

Helm Quick Install

# Add the Mockarty Helm repository
helm repo add mockarty https://charts.mockarty.com
helm repo update

# Create secrets for database and license
kubectl create namespace mockarty
kubectl -n mockarty create secret generic mockarty-db \
  --from-literal=dsn="postgres://mockarty:secret@postgres:5432/mockarty?sslmode=require"
kubectl -n mockarty create secret generic mockarty-license \
  --from-literal=key="YOUR_LICENSE_KEY"

# Install with the cluster values file
helm install mockarty mockarty/mockarty \
  -n mockarty \
  -f values.cluster.yaml \
  --set admin.image.tag=latest \
  --set resolver.replicas=2 \
  --set runner.replicas=1

Cluster Components

All components register with the Admin Node via the gRPC coordinator (port 5773) using integration tokens. Health probes (GET /health) are preconfigured in the Helm templates.

CLI Cluster Management

The Mockarty CLI provides commands for managing Kubernetes clusters without kubectl:

# View cluster status (nodes, versions, health)
mockarty-cli cluster status

# Scale resolver nodes
mockarty-cli cluster scale resolver --replicas 4

# Rolling upgrade to a new image tag
mockarty-cli cluster upgrade --tag 1.3.0

# Restart a specific component
mockarty-cli cluster restart runner

# Stream logs from cluster components
mockarty-cli cluster logs resolver --follow

Chaos Operator

For resilience testing inside Kubernetes, install the Mockarty Chaos Operator:

mockarty-cli chaos operator install --namespace mockarty-chaos

The chaos operator integrates with the Chaos Engineering feature to inject faults (latency, errors, pod kills) directly into your Kubernetes workloads. Requires a PRO license.

For full details on CRD-based configuration, HPA auto-scaling, and multi-node topologies, see the Scaling Architecture guide.

See Also

• Quick Start Guide — Get up and running in 20 minutes
• Administration Guide — Post-install configuration, users, namespaces, and security
• Integrations Guide — Detailed setup for resolver nodes, runner agents, and webhooks
• Code Generator Guide — Generate standalone servers for all supported protocols and brokers
• Contract Testing — Validate mocks against OpenAPI specs and real APIs
• Chaos Engineering — Fault injection experiments for resilience testing (PRO)
• API Reference — Full REST API documentation for programmatic mock management