Mockoon Deployment and Usage Guide

Prerequisites

Node.js: Version 18.x LTS or higher (20.x recommended)
NPM: Version 9.x or higher (included with Node.js)
Git: For cloning the repository
OS-specific build tools:
- Windows: Visual Studio Build Tools or Visual Studio Community (with "Desktop development with C++" workload)
- macOS: Xcode Command Line Tools (xcode-select --install)
- Linux: build-essential package (Ubuntu/Debian) or equivalent
Python: 2.7 or 3.x (required for native module compilation with node-gyp)

Installation

1. Clone the Repository

git clone https://github.com/mockoon/mockoon.git
cd mockoon

2. Install Dependencies

The project uses NPM workspaces. Install all dependencies from the root:

npm install

This installs dependencies for all packages (packages/app, packages/cli, packages/commons, packages/serverless).

3. Build Workspace Dependencies

Build the shared libraries before running applications:

# Build commons library (required by all other packages)
npm run build --workspace=@mockoon/commons

# Build commons-server (if present, required by CLI and Serverless)
npm run build --workspace=@mockoon/commons-server

Configuration

Environment Variables

For local development, create environment files in the respective packages:

Desktop App (packages/app/src/renderer/config.ts):

export const Config = {
  apiURL: 'https://api.mockoon.com',  // Cloud API endpoint
  syncURL: 'wss://sync.mockoon.com',  // WebSocket sync server
  // ... other config
};

CLI (Runtime environment variables):

MOCKOON_DATA_PATH: Path to mock data files
MOCKOON_PORT: Default port for mock server

SSL Certificates (Optional)

For HTTPS support in development:

# Generate self-signed certificates for local testing
openssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem -days 365 -nodes

Place in packages/app/certificates/ (gitignored by default).

Build & Run

Desktop Application (Development)

# Start the Angular dev server and Electron
npm run start --workspace=@mockoon/app

# Or from the package directory
cd packages/app
npm run start

This command:

Compiles the Angular renderer process with hot reload
Starts the Electron main process
Opens the desktop application window

CLI (Development)

# Build the CLI package
npm run build --workspace=@mockoon/cli

# Run locally
node packages/cli/dist/index.js start --data ./path/to/mock.json

# Or link globally for testing
cd packages/cli
npm link
mockoon-cli start --data ./mock.json

Serverless Package (Development)

# Build the serverless package
npm run build --workspace=@mockoon/serverless

# Local testing with AWS Lambda emulator (requires serverless framework)
cd packages/serverless
npm run test:lambda

Production Builds

Desktop App:

cd packages/app
npm run build:prod
npm run electron:build

Outputs platform-specific installers in packages/app/dist/.

CLI:

cd packages/cli
npm run build
npm pack

All Packages:

# Build entire monorepo
npm run build --workspaces

Deployment

Deploying the CLI

Publish to NPM registry (requires authentication):

cd packages/cli
npm version patch  # or minor/major
npm run build
npm publish --access public

Usage in CI/CD pipelines:

# Example GitHub Actions
- name: Install Mockoon CLI
  run: npm install -g @mockoon/cli

- name: Start mock server
  run: mockoon-cli start --data ./api-mocks.json --port 3000 &

Deploying Serverless Functions

AWS Lambda:

cd packages/serverless
npm run build
serverless deploy

Google Cloud Functions:

# Build and deploy as HTTP function
gcloud functions deploy mockoon-api \
  --runtime nodejs18 \
  --trigger-http \
  --entry-point handler \
  --source ./dist

Desktop Application Distribution

Build and publish to GitHub Releases:

cd packages/app
npm run electron:build -- --publish=always

This uses electron-builder configured for:

macOS: .dmg, .zip, Mac App Store
Windows: .exe, .msi, Windows Store
Linux: .AppImage, .deb, .rpm, Snap

Docker Deployment (CLI)

Create a Dockerfile:

FROM node:18-alpine
RUN npm install -g @mockoon/cli
COPY ./mock-data.json /data/
EXPOSE 3000
CMD ["mockoon-cli", "start", "--data", "/data/mock-data.json", "--hostname", "0.0.0.0"]

Build and run:

docker build -t mockoon-api .
docker run -p 3000:3000 mockoon-api

Troubleshooting

Build Errors

Error: Cannot find module '@mockoon/commons'

Ensure workspace dependencies are built first:
```
npm run build --workspace=@mockoon/commons
```

Error: node-gyp rebuild failures

Verify Python installation: python --version
On Windows: Ensure Visual Studio Build Tools are installed with C++ workload
Clear NPM cache: npm cache clean --force

Angular compilation errors in desktop app

Check Node version compatibility (Angular 15+ requires Node 18+)

Delete node_modules and lock files:

rm -rf node_modules package-lock.json
npm install

Runtime Issues

Desktop app shows blank screen

Check Electron main process console for Angular build errors
Verify dist folder exists in packages/app/dist
Try resetting the app data: Delete ~/.config/mockoon/ (Linux), ~/Library/Application Support/mockoon/ (macOS), or %APPDATA%/mockoon/ (Windows)

CLI port already in use

Use --port flag to specify alternative port: mockoon-cli start --port 3001
Or kill existing process: npx kill-port 3000

Sync service connection failures

Verify Config.syncURL is accessible from your network
Check firewall settings for WebSocket connections on port 443

Development Workflow

Hot reload not working in desktop app

Restart the Angular dev server: Ctrl+C, then npm run start again
Check for TypeScript compilation errors in terminal

Changes in commons not reflecting in other packages

Rebuild the commons package: npm run build --workspace=@mockoon/commons
Or use watch mode: npm run watch --workspace=@mockoon/commons

How to Deploy & Use mockoon/mockoon