Harden demo compose bindings (#580)

demo/.env.example

@@ -4,8 +4,13 @@
 # Port the demo UI will be accessible on (host side)
 DEMO_PORT=3099
 
-# Admin API key for seeding data
+# Host interface for the published demo port.
+# Keep 127.0.0.1 for local demos. Do not use 0.0.0.0 unless auth is enabled
+# and credentials are replaced.
+DEMO_BIND=127.0.0.1
+
+# Throwaway admin API key for local demo seeding only.
 VERITAS_ADMIN_KEY=demo-admin-key-2026
 
-# Set to true to disable auth entirely (easier for demos)
+# Set false only for local loopback demos. Set true before any non-loopback access.
 VERITAS_AUTH_ENABLED=false

demo/README.md

@@ -14,6 +14,8 @@ docker compose -f demo/docker-compose.demo.yml up --build
 
 Then open **http://localhost:3099**
 
+The demo binds to `127.0.0.1` and disables auth by default. Keep it local. For LAN, tunnel, VPS, or reverse-proxy access, set `VERITAS_AUTH_ENABLED=true`, replace `VERITAS_ADMIN_KEY`, and intentionally set `DEMO_BIND` to the required interface.
+
 ## What's Included
 
 The demo seeds realistic data showcasing VK's features:
@@ -34,11 +36,12 @@ Copy `.env.example` to `.env` to customize:
 cp demo/.env.example demo/.env
 ```
 
-| Variable               | Default               | Description                |
-| ---------------------- | --------------------- | -------------------------- |
-| `DEMO_PORT`            | `3099`                | Host port for the UI       |
-| `VERITAS_ADMIN_KEY`    | `demo-admin-key-2026` | API admin key              |
-| `VERITAS_AUTH_ENABLED` | `false`               | Set `true` to require auth |
+| Variable               | Default               | Description                                      |
+| ---------------------- | --------------------- | ------------------------------------------------ |
+| `DEMO_PORT`            | `3099`                | Host port for the UI                             |
+| `DEMO_BIND`            | `127.0.0.1`           | Host interface for the published port            |
+| `VERITAS_ADMIN_KEY`    | `demo-admin-key-2026` | Throwaway local demo key                         |
+| `VERITAS_AUTH_ENABLED` | `false`               | Set `true` before any non-loopback demo exposure |
 
 ## Reset Demo Data
 
@@ -58,3 +61,13 @@ docker compose -f demo/docker-compose.demo.yml up --build
 4. The sidecar exits; VK keeps running with seeded data
 
 Data persists in a Docker volume (`demo-data`) across restarts. The seed script is idempotent — it skips if tasks already exist.
+
+## Validate Compose Output
+
+Before changing bind/auth settings, inspect the generated config:
+
+```bash
+docker compose -f demo/docker-compose.demo.yml config
+```
+
+The default `ports` output should include `127.0.0.1:3099:3001`.

demo/docker-compose.demo.yml

@@ -5,6 +5,10 @@
 # Then open: http://localhost:3099
 #
 # Automatically seeds demo data on first run via the seed sidecar.
+#
+# LOCAL DEMO ONLY:
+# - Defaults to DEMO_BIND=127.0.0.1 and VERITAS_AUTH_ENABLED=false.
+# - Do not set DEMO_BIND=0.0.0.0 unless auth is enabled and credentials are replaced.
 # =============================================================================
 
 services:
@@ -15,12 +19,14 @@ services:
     container_name: vk-demo
     working_dir: /app/server
     ports:
-      - '${DEMO_PORT:-3099}:3001'
+      - '${DEMO_BIND:-127.0.0.1}:${DEMO_PORT:-3099}:3001'
     environment:
       - NODE_ENV=production
       - PORT=3001
       - DATA_DIR=/app/data
+      # Fixed local demo credential. Replace before enabling non-loopback access.
       - VERITAS_ADMIN_KEY=${VERITAS_ADMIN_KEY:-demo-admin-key-2026}
+      # Auth-disabled mode is safe only with DEMO_BIND left at 127.0.0.1.
       - VERITAS_AUTH_ENABLED=${VERITAS_AUTH_ENABLED:-false}
       - VERITAS_AUTH_LOCALHOST_BYPASS=true
       - VERITAS_AUTH_LOCALHOST_ROLE=admin

docker-compose-demo.yml

@@ -5,6 +5,11 @@
 #   docker compose -f docker-compose-demo.yml up --build -d
 #   docker compose -f docker-compose-demo.yml down
 #   docker compose -f docker-compose-demo.yml logs -f
+#
+# LOCAL DEMO ONLY:
+# - Binds to 127.0.0.1 by default so this auth-disabled demo is not exposed on
+#   LAN, VPS, tunnel, or reverse-proxy interfaces by accident.
+# - The admin key below is a throwaway demo value. Do not reuse it for deploys.
 # =============================================================================
 
 services:
@@ -16,14 +21,16 @@ services:
     # IMPORTANT: must match Dockerfile WORKDIR for relative CMD (node dist/index.js)
     working_dir: /app/server
     ports:
-      - '3099:3001'
+      - '127.0.0.1:3099:3001'
     environment:
       - NODE_ENV=production
       - PORT=3001
       - DATA_DIR=/app/data
+      # Fixed local demo credential. Replace with a generated 32+ char secret for any deployment.
       - VERITAS_ADMIN_KEY=demo-admin-key-for-product-hunt-2026
       - VERITAS_AUTH_LOCALHOST_BYPASS=true
       - VERITAS_AUTH_LOCALHOST_ROLE=admin
+      # Auth-disabled mode is safe only with the loopback port binding above.
       - VERITAS_AUTH_ENABLED=false
       - CORS_ORIGINS=http://localhost:3099
     volumes:

docker-compose.yml

@@ -6,6 +6,10 @@
 #   docker compose up -d             # Start in background
 #   docker compose down              # Stop and remove
 #   docker compose logs -f           # Follow logs
+#
+# LOCAL TESTING ONLY:
+# - Binds to 127.0.0.1 by default. Do not use this file as production config.
+# - The demo key below is not a deployment credential.
 # =============================================================================
 
 services:
@@ -18,12 +22,12 @@ services:
     working_dir: /app/server
     ports:
       # Demo instance port (do NOT use production 3001)
-      - '3099:3001'
+      - '127.0.0.1:3099:3001'
     environment:
       - NODE_ENV=production
       - PORT=3001
       - DATA_DIR=/app/data
-      # Demo auth key (Arcade walkthrough)
+      # Demo auth key (Arcade walkthrough). Replace before reusing this config.
       - VERITAS_ADMIN_KEY=demo-admin-key-for-product-hunt-2026
       # Host -> container requests come from bridge IP (not 127.0.0.1), so keep API key enabled.
       - VERITAS_AUTH_LOCALHOST_BYPASS=false

docs/DEPLOYMENT.md

@@ -30,6 +30,8 @@ This guide covers deploying Veritas Kanban in production using Docker (recommend
 
 The fastest way to get Veritas Kanban running in production:
 
+Use the production compose example in this guide for deployed instances. The repo's demo Compose files are local-only and may disable auth for walkthroughs; do not expose them on LAN, tunnel, VPS, or reverse-proxy interfaces.
+
 ```bash
 # Clone the repository
 git clone https://github.com/BradGroux/veritas-kanban.git

docs/guides/SELF_HOST.md

@@ -376,6 +376,8 @@ location /kanban/ws {
 
 Docker is the recommended approach for production deployments.
 
+Do not use the demo Compose files (`docker-compose-demo.yml` or `demo/docker-compose.demo.yml`) for production or shared-network deployments. They are local demo configs and may disable auth for convenience. Use the authenticated production compose example below and generate fresh secrets.
+
 ### Quick start
 
 ```bash