diff --git a/compose.master.yml b/compose.master.yml
index f286d6f..0355ccd 100644
--- a/compose.master.yml
+++ b/compose.master.yml
@@ -1,4 +1,17 @@
-version: "3"
+# PPF master node (odin)
+#
+# Scrapes proxy sources, runs verification, serves API/dashboard.
+# No routine proxy testing -- workers handle that.
+#
+# Prerequisites:
+#   - config.ini  (not tracked, host-specific)
+#   - data/       (created automatically)
+#
+# Usage:
+#   podman-compose -f compose.master.yml up -d
+#   podman-compose -f compose.master.yml logs -f
+#   podman-compose -f compose.master.yml down
+
 services:
   ppf:
     container_name: ppf
@@ -6,10 +19,12 @@ services:
     build: .
     network_mode: host
     restart: unless-stopped
+    stop_signal: SIGTERM
+    stop_grace_period: 30s
     environment:
       PYTHONUNBUFFERED: "1"
     volumes:
-      - .:/app:ro
-      - ./data:/app/data
-      - ./config.ini:/app/config.ini:ro
-    command: python2 -u ppf.py
+      - .:/app:ro,Z
+      - ./data:/app/data:Z
+      - ./config.ini:/app/config.ini:ro,Z
+    command: python -u ppf.py
diff --git a/compose.worker.yml b/compose.worker.yml
index f55a2c8..cac7fa5 100644
--- a/compose.worker.yml
+++ b/compose.worker.yml
@@ -1,4 +1,22 @@
-version: "3"
+# PPF worker node (cassius, edge, sentinel, ...)
+#
+# Tests proxies and reports results to master via WireGuard.
+# Each worker uses only local Tor (127.0.0.1:9050).
+#
+# Prerequisites:
+#   - config.ini    (not tracked, host-specific)
+#   - servers.txt   (deploy from repo)
+#   - src/          (deploy *.py from repo root into src/)
+#   - data/         (created automatically)
+#
+# Usage:
+#   PPF_MASTER_URL=http://10.200.1.250:8081 podman-compose -f compose.worker.yml up -d
+#   podman-compose -f compose.worker.yml logs -f
+#   podman-compose -f compose.worker.yml down
+#
+# The master URL defaults to http://10.200.1.250:8081 (odin via WireGuard).
+# Override with PPF_MASTER_URL env var or edit .env file.
+
 services:
   ppf-worker:
     container_name: ppf-worker
@@ -6,13 +24,15 @@ services:
     build: .
     network_mode: host
     restart: unless-stopped
+    stop_signal: SIGTERM
+    stop_grace_period: 30s
     logging:
       driver: k8s-file
     environment:
       PYTHONUNBUFFERED: "1"
     volumes:
-      - ./src:/app:ro
-      - ./data:/app/data
-      - ./config.ini:/app/config.ini:ro
-      - ./servers.txt:/app/servers.txt:ro
-    command: python -u ppf.py --worker-v2 --server http://10.200.1.250:8081
+      - ./src:/app:ro,Z
+      - ./data:/app/data:Z
+      - ./config.ini:/app/config.ini:ro,Z
+      - ./servers.txt:/app/servers.txt:ro,Z
+    command: python -u ppf.py --worker-v2 --server ${PPF_MASTER_URL:-http://10.200.1.250:8081}