diff --git a/README.md b/README.md
index 485e5b2..9544a61 100644
--- a/README.md
+++ b/README.md
@@ -79,6 +79,22 @@ To run the phpunit tests:
 docker-compose exec web ./vendor/bin/phpunit
 ```
 
+#### 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/.
+
 ## Configuration
 
 Task Runner commands can be customized in two ways:
diff --git a/docker-compose.yml b/docker-compose.yml
index 13575c4..8c20332 100755
--- a/docker-compose.yml
+++ b/docker-compose.yml
@@ -9,11 +9,12 @@ services:
       - .:/var/www/html # Non Mac users.
       # - 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
 
 #### Mac users: uncomment the "volumes" key to enable the NFS file sharing. You can find more information about Docker for Mac here: https://github.com/openeuropa/openeuropa/blob/master/docs/starting/tooling.md#using-docker-on-macos