docs: xdebug docker setup for linux#2123
docs: xdebug docker setup for linux#2123Jakub Rudnik (Jakub-Rudnik) wants to merge 2 commits intoshopware:mainfrom
Conversation
Added instructions for additional necessary Xdebug Docker settings to work on Linux.
There was a problem hiding this comment.
Pull request overview
This PR adds documentation for configuring Xdebug on Linux systems when using Shopware's Docker setup. The issue arises because Linux does not automatically map the host.docker.internal hostname to the Docker host gateway, which is required for Xdebug to connect back to the IDE on the host machine.
Changes:
- Added a new section documenting the Linux-specific requirement to manually configure the
host.docker.internalhostname mapping incompose.override.yaml
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| To enable Xdebug connectivity on Linux, you must manually map the host.docker.internal hostname to the Docker host gateway. Add the following configuration to your `compose.override.yaml`: | ||
|
|
||
| ```yaml | ||
| services: | ||
| web: | ||
| extra_hosts: | ||
| - "host.docker.internal:host-gateway" | ||
| ``` |
There was a problem hiding this comment.
The documentation should clarify that this extra_hosts configuration needs to be combined with the Xdebug environment variables from the previous section. As written, it appears to be a standalone configuration, but users need both the environment variables (XDEBUG_MODE, XDEBUG_CONFIG, PHP_PROFILER) and the extra_hosts mapping. Consider adding a note like "Note: This should be added to the same compose.override.yaml file alongside the environment variables shown in the previous section" or show a complete combined example.
| services: | ||
| web: | ||
| extra_hosts: | ||
| - "host.docker.internal:host-gateway" |
There was a problem hiding this comment.
The list item indentation is inconsistent with the rest of the file. In the existing example (lines 32-34), list items under properties of the web service use 12 spaces of indentation (3 levels: 4 for service, 4 for property, 4 for list item with dash). Here, the list item uses only 10 spaces. Change line 53 to use 12 spaces of indentation to match the convention established in lines 32-34.
| - "host.docker.internal:host-gateway" | |
| - "host.docker.internal:host-gateway" |
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
2 participants
Description
I had problems with xdebug working with the official docker setup on my dev machine (Fedora 43). So I started searching and found out that Linux does not map the internal Docker hostname to the Docker host gateway. I added the correct mapping and that worked for me. It would be great to have this in official docs.
Changes
Added a note about using
extra_hosts: - "host.docker.internal:host-gateway"incompose.override.yaml.Testing
Verified on Fedora 43 with PHPStorm/vscode, official shopware docker image
ghcr.io/shopware/docker-dev:php8.4-node22-caddy(PHP 8.4.17 and Xdebug 3.5.0) and Docker 29.2.1.