Installation

MockForge can be installed through multiple methods depending on your needs and environment. Choose the installation method that best fits your workflow.

Prerequisites

Before installing MockForge, ensure you have one of the following:

Rust toolchain (for cargo installation or building from source)
Docker (for containerized deployment)
Pre-built binaries (when available)

Method 1: Cargo Install (Recommended)

The easiest way to install MockForge is through Cargo, Rust’s package manager:

cargo install mockforge-cli

This installs the MockForge CLI globally on your system. After installation, you can verify it’s working:

mockforge --version

Updating

To update to the latest version:

cargo install mockforge-cli --force

Method 2: Docker (Containerized)

MockForge is also available as a Docker image, which is ideal for:

Isolated environments
CI/CD pipelines
Systems without Rust installed

Build Docker image

Since pre-built images are not yet published to Docker Hub, build the image locally:

# Clone and build
git clone https://github.com/SaaSy-Solutions/mockforge.git
cd mockforge
docker build -t mockforge .

Run with basic configuration

docker run -p 3000:3000 -p 3001:3001 -p 50051:50051 -p 9080:9080 \
  -e MOCKFORGE_ADMIN_ENABLED=true \
  -e MOCKFORGE_RESPONSE_TEMPLATE_EXPAND=true \
  mockforge

Alternative: Docker Compose

For a complete setup with all services:

git clone https://github.com/SaaSy-Solutions/mockforge.git
cd mockforge
docker-compose up

Build from source (without Docker)

git clone https://github.com/SaaSy-Solutions/mockforge.git
cd mockforge
docker build -t mockforge .

Method 3: Building from Source

For development or custom builds, you can build MockForge from source:

git clone https://github.com/SaaSy-Solutions/mockforge.git
cd mockforge
cargo build --release

The binary will be available at target/release/mockforge.

To install it system-wide after building:

cargo install --path crates/mockforge-cli

Verification

After installation, verify MockForge is working:

# Check version
mockforge --version

# View help
mockforge --help

# Start with example configuration
mockforge serve --spec examples/openapi-demo.json --http-port 3000

Platform Support

MockForge supports:

Linux (x86_64, aarch64)
macOS (x86_64, aarch64)
Windows (x86_64)
Docker (any platform with Docker support)

Every release ships a prebuilt mockforge-<version>-x86_64-pc-windows-msvc.zip asset on the GitHub releases page. Download it, unzip mockforge.exe into a directory on %PATH%, and mockforge --version works with no Rust toolchain or Visual Studio Build Tools installed. When release signing secrets are configured the binary is signed via Azure Trusted Signing, so SmartScreen does not warn on first run; unsigned builds may show the standard “unknown publisher” prompt.

If you prefer building from source:

Install Rustup (the standard Rust installer for Windows). Pick the default x86_64-pc-windows-msvc toolchain when prompted; if you do not already have the Visual Studio Build Tools, Rustup will offer to download them.
Open PowerShell (or cmd) and install:
```
cargo install mockforge-cli --locked
```
The binary lands at %USERPROFILE%\.cargo\bin\mockforge.exe, which cargo already added to %PATH%. Verify:
```
mockforge --version
```

--locked pins the Cargo.lock shipped on crates.io, which avoids build breaks from later dependency drift.

If you would rather not compile locally, the Docker image runs on Windows under Docker Desktop / WSL2:

docker run --rm -p 3000:3000 -v ${PWD}:/work ghcr.io/saasy-solutions/mockforge:latest serve --spec /work/api.yaml --http-port 3000

We track first-class signed Windows binaries (no compile step, auto-update) at #884; contributions welcome.

Troubleshooting Installation

Cargo installation fails

If cargo install fails, ensure you have Rust installed:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source $HOME/.cargo/env

Docker permission issues

If Docker commands fail with permission errors:

# Add user to docker group (Linux)
sudo usermod -aG docker $USER
# Log out and back in for changes to take effect

Port conflicts

If default ports (3000, 3001, 9080, 50051) are in use:

# Check what's using the ports
lsof -i :3000
lsof -i :3001

# Kill conflicting processes or use different ports
mockforge serve --http-port 3001 --ws-port 3002 --admin-port 8081

Next Steps

Once installed, proceed to the Quick Start guide to create your first mock server, or read about Basic Concepts to understand how MockForge works.

MockForge Documentation