diff --git a/README.md b/README.md
index 7286d38..ceb9df7 100644
--- a/README.md
+++ b/README.md
@@ -47,3 +47,18 @@ SQL files use numeric prefixes to control execution order:
 - `001-*.sql`, `002-*.sql`, etc. - Additional seed data or configuration
 
 If you need to add custom SQL scripts (e.g., for test data or configuration), use an appropriate numeric prefix to ensure correct execution order.
+
+## Remote Debugging
+
+All Openfire containers are configured with Java remote debugging enabled via JDWP. The debug agent runs in non-blocking mode (`suspend=n`), so containers start normally without waiting for a debugger to attach.
+
+Debug ports are exposed on localhost:
+
+| Server | Port |
+|--------|------|
+| xmpp1 (or xmpp) | 5005 |
+| xmpp2 | 5006 |
+| xmpp3 | 5007 |
+| otherxmpp | 5008 |
+
+To attach your IDE, create a remote debug configuration pointing to `localhost` on the appropriate port.
diff --git a/cluster/docker-compose-clustered.yml b/cluster/docker-compose-clustered.yml
index ca86e95..b8ddbb5 100644
--- a/cluster/docker-compose-clustered.yml
+++ b/cluster/docker-compose-clustered.yml
@@ -28,8 +28,12 @@ services:
       - "7071:7070"
       - "7441:7443"
       - "9091:9090"
+      - "5005:5005"
     depends_on:
       - "db"
+    environment:
+      JAVA_TOOL_OPTIONS: >
+        -agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=*:5005
     volumes:
       - ./_data/xmpp/1/conf:/var/lib/openfire/conf
       - ./_data/plugins:/opt/plugins
@@ -44,8 +48,12 @@ services:
       - "7072:7070"
       - "7442:7443"
       - "9092:9090"
+      - "5006:5005"
     depends_on:
       - "db"
+    environment:
+      JAVA_TOOL_OPTIONS: >
+        -agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=*:5005
     volumes:
       - ./_data/xmpp/2/conf:/var/lib/openfire/conf
       - ./_data/plugins:/opt/plugins
@@ -60,8 +68,12 @@ services:
       - "7073:7070"
       - "7443:7443"
       - "9093:9090"
+      - "5007:5005"
     depends_on:
       - "db"
+    environment:
+      JAVA_TOOL_OPTIONS: >
+        -agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=*:5005
     volumes:
       - ./_data/xmpp/3/conf:/var/lib/openfire/conf
       - ./_data/plugins:/opt/plugins
diff --git a/cluster_with_federation/docker-compose-clustered.yml b/cluster_with_federation/docker-compose-clustered.yml
index 9a4caf3..9922992 100644
--- a/cluster_with_federation/docker-compose-clustered.yml
+++ b/cluster_with_federation/docker-compose-clustered.yml
@@ -28,8 +28,12 @@ services:
       - "7071:7070"
       - "7441:7443"
       - "9091:9090"
+      - "5005:5005"
     depends_on:
       - "db"
+    environment:
+      JAVA_TOOL_OPTIONS: >
+        -agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=*:5005
     volumes:
       - ./_data/xmpp/1/conf:/var/lib/openfire/conf
       - ./_data/plugins:/opt/plugins
@@ -44,8 +48,12 @@ services:
       - "7072:7070"
       - "7442:7443"
       - "9092:9090"
+      - "5006:5005"
     depends_on:
       - "db"
+    environment:
+      JAVA_TOOL_OPTIONS: >
+        -agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=*:5005
     volumes:
       - ./_data/xmpp/2/conf:/var/lib/openfire/conf
       - ./_data/plugins:/opt/plugins
@@ -60,8 +68,12 @@ services:
       - "7073:7070"
       - "7443:7443"
       - "9093:9090"
+      - "5007:5005"
     depends_on:
       - "db"
+    environment:
+      JAVA_TOOL_OPTIONS: >
+        -agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=*:5005
     volumes:
       - ./_data/xmpp/3/conf:/var/lib/openfire/conf
       - ./_data/plugins:/opt/plugins
@@ -87,8 +99,12 @@ services:
       - "7079:7070"
       - "7449:7443"
       - "9099:9090"
+      - "5008:5005"
     depends_on:
       - "otherdb"
+    environment:
+      JAVA_TOOL_OPTIONS: >
+        -agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=*:5005
     volumes:
       - ./_data/xmpp/otherdomain/conf:/var/lib/openfire/conf
       - ./_data/plugins_for_otherdomain:/opt/plugins
diff --git a/federation/docker-compose-federated.yml b/federation/docker-compose-federated.yml
index c2f28d5..6beb945 100644
--- a/federation/docker-compose-federated.yml
+++ b/federation/docker-compose-federated.yml
@@ -30,8 +30,12 @@ services:
       - "7071:7070"
       - "7441:7443"
       - "9091:9090"
+      - "5005:5005"
     depends_on:
       - "db1"
+    environment:
+      JAVA_TOOL_OPTIONS: >
+        -agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=*:5005
     volumes:
       - ./_data/xmpp/1/conf:/var/lib/openfire/conf
       - ./_data/plugins:/opt/plugins
@@ -46,8 +50,12 @@ services:
       - "7072:7070"
       - "7442:7443"
       - "9092:9090"
+      - "5006:5005"
     depends_on:
       - "db2"
+    environment:
+      JAVA_TOOL_OPTIONS: >
+        -agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=*:5005
     volumes:
       - ./_data/xmpp/2/conf:/var/lib/openfire/conf
       - ./_data/plugins:/opt/plugins
diff --git a/proxy/docker-compose.yml b/proxy/docker-compose.yml
index 0271d41..2d94bde 100644
--- a/proxy/docker-compose.yml
+++ b/proxy/docker-compose.yml
@@ -31,8 +31,12 @@ services:
       - "7070:7070"
       - "7443:7443"
       - "9090:9090"
+      - "5005:5005"
     depends_on:
       - "db"
+    environment:
+      JAVA_TOOL_OPTIONS: >
+        -agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=*:5005
     volumes:
       - ./_data/xmpp/conf:/var/lib/openfire/conf
       - ./_data/plugins:/opt/plugins
diff --git a/simple/docker-compose.yml b/simple/docker-compose.yml
index 7a9fdd7..ff2754e 100644
--- a/simple/docker-compose.yml
+++ b/simple/docker-compose.yml
@@ -19,8 +19,12 @@ services:
       - "7070:7070"
       - "7443:7443"
       - "9090:9090"
+      - "5005:5005"
     depends_on:
       - "db"
+    environment:
+      JAVA_TOOL_OPTIONS: >
+        -agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=*:5005
     volumes:
       - ./_data/xmpp/conf:/var/lib/openfire/conf
       - ./_data/plugins:/opt/plugins