Port forwarding on Mac or UNIX®
To set up port forwarding on a Mac or in a UNIX® environment:
-
Open a terminal.
-
Use SSH to establish the connection.
ssh -R 9000:localhost:9000 <ssh url>
Use the
-v
(verbose) option so that whenever a socket is connected to the port that is being forwarded it shows in the terminal.If an “unable to connect” or “could not listen to port on remote” error is displayed, there could be another active SSH session persisting on the server that is occupying port 9000. If that connection is not being used, you can terminate it.
To troubleshoot the connection:
-
Use SSH to log in to the remote integration, Staging, or Production environment.
-
View a list of SSH sessions:
who
-
View existing SSH sessions by user. Be careful to not affect a user other than yourself!
- integration: usernames are similar to
dd2q5ct7mhgus
- Staging: usernames are similar to
dd2q5ct7mhgus_stg
- Production: usernames are similar to
dd2q5ct7mhgus
- integration: usernames are similar to
-
For a user session that is older than yours, find the pseudo-terminal (PTS) value, such as
pts/0
. -
Kill the process ID (PID) corresponding to the PTS value.
ps aux | grep ssh kill <PID>
Sample response:
dd2q5ct7mhgus 5504 0.0 0.0 82612 3664 ? S 18:45 0:00 sshd: dd2q5ct7mhgus@pts/0
To terminate the connection, enter a kill command with the process ID (PID).
kill 3664
Port forwarding on Windows
To set up port forwarding (SSH tunneling) on Windows, you must configure your Windows terminal application. This example steps through creating an SSH tunnel using Putty. You can use other applications such as Cygwin. For more information on other applications, see the vendor documentation provided with those applications.
To set up an SSH tunnel on Windows using Putty:
-
If you have not already done so, download Putty.
-
Start Putty.
-
In the Category pane, click Session.
-
Enter the following information:
- Hostname (or IP address) field: Enter the SSH URL for your Cloud server
- Port field: Enter
22
-
In the Category pane, click Connection > SSH > Tunnels.
-
Enter the following information:
- Source port field: Enter
9000
- Destination field: Enter
127.0.0.1:9000
- Click Remote
- Source port field: Enter
-
Click Add.
-
In the Category pane, click Session.
-
In the Saved Sessions field, enter a name for this SSH tunnel.
-
Click Save.
-
To test the SSH tunnel, click Load, then click Open.
If an “unable to connect” error displays, verify the following:
- All Putty settings are correct
- You are running Putty on the machine on which your private Adobe Commerce on cloud infrastructure SSH keys are located
Debug CLI commands
This section walks through debugging CLI commands.
To debug CLI commands:
-
SSH into the server you want to debug using CLI commands.
-
Create the following environment variables:
export XDEBUG_CONFIG='PHPSTORM'
export PHP_IDE_CONFIG="serverName=<name of the server that is configured in PHPSTORM>"
These variables are removed when the SSH session ends.
-
Begin debugging
On Starter environments and Pro integration environments, run the CLI command to debug.
You may add runtime options, for example:php -d xdebug.profiler_enable=On -d xdebug.max_nesting_level=9999 bin/magento cache:clean
On Pro Staging and Production environments, you must specify the path to the Xdebug PHP configuration file when debugging CLI commands, for example:
php -c /etc/platform/USERNAME/php.xdebug.ini bin/magento cache:clean
Debug web requests
The following steps help you debug web requests.
-
On the Extension menu, click Debug to enable.
-
Right click, select the options menu, and set the IDE key to PHPSTORM.
-
Install the Xdebug client on the browser. Configure and enable it.
Example: Chrome setup
This section discusses how to use Xdebug in Chrome using the Xdebug Helper extension. For information about Xdebug tools for other browsers, consult the browser documentation.
To use Xdebug Helper with Chrome:
-
Create an SSH tunnel to the Cloud server.
-
Install the Xdebug Helper extension from the Chrome store.
-
Enable the extension in Chrome as shown in the following figure.
-
In Chrome, right-click the green helper icon in the Chrome toolbar.
-
From the pop-up menu, click Options.
-
From the IDE Key list, click PhpStorm.
-
Click Save.
-
Open your PhpStorm project.
-
In the top navigation bar, click the Start listening icon.
If the navigation bar is not displayed, click View > Navigation Bar.
-
In the PhpStorm navigation pane, double-click the PHP file to test.
Debug local code
Because of the read-only environments, you must pull code to the local workstation from an environment or specific Git branch to perform debugging.
The method you choose is up to you. You have the following options:
-
Check out code from Git and run
composer install
This method works unless
composer.json
references packages in private repositories to which you do not have access. This method results in getting the entire Adobe Commerce codebase. -
Copy the
vendor
,app
,pub
,lib
, andsetup
directoriesThis method results in your having all code you can possibly test. Depending on how many static assets you have, it could result in a long transfer with a large volume of files.
-
Copy the
vendor
directory onlyBecause most of the code is in the
vendor
directory, this method is likely to result in good testing, although are not testing the entire codebase.
To compress files and copy them to your local machine:
-
Use SSH to log in to the remote environment.
-
Compress the files.
tar -czf /tmp/<file-name>.tgz <directory list>
For example, to compress the
vendor
directory only:tar -czf /tmp/vendor.tgz vendor
-
On your local environment, use PhpStorm to compress the files.
cd <phpstorm project root dir>
rsync <SSH-URL>:/tmp/<file-name>.tgz .
tar xzf <file-name>.tgz