diff --git a/README.md b/README.md
index 3bf61c1..4892589 100644
--- a/README.md
+++ b/README.md
@@ -23,9 +23,11 @@ Its promises, all enforced by tests:
 pnpm install
 pnpm dev                # develop on http://localhost:4321
 pnpm build              # static site + offline artifact in dist/
-docker compose up preview   # prod-like: nginx + security headers on :8080
+docker compose -f docker-compose.dev.yml up preview   # prod-like: nginx + security headers on :8080
 ```
 
+Production deploys `docker-compose.yml` (single nginx service behind the platform's reverse proxy — Coolify, etc.), or point any static host at `pnpm build` → `dist/`.
+
 ## Contributing
 
 Contributions are very welcome — a tool to add, a translation, a correction. **Read [`CONTRIBUTING.md`](./CONTRIBUTING.md) first**: it contains three simple rules for tools (traction, open source, privacy-respecting), a mandatory affiliation-disclosure policy, and a CI-enforced external-link policy. Large changes start with an issue, not a PR.
diff --git a/docker-compose.dev.yml b/docker-compose.dev.yml
new file mode 100644
index 0000000..d66b96e
--- /dev/null
+++ b/docker-compose.dev.yml
@@ -0,0 +1,23 @@
+# Local development only — NOT what production deploys.
+#   docker compose -f docker-compose.dev.yml up dev       # HMR on :4321
+#   docker compose -f docker-compose.dev.yml up preview   # prod-like on :8080
+services:
+  dev:
+    image: node:22-alpine@sha256:16e22a550f3863206a3f701448c45f7912c6896a62de43add43bb9c86130c3e2
+    working_dir: /app
+    command: sh -c "corepack enable && pnpm install --frozen-lockfile && pnpm dev --host"
+    ports:
+      - '4321:4321'
+    volumes:
+      - .:/app
+      - node_modules:/app/node_modules
+    environment:
+      - ASTRO_TELEMETRY_DISABLED=1
+
+  preview:
+    build: .
+    ports:
+      - '8080:8080'
+
+volumes:
+  node_modules:
diff --git a/docker-compose.yml b/docker-compose.yml
index 92605e9..8c4d9a4 100644
--- a/docker-compose.yml
+++ b/docker-compose.yml
@@ -1,22 +1,11 @@
+# Production compose (what Coolify deploys): one service, the static site
+# built by the multi-stage Dockerfile and served by hardened nginx on 8080.
+# No host `ports:` mapping: the platform's reverse proxy (Traefik on
+# Coolify) routes straight to the exposed container port. For local
+# development use docker-compose.dev.yml instead.
 services:
-  # live dev server with HMR on http://localhost:4321
-  dev:
-    image: node:22-alpine@sha256:16e22a550f3863206a3f701448c45f7912c6896a62de43add43bb9c86130c3e2
-    working_dir: /app
-    command: sh -c "corepack enable && pnpm install --frozen-lockfile && pnpm dev --host"
-    ports:
-      - '4321:4321'
-    volumes:
-      - .:/app
-      - node_modules:/app/node_modules
-    environment:
-      - ASTRO_TELEMETRY_DISABLED=1
-
-  # production-like: the real nginx image with security headers on :8080
-  preview:
+  web:
     build: .
-    ports:
-      - '8080:8080'
-
-volumes:
-  node_modules:
+    restart: unless-stopped
+    expose:
+      - '8080'