From f66549ae7e3a1eb4205c0e91164ea96630c215cc Mon Sep 17 00:00:00 2001
From: Johannes <johannes@bcos.cloud>
Date: Tue, 30 Jun 2026 08:24:52 -0400
Subject: [PATCH] =?UTF-8?q?docs:=20ENVIRONMENTS.md=20+=20compare-prod-dev.?=
 =?UTF-8?q?sh=20=E2=80=94=20prod/dev=20split,=20one-command=20drift=20comp?=
 =?UTF-8?q?are?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 ENVIRONMENTS.md      | 31 +++++++++++++++++++++++++++
 compare-prod-dev.sh  | 51 ++++++++++++++++++++++++++++++++++++++++++++
 hiveiq-openmetal     |  2 +-
 hiveiq-openmetal-dev |  1 +
 4 files changed, 84 insertions(+), 1 deletion(-)
 create mode 100644 ENVIRONMENTS.md
 create mode 100755 compare-prod-dev.sh
 create mode 160000 hiveiq-openmetal-dev

diff --git a/ENVIRONMENTS.md b/ENVIRONMENTS.md
new file mode 100644
index 0000000..1b7b9fc
--- /dev/null
+++ b/ENVIRONMENTS.md
@@ -0,0 +1,31 @@
+# HiveOps Deployment Environments
+
+**Two repos, one per environment — no duplication.** Production config lives only in the prod
+repo; dev config lives only in the dev repo.
+
+| Env | Repo (cloned as) | Config path | Live URL | VM |
+|-----|------------------|-------------|----------|----|
+| **PRODUCTION** | `hiveiq-openmetal-prod` (`hiveiq-openmetal/`) | `hiveops/instances/services/` | bcos.cloud | 173.231.195.250 |
+| **DEV / staging** | `hiveiq-openmetal-dev/` | `hiveops/instances/dev/` | bcos.dev | 173.231.195.251 |
+
+Production also keeps its other instances in the **prod** repo: `database`, `browser`, `ollama`,
+`logging`, and the `bcos-*` services (mail, office, share, proxy, gitea, odoo). **Dev is all-in-one**
+— one VM bundles postgres/kafka/registry/etc that prod splits across VMs.
+
+## Compare dev vs prod
+The two repos are **structurally parallel** (`compose/<svc>.yml`, `nginx/conf.d/<svc>.conf`):
+
+```bash
+./compare-prod-dev.sh            # drift summary — which configs differ or are env-only
+./compare-prod-dev.sh incident   # full diff of a specific service
+# or diff directly:
+diff hiveiq-openmetal-dev/hiveops/instances/dev/nginx/conf.d/api.conf \
+     hiveiq-openmetal/hiveops/instances/services/nginx/conf.d/api.conf
+```
+
+(For this to work, clone **both** repos side by side under this directory.)
+
+## Source of truth
+The live VMs are **hand-managed** (not git-fed). These repos are the **reference/backup** — keep
+them in sync with the VMs whenever you change deployment config. `.env` **secrets are gitignored**:
+they live only on the VMs and in **Vaultwarden** (`pw.bcos.cloud`).
diff --git a/compare-prod-dev.sh b/compare-prod-dev.sh
new file mode 100755
index 0000000..099712a
--- /dev/null
+++ b/compare-prod-dev.sh
@@ -0,0 +1,51 @@
+#!/usr/bin/env bash
+# Compare bcos.dev (DEV) vs bcos.cloud (PROD) deployment config, side by side.
+#
+#   ./compare-prod-dev.sh            # DRIFT SUMMARY: which configs differ / are env-only
+#   ./compare-prod-dev.sh incident   # FULL DIFF of every config matching "incident"
+#   ./compare-prod-dev.sh api        # FULL DIFF of the nginx api.conf, etc.
+#
+# PROD = hiveiq-openmetal/hiveops/instances/services   (bcos.cloud,  173.231.195.250)
+# DEV  = hiveiq-openmetal-dev/hiveops/instances/dev     (bcos.dev,    173.231.195.251)
+#
+# Both repos are structurally parallel: compose/<svc>.yml + nginx/conf.d/<svc>.conf.
+set -uo pipefail
+HERE=$(cd "$(dirname "$0")" && pwd)
+PROD="$HERE/hiveiq-openmetal/hiveops/instances/services"
+DEV="$HERE/hiveiq-openmetal-dev/hiveops/instances/dev"
+[ -d "$PROD" ] || { echo "PROD config not found: $PROD"; exit 1; }
+[ -d "$DEV" ]  || { echo "DEV config not found: $DEV  (clone hiveiq-openmetal-dev next to hiveiq-openmetal)"; exit 1; }
+
+FILTER="${1:-}"
+
+scan() {  # $1 = subdir ; $2 = glob
+  local sub="$1" glob="$2" df pf n
+  echo "## $sub"
+  for df in "$DEV/$sub"/$glob; do
+    [ -e "$df" ] || continue; n=$(basename "$df")
+    pf="$PROD/$sub/$n"
+    if   [ ! -e "$pf" ]; then echo "  [dev-only]  $n"
+    elif ! diff -q "$pf" "$df" >/dev/null 2>&1; then echo "  [DIFFERS]   $n"; fi
+  done
+  for pf in "$PROD/$sub"/$glob; do
+    [ -e "$pf" ] || continue; n=$(basename "$pf")
+    [ -e "$DEV/$sub/$n" ] || echo "  [prod-only] $n"
+  done
+}
+
+if [ -n "$FILTER" ]; then
+  echo "=== FULL DIFF (prod → dev) for *$FILTER* ==="
+  for sub in compose nginx/conf.d; do
+    for df in "$DEV/$sub/"*"$FILTER"*; do
+      [ -e "$df" ] || continue; n=$(basename "$df"); pf="$PROD/$sub/$n"
+      echo "--- $sub/$n ---"
+      if [ -e "$pf" ]; then diff -u "$pf" "$df" || true; else echo "  (dev-only — no prod counterpart)"; fi
+    done
+  done
+else
+  echo "=== DRIFT SUMMARY: bcos.dev (DEV) vs bcos.cloud (PROD) ==="
+  scan compose '*.yml'
+  scan nginx/conf.d '*.conf'
+  echo ""
+  echo "→ './compare-prod-dev.sh <name>' for the full diff of one config (e.g. incident, api, auth)."
+fi
diff --git a/hiveiq-openmetal b/hiveiq-openmetal
index a62c9b7..bc2c5db 160000
--- a/hiveiq-openmetal
+++ b/hiveiq-openmetal
@@ -1 +1 @@
-Subproject commit a62c9b712da9fdaf8351c70e3aa0a5955d32bdb8
+Subproject commit bc2c5dbb0d19227ffb8e1dab64284b62613ef3bc
diff --git a/hiveiq-openmetal-dev b/hiveiq-openmetal-dev
new file mode 160000
index 0000000..f9ab5ea
--- /dev/null
+++ b/hiveiq-openmetal-dev
@@ -0,0 +1 @@
+Subproject commit f9ab5ea35e05b9510f79d266649f9db398fb123d