diff --git a/ci/jenkins/README.md b/ci/jenkins/README.md
index 1970e8d..006209c 100644
--- a/ci/jenkins/README.md
+++ b/ci/jenkins/README.md
@@ -74,6 +74,25 @@ Jenkins runs as a Coolify service from a Compose file:
 - **Run no builds on it:** **Manage Jenkins → Nodes → Built-In Node →
   Configure**, set **Number of executors** to `0`.
 
+#### Upgrading from the old setup
+
+`ci/jenkins/docker-compose.yml` used to define the Jenkins **controller**
+(its `jenkins` service, built from `ci/jenkins/Dockerfile`, with the
+`jenkins_home` volume). It now defines only the build agent. If your Jenkins
+was deployed from that file, **don't redeploy that application** from this
+version: it would replace the controller with an agent, and Jenkins stops
+until you rebuild it. The data volume survives, but nothing serves it.
+
+Instead:
+
+1. Create a new service for the controller as above, on the stock Java 25
+   image, mounting the **same** data volume: reference the old volume by its
+   full name and mark it `external: true`, or Jenkins starts empty.
+2. Stop the old application, start the new service, and check that your jobs
+   and credentials are there.
+3. Deploy the agent (step 3) as a **new** application, then delete the old
+   one without deleting its volume.
+
 ### 2. The agent node
 
 **Manage Jenkins → Nodes → New Node**, a permanent agent:
diff --git a/ci/jenkins/docker-compose.yml b/ci/jenkins/docker-compose.yml
index eea0283..5afb748 100644
--- a/ci/jenkins/docker-compose.yml
+++ b/ci/jenkins/docker-compose.yml
@@ -3,6 +3,12 @@
 # /docker-compose.yml and "Connect to predefined network" on. It needs no domain: it dials out to
 # Jenkins over WebSocket on Docker's internal network. Set the variables in
 # the resource's Environment Variables; see ci/jenkins/README.md.
+#
+# This file used to define the Jenkins controller itself. If your Jenkins was
+# deployed from it, don't redeploy that application from this version: it
+# would replace the controller with an agent. Move the controller to its own
+# service first and deploy this as a NEW application (README: "Upgrading from
+# the old setup").
 services:
   agent:
     build: