diff --git a/README.md b/README.md
index a8b0632..b44460d 100644
--- a/README.md
+++ b/README.md
@@ -222,6 +222,22 @@ To run the behat tests:
 docker-compose exec web ./vendor/bin/behat
 ```
 
+#### Step debugging
+
+To enable step debugging from the command line, pass the `XDEBUG_SESSION` environment variable with any value to
+the container:
+
+```bash
+docker-compose exec -e XDEBUG_SESSION=1 web <your command>
+```
+
+Please note that, starting from XDebug 3, a connection error message will be outputted in the console if the variable is
+set but your client is not listening for debugging connections. The error message will cause false negatives for PHPUnit
+tests.
+
+To initiate step debugging from the browser, set the correct cookie using a browser extension or a bookmarklet
+like the ones generated at https://www.jetbrains.com/phpstorm/marklets/.
+
 #### Authenticating using the EULogin Mock Service
 
 EULogin Mock Service container replicates the [EU Login](https://ecas.ec.europa.eu/cas/about.html) service.
diff --git a/docker-compose.yml b/docker-compose.yml
index 8a9ffc4..85df243 100644
--- a/docker-compose.yml
+++ b/docker-compose.yml
@@ -10,11 +10,12 @@ services:
       # - ~/.cache/composer:/root/.composer/cache # use a local cache.
       # - nfsmount:/var/www/html # Mac Users with the nfsmount volume.
     environment:
-      XDEBUG_CONFIG: "remote_enable=1 remote_host=10.254.254.254 remote_port=9000 idekey=PHPSTORM remote_autostart=1"
+      XDEBUG_CONFIG: "client_host=172.17.0.1" # Non-Mac users.
+      # XDEBUG_CONFIG: "client_host=host.docker.internal" # Mac users.
+      XDEBUG_MODE: "develop, debug"
       PHP_IDE_CONFIG: "serverName=Docker"
-      # For Xdebug setup, run this command in the terminal:
-      # For Mac users: sudo ifconfig en0 alias 10.254.254.254 255.255.255.0
-      # For Linux users: sudo ip addr add 10.254.254.254/32 dev lo label lo:1
+      # Enable step debugging for all PHP request. See ./README.md#step-debugging for more information.
+      # XDEBUG_SESSION: 1
   mysql:
     image: percona/percona-server:5.7
     command: --innodb-log-file-size=1G --max_allowed_packet=1G --innodb-buffer-pool-size=512M --wait_timeout=3000 --net_write_timeout=3000 --log_error_verbosity=3