From 4a334b8812e86c7871226417e44975b20eec55ca Mon Sep 17 00:00:00 2001
From: robbond <rob@rdbsolutions.co.uk>
Date: Fri, 6 Mar 2026 13:41:14 +0000
Subject: [PATCH] fix(ci): require docker-capable Jenkins agent with preflight
 checks

---
 Jenkinsfile                   | 23 ++++++++++++++++++++++-
 docs/deployment-production.md |  8 ++++++++
 2 files changed, 30 insertions(+), 1 deletion(-)

diff --git a/Jenkinsfile b/Jenkinsfile
index 80e5a21..7049070 100644
--- a/Jenkinsfile
+++ b/Jenkinsfile
@@ -1,5 +1,7 @@
 pipeline {
-  agent any
+  // Build + deploy stages require Docker CLI/daemon access on the Jenkins node.
+  // Ensure this label maps to an agent with Docker installed and usable.
+  agent { label 'docker' }
 
   environment {
     REGISTRY_IMAGE = "plesk-agency-portal"
@@ -8,6 +10,25 @@ pipeline {
   }
 
   stages {
+    stage('Preflight') {
+      steps {
+        sh '''
+          set -euo pipefail
+
+          if ! command -v docker >/dev/null 2>&1; then
+            echo "Docker CLI is not available on this Jenkins agent."
+            echo "Run this pipeline on a Docker-capable node (label: docker) or install Docker on the current agent."
+            exit 1
+          fi
+
+          if ! docker version >/dev/null 2>&1; then
+            echo "Docker is installed but not usable by Jenkins (daemon/socket/permissions issue)."
+            exit 1
+          fi
+        '''
+      }
+    }
+
     stage('Checkout') {
       steps {
         checkout scm
diff --git a/docs/deployment-production.md b/docs/deployment-production.md
index 181d13d..a2eceef 100644
--- a/docs/deployment-production.md
+++ b/docs/deployment-production.md
@@ -109,6 +109,14 @@ Configure these values in Jenkins job/folder/global environment or credentials-b
 
 The pipeline assumes Jenkins credentials are managed outside this repository.
 
+Jenkins runtime requirements:
+
+- The pipeline must run on a Jenkins agent with the `docker` label.
+- That agent must have Docker CLI installed and permission to access Docker daemon/socket.
+- `rsync` and `ssh` must also be available on the Jenkins agent.
+
+If Docker is missing or inaccessible, the pipeline now fails early in a dedicated preflight stage with an explicit message.
+
 ## Deploy flow
 
 Deployment is intentionally simple and bash-based:
-- 
2.39.5