How to Debug Magento 2 Production Bugs Locally Using SSH Tunnel

Local Magento 2 → SSH Tunnel → Staging MySQL → Xdebug breakpoints
       ↓                    ↓              ↓
   Docker/Native        localhost:30000   Real merchant data

Local Magento 2 → SSH Tunnel → Staging MySQL → Xdebug breakpoints
       ↓                    ↓              ↓
   Docker/Native        localhost:30000   Real merchant data

# 5-minute setup
□ Local Magento 2 codebase (git cloned)
□ magento-cloud CLI: npm i -g @magento/cloud-cli
□ Staging environment SSH access
□ Docker OR PHP 8.2+ with Xdebug 3.x
□ Staging DB credentials

# 5-minute setup
□ Local Magento 2 codebase (git cloned)
□ magento-cloud CLI: npm i -g @magento/cloud-cli
□ Staging environment SSH access
□ Docker OR PHP 8.2+ with Xdebug 3.x
□ Staging DB credentials

#SSH into the remote environment
#Note DB login information
echo $MAGENTO_CLOUD_RELATIONSHIPS | base64 -d | json_pp

#SSH into the remote environment
#Note DB login information
echo $MAGENTO_CLOUD_RELATIONSHIPS | base64 -d | json_pp

cd /path/to/your/magento2-project
magento-cloud tunnel:open

cd /path/to/your/magento2-project
magento-cloud tunnel:open

Keep tunnel terminal open during debugging
Status: magento-cloud tunnel:list
Close: magento-cloud tunnel:close

Keep tunnel terminal open during debugging
Status: magento-cloud tunnel:list
Close: magento-cloud tunnel:close

<?php
return [
    'db' => [
        'connection' => [
            'default' => [
                'host' => 'host.docker.internal',  // Docker
                // 'host' => '127.0.0.1',          // Native PHP
                'port' => '30000',
                'dbname' => 'main',           // Your staging DB name
                'username' => 'staging_user',
                'password' => 'your_staging_password',
                'model' => 'mysql4',
                'engine' => 'innodb',
                'initStatements' => 'SET NAMES utf8;',
                'active' => '1',
            ],
        ],
        'table_prefix' => '',
    ],
];

<?php
return [
    'db' => [
        'connection' => [
            'default' => [
                'host' => 'host.docker.internal',  // Docker
                // 'host' => '127.0.0.1',          // Native PHP
                'port' => '30000',
                'dbname' => 'main',           // Your staging DB name
                'username' => 'staging_user',
                'password' => 'your_staging_password',
                'model' => 'mysql4',
                'engine' => 'innodb',
                'initStatements' => 'SET NAMES utf8;',
                'active' => '1',
            ],
        ],
        'table_prefix' => '',
    ],
];

return [
    // ... db config above ...
    
    'front' => 'admin',
    'web' => [
        'unsecure' => [
            'base_url' => 'http://local.magento/',
        ],
        'secure' => [
            'base_url' => 'http://local.magento/',
        ],
        'cookie' => [
            'cookie_path' => '/',
            'cookie_domain' => '',
            'cookie_httponly' => 1,
            'cookie_secure' => 0,
        ],
    ],
];

return [
    // ... db config above ...
    
    'front' => 'admin',
    'web' => [
        'unsecure' => [
            'base_url' => 'http://local.magento/',
        ],
        'secure' => [
            'base_url' => 'http://local.magento/',
        ],
        'cookie' => [
            'cookie_path' => '/',
            'cookie_domain' => '',
            'cookie_httponly' => 1,
            'cookie_secure' => 0,
        ],
    ],
];

# Nuclear option (safe with tunnel)
rm -rf var/cache/* var/page_cache/* generated/* var/view_preprocessed/* pub/static/*

# Magento commands
bin/magento setup:upgrade --keep-generated
bin/magento cache:flush
bin/magento cache:status

# Nuclear option (safe with tunnel)
rm -rf var/cache/* var/page_cache/* generated/* var/view_preprocessed/* pub/static/*

# Magento commands
bin/magento setup:upgrade --keep-generated
bin/magento cache:flush
bin/magento cache:status