docs(docker): warn about macOS AirPlay 5000 conflict for MLflow port

.env.example

@@ -257,12 +257,19 @@ ROMA_DISABLE_MLFLOW_SPANS=false
 # - If running ROMA locally (not in Docker): set to http://127.0.0.1:<port>
 # - If running ROMA inside docker-compose: set to http://mlflow:5000
 # You can change the host port with MLFLOW_PORT; container port is always 5000.
+#
+# NOTE for macOS users (Monterey/Ventura/Sonoma): the AirPlay Receiver service
+# binds 0.0.0.0:5000 by default and will collide with the default mapping
+# below ("bind: address already in use"). Either disable AirPlay Receiver
+# (System Settings → General → AirDrop & Handoff) or override MLFLOW_PORT
+# and MLFLOW_TRACKING_URI to the same non-5000 port (e.g. 5050).
 MLFLOW_TRACKING_URI=http://127.0.0.1:5000
 
 # MLflow experiment name
 MLFLOW_EXPERIMENT=ROMA-DSPy
 
 # MLflow port (for docker-compose)
+# See the MLFLOW_TRACKING_URI block above for the macOS AirPlay caveat.
 MLFLOW_PORT=5000
 
 # MLflow S3 artifact storage (MinIO)

README.md

@@ -198,6 +198,8 @@ just solve "What is the capital of France?"
 - 📦 **MinIO**: S3-compatible storage (http://localhost:9001)
 - 📊 **MLflow**: http://localhost:5000 (with `docker-up-full`)
 
+> **macOS users:** the AirPlay Receiver service binds `0.0.0.0:5000` by default on Monterey and newer, which collides with the MLflow port mapping above (`bind: address already in use`). Either disable AirPlay Receiver (System Settings → General → AirDrop & Handoff) or set `MLFLOW_PORT` and update `MLFLOW_TRACKING_URI` to a free port (e.g. `5050`) in your `.env`. See issue [#34](https://github.com/sentient-agi/ROMA/issues/34).
+
 See [Quick Start Guide](docs/QUICKSTART.md) and [Deployment Guide](docs/DEPLOYMENT.md) for details.
 
 ---

docker-compose.yaml

@@ -136,6 +136,10 @@ services:
     container_name: roma-dspy-mlflow
     env_file:
       - .env
+    # NOTE: macOS Monterey+ binds 0.0.0.0:5000 for AirPlay Receiver and will
+    # collide with the default port mapping below. Set MLFLOW_PORT in .env
+    # (e.g. MLFLOW_PORT=5050) and update MLFLOW_TRACKING_URI to match, or
+    # disable the AirPlay Receiver service. See issue #34.
     ports:
       - "${MLFLOW_PORT:-5000}:5000"
     environment: