feat: randomized ports via setup.sh + .env on first run

- setup.sh generates .env with random ports (10000-59999) on first run,
  ensuring WEB_PORT, RELAY_TCP_PORT, and RELAY_UDP_PORT are all distinct
- .env.example documents all available env vars with defaults
- docker-compose.yml already reads from .env via ${VAR:-default} syntax
- Run `bash setup.sh` to generate ports, `bash setup.sh --start` to also
  bring up the stack in one step

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

.env.example

@@ -1,29 +1,23 @@
-# Dragon Wind — Environment Configuration
-# Copy this file to .env and fill in your values.
+# Dragon Wind — example .env
+# Let setup.sh generate .env automatically (randomized ports), or copy this file:
+#   cp .env.example .env
 
-# ── Web App ──────────────────────────────────────────────────
-WEB_PORT=3000                          # Port the web UI listens on
-AUTH_USER=Admin                        # Default admin username
-AUTH_PASS=DragonWind2026!              # Change this before going to production!
+# ---- Ports (randomized by setup.sh on first run) ------------
+WEB_PORT=3000
+RELAY_TCP_PORT=3001
+RELAY_UDP_PORT=5000
 
-# ── S3 Storage ───────────────────────────────────────────────
-# These can also be configured via Admin → S3 Settings in the web UI.
-# Values set here are loaded at first boot; changes via UI override them.
-S3_ENDPOINT=https://s3.example.com     # or https://minio.yourhost.com:9000
+# ---- Auth ---------------------------------------------------
+AUTH_USER=admin
+AUTH_PASS=DragonWind2026!
+
+# ---- S3 (can also be configured via Admin UI) ---------------
+S3_ENDPOINT=
 S3_REGION=us-east-1
-S3_BUCKET=uploads
-S3_ACCESS_KEY=your-access-key-id
-S3_SECRET_KEY=your-secret-access-key
+S3_BUCKET=
+S3_ACCESS_KEY=
+S3_SECRET_KEY=
 
-# ── UDP Relay ─────────────────────────────────────────────────
-# These can also be configured via Admin → UDP Relay in the web UI.
-RELAY_URL=http://udp-relay:3001        # Internal Docker URL (auto-set in compose)
-# RELAY_URL=https://relay.yourdomain.com  # Use this if relay is external
-RELAY_TCP_PORT=3001                    # Host port for relay control API
-RELAY_UDP_PORT=5000                    # Host port for UDP data — MUST be port-forwarded!
-UDP_PORT=5000
-MAX_RELAY_SESSIONS=50
-
-# ── AMPP Integration (optional) ──────────────────────────────
+# ---- AMPP (can also be configured via Admin UI) -------------
 AMPP_BASE_URL=https://us-east-1.gvampp.com
-AMPP_API_KEY=                          # Base64 encoded client_id:client_secret
+AMPP_API_KEY=

setup.sh

@@ -0,0 +1,81 @@
+#!/usr/bin/env bash
+# =============================================================
+# Dragon Wind — First-Run Setup
+# Generates a .env file with randomized ports if one doesn't
+# already exist, then optionally starts the stack.
+# =============================================================
+
+set -euo pipefail
+
+ENV_FILE="$(dirname "$0")/.env"
+
+# ---- Random port helper (avoids well-known ports) -----------
+rand_port() {
+  # Pick a random port in range 10000–59999
+  echo $(( RANDOM % 50000 + 10000 ))
+}
+
+# ---- Only generate .env if it doesn't exist -----------------
+if [ -f "$ENV_FILE" ]; then
+  echo "✅  .env already exists — skipping generation."
+  echo "    Edit $ENV_FILE to change ports or credentials."
+else
+  WEB_PORT=$(rand_port)
+  RELAY_TCP_PORT=$(rand_port)
+  RELAY_UDP_PORT=$(rand_port)
+
+  # Ensure all three are distinct
+  while [ "$RELAY_TCP_PORT" -eq "$WEB_PORT" ]; do RELAY_TCP_PORT=$(rand_port); done
+  while [ "$RELAY_UDP_PORT" -eq "$WEB_PORT" ] || [ "$RELAY_UDP_PORT" -eq "$RELAY_TCP_PORT" ]; do
+    RELAY_UDP_PORT=$(rand_port)
+  done
+
+  cat > "$ENV_FILE" <<EOF
+# Dragon Wind — auto-generated by setup.sh
+# Ports are randomized on first run. Edit freely.
+
+# ---- Ports --------------------------------------------------
+WEB_PORT=$WEB_PORT
+RELAY_TCP_PORT=$RELAY_TCP_PORT
+RELAY_UDP_PORT=$RELAY_UDP_PORT
+
+# ---- Auth (change these!) -----------------------------------
+AUTH_USER=admin
+AUTH_PASS=DragonWind2026!
+
+# ---- S3 (set via Admin UI or here) --------------------------
+S3_ENDPOINT=
+S3_REGION=us-east-1
+S3_BUCKET=
+S3_ACCESS_KEY=
+S3_SECRET_KEY=
+
+# ---- AMPP (set via Admin UI or here) ------------------------
+AMPP_BASE_URL=https://us-east-1.gvampp.com
+AMPP_API_KEY=
+EOF
+
+  echo ""
+  echo "🐉  Dragon Wind setup complete!"
+  echo ""
+  echo "    Ports assigned:"
+  echo "      Web UI       →  http://localhost:$WEB_PORT"
+  echo "      Relay TCP    →  :$RELAY_TCP_PORT"
+  echo "      UDP Data     →  :$RELAY_UDP_PORT/udp"
+  echo ""
+  echo "    ⚠️  Change AUTH_PASS in .env before going live!"
+  echo ""
+fi
+
+# ---- Optionally start the stack -----------------------------
+if [ "${1:-}" = "--start" ] || [ "${1:-}" = "-s" ]; then
+  echo "🚀  Starting Dragon Wind..."
+  docker compose up -d --build
+  echo ""
+  # Re-read the port in case .env was pre-existing
+  WEB_PORT_LIVE=$(grep '^WEB_PORT=' "$ENV_FILE" | cut -d= -f2)
+  echo "✅  Running at http://localhost:${WEB_PORT_LIVE}"
+else
+  echo "    To start: docker compose up -d --build"
+  echo "    Or run:   bash setup.sh --start"
+fi