madock

Local development environment based on Docker

Supported platforms: Magento2, Shopify, BigCommerce, Shopware, PrestaShop, WooCommerce, Medusa.js, Saleor, Spree Commerce, Sylius, Custom projects (PHP, Node.js, Python, Go, Ruby).

madock is a Docker-based local development environment for web projects across many languages and stacks — PHP, Node.js, Python, Go and Ruby. It ships first-class support for popular e-commerce and CMS platforms (Magento 2, Shopify, BigCommerce, Shopware, PrestaShop, WooCommerce, Medusa.js, Saleor, Spree Commerce, Sylius) and handles any custom project just as well. This project is written in Golang and distributed under the MIT License.

• Automatic project setup
• Two or more projects can work simultaneously
• Magento as a separate service. Works by default. Learn more
• Shopify as a separate service. Learn more
• Custom project as a separate service (PHP, Node.js, Python, Go, Ruby)
• Shopware as a separate service. Learn more
• PrestaShop as a separate service. Learn more
• WooCommerce as a separate service (WordPress + WooCommerce + WP-CLI)
• Medusa.js as a separate service (Node.js backend + auto-provisioned Next.js storefront + PostgreSQL + Redis, optional Meilisearch). Learn more
• Saleor as a separate service (Python 3.12 + PostgreSQL + Redis + uvicorn, optional Celery worker and Saleor Dashboard). Learn more
• Spree Commerce as a separate service (Ruby on Rails admin + auto-provisioned Next.js storefront + PostgreSQL + Redis, optional Sidekiq worker). Learn more
• Sylius as a separate service (PHP 8.3 / Symfony + MariaDB + Redis + Webpack Encore frontend pipeline, optional RabbitMQ for Messenger). Learn more
• BigCommerce as a separate service with 4 SDK presets (Catalyst Next.js storefront, Stencil theme dev, PHP bigcommerce/api SDK, Node embedded app). Learn more
• Cron support
• Flexible configuration for each project
• Database import and export in two clicks
• Simple viewing of logs with one command
• Debug support
• Synchronization of the local database and media files with the dev site
• Multiple database engines: MariaDB, MySQL, PostgreSQL, MongoDB
• Admin UI: phpMyAdmin, pgAdmin, Mongo Express
• Additional services: redis, valkey, memcached, rabbitMQ, elasticsearch, Kibana, ioncube, xdebug, cron
• LiveReload. Learn more
• HMR / file watching on macOS (Next.js, Chokidar, nodemon, vite, …). Learn more
• Mailpit (email testing tool for developers)
• Magento Cloud
• Composer patches in two clicks
• Magento Functional Testing Framework (MFTF). Learn more
• Scopes. Learn more
• Configuration in a project. Learn more
• Snapshots. Learn more
• Isolation mode more
• Varnish Cache more
• Memcached more
• Custom commands more
• MCP Server for AI assistants (Claude Code, Cursor, VS Code) more

• Madock Integration for JetBrains — PhpStorm / IntelliJ plugin for managing madock projects directly from the IDE

• Linux (Ubuntu 20.04)
• macOS (Monterey, Sonoma)
• Windows (10, 11) — via WSL2

You need 5 things on your local machine: git, docker, docker-compose, golang and madock

The new version 2 is not backwards compatible with version 1. If you have problems with version 2, you can use version 1.x temporarily as it is more stable. Version 1 does not receive any more improvements. To use version 1 you should switch to master-1.x.x branch

Each release ships a single self-contained binary on the Releases page. Pick the one for your platform — no Go toolchain required.

Important: the binary keeps its working data (docker/, scripts/, projects/, aruntime/) next to itself — these are auto-extracted on first run. Put the binary in a dedicated, writable folder (e.g. ~/.madock/) and add it to your PATH via a symlink. Do not drop the real file straight into a system directory like /opt/homebrew/bin or /usr/local/bin — only the symlink goes there.

# 1. Put the binary in a dedicated, writable folder
mkdir -p ~/.madock
mv ~/Downloads/madock-darwin-arm64 ~/.madock/madock     # Apple Silicon
# mv ~/Downloads/madock-darwin-amd64 ~/.madock/madock   # Intel

# 2. Make it executable
chmod +x ~/.madock/madock

# 3. Remove the Gatekeeper quarantine flag (binaries are not Apple-notarized)
xattr -dr com.apple.quarantine ~/.madock/madock

# 4. Symlink into your $PATH (the real file stays in ~/.madock)
sudo ln -s ~/.madock/madock /opt/homebrew/bin/madock    # Apple Silicon
# sudo ln -s ~/.madock/madock /usr/local/bin/madock      # Intel

# 5. Check it works (first run auto-extracts docker/ and scripts/ into ~/.madock)
madock

mkdir -p ~/.madock
mv ~/Downloads/madock-linux-amd64 ~/.madock/madock      # or madock-linux-arm64
chmod +x ~/.madock/madock
sudo ln -s ~/.madock/madock /usr/local/bin/madock       # real file stays in ~/.madock
madock                                                   # first run auto-extracts assets

Working on madock itself? Turn on the repository's git hooks once: git config core.hooksPath .githooks. Before every push they build the code and run the test suite — about two seconds, no Docker needed. The end-to-end suite is separate and runs in a VM of its own; see docs/testing.md.

Follow the installation steps for your system.

git clone git@github.com:faradey/madock.git

cd madock

Run command below for Apple M1

GOARCH=arm64 go build -o madock

Run command below for Apple Intel

go build -o madock

Run command below for Apple M1

sudo ln -s absolute_path_to_your_madock_dir/madock /opt/homebrew/bin/

Run command below for Apple Intel

sudo ln -s absolute_path_to_your_madock_dir/madock /usr/local/bin/

which madock
madock

git clone git@github.com:faradey/madock.git

go build -o madock

ln -s absolute_path_to_your_madock_dir/madock /usr/local/bin/

which madock
madock

cd <your_project>
madock setup --download --install # for a new empty project with the clean Magento
madock setup # for an existing project

madock start
madock composer install
sudo vim /etc/hosts
// Add -> 127.0.0.1 <your-domain>

See detailed documentation about development workflow with madock IMPORTANT: Please, read all items before starting work.

• Development Workflow

• Deployment Guide (Setup existing projects on macOS, Linux, Windows)
• JSON Output
• VSCODE + Xdebug Setup
• PHPStorm + Xdebug Setup
• Docker images list
• Customizations
• Docker Compose override
• Database import, export, synchronization, phpmyadmin
• Media synchronization
• Cron
• ENV variables
• Memcached
• Kibana. URL http://{you_domain_name}/kibana
• Mailpit. Default URL http://localhost:8025
• Store scopes: website vs store
• MCP Server (AI integration for Claude Code, Cursor, VS Code)

If you find it useful and want to invite us for a beer, just click on the donation button. Thanks!

This project has been possible thanks to the following resources:

• docker-magento
• dockergento

• The MIT License

(c) faradey