How to Debug Magento 2 Production Bugs Locally Using SSH Tunnel

Tired of production-only Magento 2 bugs that disappear on your local setup? Merchants constantly updating products, prices, and configs in live admin make database dumps useless within hours.

This 2026-proof workflow connects your local Magento 2 instance directly to staging database via secure SSH tunnel. Debug with real-time merchant data – no more 50GB imports!

Perfect for Adobe Commerce Cloud, on-prem, or any Magento 2 setup. Let’s fix those sneaky prod bugs in 90 minutes flat.

Table of Contents

SSH Tunnel Workflow Overview

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

Benefits:

Live data (no stale dumps)
Full Xdebug (local IDE power)
90min debugging (vs 8hrs)
Production-accurate reproduction

Prerequisites Checklist

# 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

Get 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

Step-by-Step Setup

Step 1: Open Secure SSH Database Tunnel

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

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

✅ Success: staging-mysql:3306 → localhost:30000

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

Step 2: Configure app/etc/env.php

<?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' => '',
    ],
];

Step 3: Override Base URLs & Cookies

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,
        ],
    ],
];

Step 4: Clear Caches & Verify

# 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

Success indicators:

Admin loads with live staging catalog
Product counts match production
Recent orders visible

eady to kill production bugs in 90 minutes? Try this workflow on your next merchant ticket!

👉 Bookmark this guide | 👇 Share with your team

Want weekly Magento 2 performance tips?
Subscribe to Jigar Karangiya’s Newsletter

Related Guides:

Happy debugging! ✨

How to Disable the “It’s Time to Change Your Password” Prompt in Magento 2

Leave a Comment

Leave a Reply Cancel reply