Installation & Deployment Guide

Contents

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

Overview

Mockarty is distributed as pre-built binaries for Linux (amd64/arm64), macOS (amd64/arm64), and Windows (amd64). You can deploy Mockarty in two ways:

1. Run binaries directly — download from the Downloads page and run as native processes
2. Run with Docker — create a minimal Docker image with the pre-built binary

Source code is not required. All binaries are self-contained and include embedded web UI assets, database migrations, and default configurations.

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.

Running Binaries Directly

1. Download

Download the appropriate binary for your platform from the Downloads page.

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

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
Environment=AUTH_ENABLED=true
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target

sudo systemctl enable mockarty
sudo systemctl start mockarty

Running with Docker

Since Mockarty is distributed as pre-built binaries (not source code), you create a minimal Docker image by copying the binary into a base image.

Creating a Docker image from the binary

Admin Node

FROM alpine:3.20
RUN apk add --no-cache ca-certificates tzdata
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 wget -qO- 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 \
  -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:latest

Mock Resolver

FROM alpine:3.20
RUN apk add --no-cache ca-certificates tzdata
COPY mock-resolver /usr/local/bin/mock-resolver
RUN chmod +x /usr/local/bin/mock-resolver
EXPOSE 5780 6780
HEALTHCHECK --interval=30s --timeout=5s --retries=3 \
  CMD wget -qO- http://localhost:5780/health/live || exit 1
ENTRYPOINT ["mock-resolver"]

Runner Agent

FROM alpine:3.20
RUN apk add --no-cache ca-certificates tzdata
COPY runner-agent /usr/local/bin/runner-agent
RUN chmod +x /usr/local/bin/runner-agent
EXPOSE 6770
HEALTHCHECK --interval=30s --timeout=5s --retries=3 \
  CMD wget -qO- http://localhost:6770/health || exit 1
ENTRYPOINT ["runner-agent"]

Server Generator

FROM alpine:3.20
RUN apk add --no-cache ca-certificates tzdata
COPY mockarty-server-generator /usr/local/bin/mockarty-server-generator
RUN chmod +x /usr/local/bin/mockarty-server-generator
EXPOSE 8888
ENTRYPOINT ["mockarty-server-generator"]

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

Running with SQLite in 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:latest

Docker Compose Examples

Minimal: Admin + PostgreSQL

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

  mockarty:
    image: mockarty:latest
    ports:
      - "5770:5770"   # HTTP — Web UI, REST API, mock traffic
      - "5771:5771"   # HTTPS
      - "5772:5772"   # MCP
    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

volumes:
  pg-data:

Minimal: Admin + SQLite (no database server)

services:
  mockarty:
    image: 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

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:latest
    ports:
      - "5770:5770"
      - "5771:5771"
      - "5772:5772"
    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
      AUTH_ENABLED: "true"
      ENABLE_MCP: "true"
      RUNNER_GRPC_BIND_ADDR: "0.0.0.0"
    depends_on:
      postgres:
        condition: service_healthy
      redis:
        condition: service_healthy

  resolver:
    image: mock-resolver:latest
    ports:
      - "5780:5780"
      - "6780:6780"
    environment:
      COORDINATOR_ADDR: mockarty:5773
      API_TOKEN: "mki_your_resolver_token"
      RESOLVER_NAME: "resolver-1"
      HTTP_PORT: "5780"
    depends_on:
      - mockarty

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

volumes:
  pg-data:

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: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.

Environment Variables Reference

Core

HTTP Server

MCP Server

LLM / AI Assistant

Database

Cache

Authentication

| AUTH_BASE_URL | Base URL for auth callbacks | http://localhost:5770 |
| FIRST_ADMIN_LOGIN | Bootstrap admin username | admin |
| FIRST_ADMIN_PASSWORD | Bootstrap admin password | admin |
| FIRST_ADMIN_EMAIL | Bootstrap admin email | (empty) |
| COOKIE_SECURE | Set Secure flag on cookies | true |

OAuth Providers

LDAP / Active Directory

Email Notifications

Runner Coordinator

License

Paths

Security

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:latest

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

Limitations:

• No distributed resolver/runner coordination (coordinator always requires PostgreSQL)
• Some dashboard statistics queries 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=admin-node:5773
export API_TOKEN="mki_your_resolver_token"
export RESOLVER_NAME="resolver-1"
export HTTP_PORT=5780

./mock-resolver

Running with Docker

resolver:
  image: mock-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"
    HTTP_PORT: "5780"
  depends_on:
    - mockarty

Creating integration tokens

Create resolver tokens via admin UI (Settings > Integrations) or API:

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

The response includes the token (shown once). Token format: mki_*.

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=admin-node:5773
export API_TOKEN="mki_your_runner_token"
export RUNNER_NAME="runner-1"
export SHARED=true
export CAPABILITIES="api_test,performance"

./runner-agent

Running with Docker

runner:
  image: runner-agent:latest
  environment:
    COORDINATOR_ADDR: mockarty:5773
    API_TOKEN: "mki_your_runner_token"
    RUNNER_NAME: "runner-1"
    SHARED: "true"
    MAX_CONCURRENT: "5"
    CAPABILITIES: "api_test,performance"
  depends_on:
    - mockarty

Environment variables

Creating integration tokens

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

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-server-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: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: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

Scheduled backups (every 48 hours by default) include the database, documentation, and uploaded files.

# Download backup
curl http://localhost:5770/api/admin/backup/download > backup.tar.gz

# Restore from backup
curl -X POST http://localhost:5770/api/admin/backup/restore \
  -F "backup=@backup.tar.gz"

For Docker deployments, mount a persistent volume for data and backups.

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. Enable authentication — set AUTH_ENABLED=true in production
4. Use a reverse proxy (nginx/Traefik) in front for TLS termination and routing
5. Use Redis with CACHE_TYPE=redis for better performance at scale
6. Enable backups — mount a persistent volume for backup storage
7. Use resolver nodes for high-traffic mock resolution (separates mock traffic from admin UI)
8. Use runner agents for distributed test execution
9. Set COOKIE_SECURE=true — enabled by default, ensures cookies are only sent over HTTPS
10. Keep ALLOW_PROXY_TO_PRIVATE_IPS=false — default, prevents SSRF through proxy feature
11. Set HTTP_BIND_ADDR=0.0.0.0 in Docker/production to accept external connections (defaults to localhost)

See Also

• Quick Start Guide — Get up and running in 10 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 9 protocols
• API Reference — Full REST API documentation for programmatic mock management