feat: devcontainer.json, explicit sshd_config, Xdebug 3 docs

josecarlospeer-cloud · jorge07 · commit 232676a08308 · 2026-02-22T11:49:58.000+01:00
.devcontainer/devcontainer.json (new) Modern VS Code Dev Containers config. Uses jorge07/alpine-php:8.3-dev, forwards ports 22 and 9003, pre-installs php-debug + Intelephense, sets php.validate.executablePath and intelephense.phpVersion. devfs/etc/ssh/sshd_config (new, all 4 versions) Replaces the brittle 'sed -i s/#PermitRootLogin...' hack with an explicit, self-documenting sshd_config. Settings: - PermitRootLogin yes, PasswordAuthentication yes (IDE SSH compat) - PubkeyAuthentication yes (allows key-based auth as alternative) - TCPKeepAlive + ClientAlive (stable IDE sessions) - AllowTcpForwarding + GatewayPorts (remote debug port forwarding) Dockerfile sed line removed from all four PHP versions. doc/IDE.md (rewritten) Updated from PHP 7.x/Xdebug 2 era to current: - VS Code Dev Containers workflow with launch.json config - PHPStorm SSH remote interpreter setup (modern UI paths) - Xdebug 3 trigger mode: XDEBUG_SESSION env var, port 9003 - Side-by-side Xdebug 2 vs 3 config table - CLI debugging examples with docker exec Build-tested locally: 8.3 dev image, sshd_config confirmed present. Closes #104
diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json
@@ -0,0 +1,40 @@
+{
+    "name": "alpine-php dev",
+
+    // Use the latest stable dev image. Change to 8.1-dev, 8.2-dev, or 8.4-dev as needed.
+    "image": "jorge07/alpine-php:8.3-dev",
+
+    // Mount the workspace at /app (matches the container's WORKDIR)
+    "workspaceFolder": "/app",
+    "workspaceMount": "source=${localWorkspaceFolder},target=/app,type=bind,consistency=cached",
+
+    // Forward Xdebug port and SSH port
+    "forwardPorts": [9003, 22],
+    "portsAttributes": {
+        "9003": { "label": "Xdebug", "onAutoForward": "silent" },
+        "22":   { "label": "SSH (IDE integration)", "onAutoForward": "silent" }
+    },
+
+    // VS Code extensions for PHP development
+    "customizations": {
+        "vscode": {
+            "extensions": [
+                "xdebug.php-debug",
+                "bmewburn.vscode-intelephense-client",
+                "junstyle.php-cs-fixer",
+                "neilbrayfield.php-docblocker"
+            ],
+            "settings": {
+                "php.validate.executablePath": "/usr/bin/php",
+                "intelephense.environment.phpVersion": "8.3",
+                "php.debug.ideKey": "VSCODE"
+            }
+        }
+    },
+
+    // Remote user — root matches the dev image's default
+    "remoteUser": "root",
+
+    // Override CMD to keep the container running with supervisor
+    "overrideCommand": false
+}
diff --git a/8.1/Dockerfile b/8.1/Dockerfile
@@ -83,7 +83,6 @@ RUN apk add -U --no-cache --repository https://dl-cdn.alpinelinux.org/alpine/v3.
         make \
         zip \
     && rm -rf /var/cache/apk/* \
-    && sed -i s/#PermitRootLogin.*/PermitRootLogin\ yes/ /etc/ssh/sshd_config \
     && echo "${USER}:${PASSWORD}" | chpasswd \
     && ssh-keygen -A \
     && curl -sS https://getcomposer.org/installer | php -- --install-dir=/usr/bin --filename=composer --version=${COMPOSER_VERSION}
diff --git a/8.1/devfs/etc/ssh/sshd_config b/8.1/devfs/etc/ssh/sshd_config
@@ -0,0 +1,27 @@
+# OpenSSH configuration for alpine-php dev image
+# Intended for local development only — do not use in production.
+
+Port 22
+AddressFamily inet
+Protocol 2
+
+# Authentication
+PermitRootLogin yes
+PasswordAuthentication yes
+PubkeyAuthentication yes
+AuthorizedKeysFile .ssh/authorized_keys
+PermitEmptyPasswords no
+IgnoreRhosts yes
+HostbasedAuthentication no
+
+# Keep connections alive (important for IDE SSH sessions)
+TCPKeepAlive yes
+ClientAliveInterval 60
+ClientAliveCountMax 3
+
+# Forwarding (required for IDE remote debugging port forwarding)
+AllowTcpForwarding yes
+GatewayPorts yes
+
+# SFTP
+Subsystem sftp /usr/lib/ssh/sftp-server
diff --git a/8.2/Dockerfile b/8.2/Dockerfile
@@ -88,7 +88,6 @@ RUN apk add -U --no-cache --repository https://dl-cdn.alpinelinux.org/alpine/v3.
     # Delete APK cache.
     && rm -rf /var/cache/apk/* \
     # Create ssh user for dev.
-    && sed -i s/#PermitRootLogin.*/PermitRootLogin\ yes/ /etc/ssh/sshd_config \
     && echo "${USER}:${PASSWORD}" | chpasswd \
     && ssh-keygen -A \
     # Download composer.
diff --git a/8.2/devfs/etc/ssh/sshd_config b/8.2/devfs/etc/ssh/sshd_config
@@ -0,0 +1,27 @@
+# OpenSSH configuration for alpine-php dev image
+# Intended for local development only — do not use in production.
+
+Port 22
+AddressFamily inet
+Protocol 2
+
+# Authentication
+PermitRootLogin yes
+PasswordAuthentication yes
+PubkeyAuthentication yes
+AuthorizedKeysFile .ssh/authorized_keys
+PermitEmptyPasswords no
+IgnoreRhosts yes
+HostbasedAuthentication no
+
+# Keep connections alive (important for IDE SSH sessions)
+TCPKeepAlive yes
+ClientAliveInterval 60
+ClientAliveCountMax 3
+
+# Forwarding (required for IDE remote debugging port forwarding)
+AllowTcpForwarding yes
+GatewayPorts yes
+
+# SFTP
+Subsystem sftp /usr/lib/ssh/sftp-server
diff --git a/8.3/Dockerfile b/8.3/Dockerfile
@@ -83,7 +83,6 @@ RUN apk add -U --no-cache --repository https://dl-cdn.alpinelinux.org/alpine/v3.
         make \
         zip \
     && rm -rf /var/cache/apk/* \
-    && sed -i s/#PermitRootLogin.*/PermitRootLogin\ yes/ /etc/ssh/sshd_config \
     && echo "${USER}:${PASSWORD}" | chpasswd \
     && ssh-keygen -A \
     && curl -sS https://getcomposer.org/installer | php -- --install-dir=/usr/bin --filename=composer --version=${COMPOSER_VERSION}
diff --git a/8.3/devfs/etc/ssh/sshd_config b/8.3/devfs/etc/ssh/sshd_config
@@ -0,0 +1,27 @@
+# OpenSSH configuration for alpine-php dev image
+# Intended for local development only — do not use in production.
+
+Port 22
+AddressFamily inet
+Protocol 2
+
+# Authentication
+PermitRootLogin yes
+PasswordAuthentication yes
+PubkeyAuthentication yes
+AuthorizedKeysFile .ssh/authorized_keys
+PermitEmptyPasswords no
+IgnoreRhosts yes
+HostbasedAuthentication no
+
+# Keep connections alive (important for IDE SSH sessions)
+TCPKeepAlive yes
+ClientAliveInterval 60
+ClientAliveCountMax 3
+
+# Forwarding (required for IDE remote debugging port forwarding)
+AllowTcpForwarding yes
+GatewayPorts yes
+
+# SFTP
+Subsystem sftp /usr/lib/ssh/sftp-server
diff --git a/8.4/Dockerfile b/8.4/Dockerfile
@@ -85,7 +85,6 @@ RUN apk add -U --no-cache --repository https://dl-cdn.alpinelinux.org/alpine/edg
         make \
         zip \
     && rm -rf /var/cache/apk/* \
-    && sed -i s/#PermitRootLogin.*/PermitRootLogin\ yes/ /etc/ssh/sshd_config \
     && echo "${USER}:${PASSWORD}" | chpasswd \
     && ssh-keygen -A \
     && curl -sS https://getcomposer.org/installer | php -- --install-dir=/usr/bin --filename=composer --version=${COMPOSER_VERSION}
diff --git a/8.4/devfs/etc/ssh/sshd_config b/8.4/devfs/etc/ssh/sshd_config
@@ -0,0 +1,27 @@
+# OpenSSH configuration for alpine-php dev image
+# Intended for local development only — do not use in production.
+
+Port 22
+AddressFamily inet
+Protocol 2
+
+# Authentication
+PermitRootLogin yes
+PasswordAuthentication yes
+PubkeyAuthentication yes
+AuthorizedKeysFile .ssh/authorized_keys
+PermitEmptyPasswords no
+IgnoreRhosts yes
+HostbasedAuthentication no
+
+# Keep connections alive (important for IDE SSH sessions)
+TCPKeepAlive yes
+ClientAliveInterval 60
+ClientAliveCountMax 3
+
+# Forwarding (required for IDE remote debugging port forwarding)
+AllowTcpForwarding yes
+GatewayPorts yes
+
+# SFTP
+Subsystem sftp /usr/lib/ssh/sftp-server
diff --git a/doc/IDE.md b/doc/IDE.md
@@ -1,64 +1,130 @@
-# IDE integration
+# IDE Integration
 
-### Up container
+## Start the dev container
 
-Run this in your project root path: 
-    
-    docker run -itd --name php7 -v $PWD:/app -p 2244:22 jorge07/alpine-php:7.4-dev
+Run this in your project root:
 
-- `-v $PWD:/app` will create a volume to share the host folder with the container
-- `-p 2244:22` will export the 22 container port to the 2244 host machine. This will allow us to connect the IDE via SSH.
+```sh
+docker run -itd --name php-dev \
+  -v $PWD:/app \
+  -p 2244:22 \
+  -p 9003:9003 \
+  jorge07/alpine-php:8.3-dev
+```
 
-### PHPSTORM
+- `-v $PWD:/app` — mounts your project at `/app` inside the container
+- `-p 2244:22` — SSH port for remote interpreter
+- `-p 9003:9003` — Xdebug 3 port (default, replaces 9000 from Xdebug 2)
 
-- Languages & Frameworks > PHP > Add > Remote...
-    - SSH Credentials
-        - HOST
-            - Docker-machine: 192.168.99.100 ([Recommended](https://github.com/adlogix/docker-machine-nfs))
-            - Linux or Docker4{MAc|Windows}: localhost
-        - port: 2244 (or the one you choose on the docker run command)
-        - user: root
-        - pass: root 
-        - Executable: /usr/bin/php
-    - Path mappings:
-        - <Project root> -> /app
-      
-**Remote Interpreter**
-![Remote](https://raw.githubusercontent.com/jorge07/alpine-php/master/doc/images/remote-interpreter.png)
+**Default credentials:** `root` / `root`
 
-**Mapping**
-![Remote](https://raw.githubusercontent.com/jorge07/alpine-php/master/doc/images/mapping.png)
+---
 
-Now your breakpoints should work.
+## VS Code (Dev Containers)
 
-You can also use the oficial PHPStrom documentation for [remote connexion via SSH Credentials](https://confluence.jetbrains.com/display/PhpStorm/Working+with+Remote+PHP+Interpreters+in+PhpStorm) they will explain it better than me.
+The repo ships a `.devcontainer/devcontainer.json`. Open the project in VS Code and click **Reopen in Container** — it will use `jorge07/alpine-php:8.3-dev` and pre-install the PHP Debug and Intelephense extensions.
 
-### Steps in detail
+### Xdebug launch config
 
-**Credentials**
+Add to `.vscode/launch.json`:
 
-Use the ARG variables to change the *USER* and *PASSWORD* for ssh and *COMPOSER_VERSION* to select an specific version on the build. 
+```json
+{
+    "version": "0.2.0",
+    "configurations": [
+        {
+            "name": "Listen for Xdebug",
+            "type": "php",
+            "request": "launch",
+            "port": 9003,
+            "pathMappings": {
+                "/app": "${workspaceFolder}"
+            }
+        },
+        {
+            "name": "Debug CLI script",
+            "type": "php",
+            "request": "launch",
+            "port": 9003,
+            "pathMappings": {
+                "/app": "${workspaceFolder}"
+            },
+            "runtimeExecutable": "php",
+            "program": "${file}"
+        }
+    ]
+}
+```
 
-**Default Credentials Values:**
+Set the `XDEBUG_SESSION` env var or use the browser extension to trigger a debug session. For CLI scripts:
 
-- user: root 
-- pass: root
+```sh
+docker exec php-dev sh -c "XDEBUG_SESSION=1 php /app/bin/console something"
+```
 
-**Binary path**
+---
 
-- /usr/bin/php
+## PHPStorm
 
-**Xdebug.so path**
+### Remote interpreter via SSH
 
-- /usr/lib/php{7}/modules/xdebug.so
+**Languages & Frameworks → PHP → Add → SSH Credentials**
 
-**Server mappings**
+| Field | Value |
+|---|---|
+| Host | `localhost` (or your Docker host IP) |
+| Port | `2244` |
+| User | `root` |
+| Password | `root` |
+| PHP executable | `/usr/bin/php` |
 
-Add your **Path mapping** from your workspace folder to the `/app` folder inside the container.
+**Path mappings:** `<project root>` → `/app`
 
-**Xdebug**
+### Xdebug 3 configuration
 
-If you want to [debug php script commands remotely](https://confluence.jetbrains.com/display/PhpStorm/Debugging+PHP+CLI+scripts+with+PhpStorm) (I.E: php bin/console something) with Your IDE (PHPStorm in this case):
- 
- - Set the PHP_IDE_CONFIG environment variable with **serverName=SomeName**
- - where **SomeName** is the name of the server configured in *Settings / Preferences | Languages & Frameworks | PHP | Servers* in the PHPStorm IDE.
+**Languages & Frameworks → PHP → Debug**
+
+| Setting | Value |
+|---|---|
+| Debug port | `9003` |
+| Can accept external connections | ✅ |
+
+**Run → Edit Configurations → PHP Remote Debug**
+
+| Setting | Value |
+|---|---|
+| Server | (the SSH server you configured above) |
+| IDE key | `PHPSTORM` |
+
+For CLI debugging, set the env var before running:
+
+```sh
+docker exec php-dev sh -c "PHP_IDE_CONFIG='serverName=MyServer' XDEBUG_SESSION=PHPSTORM php /app/script.php"
+```
+
+### Key differences from Xdebug 2
+
+| | Xdebug 2 | Xdebug 3 |
+|---|---|---|
+| Default port | `9000` | `9003` |
+| Trigger env var | `XDEBUG_REMOTE_ENABLE=1` | `XDEBUG_SESSION=1` |
+| ini key (enable) | `xdebug.remote_enable=1` | `xdebug.mode=debug` |
+| ini key (host) | `xdebug.remote_host` | `xdebug.client_host` |
+| ini key (port) | `xdebug.remote_port` | `xdebug.client_port` |
+
+The images ship with `xdebug.mode=debug` and `xdebug.start_with_request=trigger` — Xdebug only activates when a session is triggered, not on every request.
+
+---
+
+## SSH credentials (custom)
+
+Pass build args to change the default user/password:
+
+```sh
+docker build \
+  --build-arg USER=myuser \
+  --build-arg PASSWORD=mypassword \
+  -t myapp:dev \
+  --target dev \
+  -f 8.3/Dockerfile 8.3/
+```
