Mockzilla 🦖

A powerful self-hosted API mocking platform for development and testing. Deploy your own private mock server with an intuitive interface and advanced response generation capabilities.

🚀 Quick Start

Option 1: Fast In-Memory with PGLite (Recommended for Development)

Perfect for quick testing and development. By default, all data is stored in memory and will be lost when the container stops. Use volume persistence to maintain data between restarts (if needed).

# Pull the latest image
docker pull andrecrjr/mockzilla:latest

# run with volume persistence to maintain data between container restarts
docker run -p 36666:36666 \
  -v mockzilla-data:/data \
  andrecrjr/mockzilla:latest

[!TIP] This option is ideal for development, testing, and quick experimentation. It starts instantly with no external dependencies. Use volume persistence to keep your mocks between container restarts.

Your mock server will be available at http://localhost:36666

Option 2: Persistent with External PostgreSQL (Recommended for Production)

For production use or when you need data persistence between container restarts.

# Pull the latest image
docker pull andrecrjr/mockzilla:latest

# Run with external PostgreSQL database
docker run -p 36666:36666 \
  -e DATABASE_URL=postgresql://username:password@host:5432/database_name \
  andrecrjr/mockzilla:latest

[!NOTE] This option is recommended for production environments where data persistence is required. Make sure your PostgreSQL database is accessible from the container.

Your mock server will be available at http://localhost:36666

🤖 AI Agent Skills

Mockzilla includes specialized AI agent skills to help you build and manage mocks. You can add easier with add-skill:

npx add-skill https://github.com/andrecrjr/mockzilla

or copy the .agent/skills folder to your project's root.

📦 Available Scripts

Development

• bun run dev - Start development server on port 36666
• bun run build - Build for production
• bun run start - Start production server
• bun run lint - Run ESLint

Database

• bun run db:generate - Generate database migrations
• bun run db:migrate - Run database migrations
• bun run db:push - Push schema changes to database
• bun run db:studio - Open Drizzle Studio (database UI)

Docker Commands

• docker pull andrecrjr/mockzilla:latest - Pull latest image
• docker run -p 36666:36666 andrecrjr/mockzilla:latest - Run with PGLite (in-memory)
• docker run -p 36666:36666 -e DATABASE_URL=... andrecrjr/mockzilla:latest - Run with PostgreSQL

Running in Background

docker run -d \
  --name mockzilla \
  -p 36666:36666 \
  andrecrjr/mockzilla:latest

Running with Volume Persistence

docker run -d \
  --name mockzilla \
  -p 36666:36666 \
  -v mockzilla-data:/data \
  andrecrjr/mockzilla:latest

Development and Contributing

For development purposes, the project includes Makefile commands:

• make dev-up - Start development environment with hot-reload
• make dev-down - Stop development environment
• make dev-logs - View logs
• make db-studio - Open Drizzle Studio in Docker
• make help - See all available development commands

[!NOTE] Makefile commands are primarily for development and contributing to the project, not for production self-hosting.

🛠️ Self-Hosting Stack

Mockzilla is designed for easy self-hosting with the following technologies:

• Framework: Next.js 16 with App Router (for mock server UI)
• Runtime: Bun (fast JavaScript runtime)
• Language: TypeScript
• Database: PostgreSQL with Drizzle ORM (for mock configuration storage)
• Styling: Tailwind CSS 4
• UI Components: Radix UI
• Forms: React Hook Form + Zod
• Containerization: Docker (for simplified self-hosting)

🐳 Self-Hosting with Docker

Mockzilla provides optimized Docker images for reliable self-hosting:

• Docker Hub Image: andrecrjr/mockzilla:latest - Production-ready image
• In-Memory Option: Uses PGLite for fast, ephemeral storage
• Persistent Option: Connects to external PostgreSQL for data persistence

Pulling the Image

Always start by pulling the latest image:

docker pull andrecrjr/mockzilla:latest

Running with Data Persistence

For production use, connect to an external PostgreSQL database:

docker run -d \
  --name mockzilla \
  -p 36666:36666 \
  -e DATABASE_URL=postgresql://username:password@host:5432/database_name \
  andrecrjr/mockzilla:latest

Running with Volume Persistence

To persist data without an external database, mount a volume to /data/:

docker run -d \
  --name mockzilla \
  -p 36666:36666 \
  -v mockzilla-data:/data \
  andrecrjr/mockzilla:latest

Or mount a local directory:

docker run -d \
  --name mockzilla \
  -p 36666:36666 \
  -v /path/to/local/data:/data 

...