Deployment Guide for Existing Projects

This guide covers deploying existing Magento 2 and Shopware projects using madock.

Prerequisites

sudo nano /etc/hosts
# Add: 127.0.0.1 your-project.local

sudo nano /etc/hosts
# Add: 127.0.0.1 your-project.local

Magento 2

# 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. Start containers (with rebuild)
madock rebuild

# 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

Shopware

# 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. Start containers (with rebuild)
madock rebuild

# 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
exit

Custom Platform

madock 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. Start containers (with rebuild)
madock rebuild

# 4. Work inside the container
madock bash
# Your application code is available at the configured workdir

Supported languages:

For non-PHP languages, nginx uses reverse proxy to port 3000 of the main container.

Database Import Notes

• 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

Troubleshooting Permissions (Shopware)

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/ or var/ directories owned by root

Quick fix:

madock rebuild --with-chown

If 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):

Step 1: Rebuild containers with chown

madock rebuild --with-chown

The --with-chown flag ensures proper file ownership after container starts.

Step 2: Verify user ID inside container

madock bash
id
# Should show your UID, e.g.: uid=1000(www-data) gid=1000(www-data)
exit

Step 3: Always use www-data user

When 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:clear

Step 4: Fix permissions on host

If permissions are still broken, fix them on the host system:

# 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 files

# Navigate to project folder
cd /mnt/c/path/to/project

# Fix ownership
sudo chown -R $(whoami):$(whoami) var public files

# Fix permissions
chmod -R 775 var public files

Step 5: Full reset (if nothing helps)

madock stop
docker system prune -f
madock rebuild --with-chown

Useful Commands

Managing Services

madock allows you to enable/disable additional services for your project.

Enable/Disable Services

# 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

Available Services

Magento-specific:

Shopify:

Examples

Enable Node.js for frontend builds (Shopware/Magento):

madock service:enable nodejs

Enable Xdebug for debugging:

madock service:enable xdebug

Enable Redis for caching:

madock service:enable redis

Enable phpMyAdmin for database management:

madock service:enable phpmyadmin

Node.js: Container vs PHP-embedded

There 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 bash

2. php/nodejs — Node.js inside PHP 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 php/nodejs

# Run npm/grunt inside PHP container
madock bash
npm install
grunt exec:all
grunt watch

When to use which:

• Use nodejs when you need a dedicated Node.js environment or run long watchers
• Use php/nodejs for Magento 2 grunt tasks or when you want to keep things simple

Using Redis

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 (via Custom Platform)

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 rebuild

Custom Docker overrides

Create 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;
}

Configuration

Set the PWA backend URL if needed by your application:

madock config:set --name=pwa/backend_url --value=magento.test

Common Issues

"Connection refused" after import

The 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

Container won't start

Check if ports are already in use:

madock logs

# View allocated ports for the project
madock info:ports

Elasticsearch/OpenSearch errors

Make sure the search engine version in madock setup matches your project requirements.