Merge pull request #3555 from uselagoon/xdebug-troubleshooting

Xdebug troubleshooting for Linux
uselagoon · Oct 3, 2023 · 7817277 · 7817277
2 parents c9d04e4 + 41d0135
commit 7817277
Showing 1 changed file with 37 additions and 17 deletions.
diff --git a/docs/using-lagoon-advanced/setting-up-xdebug-with-lagoon.md b/docs/using-lagoon-advanced/setting-up-xdebug-with-lagoon.md
@@ -1,27 +1,26 @@
 # Setting up Xdebug with Lagoon
 
-## Enable Xdebug Extension
+## Enable Xdebug extension in the containers
 
 The Lagoon base images are pre-configured with Xdebug but, for performance
 reasons, the extension is not loaded by default. To enable the extension, the
 `XDEBUG_ENABLE` environment variable must be set to `true`:
 
-- **Locally** \(pygmy and Lando\)
+- **Locally** (Pygmy and Lando)
   1.  If your project is based off the lagoon-examples `docker-compose.yml`
-      file, the environment variable already exists. Uncomment these lines:
-      [https://github.com/lagoon-examples/drupal9-base/blob/main/docker-compose.yml#L16-L17](https://github.com/lagoon-examples/drupal9-base/blob/main/docker-compose.yml#L16-L17).
-  2.  Make sure to rebuild and restart the containers after changing this
-      setting.
-- **Remotely** \(dev/prod\)
+      file, the environment variable already exists. [Uncomment these lines](https://github.com/lagoon-examples/drupal10-base/blob/main/docker-compose.yml#L14-L15).
+  2.  Make sure to rebuild and restart the containers after changing any
+      environment variables.
+- **Remotely** (dev/prod)
   1.  You can
       [use the Lagoon API to add the environment variable to a running environment](environment-variables.md#runtime-environment-variables-lagoon-api).
-  2.  Make sure to redeploy the environment after changing this setting.
+  2.  Make sure to redeploy the environment after changing this any
+      environment variables.
 
 ## Activate Xdebug Extension
 
 The default Xdebug configuration requires a "trigger" to activate the extension
-and start a session. You can
-[view the complete documentation](https://xdebug.org/docs/step_debug#activate_debugger)
+and start a session. You can [view the complete documentation](https://xdebug.org/docs/step_debug#activate_debugger)
 for activating the debugger but the most straightforward instructions are below.
 
 ### CLI
@@ -77,11 +76,15 @@ debugging.
 - Verify the following settings:
 
 | Directive          | Local Value                               |
-| :----------------- | :---------------------------------------- |
+|:-------------------|:------------------------------------------|
 | xdebug.mode        | debug                                     |
 | xdebug.client_host | `host.docker.internal` or your IP address |
 | xdebug.client_port | 9003                                      |
 
+- Enable Xdebug logging within the running containers. All you need is an
+  environment variable named `XDEBUG_LOG` set to anything to enable logging.
+  Logs will be saved to `/tmp/xdebug.log`. If you are using the lagoon-examples
+  then you can uncomment [some existing lines](https://github.com/lagoon-examples/drupal10-base/blob/main/docker-compose.yml#L16-L18).
 - Verify you have the activation cookie set. You can use the browser tools in
   Chrome or Firefox to check that a `XDEBUG_SESSION` cookie is set.
 - Verify that Xdebug is activated and attempting to start a debug session with
@@ -93,6 +96,12 @@ debugging.
   For remote debugging this value should be your IP address. If this value was
   not correctly determined, you can override it by setting the `DOCKERHOST`
   environment variable.
+- When using Lando locally, in order to debug scripts run from the CLI you must
+  first SSH into the CLI container via `lando ssh`. You won’t be able to debug
+  things by running `lando drush` or `lando php`.
+
+### Mac specific troubleshooting
+
 - Verify that Docker for Mac networking is not broken. On your host machine, run
   `nc -l 9003`, then in a new terminal window, run:
 
@@ -103,11 +112,22 @@ debugging.
   You should see a message like:
   `host.docker.internal (192.168.65.2:9003) open`.
 
-- When using Lando locally, in order to debug scripts run from the CLI you must
-  first SSH into the CLI container via `lando ssh`. You won’t be able to debug
-  things by running `lando drush` or `lando php`.
-- You can enable the Xdebug log by setting the `XDEBUG_LOG` environment
-  variable. Logs will be saved to `/tmp/xdebug.log`.
+## Linux specific troubleshooting
+
+- Ensure the host `host.docker.internal` can be reached. If `docker` has been
+  installed manually (and not through Docker Desktop), this host will not
+  resolve. You can force this to resolve with an additional snippet in your
+  `docker-compose.yml` file (instructions taken from [this blog post](https://medium.com/the-sensiolabs-tech-blog/how-to-use-xdebug-in-docker-phpstorm-76d998ef2534)):
+
+  ```yaml title="docker-compose.yml alterations for Linux"
+    services:
+      cli:
+        extra_hosts:
+          host.docker.internal: host-gateway
+      php:
+        extra_hosts:
+          host.docker.internal: host-gateway
+  ```
 
 ## Xdebug 2
 
@@ -116,7 +136,7 @@ information on this page still applies, but some of the configuration names and
 values have changes:
 
 | v3                 | v2                    |                                           |
-| :----------------- | :-------------------- | :---------------------------------------- |
+|:-------------------|:----------------------|:------------------------------------------|
 | xdebug.mode        | xdebug.remote_enabled | On                                        |
 | xdebug.client_host | xdebug.remote_host    | `host.docker.internal` or your IP address |
 | xdebug.client_port | xdebug.remote_port    | 9000                                      |