diff --git a/docker-compose.yml b/docker-compose.yml
index 54aa076..1c33fbc 100644
--- a/docker-compose.yml
+++ b/docker-compose.yml
@@ -46,7 +46,7 @@ services:
     ports:
       - "5222:5222"   # C2S
       - "5280:5280"   # HTTP (BOSH/WS/REST/admin)
-      - "5582:5582"   # admin telnet
+      - "${TELNET_HOST_PORT:-5582}:5582"   # admin telnet
     environment:
       prosodyDomain:      example.com
       prosodyDBhost:      postgres
diff --git a/run-compose-tests.sh b/run-compose-tests.sh
new file mode 100755
index 0000000..0de8a6e
--- /dev/null
+++ b/run-compose-tests.sh
@@ -0,0 +1,107 @@
+#!/bin/bash
+#
+# run-compose-tests.sh — bring up the compose test harness and run the full
+# pytest suite against it with all env vars set so no test is skipped for
+# missing infrastructure.
+#
+# Usage:
+#   ./run-compose-tests.sh              # up + test + down
+#   ./run-compose-tests.sh --no-down    # up + test (leave stack running)
+#   ./run-compose-tests.sh --down       # just tear down
+#
+set -euo pipefail
+
+REPO_ROOT="$(cd "$(dirname "$0")" && pwd)"
+cd "$REPO_ROOT"
+
+TEARDOWN=true
+if [[ "${1:-}" == "--no-down" ]]; then TEARDOWN=false; fi
+if [[ "${1:-}" == "--down" ]]; then
+    docker compose down
+    exit 0
+fi
+
+# ---------------------------------------------------------------------------
+# 1. Python venv (for host-run pytest)
+# ---------------------------------------------------------------------------
+VENV="$REPO_ROOT/tests/venv"
+if [[ ! -d "$VENV" ]]; then
+    echo ">>> creating python venv"
+    python3 -m venv "$VENV"
+fi
+# shellcheck disable=SC1091
+source "$VENV/bin/activate"
+pip install -q -r tests/requirements.txt
+
+# ---------------------------------------------------------------------------
+# 2. Port conflict detection — 5582 is frequently taken by kubectl port-forward
+# ---------------------------------------------------------------------------
+export TELNET_HOST_PORT=5582
+if ss -tlnp 2>/dev/null | grep -q ':5582 ' ; then
+    export TELNET_HOST_PORT=5583
+    echo ">>> port 5582 is in use — remapping telnet to ${TELNET_HOST_PORT}"
+fi
+
+# ---------------------------------------------------------------------------
+# 3. Bring up the stack
+# ---------------------------------------------------------------------------
+echo ">>> building + starting compose stack"
+docker compose down 2>/dev/null || true
+docker compose up -d --build postgres mocks prosody
+
+# ---------------------------------------------------------------------------
+# 4. Wait for prosody to be healthy
+# ---------------------------------------------------------------------------
+echo ">>> waiting for prosody to become healthy"
+MAX_WAIT=60
+for i in $(seq 1 "$MAX_WAIT"); do
+    status=$(docker compose ps --format json prosody 2>/dev/null \
+        | python3 -c "import sys,json; print(json.load(sys.stdin).get('Health',''))" 2>/dev/null || echo "")
+    if [[ "$status" == "healthy" ]]; then
+        echo ">>> prosody is healthy (after ${i}s)"
+        break
+    fi
+    if [[ "$i" -eq "$MAX_WAIT" ]]; then
+        echo ">>> prosody did not become healthy in ${MAX_WAIT}s — showing logs:"
+        docker compose logs --tail=30 prosody
+        exit 1
+    fi
+    sleep 1
+done
+
+# ---------------------------------------------------------------------------
+# 5. Run the full testsuite with all env vars set
+# ---------------------------------------------------------------------------
+echo ">>> running testsuite"
+XMPP_HOST=localhost \
+XMPP_PORT=5222 \
+XMPP_DOMAIN=example.com \
+MUC_DOMAIN=conference.example.com \
+XMPP_JID=user1@example.com \
+XMPP_PASSWORD=pass1 \
+XMPP_JID2=user2@example.com \
+XMPP_PASSWORD2=pass2 \
+REST_URL=http://localhost:5280/rest \
+BOSH_URL=http://localhost:5280/http-bind \
+WS_URL=ws://localhost:5280/xmpp-websocket \
+ADMIN_TELNET_HOST=localhost \
+ADMIN_TELNET_PORT="$TELNET_HOST_PORT" \
+PG_HOST=localhost \
+PG_PORT=5434 \
+PG_DB=prosody \
+PG_USER=prosody \
+PG_PASSWORD=prosody \
+MOCK_URL=http://localhost:8092 \
+pytest tests/ -v -c tests/pytest.ini
+
+TEST_RC=$?
+
+# ---------------------------------------------------------------------------
+# 6. Tear down (unless --no-down)
+# ---------------------------------------------------------------------------
+if $TEARDOWN; then
+    echo ">>> tearing down compose stack"
+    docker compose down
+fi
+
+exit $TEST_RC