From 704fecdcc0ea9c19c5c21158fda960d0c2cf4520 Mon Sep 17 00:00:00 2001
From: Matthew Meszaros <meszmatew@gmail.com>
Date: Wed, 9 Sep 2026 05:04:55 -0700
Subject: [PATCH] feat: settle on WARMBLY_NODE_REGION as the one region
 variable for every role, because the join script wrote it while the worker
 still read WORKER_REGION, so a joined worker reported no region and the
 placement geography term stayed dead for exactly the machines that had been
 given one

---
 .env.example                                    |  2 +-
 cmd/worker/main.go                              | 13 ++++++++++++-
 docker-compose.yml                              |  2 +-
 docs/content/docs/development/bare-metal.mdx    |  2 +-
 docs/content/docs/development/configuration.mdx |  2 +-
 internal/app/instanceconfig/entries.go          |  6 +++---
 6 files changed, 19 insertions(+), 8 deletions(-)

diff --git a/.env.example b/.env.example
index 0fe2828c..cc61507b 100644
--- a/.env.example
+++ b/.env.example
@@ -468,7 +468,7 @@ BILLING_PROVIDER=none
 # WORKER_STATE_DIR=/data/state
 # WORKER_BIND_IP=
 # WORKER_PUBLIC_IP=
-# WORKER_REGION=                     # free-form egress location label, e.g. eu-central
+# WARMBLY_NODE_REGION=               # free-form egress location label, e.g. eu-central
 # MAIL_TLS_INSECURE=false            # skips cert verification on mailbox connections
 #
 # Set on the BACKEND: the image the remote installer pulls. The built-in default
diff --git a/cmd/worker/main.go b/cmd/worker/main.go
index d0950792..c68d73a8 100644
--- a/cmd/worker/main.go
+++ b/cmd/worker/main.go
@@ -239,7 +239,7 @@ func newNodeAgent(workerID uuid.UUID, bindIP string) *nodeagent.Agent {
 		NodeID:  workerID,
 		Role:    models.NodeRoleWorker,
 		Name:    os.Getenv("WARMBLY_NODE_NAME"),
-		Region:  os.Getenv("WORKER_REGION"),
+		Region:  nodeRegion(),
 		Address: reportedIP,
 		Version: buildVersion(),
 		BaseURL: os.Getenv("ENCRYPTED_KEYS_BACKEND_URL"),
@@ -249,6 +249,17 @@ func newNodeAgent(workerID uuid.UUID, bindIP string) *nodeagent.Agent {
 	})
 }
 
+// nodeRegion reads the sign-in geography hint. WARMBLY_NODE_REGION is what the
+// join script writes and what every role uses; WORKER_REGION is the older
+// worker-only name, kept as a fallback so a machine configured by hand before
+// the join flow existed keeps reporting its region.
+func nodeRegion() string {
+	if v := os.Getenv("WARMBLY_NODE_REGION"); v != "" {
+		return v
+	}
+	return os.Getenv("WORKER_REGION")
+}
+
 // buildVersion is the image tag this build reports. Set by the join script
 // from the tag it pulled; empty means unknown, which the control plane must
 // not read as "needs updating".
diff --git a/docker-compose.yml b/docker-compose.yml
index ce6c2086..66b6ba6e 100644
--- a/docker-compose.yml
+++ b/docker-compose.yml
@@ -483,7 +483,7 @@ services:
       # so ids survive container recreates and --scale still works.
       WORKER_ID: ${WORKER_ID:-}
       WORKER_STATE_DIR: ${WORKER_STATE_DIR:-/data/state}
-      WORKER_REGION: ${WORKER_REGION:-}
+      WARMBLY_NODE_REGION: ${WARMBLY_NODE_REGION:-}
       BOX_GOOGLE_CLIENT_ID: ${BOX_GOOGLE_CLIENT_ID:-}
       BOX_GOOGLE_CLIENT_SECRET: ${BOX_GOOGLE_CLIENT_SECRET:-}
       BOX_OUTLOOK_CLIENT_ID: ${BOX_OUTLOOK_CLIENT_ID:-}
diff --git a/docs/content/docs/development/bare-metal.mdx b/docs/content/docs/development/bare-metal.mdx
index da17a933..188119d0 100644
--- a/docs/content/docs/development/bare-metal.mdx
+++ b/docs/content/docs/development/bare-metal.mdx
@@ -377,7 +377,7 @@ sudo tee /etc/warmbly/worker.env >/dev/null <<EOF
 APP_ENV=prod
 AWS_CONFIG_ENABLED=false
 WORKER_ID=$(uuidgen)
-WORKER_REGION=eu-central
+WARMBLY_NODE_REGION=eu-central
 
 EVENTBUS_PROVIDER=nats
 NATS_URL=nats://127.0.0.1:4222
diff --git a/docs/content/docs/development/configuration.mdx b/docs/content/docs/development/configuration.mdx
index e3e044d3..23b34699 100644
--- a/docs/content/docs/development/configuration.mdx
+++ b/docs/content/docs/development/configuration.mdx
@@ -315,7 +315,7 @@ The variable must be set on the backend in every environment. The file itself is
 | `WORKER_ID` | Stable uuid for this worker. Leave unset when running scaled replicas, which share one environment | derived, then random | yes |
 | `WORKER_BIND_IP` | Source address to bind outbound connections to, and the seed for a derived `WORKER_ID` | unset | yes |
 | `WORKER_PUBLIC_IP` | The address the worker reports to the control plane | detected | yes |
-| `WORKER_REGION` | Free-form label for where this worker egresses from, e.g. `eu-central`. Placement prefers a worker near where a mailbox's provider expects sign-ins; unset scores neutral | unset | yes |
+| `WARMBLY_NODE_REGION` | Free-form label for where this node egresses from, e.g. `eu-central`. Placement prefers a worker near where a mailbox's provider expects sign-ins; unset scores neutral. Written by the join script from `--region` | unset | yes |
 | `WORKER_IMAGE` | Image the remote installer pulls. The built-in default does not match what CI publishes, so set it | built-in | yes |
 | `ENCRYPTED_KEYS_BACKEND_URL` | Backend base the worker fetches organization keys from | unset | yes |
 | `ENCRYPTED_KEYS_WORKER_TOKEN` | The worker's copy of `INTERNAL_API_TOKEN` | unset | yes |
diff --git a/internal/app/instanceconfig/entries.go b/internal/app/instanceconfig/entries.go
index d4f994e2..dc16e669 100644
--- a/internal/app/instanceconfig/entries.go
+++ b/internal/app/instanceconfig/entries.go
@@ -702,10 +702,10 @@ var table = []Entry{
 		Resolve:    envValue("WORKER_ID"),
 	},
 	{
-		Key: "WORKER_REGION", Group: GroupWorkers, RuntimeChangeable: ChangeBootOnly,
-		Effect:     "Where this worker egresses from, as a free-form label. Placement prefers a worker near where a mailbox's provider expects sign-ins; unset scores neutral.",
+		Key: "WARMBLY_NODE_REGION", Group: GroupWorkers, RuntimeChangeable: ChangeBootOnly,
+		Effect:     "Where this node egresses from, as a free-form label. Placement prefers a worker near where a mailbox's provider expects sign-ins; unset scores neutral.",
 		DocsAnchor: docsWorkers,
-		Resolve:    envValue("WORKER_REGION"),
+		Resolve:    envValue("WARMBLY_NODE_REGION"),
 	},
 	{
 		Key: "MAIL_TLS_INSECURE", Group: GroupWorkers, RuntimeChangeable: ChangeBootOnly,