This guide covers deploying existing Magento 2 and Shopware projects using madock.
macOS
- Docker Desktop for Mac installed and running
- Git installed
- madock installed and available in PATH (see main README for installation)
Add host to /etc/hosts:
sudo nano /etc/hosts
# Add: 127.0.0.1 your-project.localLinux (Ubuntu/Debian)
- Docker and Docker Compose installed
- Git installed
- madock installed and available in PATH (see main README for installation)
- User added to docker group:
sudo usermod -aG docker $USER
Add host to /etc/hosts:
sudo nano /etc/hosts
# Add: 127.0.0.1 your-project.localWindows
- Docker Desktop for Windows installed and running, with the WSL2 backend
- WSL2 — required: madock on Windows runs inside it, as the Linux binary
- Git installed
- madock installed and available in PATH
Add host to hosts file:
- Open Notepad as Administrator
- Open file:
C:\Windows\System32\drivers\etc\hosts - Add:
127.0.0.1 your-project.local
# 1. Clone the repository
git clone <repository-url> project-name
cd project-name
# 2. Configure the project
madock setup
# Select PHP, MySQL, Elasticsearch versions matching your project
# Enter host (e.g.: magento.local)
# 3. The containers are already up — setup ends with a rebuild
madock status
# 4. Install dependencies
madock composer install
# 5. Import database
# Supported formats: .sql, .sql.gz, .sql.zip
madock db:import path/to/dump.sql.gz
# 6. Update Magento configuration (base URLs)
madock m setup:store-config:set --base-url="https://magento.local/"
madock m setup:store-config:set --base-url-secure="https://magento.local/"
# 7. Run migrations (if needed)
madock m setup:upgrade
# 8. Reindex and clear cache
madock m indexer:reindex
madock m cache:flush# 1. Clone the repository
git clone <repository-url> project-name
cd project-name
# 2. Configure the project
madock setup
# Select PHP, MySQL/MariaDB versions matching your project
# Enter host (e.g.: shopware.local)
# 3. The containers are already up — setup ends with a rebuild
madock status
# 4. Install dependencies
madock composer install
# 5. Import database
madock db:import path/to/dump.sql.gz
# 6. Update .env file
# Make sure APP_URL matches the host from setup
# Example: APP_URL=https://shopware.local
# 7. Clear cache and rebuild assets
madock bash
bin/console cache:clear
bin/console theme:compile
bin/console assets:install
exitmadock supports custom projects with different programming languages.
# 1. Clone the repository
git clone <repository-url> project-name
cd project-name
# 2. Configure the project
madock setup
# Select platform: custom
# Select language: php, nodejs, python, golang, ruby, or none
# Configure language version and other settings
# Enter host (e.g.: myproject.test)
# 3. The containers are already up — setup ends with a rebuild
madock status
# 4. Work inside the container
madock bash
# Your application code is available at the configured workdirSupported languages:
| Language | Main container | Nginx config |
|---|---|---|
| PHP | PHP-FPM (FastCGI) | fastcgi_pass php:9000 |
| Node.js | Node.js | proxy_pass http://nodejs:3000 |
| Python | Ubuntu + Python | proxy_pass http://python:3000 |
| Go | golang image | proxy_pass http://golang:3000 |
| Ruby | Ubuntu + Ruby | proxy_pass http://ruby:3000 |
| None | Ubuntu (bare) | proxy_pass http://app:3000 |
For non-PHP languages, nginx uses reverse proxy to port 3000 of the main container.
- Supported formats:
.sql,.sql.gz,.sql.zip - madock automatically extracts archives
- The dump should contain the database structure and data
- For large databases, import may take several minutes
Shopware may create directories and files with root ownership during runtime operations (e.g., files/theme-config/, var/cache/). This happens because some Shopware background processes (scheduled tasks, message queue consumers) may run as root.
Symptoms:
- "Permission denied" errors when accessing directories from host
- Theme compilation or cache operations fail
- Files in
files/orvar/directories owned by root
Quick fix:
madock rebuild --with-chownIf the problem reoccurs after Shopware operations (theme changes, cache rebuild, etc.), simply run the command again.
If you encounter permission errors (especially with var/, public/ folders):
madock rebuild --with-chownThe --with-chown flag ensures proper file ownership after container starts.
madock bash
id
# Should show your UID, e.g.: uid=1000(www-data) gid=1000(www-data)
exitWhen running commands inside the container, always use the default user:
# Correct - uses www-data
madock bash
bin/console cache:clear
# Incorrect - creates files as root, causes permission issues
madock bash --root
bin/console cache:clearIf permissions are still broken, fix them on the host system:
macOS / Linux
# Navigate to project folder
cd /path/to/project
# Fix ownership
sudo chown -R $(whoami):$(whoami) var public files
# Fix permissions
chmod -R 775 var public filesWindows (WSL2)
Run from WSL2 terminal:
Keep the project on the Linux side of WSL2. Across the /mnt/c boundary file
access is slow and file-change events do not arrive, so watchers and rebuilds
behave differently from everywhere else.
# Navigate to project folder
cd ~/projects/your-project
# Fix ownership
sudo chown -R $(whoami):$(whoami) var public files
# Fix permissions
chmod -R 775 var public filesmadock stop
docker system prune -f
madock rebuild --with-chown| Command | Description |
|---|---|
madock start |
Start containers |
madock start --with-chown |
Start with permission fix |
madock stop |
Stop containers |
madock rebuild |
Rebuild and restart containers |
madock rebuild --with-chown |
Rebuild with permission fix |
madock bash |
Open bash in PHP container |
madock bash --root |
Open bash as root (use with caution) |
madock logs |
View container logs |
madock db:import <file> |
Import database |
madock db:export |
Export database |
madock composer <args> |
Run composer commands |
madock m <args> |
Run Magento CLI (Magento only) |
madock allows you to enable/disable additional services for your project.
# Enable a service (automatically rebuilds containers)
madock service:enable <service-name>
# Disable a service
madock service:disable <service-name>
# Enable multiple services at once
madock service:enable nodejs redis
# Enable globally (for all projects)
madock service:enable xdebug --global| Service | Description |
|---|---|
nodejs |
Separate Node.js container for frontend builds |
nodejs/embedded/enabled |
Node.js inside the application container (for grunt, simple npm tasks) |
redis |
Redis cache server (container hostname: redisdb) |
rabbitmq |
RabbitMQ message broker |
xdebug |
PHP Xdebug extension |
ioncube |
IonCube loader |
elasticsearch |
Elasticsearch search engine |
opensearch |
OpenSearch search engine |
phpmyadmin |
phpMyAdmin database GUI |
ssl |
SSL/HTTPS support |
cron |
Cron scheduler |
Magento-specific:
| Service | Description |
|---|---|
cloud |
Magento Cloud CLI |
n98magerun |
n98-magerun tool |
mftf |
Magento Functional Testing Framework |
Shopify:
| Service | Description |
|---|---|
yarn |
Yarn package manager (instead of npm) |
Enable Node.js for frontend builds (Shopware/Magento):
madock service:enable nodejsEnable Xdebug for debugging:
madock service:enable xdebugEnable Redis for caching:
madock service:enable redisEnable phpMyAdmin for database management:
madock service:enable phpmyadminThere are two ways to use Node.js in madock:
1. nodejs — Separate container
Best for: complex frontend builds, long-running watchers, PWA projects.
madock service:enable nodejs
# Run npm commands in nodejs container
madock node npm install
madock node npm run build
madock node npm run watch
# Enter the nodejs container
madock node bash2. nodejs/embedded/enabled — Node.js inside the application container
Best for: simple tasks like Magento 2 grunt compilation, quick npm scripts. No separate container needed — runs directly in PHP container.
madock service:enable nodejs/embedded
# Run npm/grunt inside PHP container
madock bash
npm install
grunt exec:all
grunt watchWhen to use which:
- Use
nodejswhen you need a dedicated Node.js environment or run long watchers - Use
nodejs/embedded/enabledfor Magento 2 grunt tasks or when you want to keep things simple
After enabling redis, configure your application to use it:
Magento:
Edit app/etc/env.php:
'session' => [
'save' => 'redis',
'redis' => [
'host' => 'redisdb',
'port' => '6379',
'database' => '0'
]
],
'cache' => [
'frontend' => [
'default' => [
'backend' => 'Magento\\Framework\\Cache\\Backend\\Redis',
'backend_options' => [
'server' => 'redisdb',
'port' => '6379',
'database' => '1'
]
]
]
]Shopware:
Add to .env:
REDIS_URL=redis://redisdb:6379
PWA Studio can be set up using the custom platform with Node.js language:
# 1. Configure the project
madock setup
# Select platform: custom
# Select language: nodejs
# Configure host and Node.js version
# 2. Start containers
madock rebuildCreate override files in .madock/docker/ for PWA-specific configuration:
.madock/docker/docker-compose.yml - Add backend URL extra_host and SSH key volumes:
services:
nodejs:
extra_hosts:
- "magento.test:host-gateway"
volumes:
- ~/.ssh:/var/www/.ssh:cached.madock/docker/Dockerfile (optional) - If Yarn Berry setup is needed:
RUN yarn set version berry.madock/docker/nginx/conf/default.conf (optional) - Override nginx proxy_pass if needed:
location / {
proxy_pass http://nodejs:10000;
}Set the PWA backend URL if needed by your application:
madock config:set --name=pwa/backend_url --value=magento.testThe database host in your dump may differ from madock's setup. Update the configuration:
Magento:
madock m setup:store-config:set --base-url="https://your-host.local/"Shopware:
Edit .env file and ensure DATABASE_URL uses db as host:
DATABASE_URL=mysql://magento:magento@db:3306/magento
Check if ports are already in use:
madock logs
# View allocated ports for the project
madock info:portsMake sure the search engine version in madock setup matches your project requirements.