Optimize Docker test setup with BuildKit caching and Strauss detection

Add two performance optimizations for local Docker testing:

1. Strauss fork Docker detection
   - Add isRunningInDocker() to PluginPackager to detect container environment
   - Use /tmp for Strauss fork in Docker (no cross-drive issues on Linux)
   - Skip fork cleanup in Docker since /tmp is ephemeral
   - Maintains Windows compatibility (still uses target directory locally)
   - Saves ~30 seconds per Docker test run

2. BuildKit cache mounts
   - Enable DOCKER_BUILDKIT=1 in run-docker-tests.sh
   - Add cache mounts for /var/cache/apt (downloaded packages)
   - Add cache mount for /root/.composer/cache (PHPUnit dependencies)
   - Intentionally exclude /var/lib/apt/lists to ensure fresh package indexes
   - Cache auto-creates on first run, persists across builds
   - Saves ~45-60 seconds on subsequent runs

Expected total savings: ~1-1.5 minutes per Docker test run after initial cache population.

No impact on GitHub Actions (uses separate GHA layer caching).

Author: paulgoodchild

bin/run-docker-tests.sh

@@ -27,6 +27,11 @@ fi
 # Prevents /app from being converted to C:/Program Files/Git/app
 export MSYS_NO_PATHCONV=1
 
+# Enable Docker BuildKit for cache mount support
+# BuildKit provides automatic caching of apt packages and composer dependencies
+# Cache is created automatically if missing, reused on subsequent builds
+export DOCKER_BUILDKIT=1
+
 echo "🚀 Starting Local Docker Tests (matching CI configuration)"
 echo "=================================================="
 

infrastructure/src/Tooling/PluginPackager.php

@@ -596,17 +596,41 @@ private function provideStraussBinary( string $targetDir ) :string {
 		return Path::join( $libDir, 'strauss.phar' );
 	}
 
+	/**
+	 * Detect if running inside a Docker container.
+	 * Used to optimize file operations (e.g., use /tmp for ephemeral data).
+	 */
+	private function isRunningInDocker() :bool {
+		// Check for Docker environment file (standard Docker indicator)
+		if ( file_exists( '/.dockerenv' ) ) {
+			return true;
+		}
+		// Check for SHIELD_TEST_MODE environment variable (set in our Dockerfile)
+		if ( getenv( 'SHIELD_TEST_MODE' ) === 'docker' ) {
+			return true;
+		}
+		return false;
+	}
+
 	/**
 	 * Clone Strauss fork and prepare it for use.
 	 * Returns path to bin/strauss executable.
 	 * @throws RuntimeException if clone or setup fails
 	 */
 	private function cloneAndPrepareStraussFork( string $targetDir ) :string {
-		// Clone to a temp directory WITHIN the target directory to ensure same drive on Windows.
-		// This avoids cross-drive path resolution issues where Strauss (on C:) can't properly
-		// calculate relative paths for a project on D:.
 		$forkHash = substr( md5( $this->straussForkRepo ), 0, 12 );
-		$forkDir = Path::join( $targetDir, '_strauss-fork-'.$forkHash );
+
+		// In Docker/Linux: use /tmp (no cross-drive issues, ephemeral so no cleanup needed)
+		// On Windows: use target directory to avoid cross-drive path resolution issues
+		if ( $this->isRunningInDocker() ) {
+			$forkDir = '/tmp/_strauss-fork-'.$forkHash;
+		}
+		else {
+			// Clone to a temp directory WITHIN the target directory to ensure same drive on Windows.
+			// This avoids cross-drive path resolution issues where Strauss (on C:) can't properly
+			// calculate relative paths for a project on D:.
+			$forkDir = Path::join( $targetDir, '_strauss-fork-'.$forkHash );
+		}
 		$binPath = Path::join( $forkDir, 'bin', 'strauss' );
 
 		// Skip clone if already exists and has bin/strauss
@@ -619,7 +643,9 @@ private function cloneAndPrepareStraussFork( string $targetDir ) :string {
 		$this->log( sprintf( 'Cloning Strauss fork: %s', $this->straussForkRepo ) );
 
 		if ( is_dir( $forkDir ) ) {
-			$this->removeDirectorySafelyForTemp( $forkDir, $targetDir );
+			// Pass appropriate base path for safety check
+			$allowedBase = $this->isRunningInDocker() ? '/tmp' : $targetDir;
+			$this->removeDirectorySafelyForTemp( $forkDir, $allowedBase );
 		}
 
 		// Clone to parent directory since git clone creates the target
@@ -886,11 +912,12 @@ private function cleanupPackageFiles( string $targetDir ) :void {
 		$fs = new Filesystem();
 		$libDir = Path::join( $targetDir, 'src', 'lib' );
 
-		// Remove Strauss fork directory if it exists
+		// Remove Strauss fork directory if it exists (only when not in Docker)
+		// In Docker, we use /tmp which is ephemeral - no cleanup needed
 		// NOTE: We use removeDirectoryRecursive() instead of Symfony's $fs->remove() because
 		// Symfony renames directories to .!xxx temp names before deletion, and if deletion fails,
 		// these temp directories are left behind causing issues on subsequent runs.
-		if ( $this->straussForkRepo !== null ) {
+		if ( $this->straussForkRepo !== null && !$this->isRunningInDocker() ) {
 			$forkHash = substr( md5( $this->straussForkRepo ), 0, 12 );
 			$forkDir = Path::join( $targetDir, '_strauss-fork-'.$forkHash );
 			if ( is_dir( $forkDir ) ) {
@@ -904,6 +931,9 @@ private function cleanupPackageFiles( string $targetDir ) :void {
 				}
 			}
 		}
+		elseif ( $this->straussForkRepo !== null && $this->isRunningInDocker() ) {
+			$this->log( 'Skipping Strauss fork cleanup (Docker /tmp is ephemeral)' );
+		}
 
 		// Directories to remove (duplicates after Strauss prefixing)
 		$this->log( 'Removing duplicate libraries from main vendor...' );

tests/docker/Dockerfile

@@ -1,6 +1,12 @@
+# syntax=docker/dockerfile:1
 # Shield Security - Multi-Stage Test Runner
 # Optimized for matrix testing with multi-PHP support and caching
 # Part of Docker Matrix Testing Optimization (Phase 3, Task 3.1)
+#
+# BuildKit Cache Optimization:
+# This Dockerfile uses BuildKit cache mounts to speed up repeated builds.
+# Cache is automatic - created if missing, reused if present.
+# Requires: DOCKER_BUILDKIT=1 (set in run-docker-tests.sh)
 
 # Build arguments for matrix customization
 # Note: PHP_VERSION default should match DEFAULT_PHP in .github/config/matrix.conf
@@ -17,16 +23,19 @@ FROM ubuntu:22.04 AS base-deps
 ENV DEBIAN_FRONTEND=noninteractive
 ENV TZ=UTC
 
-# Install system dependencies
-RUN apt-get update && apt-get install -y \
+# Install system dependencies with apt cache mount for faster rebuilds
+# Only cache /var/cache/apt (downloaded .deb files), NOT /var/lib/apt/lists (package indexes)
+# This ensures apt-get update always fetches fresh package indexes to avoid staleness
+RUN --mount=type=cache,target=/var/cache/apt,sharing=locked \
+    rm -rf /var/lib/apt/lists/* && \
+    apt-get update && apt-get install -y \
     curl \
     git \
     unzip \
     subversion \
     default-mysql-client \
     software-properties-common \
-    gpg-agent \
-    && rm -rf /var/lib/apt/lists/*
+    gpg-agent
 
 # Install Composer globally (cached layer)
 COPY --from=composer:2 /usr/bin/composer /usr/bin/composer
@@ -45,11 +54,13 @@ ARG PHP_VERSION
 ENV DEBIAN_FRONTEND=noninteractive
 ENV TZ=UTC
 
-# Add PHP repository
-RUN add-apt-repository ppa:ondrej/php && apt-get update
+# Add PHP repository with cache mount (only cache downloaded packages, not indexes)
+RUN --mount=type=cache,target=/var/cache/apt,sharing=locked \
+    add-apt-repository ppa:ondrej/php && apt-get update
 
-# Install PHP and required extensions
-RUN apt-get install -y \
+# Install PHP and required extensions with cache mount
+RUN --mount=type=cache,target=/var/cache/apt,sharing=locked \
+    apt-get install -y \
     php${PHP_VERSION} \
     php${PHP_VERSION}-cli \
     php${PHP_VERSION}-mysql \
@@ -62,8 +73,7 @@ RUN apt-get install -y \
     php${PHP_VERSION}-bcmath \
     php${PHP_VERSION}-soap \
     php${PHP_VERSION}-sqlite3 \
-    php${PHP_VERSION}-dev \
-    && rm -rf /var/lib/apt/lists/*
+    php${PHP_VERSION}-dev
 
 # Create symlinks for php commands
 RUN update-alternatives --install /usr/bin/php php /usr/bin/php${PHP_VERSION} 100
@@ -80,17 +90,18 @@ RUN echo "memory_limit=512M" > /etc/php/${PHP_VERSION}/cli/conf.d/99-testing.ini
 FROM php-runtime AS test-framework
 ARG PHP_VERSION
 
-# Install PHPUnit based on PHP version compatibility
+# Install PHPUnit based on PHP version compatibility with composer cache mount
 # PHPUnit 9.6: PHP >=7.3 (works with 7.4, 8.0, 8.1)
 # PHPUnit 11.x: PHP >=8.2 (works with 8.2, 8.3, 8.4)
 # Note: PHPUnit 10.x is NOT supported by yoast/phpunit-polyfills 4.x
 # yoast/phpunit-polyfills 4.x: Supports PHPUnit ^7.5|^8.0|^9.0|^11.0|^12.0
-RUN if [ "$(echo ${PHP_VERSION} | cut -d. -f1)" = "7" ] || [ "${PHP_VERSION}" = "8.0" ] || [ "${PHP_VERSION}" = "8.1" ]; then \
-        composer global require --no-interaction --no-cache \
+RUN --mount=type=cache,target=/root/.composer/cache \
+    if [ "$(echo ${PHP_VERSION} | cut -d. -f1)" = "7" ] || [ "${PHP_VERSION}" = "8.0" ] || [ "${PHP_VERSION}" = "8.1" ]; then \
+        composer global require --no-interaction \
             phpunit/phpunit:^9.6 \
             yoast/phpunit-polyfills:^4.0; \
     else \
-        composer global require --no-interaction --no-cache \
+        composer global require --no-interaction \
             phpunit/phpunit:^11.5 \
             yoast/phpunit-polyfills:^4.0; \
     fi