Enable debugging for Nextcloud with Xdebug and update related configurations

.vscode/launch.json

@@ -0,0 +1,21 @@
+{
+  "version": "0.2.0",
+  "configurations": [
+    {
+      "name": "Listen for Xdebug (Nextcloud prod)",
+      "type": "php",
+      "request": "launch",
+      "port": 9003,
+      "log": true,
+      "pathMappings": {
+        "/var/www/html/apps/gdatavaas": "${workspaceFolder}",
+        "/var/www/html/apps-extra/gdatavaas": "${workspaceFolder}"
+      },
+      "xdebugSettings": {
+        "max_children": 128,
+        "max_data": 1024,
+        "max_depth": 5
+      }
+    }
+  ]
+}

.vscode/launch.json.license

@@ -0,0 +1,3 @@
+SPDX-FileCopyrightText: 2026 G DATA CyberDefense AG
+
+SPDX-License-Identifier: AGPL-3.0-or-later

README.md

@@ -192,6 +192,29 @@ make npm
 - make appstore
   - Builds a distributable tarball at build/artifacts/gdatavaas.tar.gz. Intended for releases; requires php-scoper available in PATH.
 
+### Debugging PHP with VS Code (make prod)
+
+`make prod` now starts Nextcloud with Xdebug enabled in the `nextcloud-container` service.
+For local runs, it also deploys workspace-identical app sources so breakpoints in your normal source tree bind directly.
+
+To debug app code:
+
+1. Start the stack:
+
+```bash
+make prod
+```
+
+2. In VS Code, start the launch configuration `Listen for Xdebug (Nextcloud prod)`.
+3. Trigger a request in Nextcloud (UI action, API call, or OCC command) that hits your breakpoint.
+
+Notes:
+- The Xdebug client host is configured as `host.docker.internal` (mapped to the Docker host gateway on Linux).
+- The debug listener port is `9003`.
+- For VS Code, install the PHP Debug extension (`xdebug.php-debug`) if it is not installed yet.
+- Local `make prod` keeps line numbers/content aligned with workspace files for source-level debugging.
+- Local `make prod` debugging is intentionally bound to the local build package (not the appstore/scoper package).
+
 ### Stopping and restarting
 
 - Stop/remove the dev container manually if needed:

docker-compose.yaml

@@ -4,11 +4,21 @@
 
 services:
   nextcloud-container:
-    image: nextcloud:${NEXTCLOUD_VERSION:?NEXTCLOUD_VERSION must be set}
+    pull_policy: never
+    build:
+      context: .
+      dockerfile: docker/Dockerfile
+      args:
+        NEXTCLOUD_VERSION: ${NEXTCLOUD_VERSION:?NEXTCLOUD_VERSION must be set}
     ports:
       - "8080:80"
     container_name: nextcloud-container
     hostname: nextcloud-container
+    extra_hosts:
+      - "host.docker.internal:host-gateway"
+    environment:
+      XDEBUG_MODE: debug,develop
+      XDEBUG_CONFIG: client_host=host.docker.internal client_port=9003 idekey=VSCODE
     depends_on:
       - smtp
     restart: unless-stopped

docker/Dockerfile

@@ -0,0 +1,16 @@
+# SPDX-FileCopyrightText: 2026 G DATA CyberDefense AG
+#
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+ARG NEXTCLOUD_VERSION
+FROM nextcloud:${NEXTCLOUD_VERSION}
+
+# Install and enable Xdebug for web and CLI PHP execution.
+RUN apt-get update \
+    && apt-get install -y --no-install-recommends $PHPIZE_DEPS \
+    && pecl install xdebug \
+    && docker-php-ext-enable xdebug \
+    && apt-get purge -y --auto-remove $PHPIZE_DEPS \
+    && rm -rf /var/lib/apt/lists/*
+
+COPY xdebug.ini /usr/local/etc/php/conf.d/99-xdebug.ini

docker/xdebug.ini

@@ -0,0 +1,10 @@
+; SPDX-FileCopyrightText: 2026 G DATA CyberDefense AG
+;
+; SPDX-License-Identifier: AGPL-3.0-or-later
+
+xdebug.mode=debug,develop
+xdebug.start_with_request=yes
+xdebug.client_host=host.docker.internal
+xdebug.client_port=9003
+xdebug.idekey=VSCODE
+xdebug.discover_client_host=0

scripts/run-app.sh

@@ -15,6 +15,13 @@ IS_CI_FROM_ENV="${IS_CI-}"
 
 export NEXTCLOUD_VERSION=${1:-${NEXTCLOUD_VERSION}}
 export IS_CI=${2:-${IS_CI_FROM_ENV:-0}}
+# Force local make prod runs to use workspace-identical code for debugging.
+# Only real CI environments (IS_CI env var set to 1) use the appstore/scoper package.
+if [ "${IS_CI_FROM_ENV:-0}" -eq 1 ]; then
+  export USE_APPSTORE_PACKAGE=${USE_APPSTORE_PACKAGE:-1}
+else
+  export USE_APPSTORE_PACKAGE=0
+fi
 
 if [ "$IS_CI" -eq 0 ]; then
   make oc
@@ -88,8 +95,26 @@ setup_s3 () {
 build_app () {
   echo "Building G DATA Antivirus App for Nextcloud..."
   make distclean
-  make appstore
-  tar -xf ./build/artifacts/gdatavaas.tar.gz -C ./build/artifacts
+  if [ "$USE_APPSTORE_PACKAGE" -eq 1 ]; then
+    make appstore
+    tar -xf ./build/artifacts/gdatavaas.tar.gz -C ./build/artifacts
+  else
+    make build
+    rm -rf ./build/artifacts/gdatavaas
+    mkdir -p ./build/artifacts/gdatavaas
+    # Keep file contents/line numbers identical to workspace for VS Code breakpoints.
+    tar \
+      --exclude='./.git' \
+      --exclude='./.github' \
+      --exclude='./.devcontainer' \
+      --exclude='./build' \
+      --exclude='./nextcloud-server' \
+      --exclude='./tests' \
+      --exclude='./scripts' \
+      --exclude='./node_modules' \
+      --exclude='./src' \
+      -cf - . | tar -xf - -C ./build/artifacts/gdatavaas
+  fi
   echo "Building G DATA Antivirus App for Nextcloud finished."
 }