fix(security): load Docker environment configuration as data

[wyattwalter]

Description

Treat persisted docker.env as data rather than shell code. This is defense-in-depth hardening on top of the existing admin API escaping protections.

Startup and service restarts validate the complete file before loading it. Invalid configuration stops startup with a line number and variable name, without printing values. Resolved external environment values retain precedence.

Backup and restore share the parser and literal-value serializer; restore validates configuration before stopping services or changing the database. Embedded PostgreSQL initialization uses a fixed database name and passes database arguments as data.

Fixes APP-15243.

Compatibility example

Previously, a manually edited docker.env could reference another variable:

MONGO_PASS="asdf"
APPSMITH_DB_URL="mongodb://user:${MONGO_PASS}@mongodb.host.company.com/appsmith"

The shell expanded ${MONGO_PASS} to asdf. With this change, startup exits with code 1 and logs:

Unable to load environment configuration: line 2 (APPSMITH_DB_URL): shell expression requires migration to a resolved literal; single-quote intentional literal expressions.

Supply the resolved value instead, in docker.env or through the deployment's environment/secret configuration:

APPSMITH_DB_URL='mongodb://user:asdf@mongodb.host.company.com/appsmith'

Single-quoting the original expression preserves it literally; it does not resolve the reference.

Impact on existing instances

• Fresh install: generated defaults work unchanged.
• Upgrade from defaults/Admin Settings: existing generated and quoted values remain supported.
• Upgrade from customized configuration: resolve shell expressions and correct unsupported names or malformed assignments before upgrading. Preserve the effective encryption password and salt exactly. Do not source an untrusted file to convert it. Incompatible legacy backups and multiline replacement values must be corrected before restore.
• Rollback: the loader does not rewrite docker.env; backup/restore output remains shell-quote compatible. Older images resume shell evaluation, so inspect configuration before rollback.

Draft release note

Customized docker.env files must contain resolved values before upgrading. Shell expressions now stop startup with a redacted diagnostic identifying the affected variable. Generated defaults and Admin Settings values need no changes.

Verification

• 15 parser/startup tests pass locally and in the cached Appsmith Linux runtime; 52 CE backup/restore tests pass.
• Shell syntax, shared-loader ShellCheck, changed-file TypeScript lint, RTS typecheck, Docker defaults, and rate-limit checks pass.
• Loader checks run in the existing Caddy route workflow. CE CI and Cypress will run after the PR is opened.
• Paths checked: startup, supervised restart, external snapshot, backup/restore writers, embedded PostgreSQL initialization, and the existing Java configuration writer.

Automation

/ok-to-test tags="@tag.All"

🔍 Cypress test results

Communication

Should the DevRel and Marketing teams inform users about this change?

• Yes
• No

Tip

🟢 🟢 🟢 All cypress tests have passed! 🎉 🎉 🎉
Workflow run: https://github.com/appsmithorg/appsmith/actions/runs/34652334073
Commit: 60298a5
Cypress dashboard.
Tags: @tag.All
Spec:

---

Fri, 11 Sep 2026 23:12:03 UTC

[linear-code]

APP-15243

[coderabbitai]

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

• Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
  auto_review:
    drafts: true

---

_{Comment @coderabbitai help to get the list of available commands.}