Skip to content

Commit

Permalink
Merge pull request #3555 from uselagoon/xdebug-troubleshooting
Browse files Browse the repository at this point in the history
Xdebug troubleshooting for Linux
  • Loading branch information
tobybellwood authored Oct 3, 2023
2 parents c9d04e4 + 41d0135 commit 7817277
Showing 1 changed file with 37 additions and 17 deletions.
54 changes: 37 additions & 17 deletions docs/using-lagoon-advanced/setting-up-xdebug-with-lagoon.md
Original file line number Diff line number Diff line change
@@ -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
Expand Down Expand Up @@ -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
Expand All @@ -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:

Expand All @@ -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

Expand All @@ -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 |

0 comments on commit 7817277

Please sign in to comment.