From cbc5e2576f0aa9cfaf81ab765ce5073730006fc8 Mon Sep 17 00:00:00 2001
From: Wyatt Walter <wyattwalter@gmail.com>
Date: Thu, 16 Apr 2026 10:45:57 -0500
Subject: [PATCH 01/11] chore(mongo): upgrade embedded MongoDB from 6.0 to 7.0
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

MongoDB 6.0 reached end of life, so we are bumping the embedded MongoDB
in the Docker image to 7.0. This is a major version upgrade and requires
the existing data to be at featureCompatibilityVersion (FCV) >= 6.0 —
MongoDB 7.0 refuses to start otherwise.

Changes:

- base.dockerfile: switch the apt repo, GPG key, and list file from the
  6.0 stream to 7.0. Stay on the jammy (22.04) packages since MongoDB
  does not publish a noble (24.04) apt repo — same pattern the 6.0
  install already used on Ubuntu 24.04.

- mongodb-fixer.sh: after confirming / raising FCV, write the observed
  value to a marker file (.appsmith-fcv) in the Mongo data directory.
  Keep the target FCV at 6.0 (not 7.0) to preserve the ability to
  downgrade to a 6.x Appsmith release. Add confirm:true to the
  setFeatureCompatibilityVersion call, required as of MongoDB 7.0.

- entrypoint.sh: add ensure_mongodb_fcv_compatible, a pre-flight check
  that reads the marker before handing off to supervisord. Fast path
  when the marker is present and >= 6.0; hard-fail with an actionable
  error (roll back to last 6.x release, let it boot, upgrade again) if
  the marker indicates FCV < 6.0. On the rare transitional case of
  marker-missing-with-data (first boot after upgrading from a pre-
  marker Appsmith release), do a one-time mongod --fork probe to
  confirm compatibility, then let the fixer write the marker after
  supervisord brings mongod up. Also seed the marker on fresh install
  inside init_replica_set so the probe is skipped on the very first
  boot of a new deployment.

This gives operators a clear error message when their data is
incompatible, without paying the cost of multiple mongod starts on
every container boot.
---
 deploy/docker/base.dockerfile                 |  7 +-
 deploy/docker/fs/opt/appsmith/entrypoint.sh   | 83 +++++++++++++++++++
 .../docker/fs/opt/appsmith/mongodb-fixer.sh   | 43 ++++++++--
 3 files changed, 125 insertions(+), 8 deletions(-)

diff --git a/deploy/docker/base.dockerfile b/deploy/docker/base.dockerfile
index 575cdaf6b247..51f197bc8817 100644
--- a/deploy/docker/base.dockerfile
+++ b/deploy/docker/base.dockerfile
@@ -27,9 +27,10 @@ RUN set -o xtrace \
     software-properties-common \
     git \
   && add-apt-repository -y ppa:git-core/ppa \
-  # Install MongoDB v6, PostgreSQL v14
-  && curl -fsSL https://www.mongodb.org/static/pgp/server-6.0.asc | gpg --dearmor -o /usr/share/keyrings/mongodb-server-6.0.gpg \
-  && echo "deb [ arch=amd64,arm64 signed-by=/usr/share/keyrings/mongodb-server-6.0.gpg ] https://repo.mongodb.org/apt/ubuntu jammy/mongodb-org/6.0 multiverse" | tee /etc/apt/sources.list.d/mongodb-org-6.0.list \
+  # Install MongoDB v7, PostgreSQL v14
+  # Note: MongoDB 7.0 does not publish apt packages for Ubuntu 24.04 (noble) yet, so we use the jammy (22.04) packages — same pattern used for the previous 6.0 install.
+  && curl -fsSL https://www.mongodb.org/static/pgp/server-7.0.asc | gpg --dearmor -o /usr/share/keyrings/mongodb-server-7.0.gpg \
+  && echo "deb [ arch=amd64,arm64 signed-by=/usr/share/keyrings/mongodb-server-7.0.gpg ] https://repo.mongodb.org/apt/ubuntu jammy/mongodb-org/7.0 multiverse" | tee /etc/apt/sources.list.d/mongodb-org-7.0.list \
   && echo "deb http://apt.postgresql.org/pub/repos/apt $(grep CODENAME /etc/lsb-release | cut -d= -f2)-pgdg main" | tee /etc/apt/sources.list.d/pgdg.list \
   && curl --silent --show-error --location https://www.postgresql.org/media/keys/ACCC4CF8.asc | apt-key add - \
   && apt update \
diff --git a/deploy/docker/fs/opt/appsmith/entrypoint.sh b/deploy/docker/fs/opt/appsmith/entrypoint.sh
index ed569fd28212..e774846e06d1 100644
--- a/deploy/docker/fs/opt/appsmith/entrypoint.sh
+++ b/deploy/docker/fs/opt/appsmith/entrypoint.sh
@@ -296,6 +296,11 @@ init_replica_set() {
     sleep 10
     mongosh "$APPSMITH_DB_URL" --eval 'rs.initiate()'
     mongod --dbpath "$MONGO_DB_PATH" --shutdown || true
+    # Seed the FCV marker so the pre-flight compatibility check can fast-path on the
+    # next container boot. A fresh MongoDB 7.0 install defaults featureCompatibilityVersion
+    # to 7.0; mongodb-fixer will refresh this with the authoritative value shortly after
+    # supervisord starts mongod. See ensure_mongodb_fcv_compatible below.
+    ( printf '%s\n' "7.0" > "$MONGO_DB_PATH/.appsmith-fcv.tmp" && mv -f "$MONGO_DB_PATH/.appsmith-fcv.tmp" "$MONGO_DB_PATH/.appsmith-fcv" ) || tlog "warning: failed to write initial FCV marker"
   fi
 
   if [[ $isUriLocal -gt 0 ]]; then
@@ -313,6 +318,83 @@ init_replica_set() {
   fi
 }
 
+# Pre-flight check for embedded MongoDB 7.0 upgrades.
+#
+# MongoDB 7.0 refuses to start on data whose featureCompatibilityVersion (FCV)
+# is below 6.0. Without a check up front, supervisord would retry mongod a few
+# times and give up, leaving the container in a confusing degraded state with
+# no clear error for the operator.
+#
+# Strategy:
+#   - Fast path (common): a marker file ($MONGO_DB_PATH/.appsmith-fcv) maintained
+#     by mongodb-fixer.sh on every successful boot records the current FCV. If
+#     it's present and >= 6.0, we proceed with zero overhead.
+#   - Hard fail: marker says FCV < 6.0 → print actionable error and exit.
+#   - Transitional (rare): marker missing but data exists (e.g., first boot on
+#     this release after upgrading from an older Appsmith that predates the
+#     marker). Do a one-time mongod --fork to probe compatibility. If it starts,
+#     proceed; the fixer will write the marker after supervisord brings mongod
+#     up for real. If it fails, print the same actionable error and exit.
+ensure_mongodb_fcv_compatible() {
+  # Only applies to the embedded (local) MongoDB.
+  if [[ $isUriLocal -ne 0 ]]; then
+    return
+  fi
+
+  local marker="$MONGO_DB_PATH/.appsmith-fcv"
+
+  # Fresh install / no data on disk — nothing to check.
+  if [[ ! -e "$MONGO_DB_PATH/WiredTiger" ]]; then
+    return
+  fi
+
+  if [[ -f "$marker" ]]; then
+    local marker_fcv
+    marker_fcv="$(tr -d '[:space:]' < "$marker" 2>/dev/null || true)"
+    if [[ "$marker_fcv" =~ ^[0-9]+\.[0-9]+$ ]] && awk -v v="$marker_fcv" 'BEGIN {exit !(v+0 >= 6.0)}'; then
+      tlog "MongoDB FCV marker ok (featureCompatibilityVersion=$marker_fcv); skipping pre-flight check"
+      return
+    fi
+    tlog "====================================================================================================" >&2
+    tlog "==" >&2
+    tlog "== ERROR: Embedded MongoDB has been upgraded to 7.0, but the existing data is at featureCompatibilityVersion '${marker_fcv:-unknown}', which is below the required 6.0 minimum." >&2
+    tlog "== To upgrade safely:" >&2
+    tlog "==   1. Roll back to the previous Appsmith release (the last one shipped with MongoDB 6.x)" >&2
+    tlog "==   2. Let the container start fully — it will raise the compatibility version to 6.0 automatically" >&2
+    tlog "==   3. Shut down, then upgrade to this release" >&2
+    tlog "==" >&2
+    tlog "====================================================================================================" >&2
+    exit 1
+  fi
+
+  # Marker missing, but data exists — one-time pre-flight probe.
+  tlog "No MongoDB FCV marker found on existing data; running one-time compatibility probe"
+  local probe_log="$TMP/mongo-fcv-probe.log"
+  : > "$probe_log"
+  if mongod --fork --port 27017 --dbpath "$MONGO_DB_PATH" --logpath "$probe_log" --bind_ip localhost >/dev/null 2>&1; then
+    mongod --dbpath "$MONGO_DB_PATH" --shutdown >/dev/null 2>&1 || true
+    tlog "Pre-flight probe succeeded; mongodb-fixer will write the FCV marker after supervisord starts mongod"
+    return
+  fi
+
+  local probe_err
+  probe_err="$(grep -Ei 'featurecompatibilityversion|upgrade|downgrade' "$probe_log" 2>/dev/null | tail -n 1 || true)"
+  tlog "====================================================================================================" >&2
+  tlog "==" >&2
+  tlog "== ERROR: Embedded MongoDB 7.0 failed to start on the existing data. The most common cause is that the data is at featureCompatibilityVersion below the required 6.0 minimum." >&2
+  if [[ -n "$probe_err" ]]; then
+    tlog "== mongod log: $probe_err" >&2
+  fi
+  tlog "== To upgrade safely:" >&2
+  tlog "==   1. Roll back to the previous Appsmith release (the last one shipped with MongoDB 6.x)" >&2
+  tlog "==   2. Let the container start fully — it will raise the compatibility version to 6.0 automatically" >&2
+  tlog "==   3. Shut down, then upgrade to this release" >&2
+  tlog "==" >&2
+  tlog "== Full mongod log: $probe_log" >&2
+  tlog "====================================================================================================" >&2
+  exit 1
+}
+
 use-mongodb-key() {
   # We copy the MongoDB key file to `$MONGODB_TMP_KEY_PATH`, so that we can reliably set its permissions to 600.
   # Why? When the host machine of this Docker container is Windows, file permissions cannot be set on files in volumes.
@@ -602,6 +684,7 @@ if [[ -z "${DYNO}" ]]; then
     tlog "Initializing MongoDB"
     init_mongodb
     init_replica_set
+    ensure_mongodb_fcv_compatible
   fi
 else
   # These functions are used to limit heap size for Backend process when deployed on Heroku
diff --git a/deploy/docker/fs/opt/appsmith/mongodb-fixer.sh b/deploy/docker/fs/opt/appsmith/mongodb-fixer.sh
index a08d0be98e4c..e3f7cf6dc862 100644
--- a/deploy/docker/fs/opt/appsmith/mongodb-fixer.sh
+++ b/deploy/docker/fs/opt/appsmith/mongodb-fixer.sh
@@ -3,6 +3,22 @@
 set -o errexit
 set -o nounset
 
+# Path to the FCV marker file in the Mongo data directory. Written here after we
+# confirm the current featureCompatibilityVersion; read by entrypoint.sh on
+# subsequent boots to fast-path the pre-flight compatibility check. See
+# entrypoint.sh::ensure_mongodb_fcv_compatible.
+MONGO_FCV_MARKER="/appsmith-stacks/data/mongodb/.appsmith-fcv"
+
+write_fcv_marker() {
+  local version="$1"
+  local tmp="${MONGO_FCV_MARKER}.tmp"
+  if ! printf '%s\n' "$version" > "$tmp" 2>/dev/null; then
+    tlog "warning: failed to write FCV marker temp file"
+    return 0
+  fi
+  mv -f "$tmp" "$MONGO_FCV_MARKER" 2>/dev/null || tlog "warning: failed to move FCV marker into place"
+}
+
 {
 
 while [[ ! -S "$TMP/supervisor.sock" ]]; do
@@ -16,11 +32,28 @@ done
 tlog "MongoDB is RUNNING"
 
 for _ in {1..60}; do
-  if mongosh --quiet "$APPSMITH_DB_URL" --eval '
-    parseFloat(db.adminCommand({getParameter: 1, featureCompatibilityVersion: 1}).featureCompatibilityVersion.version) < 6 &&
-      db.adminCommand({setFeatureCompatibilityVersion: "6.0"})
-  '; then
-    tlog "MongoDB version set to 6.0"
+  # On each attempt: read the current FCV, raise it to 6.0 if it is below 6.0,
+  # and print the resulting FCV as the last line of output so the shell can
+  # capture it for the marker file.
+  #
+  # We deliberately do NOT raise FCV to 7.0 — keeping it at 6.0 preserves the
+  # ability to roll back to a 6.x Appsmith release if something goes wrong.
+  # The raise-to-6.0 branch is not expected to fire post-upgrade (MongoDB 7.0
+  # won't start on data with FCV below 6.0 — the entrypoint pre-flight check
+  # catches that). It's kept as a safety net for edge cases.
+  #
+  # `setFeatureCompatibilityVersion` requires `confirm: true` as of MongoDB 7.0.
+  if fcv="$(mongosh --quiet "$APPSMITH_DB_URL" --eval '
+    const current = db.adminCommand({getParameter: 1, featureCompatibilityVersion: 1}).featureCompatibilityVersion.version;
+    if (parseFloat(current) < 6) {
+      db.adminCommand({setFeatureCompatibilityVersion: "6.0", confirm: true});
+      print("6.0");
+    } else {
+      print(current);
+    }
+  ' 2>/dev/null | tail -n 1)" && [[ "$fcv" =~ ^[0-9]+\.[0-9]+$ ]]; then
+    tlog "MongoDB featureCompatibilityVersion: $fcv"
+    write_fcv_marker "$fcv"
     break
   fi
   sleep 1

From dd2d5baec2d84601f28eded11ffd72d25219adfc Mon Sep 17 00:00:00 2001
From: Wyatt Walter <wyattwalter@gmail.com>
Date: Thu, 16 Apr 2026 10:52:08 -0500
Subject: [PATCH 02/11] chore(mongo): reference v1.99 as the last 6.x release
 in FCV error messages

---
 deploy/docker/fs/opt/appsmith/entrypoint.sh | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/deploy/docker/fs/opt/appsmith/entrypoint.sh b/deploy/docker/fs/opt/appsmith/entrypoint.sh
index e774846e06d1..6b51be8a501f 100644
--- a/deploy/docker/fs/opt/appsmith/entrypoint.sh
+++ b/deploy/docker/fs/opt/appsmith/entrypoint.sh
@@ -359,7 +359,7 @@ ensure_mongodb_fcv_compatible() {
     tlog "==" >&2
     tlog "== ERROR: Embedded MongoDB has been upgraded to 7.0, but the existing data is at featureCompatibilityVersion '${marker_fcv:-unknown}', which is below the required 6.0 minimum." >&2
     tlog "== To upgrade safely:" >&2
-    tlog "==   1. Roll back to the previous Appsmith release (the last one shipped with MongoDB 6.x)" >&2
+    tlog "==   1. Roll back to Appsmith v1.99 (the last release shipped with MongoDB 6.x)" >&2
     tlog "==   2. Let the container start fully — it will raise the compatibility version to 6.0 automatically" >&2
     tlog "==   3. Shut down, then upgrade to this release" >&2
     tlog "==" >&2
@@ -386,7 +386,7 @@ ensure_mongodb_fcv_compatible() {
     tlog "== mongod log: $probe_err" >&2
   fi
   tlog "== To upgrade safely:" >&2
-  tlog "==   1. Roll back to the previous Appsmith release (the last one shipped with MongoDB 6.x)" >&2
+  tlog "==   1. Roll back to Appsmith v1.99 (the last release shipped with MongoDB 6.x)" >&2
   tlog "==   2. Let the container start fully — it will raise the compatibility version to 6.0 automatically" >&2
   tlog "==   3. Shut down, then upgrade to this release" >&2
   tlog "==" >&2

From f73a3e06ca3b30895cb584c01149e84a9aa9bb8e Mon Sep 17 00:00:00 2001
From: Wyatt Walter <wyattwalter@gmail.com>
Date: Thu, 16 Apr 2026 11:04:57 -0500
Subject: [PATCH 03/11] chore(mongo): drop fresh-init marker seed in entrypoint
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The entrypoint should only read the FCV marker, never write it — that
responsibility belongs solely to mongodb-fixer.sh. Fresh installs pay a
cheap one-time pre-flight probe on the first boot; the fixer writes the
marker on the same boot once supervisord brings mongod up, so subsequent
boots take the fast path.
---
 deploy/docker/fs/opt/appsmith/entrypoint.sh | 5 -----
 1 file changed, 5 deletions(-)

diff --git a/deploy/docker/fs/opt/appsmith/entrypoint.sh b/deploy/docker/fs/opt/appsmith/entrypoint.sh
index 6b51be8a501f..b4515bf982ea 100644
--- a/deploy/docker/fs/opt/appsmith/entrypoint.sh
+++ b/deploy/docker/fs/opt/appsmith/entrypoint.sh
@@ -296,11 +296,6 @@ init_replica_set() {
     sleep 10
     mongosh "$APPSMITH_DB_URL" --eval 'rs.initiate()'
     mongod --dbpath "$MONGO_DB_PATH" --shutdown || true
-    # Seed the FCV marker so the pre-flight compatibility check can fast-path on the
-    # next container boot. A fresh MongoDB 7.0 install defaults featureCompatibilityVersion
-    # to 7.0; mongodb-fixer will refresh this with the authoritative value shortly after
-    # supervisord starts mongod. See ensure_mongodb_fcv_compatible below.
-    ( printf '%s\n' "7.0" > "$MONGO_DB_PATH/.appsmith-fcv.tmp" && mv -f "$MONGO_DB_PATH/.appsmith-fcv.tmp" "$MONGO_DB_PATH/.appsmith-fcv" ) || tlog "warning: failed to write initial FCV marker"
   fi
 
   if [[ $isUriLocal -gt 0 ]]; then

From a6a96df5d681d122f67e50dd8d0c811467f4f4d3 Mon Sep 17 00:00:00 2001
From: Wyatt Walter <wyattwalter@gmail.com>
Date: Thu, 16 Apr 2026 11:27:33 -0500
Subject: [PATCH 04/11] chore(mongo): skip FCV check on fresh install and drop
 unreachable branches

Three related simplifications:

- entrypoint: gate ensure_mongodb_fcv_compatible on shouldPerformInitdb=0
  at the call site. A fresh install has no data to be incompatible with.

- entrypoint: delete the "marker says FCV < 6.0" hard-fail branch. The
  fixer writes the marker only after observing current FCV on a running
  mongod 7, so marker presence implies a compatible FCV. The branch was
  unreachable.

- mongodb-fixer: drop the raise-to-6.0 FCV branch. The entrypoint's
  pre-flight probe ensures mongod won't start on FCV < 6.0, so the fixer
  never sees that state. The raise-FCV scaffolding can come back when the
  MongoDB 8 upgrade needs to bump FCV to 7.0.
---
 deploy/docker/fs/opt/appsmith/entrypoint.sh   | 58 ++++++-------------
 .../docker/fs/opt/appsmith/mongodb-fixer.sh   | 23 ++------
 2 files changed, 23 insertions(+), 58 deletions(-)

diff --git a/deploy/docker/fs/opt/appsmith/entrypoint.sh b/deploy/docker/fs/opt/appsmith/entrypoint.sh
index b4515bf982ea..d1ed6a4b6d7b 100644
--- a/deploy/docker/fs/opt/appsmith/entrypoint.sh
+++ b/deploy/docker/fs/opt/appsmith/entrypoint.sh
@@ -313,56 +313,32 @@ init_replica_set() {
   fi
 }
 
-# Pre-flight check for embedded MongoDB 7.0 upgrades.
+# Pre-flight check for embedded MongoDB 7.0 upgrades on existing data.
 #
 # MongoDB 7.0 refuses to start on data whose featureCompatibilityVersion (FCV)
 # is below 6.0. Without a check up front, supervisord would retry mongod a few
 # times and give up, leaving the container in a confusing degraded state with
 # no clear error for the operator.
 #
-# Strategy:
-#   - Fast path (common): a marker file ($MONGO_DB_PATH/.appsmith-fcv) maintained
-#     by mongodb-fixer.sh on every successful boot records the current FCV. If
-#     it's present and >= 6.0, we proceed with zero overhead.
-#   - Hard fail: marker says FCV < 6.0 → print actionable error and exit.
-#   - Transitional (rare): marker missing but data exists (e.g., first boot on
-#     this release after upgrading from an older Appsmith that predates the
-#     marker). Do a one-time mongod --fork to probe compatibility. If it starts,
-#     proceed; the fixer will write the marker after supervisord brings mongod
-#     up for real. If it fails, print the same actionable error and exit.
+# Fast path (common): marker file ($MONGO_DB_PATH/.appsmith-fcv) is written by
+# mongodb-fixer.sh only after it confirms the current FCV on a running mongod,
+# so its presence implies a compatible FCV. Skip the probe with zero overhead.
+#
+# Transitional (rare): on first boot of this release after upgrading from an
+# older Appsmith that predates the marker, the marker is missing. Do a one-time
+# mongod --fork probe to verify the data is compatible. If it starts, proceed;
+# the fixer will write the marker after supervisord brings mongod up for real.
+# If it fails, print an actionable error and exit.
+#
+# Caller is responsible for invoking this only when there's existing local-Mongo
+# data to check (i.e. not a fresh install, not an external mongo).
 ensure_mongodb_fcv_compatible() {
-  # Only applies to the embedded (local) MongoDB.
-  if [[ $isUriLocal -ne 0 ]]; then
-    return
-  fi
-
   local marker="$MONGO_DB_PATH/.appsmith-fcv"
-
-  # Fresh install / no data on disk — nothing to check.
-  if [[ ! -e "$MONGO_DB_PATH/WiredTiger" ]]; then
-    return
-  fi
-
   if [[ -f "$marker" ]]; then
-    local marker_fcv
-    marker_fcv="$(tr -d '[:space:]' < "$marker" 2>/dev/null || true)"
-    if [[ "$marker_fcv" =~ ^[0-9]+\.[0-9]+$ ]] && awk -v v="$marker_fcv" 'BEGIN {exit !(v+0 >= 6.0)}'; then
-      tlog "MongoDB FCV marker ok (featureCompatibilityVersion=$marker_fcv); skipping pre-flight check"
-      return
-    fi
-    tlog "====================================================================================================" >&2
-    tlog "==" >&2
-    tlog "== ERROR: Embedded MongoDB has been upgraded to 7.0, but the existing data is at featureCompatibilityVersion '${marker_fcv:-unknown}', which is below the required 6.0 minimum." >&2
-    tlog "== To upgrade safely:" >&2
-    tlog "==   1. Roll back to Appsmith v1.99 (the last release shipped with MongoDB 6.x)" >&2
-    tlog "==   2. Let the container start fully — it will raise the compatibility version to 6.0 automatically" >&2
-    tlog "==   3. Shut down, then upgrade to this release" >&2
-    tlog "==" >&2
-    tlog "====================================================================================================" >&2
-    exit 1
+    tlog "MongoDB FCV marker present; skipping pre-flight check"
+    return
   fi
 
-  # Marker missing, but data exists — one-time pre-flight probe.
   tlog "No MongoDB FCV marker found on existing data; running one-time compatibility probe"
   local probe_log="$TMP/mongo-fcv-probe.log"
   : > "$probe_log"
@@ -679,7 +655,9 @@ if [[ -z "${DYNO}" ]]; then
     tlog "Initializing MongoDB"
     init_mongodb
     init_replica_set
-    ensure_mongodb_fcv_compatible
+    if [[ $shouldPerformInitdb -eq 0 && $isUriLocal -eq 0 ]]; then
+      ensure_mongodb_fcv_compatible
+    fi
   fi
 else
   # These functions are used to limit heap size for Backend process when deployed on Heroku
diff --git a/deploy/docker/fs/opt/appsmith/mongodb-fixer.sh b/deploy/docker/fs/opt/appsmith/mongodb-fixer.sh
index e3f7cf6dc862..bbce22bd02f9 100644
--- a/deploy/docker/fs/opt/appsmith/mongodb-fixer.sh
+++ b/deploy/docker/fs/opt/appsmith/mongodb-fixer.sh
@@ -32,25 +32,12 @@ done
 tlog "MongoDB is RUNNING"
 
 for _ in {1..60}; do
-  # On each attempt: read the current FCV, raise it to 6.0 if it is below 6.0,
-  # and print the resulting FCV as the last line of output so the shell can
-  # capture it for the marker file.
-  #
-  # We deliberately do NOT raise FCV to 7.0 — keeping it at 6.0 preserves the
-  # ability to roll back to a 6.x Appsmith release if something goes wrong.
-  # The raise-to-6.0 branch is not expected to fire post-upgrade (MongoDB 7.0
-  # won't start on data with FCV below 6.0 — the entrypoint pre-flight check
-  # catches that). It's kept as a safety net for edge cases.
-  #
-  # `setFeatureCompatibilityVersion` requires `confirm: true` as of MongoDB 7.0.
+  # Read the current FCV and write it to the marker file. We deliberately do
+  # NOT raise FCV to 7.0 — keeping it at 6.0 preserves the ability to roll back
+  # to a 6.x Appsmith release if something goes wrong. (The entrypoint's
+  # pre-flight check guarantees mongod won't reach this point with FCV < 6.0.)
   if fcv="$(mongosh --quiet "$APPSMITH_DB_URL" --eval '
-    const current = db.adminCommand({getParameter: 1, featureCompatibilityVersion: 1}).featureCompatibilityVersion.version;
-    if (parseFloat(current) < 6) {
-      db.adminCommand({setFeatureCompatibilityVersion: "6.0", confirm: true});
-      print("6.0");
-    } else {
-      print(current);
-    }
+    print(db.adminCommand({getParameter: 1, featureCompatibilityVersion: 1}).featureCompatibilityVersion.version);
   ' 2>/dev/null | tail -n 1)" && [[ "$fcv" =~ ^[0-9]+\.[0-9]+$ ]]; then
     tlog "MongoDB featureCompatibilityVersion: $fcv"
     write_fcv_marker "$fcv"

From 2f95cfebe952784b870cadbdc14785019f46dfe9 Mon Sep 17 00:00:00 2001
From: Wyatt Walter <wyattwalter@gmail.com>
Date: Thu, 16 Apr 2026 12:26:56 -0500
Subject: [PATCH 05/11] chore(mongo): move FCV pre-flight gate inside
 ensure_mongodb_fcv_compatible

Matches the pattern used by sibling mongo-bootstrap logic in the same
file (e.g., init_replica_set gates its fresh-init branch on
shouldPerformInitdb/isUriLocal internally). Keeps "when does this run"
in one place instead of splitting it between the function body and the
main section.

No behavior change.
---
 deploy/docker/fs/opt/appsmith/entrypoint.sh | 13 +++++++------
 1 file changed, 7 insertions(+), 6 deletions(-)

diff --git a/deploy/docker/fs/opt/appsmith/entrypoint.sh b/deploy/docker/fs/opt/appsmith/entrypoint.sh
index d1ed6a4b6d7b..574fb6fe740d 100644
--- a/deploy/docker/fs/opt/appsmith/entrypoint.sh
+++ b/deploy/docker/fs/opt/appsmith/entrypoint.sh
@@ -329,10 +329,13 @@ init_replica_set() {
 # mongod --fork probe to verify the data is compatible. If it starts, proceed;
 # the fixer will write the marker after supervisord brings mongod up for real.
 # If it fails, print an actionable error and exit.
-#
-# Caller is responsible for invoking this only when there's existing local-Mongo
-# data to check (i.e. not a fresh install, not an external mongo).
 ensure_mongodb_fcv_compatible() {
+  # Only applies to existing local-Mongo data — fresh installs have nothing to
+  # check, and external Mongo is out of our control.
+  if [[ $shouldPerformInitdb -ne 0 || $isUriLocal -ne 0 ]]; then
+    return
+  fi
+
   local marker="$MONGO_DB_PATH/.appsmith-fcv"
   if [[ -f "$marker" ]]; then
     tlog "MongoDB FCV marker present; skipping pre-flight check"
@@ -655,9 +658,7 @@ if [[ -z "${DYNO}" ]]; then
     tlog "Initializing MongoDB"
     init_mongodb
     init_replica_set
-    if [[ $shouldPerformInitdb -eq 0 && $isUriLocal -eq 0 ]]; then
-      ensure_mongodb_fcv_compatible
-    fi
+    ensure_mongodb_fcv_compatible
   fi
 else
   # These functions are used to limit heap size for Backend process when deployed on Heroku

From 912ad5d25967936b6e4fc724ff6c14cbe968f060 Mon Sep 17 00:00:00 2001
From: Wyatt Walter <wyattwalter@gmail.com>
Date: Thu, 16 Apr 2026 12:42:06 -0500
Subject: [PATCH 06/11] chore(mongo): polish FCV pre-flight comments, match
 gate style, harden probe shutdown
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Use -gt 0 for the gate check to match the style used by init_replica_set
  elsewhere in this file.
- Drop the "rare" framing on the no-marker branch — every upgraded instance
  takes this path exactly once, so it's the expected first-boot flow.
- "operator" -> "administrator" to avoid collision with the Kubernetes
  operator pattern.
- Abort explicitly if the probe's --shutdown fails instead of swallowing
  the error with || true. Probe mongod and supervisord's mongod share port
  27017 and the data lock, so a silent shutdown failure would make
  supervisord's mongod fail to start — exactly the "confusing degraded
  state" this pre-flight exists to prevent.
---
 deploy/docker/fs/opt/appsmith/entrypoint.sh | 20 +++++++++++---------
 1 file changed, 11 insertions(+), 9 deletions(-)

diff --git a/deploy/docker/fs/opt/appsmith/entrypoint.sh b/deploy/docker/fs/opt/appsmith/entrypoint.sh
index 574fb6fe740d..4b46ec6e52fc 100644
--- a/deploy/docker/fs/opt/appsmith/entrypoint.sh
+++ b/deploy/docker/fs/opt/appsmith/entrypoint.sh
@@ -318,21 +318,20 @@ init_replica_set() {
 # MongoDB 7.0 refuses to start on data whose featureCompatibilityVersion (FCV)
 # is below 6.0. Without a check up front, supervisord would retry mongod a few
 # times and give up, leaving the container in a confusing degraded state with
-# no clear error for the operator.
+# no clear error for the administrator.
 #
-# Fast path (common): marker file ($MONGO_DB_PATH/.appsmith-fcv) is written by
+# Fast path: marker file ($MONGO_DB_PATH/.appsmith-fcv) is written by
 # mongodb-fixer.sh only after it confirms the current FCV on a running mongod,
 # so its presence implies a compatible FCV. Skip the probe with zero overhead.
 #
-# Transitional (rare): on first boot of this release after upgrading from an
-# older Appsmith that predates the marker, the marker is missing. Do a one-time
-# mongod --fork probe to verify the data is compatible. If it starts, proceed;
-# the fixer will write the marker after supervisord brings mongod up for real.
-# If it fails, print an actionable error and exit.
+# First boot after upgrade: no marker yet. Do a one-time mongod --fork probe
+# to verify the data is compatible. If it starts, proceed; the fixer will
+# write the marker after supervisord brings mongod up for real. If it fails,
+# print an actionable error and exit.
 ensure_mongodb_fcv_compatible() {
   # Only applies to existing local-Mongo data — fresh installs have nothing to
   # check, and external Mongo is out of our control.
-  if [[ $shouldPerformInitdb -ne 0 || $isUriLocal -ne 0 ]]; then
+  if [[ $shouldPerformInitdb -gt 0 || $isUriLocal -gt 0 ]]; then
     return
   fi
 
@@ -346,7 +345,10 @@ ensure_mongodb_fcv_compatible() {
   local probe_log="$TMP/mongo-fcv-probe.log"
   : > "$probe_log"
   if mongod --fork --port 27017 --dbpath "$MONGO_DB_PATH" --logpath "$probe_log" --bind_ip localhost >/dev/null 2>&1; then
-    mongod --dbpath "$MONGO_DB_PATH" --shutdown >/dev/null 2>&1 || true
+    if ! mongod --dbpath "$MONGO_DB_PATH" --shutdown >/dev/null 2>&1; then
+      tlog "ERROR: Pre-flight mongod probe started but shutdown failed. The probe mongod may still hold port 27017 or the data lock, which would prevent supervisord from starting mongod. Aborting. See $probe_log for details." >&2
+      exit 1
+    fi
     tlog "Pre-flight probe succeeded; mongodb-fixer will write the FCV marker after supervisord starts mongod"
     return
   fi

From 94805f1dab67d7487d9bcb51d8fd2e89f0bc103b Mon Sep 17 00:00:00 2001
From: Wyatt Walter <wyattwalter@gmail.com>
Date: Thu, 16 Apr 2026 16:10:47 -0500
Subject: [PATCH 07/11] chore(mongo): reframe FCV marker as release-level FCV
 floor
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The old marker (.appsmith-fcv) recorded "the observed FCV at the moment
mongod came up." That was misleading in two ways:
- On fresh installs, mongod 7.0 sets FCV to 7.0 by default, so the file
  read "7.0" even though this release commits to preserving 6.0 (for
  downgrade safety).
- Nothing was actually enforcing the written value — FCV can drift via
  setFeatureCompatibilityVersion, and the marker never updates.

Reframed: the marker now records the *minimum FCV this Appsmith release
commits to preserve* — a release-level contract, constant across all
installs of this release. Value is "6.0" until MongoDB 8 forces a bump
to 7.0, at which point the constant and the corresponding setFCV call
both change together. Useful for future releases deciding "can this
data still be upgraded?"

Changes:
- File renamed: .appsmith-fcv -> .appsmith-mongo-fcv-min.
- Fixer writes the FCV_MIN constant instead of querying mongod. The
  mongosh retry loop that did the FCV query is gone — the marker's
  value no longer depends on a live reading.
- The "wait for mongod RUNNING" supervisorctl loop in the fixer was
  previously semantically inverted (`while ... RUNNING; do sleep ...`
  looped WHILE running, exited on not-running). It happened to work
  because the mongosh retry loop after it did the real wait. With the
  mongosh loop removed, the supervisorctl loop becomes load-bearing, so
  fix it with the missing `!`.
- entrypoint.sh's pre-flight check still only reads presence of the
  marker; only the path and the header comment change.
---
 deploy/docker/fs/opt/appsmith/entrypoint.sh   | 11 +++--
 .../docker/fs/opt/appsmith/mongodb-fixer.sh   | 45 +++++++++----------
 2 files changed, 29 insertions(+), 27 deletions(-)

diff --git a/deploy/docker/fs/opt/appsmith/entrypoint.sh b/deploy/docker/fs/opt/appsmith/entrypoint.sh
index 4b46ec6e52fc..3ac6272bbca1 100644
--- a/deploy/docker/fs/opt/appsmith/entrypoint.sh
+++ b/deploy/docker/fs/opt/appsmith/entrypoint.sh
@@ -320,9 +320,12 @@ init_replica_set() {
 # times and give up, leaving the container in a confusing degraded state with
 # no clear error for the administrator.
 #
-# Fast path: marker file ($MONGO_DB_PATH/.appsmith-fcv) is written by
-# mongodb-fixer.sh only after it confirms the current FCV on a running mongod,
-# so its presence implies a compatible FCV. Skip the probe with zero overhead.
+# Fast path: marker file ($MONGO_DB_PATH/.appsmith-mongo-fcv-min) is written by
+# mongodb-fixer.sh only after mongod is confirmed running under this Appsmith
+# release. Its presence proves this release has already booted successfully on
+# this data, so the probe can be skipped with zero overhead. Contents record
+# the FCV floor this release commits to, for future upgrade decisions; they
+# aren't consulted here.
 #
 # First boot after upgrade: no marker yet. Do a one-time mongod --fork probe
 # to verify the data is compatible. If it starts, proceed; the fixer will
@@ -335,7 +338,7 @@ ensure_mongodb_fcv_compatible() {
     return
   fi
 
-  local marker="$MONGO_DB_PATH/.appsmith-fcv"
+  local marker="$MONGO_DB_PATH/.appsmith-mongo-fcv-min"
   if [[ -f "$marker" ]]; then
     tlog "MongoDB FCV marker present; skipping pre-flight check"
     return
diff --git a/deploy/docker/fs/opt/appsmith/mongodb-fixer.sh b/deploy/docker/fs/opt/appsmith/mongodb-fixer.sh
index bbce22bd02f9..759e7447a829 100644
--- a/deploy/docker/fs/opt/appsmith/mongodb-fixer.sh
+++ b/deploy/docker/fs/opt/appsmith/mongodb-fixer.sh
@@ -3,20 +3,32 @@
 set -o errexit
 set -o nounset
 
-# Path to the FCV marker file in the Mongo data directory. Written here after we
-# confirm the current featureCompatibilityVersion; read by entrypoint.sh on
+# Marker file recording the minimum MongoDB featureCompatibilityVersion that
+# this Appsmith release commits to preserve. Written once mongod is confirmed
+# RUNNING under this release; read (presence only) by entrypoint.sh on
 # subsequent boots to fast-path the pre-flight compatibility check. See
 # entrypoint.sh::ensure_mongodb_fcv_compatible.
-MONGO_FCV_MARKER="/appsmith-stacks/data/mongodb/.appsmith-fcv"
+#
+# The marker value is a release-level contract, not a live reading of mongod's
+# current FCV. Use `mongosh` if you want the live value.
+MONGO_FCV_MIN_MARKER="/appsmith-stacks/data/mongodb/.appsmith-mongo-fcv-min"
+
+# Minimum FCV this Appsmith release commits to preserve. We deliberately do
+# NOT raise FCV to 7.0 — keeping it at 6.0 preserves the ability to roll back
+# to a 6.x Appsmith release if something goes wrong. When MongoDB 8 arrives
+# and needs FCV bumped to 7.0, change this constant and add a
+# `setFeatureCompatibilityVersion("7.0", {confirm: true})` call before writing
+# the marker.
+FCV_MIN="6.0"
 
 write_fcv_marker() {
-  local version="$1"
-  local tmp="${MONGO_FCV_MARKER}.tmp"
-  if ! printf '%s\n' "$version" > "$tmp" 2>/dev/null; then
+  local value="$1"
+  local tmp="${MONGO_FCV_MIN_MARKER}.tmp"
+  if ! printf '%s\n' "$value" > "$tmp" 2>/dev/null; then
     tlog "warning: failed to write FCV marker temp file"
     return 0
   fi
-  mv -f "$tmp" "$MONGO_FCV_MARKER" 2>/dev/null || tlog "warning: failed to move FCV marker into place"
+  mv -f "$tmp" "$MONGO_FCV_MIN_MARKER" 2>/dev/null || tlog "warning: failed to move FCV marker into place"
 }
 
 {
@@ -26,26 +38,13 @@ while [[ ! -S "$TMP/supervisor.sock" ]]; do
 done
 tlog "supervisor.sock found"
 
-while supervisorctl status mongodb | grep -q RUNNING; do
+while ! supervisorctl status mongodb | grep -q RUNNING; do
   sleep 1
 done
 tlog "MongoDB is RUNNING"
 
-for _ in {1..60}; do
-  # Read the current FCV and write it to the marker file. We deliberately do
-  # NOT raise FCV to 7.0 — keeping it at 6.0 preserves the ability to roll back
-  # to a 6.x Appsmith release if something goes wrong. (The entrypoint's
-  # pre-flight check guarantees mongod won't reach this point with FCV < 6.0.)
-  if fcv="$(mongosh --quiet "$APPSMITH_DB_URL" --eval '
-    print(db.adminCommand({getParameter: 1, featureCompatibilityVersion: 1}).featureCompatibilityVersion.version);
-  ' 2>/dev/null | tail -n 1)" && [[ "$fcv" =~ ^[0-9]+\.[0-9]+$ ]]; then
-    tlog "MongoDB featureCompatibilityVersion: $fcv"
-    write_fcv_marker "$fcv"
-    break
-  fi
-  sleep 1
-done
-
+tlog "Recording committed FCV minimum: $FCV_MIN"
+write_fcv_marker "$FCV_MIN"
 tlog Done
 
 } | sed -u 's/^/mongodb-fixer: /'

From f4b16d704ede0227bf475b8310b866a03672cafe Mon Sep 17 00:00:00 2001
From: Wyatt Walter <wyattwalter@gmail.com>
Date: Mon, 4 May 2026 11:09:29 -0500
Subject: [PATCH 08/11] chore(mongo): persist FCV probe log to data dir,
 restore live FCV floor

Two PR-feedback fixes:

1. Move the pre-flight probe log from $TMP/mongo-fcv-probe.log to
   $MONGO_DB_PATH/fcv-probe.log so it survives container restarts.
   $TMP gets wiped, which left admins with no forensic trail when
   investigating why their container exited. The log now lives next
   to the MongoDB data and uses --logappend with a UTC timestamp
   header per probe run, so repeated upgrade attempts all stay on
   record.

2. Restore the active setFeatureCompatibilityVersion call in
   mongodb-fixer.sh, gated on FCV being below $FCV_MIN. In the
   steady state this is a no-op (the pre-flight probe already
   guarantees mongod won't start on data below the supported FCV),
   but keeping the call live makes the upgrade scaffolding
   self-documenting and reduces the next major-version bump to a
   constant change.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 deploy/docker/fs/opt/appsmith/entrypoint.sh   | 10 ++++---
 .../docker/fs/opt/appsmith/mongodb-fixer.sh   | 27 ++++++++++++++++---
 2 files changed, 30 insertions(+), 7 deletions(-)

diff --git a/deploy/docker/fs/opt/appsmith/entrypoint.sh b/deploy/docker/fs/opt/appsmith/entrypoint.sh
index 5d111058d471..768139c66198 100644
--- a/deploy/docker/fs/opt/appsmith/entrypoint.sh
+++ b/deploy/docker/fs/opt/appsmith/entrypoint.sh
@@ -366,9 +366,13 @@ ensure_mongodb_fcv_compatible() {
   fi
 
   tlog "No MongoDB FCV marker found on existing data; running one-time compatibility probe"
-  local probe_log="$TMP/mongo-fcv-probe.log"
-  : > "$probe_log"
-  if mongod --fork --port 27017 --dbpath "$MONGO_DB_PATH" --logpath "$probe_log" --bind_ip localhost >/dev/null 2>&1; then
+  # Persist the probe log inside the Mongo data directory so it survives container
+  # restarts. $TMP would be wiped, leaving no forensic trail when an admin comes
+  # back to investigate why their container exited. Append rather than truncate so
+  # repeated probe runs (e.g. multiple failed upgrade attempts) all stay on record.
+  local probe_log="$MONGO_DB_PATH/fcv-probe.log"
+  printf '\n===== Appsmith MongoDB FCV pre-flight probe @ %s =====\n' "$(date -u +%Y-%m-%dT%H:%M:%SZ)" >> "$probe_log" 2>/dev/null || true
+  if mongod --fork --port 27017 --dbpath "$MONGO_DB_PATH" --logpath "$probe_log" --logappend --bind_ip localhost >/dev/null 2>&1; then
     if ! mongod --dbpath "$MONGO_DB_PATH" --shutdown >/dev/null 2>&1; then
       tlog "ERROR: Pre-flight mongod probe started but shutdown failed. The probe mongod may still hold port 27017 or the data lock, which would prevent supervisord from starting mongod. Aborting. See $probe_log for details." >&2
       exit 1
diff --git a/deploy/docker/fs/opt/appsmith/mongodb-fixer.sh b/deploy/docker/fs/opt/appsmith/mongodb-fixer.sh
index 759e7447a829..e423edd75376 100644
--- a/deploy/docker/fs/opt/appsmith/mongodb-fixer.sh
+++ b/deploy/docker/fs/opt/appsmith/mongodb-fixer.sh
@@ -15,10 +15,9 @@ MONGO_FCV_MIN_MARKER="/appsmith-stacks/data/mongodb/.appsmith-mongo-fcv-min"
 
 # Minimum FCV this Appsmith release commits to preserve. We deliberately do
 # NOT raise FCV to 7.0 — keeping it at 6.0 preserves the ability to roll back
-# to a 6.x Appsmith release if something goes wrong. When MongoDB 8 arrives
-# and needs FCV bumped to 7.0, change this constant and add a
-# `setFeatureCompatibilityVersion("7.0", {confirm: true})` call before writing
-# the marker.
+# to a 6.x Appsmith release if something goes wrong. When MongoDB 8 arrives,
+# bump this constant to 7.0; the ensure_fcv_floor block below will handle the
+# `setFeatureCompatibilityVersion` call automatically.
 FCV_MIN="6.0"
 
 write_fcv_marker() {
@@ -43,6 +42,26 @@ while ! supervisorctl status mongodb | grep -q RUNNING; do
 done
 tlog "MongoDB is RUNNING"
 
+# Ensure FCV is at the floor this release commits to. In the steady state this
+# is a no-op — entrypoint.sh's pre-flight probe already guarantees mongod won't
+# come up on data below the supported FCV. The check is kept active so the
+# upgrade scaffolding is exercised and the next major-version bump is just a
+# constant change.
+tlog "Ensuring MongoDB featureCompatibilityVersion is at least $FCV_MIN"
+for _ in {1..60}; do
+  if mongosh --quiet "$APPSMITH_DB_URL" --eval '
+    const floor = '"$FCV_MIN"';
+    const current = parseFloat(db.adminCommand({getParameter: 1, featureCompatibilityVersion: 1}).featureCompatibilityVersion.version);
+    if (current < floor) {
+      db.adminCommand({setFeatureCompatibilityVersion: "'"$FCV_MIN"'", confirm: true});
+    }
+  '; then
+    tlog "MongoDB featureCompatibilityVersion floor of $FCV_MIN confirmed"
+    break
+  fi
+  sleep 1
+done
+
 tlog "Recording committed FCV minimum: $FCV_MIN"
 write_fcv_marker "$FCV_MIN"
 tlog Done

From 2455ab0dce79988bfd4bed97b3222520ec8782f0 Mon Sep 17 00:00:00 2001
From: Wyatt Walter <wyattwalter@gmail.com>
Date: Mon, 4 May 2026 14:40:57 -0500
Subject: [PATCH 09/11] chore(mongo): clarify FCV pre-flight error message
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

PR feedback — make the recovery instructions more actionable for
admins seeing this for the first time:

- Reassure up front that data has NOT been altered. The container
  exits before mongod starts, so on-disk files are untouched and no
  backup restore is needed. This was implicit before; now explicit.
- Frame each step as an Appsmith deployment action ("Alter your
  Appsmith deployment to use v1.99 ...") rather than a generic
  "roll back". Operators running Helm, ECS, k8s manifests, etc.
  recognize this as their own task immediately.
- Step 2 names "MongoDB compatibility version" explicitly so it's
  clear what's being changed under the hood.
- Add blank `==` separator lines around the steps so the recovery
  block stands out in a wall of stderr.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 deploy/docker/fs/opt/appsmith/entrypoint.sh | 10 +++++++---
 1 file changed, 7 insertions(+), 3 deletions(-)

diff --git a/deploy/docker/fs/opt/appsmith/entrypoint.sh b/deploy/docker/fs/opt/appsmith/entrypoint.sh
index 768139c66198..ff0833f10587 100644
--- a/deploy/docker/fs/opt/appsmith/entrypoint.sh
+++ b/deploy/docker/fs/opt/appsmith/entrypoint.sh
@@ -389,10 +389,14 @@ ensure_mongodb_fcv_compatible() {
   if [[ -n "$probe_err" ]]; then
     tlog "== mongod log: $probe_err" >&2
   fi
+  tlog "==" >&2
+  tlog "== Your data has NOT been altered. This container exited before MongoDB started, so the database files on disk are exactly as you left them. You do not need to restore from backup — follow the steps below to recover." >&2
+  tlog "==" >&2
   tlog "== To upgrade safely:" >&2
-  tlog "==   1. Roll back to Appsmith v1.99 (the last release shipped with MongoDB 6.x)" >&2
-  tlog "==   2. Let the container start fully — it will raise the compatibility version to 6.0 automatically" >&2
-  tlog "==   3. Shut down, then upgrade to this release" >&2
+  tlog "==" >&2
+  tlog "==   1. Alter your Appsmith deployment to use v1.99 (the latest release shipped with MongoDB 6.x)" >&2
+  tlog "==   2. Let the container start fully — it will raise the MongoDB compatibility version to 6.0 automatically" >&2
+  tlog "==   3. Shut down, then alter your Appsmith deployment to use this version again" >&2
   tlog "==" >&2
   tlog "== Full mongod log: $probe_log" >&2
   tlog "====================================================================================================" >&2

From 33dc825296b4f88f1dfc80d11483a32d656d9129 Mon Sep 17 00:00:00 2001
From: Wyatt Walter <wyattwalter@gmail.com>
Date: Tue, 5 May 2026 12:46:54 -0500
Subject: [PATCH 10/11] chore(mongo): expand FCV pre-flight error with version
 context
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Reframe the error block to convey the full upgrade story rather than
just the recovery steps. Feedback was that the previous wording
under-explained why this happens and over-promised on data safety.

Now covers:
- Appsmith 2.x ships MongoDB 7.x; FCV must be 6.0 or higher.
- 1.93–1.99 raise FCV to 6.0 automatically; only pre-1.66-only
  instances are at risk.
- This check applies only to embedded MongoDB. External MongoDB
  instances bypass it entirely.
- The failure happens before any Appsmith service comes online, so
  no Appsmith database migrations have been attempted — rolling back
  to a 1.x release is just an image version swap.

Drops the prior "your data has NOT been altered" line, which
overpromised: mongod 7.0 may have touched journal/lock files just
attempting to start. The accurate and more useful guarantee is that
Appsmith's own migrations haven't run, which is what's stated now.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 deploy/docker/fs/opt/appsmith/entrypoint.sh | 15 ++++++++++-----
 1 file changed, 10 insertions(+), 5 deletions(-)

diff --git a/deploy/docker/fs/opt/appsmith/entrypoint.sh b/deploy/docker/fs/opt/appsmith/entrypoint.sh
index ff0833f10587..d1ee89d122c5 100644
--- a/deploy/docker/fs/opt/appsmith/entrypoint.sh
+++ b/deploy/docker/fs/opt/appsmith/entrypoint.sh
@@ -390,13 +390,18 @@ ensure_mongodb_fcv_compatible() {
     tlog "== mongod log: $probe_err" >&2
   fi
   tlog "==" >&2
-  tlog "== Your data has NOT been altered. This container exited before MongoDB started, so the database files on disk are exactly as you left them. You do not need to restore from backup — follow the steps below to recover." >&2
+  tlog "== About this error:" >&2
+  tlog "==   Appsmith 2.x ships with MongoDB 7.x, which requires the database to be at featureCompatibilityVersion (FCV) 6.0 or higher. Appsmith releases 1.93 to 1.99 automatically raise FCV to 6.0 on boot, so any instance that has run one of those releases is fine. Instances that have only ever run Appsmith older than 1.66 may still be at FCV 5.0, which MongoDB 7.x refuses to load." >&2
   tlog "==" >&2
-  tlog "== To upgrade safely:" >&2
+  tlog "==   This check only runs for instances using the embedded MongoDB. Instances configured with an external MongoDB are not affected." >&2
   tlog "==" >&2
-  tlog "==   1. Alter your Appsmith deployment to use v1.99 (the latest release shipped with MongoDB 6.x)" >&2
-  tlog "==   2. Let the container start fully — it will raise the MongoDB compatibility version to 6.0 automatically" >&2
-  tlog "==   3. Shut down, then alter your Appsmith deployment to use this version again" >&2
+  tlog "==   The failure happens during MongoDB pre-flight, before any Appsmith service comes online. No Appsmith database migrations have been attempted, so rolling back to a 1.x release is simply a matter of changing the image version on your deployment." >&2
+  tlog "==" >&2
+  tlog "== To recover:" >&2
+  tlog "==" >&2
+  tlog "==   1. Alter your Appsmith deployment to use a release in the 1.93 to 1.99 range (we recommend the latest, 1.99). These ship with MongoDB 6.x and will raise the compatibility version automatically." >&2
+  tlog "==   2. Let the container start fully so the MongoDB FCV upgrade completes." >&2
+  tlog "==   3. Shut down, then alter your Appsmith deployment to use this version again." >&2
   tlog "==" >&2
   tlog "== Full mongod log: $probe_log" >&2
   tlog "====================================================================================================" >&2

From af34f2d3d33c2f2853e4707dd06147b327337034 Mon Sep 17 00:00:00 2001
From: Wyatt Walter <wyattwalter@gmail.com>
Date: Tue, 5 May 2026 17:43:50 -0500
Subject: [PATCH 11/11] chore(mongo): correct release ranges in FCV pre-flight
 error
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The stepping-stone range and FCV-5.x risk threshold in the error
message were both off:

- Stepping stone for raising FCV to 6.0 is releases 1.96 to 1.99
  (was: 1.93 to 1.99). Earlier 1.9x releases didn't yet have the
  FCV-bump logic.
- The MongoDB 5 → 6 upgrade landed in 1.70, not 1.66, so the
  at-risk population is instances that have only ever run Appsmith
  older than 1.70.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 deploy/docker/fs/opt/appsmith/entrypoint.sh | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/deploy/docker/fs/opt/appsmith/entrypoint.sh b/deploy/docker/fs/opt/appsmith/entrypoint.sh
index d1ee89d122c5..50cc0fe54acc 100644
--- a/deploy/docker/fs/opt/appsmith/entrypoint.sh
+++ b/deploy/docker/fs/opt/appsmith/entrypoint.sh
@@ -391,7 +391,7 @@ ensure_mongodb_fcv_compatible() {
   fi
   tlog "==" >&2
   tlog "== About this error:" >&2
-  tlog "==   Appsmith 2.x ships with MongoDB 7.x, which requires the database to be at featureCompatibilityVersion (FCV) 6.0 or higher. Appsmith releases 1.93 to 1.99 automatically raise FCV to 6.0 on boot, so any instance that has run one of those releases is fine. Instances that have only ever run Appsmith older than 1.66 may still be at FCV 5.0, which MongoDB 7.x refuses to load." >&2
+  tlog "==   Appsmith 2.x ships with MongoDB 7.x, which requires the database to be at featureCompatibilityVersion (FCV) 6.0 or higher. Appsmith releases 1.96 to 1.99 automatically raise FCV to 6.0 on boot, so any instance that has run one of those releases is fine. Instances that have only ever run Appsmith older than 1.70 may still be at FCV 5.0, which MongoDB 7.x refuses to load." >&2
   tlog "==" >&2
   tlog "==   This check only runs for instances using the embedded MongoDB. Instances configured with an external MongoDB are not affected." >&2
   tlog "==" >&2
@@ -399,7 +399,7 @@ ensure_mongodb_fcv_compatible() {
   tlog "==" >&2
   tlog "== To recover:" >&2
   tlog "==" >&2
-  tlog "==   1. Alter your Appsmith deployment to use a release in the 1.93 to 1.99 range (we recommend the latest, 1.99). These ship with MongoDB 6.x and will raise the compatibility version automatically." >&2
+  tlog "==   1. Alter your Appsmith deployment to use a release in the 1.96 to 1.99 range (we recommend the latest, 1.99). These ship with MongoDB 6.x and will raise the compatibility version automatically." >&2
   tlog "==   2. Let the container start fully so the MongoDB FCV upgrade completes." >&2
   tlog "==   3. Shut down, then alter your Appsmith deployment to use this version again." >&2
   tlog "==" >&2