Starter template hard codes reloadPassword in config settings, right way to use environment variables?

[teleotic]

I'm not sure this is a bug, per se, which is why I didn't raise this question as an issue. Currently (v4.0.2) wheels new hard codes a (randomized) reloadPassword into three locations: .env, config/settings.cfm, and a comment line in config/settings.cfm. Now .env makes sense to me, but putting it in the config settings seems to violate the recommendation that you shouldn't store secrets in your git repository. So before committing, I decided to change that line to pull from an environment variable per the docs. That's where I ran into a little confusion.

In the documentation on "Environments and Configuration," the recommendation is to change your config settings to something like the following, calling it the "canonical accessor":
set(reloadPassword = application.wo.env("RELOAD_PASSWORD"));.

However, in the 3.x to 4.0 guide it recommends this syntax as the "canonical pattern":
set(reloadPassword = env("WHEELS_RELOAD_PASSWORD", ""));

This is because (apparently) application.env, and therefore application.wo.env, may not be populated before config/settings.cfm is run.

So my question is -- which syntax should I use? Is this just a case of the docs being out of sync?

(The same question applies to config/environment.cfm, which hard codes a development environment setting instead of pulling from environment variables.)

Thanks for any guidance!

[bpamiri]

Thanks for the careful write-up, @teleotic — this is exactly the kind of report we like to get, and you've actually surfaced more than one thing. Short version: you're right to be uncomfortable, the two doc snippets are partly out of sync, and the more important issue is the scaffold itself. Here's what we found after tracing the code.

What's actually going on

Three independent things are tangled together here:

1. The accessor — env(...) vs application.wo.env(...) is cosmetic. Both call the same helper (vendor/wheels/Global.cfc), which checks application.env (your .env) first, then OS environment variables, then your default. Inside config/settings.cfm the bare env() form works for the same reason bare set() does — the file runs in the framework's global scope. We consider bare env() the canonical form; application.wo.env(...) is just a more verbose way to reach the identical function. Neither is wrong, but showing two styles is on us.

2. The variable name — this is the real inconsistency. Your generated .env defines RELOAD_PASSWORD, and the core-concepts page reads RELOAD_PASSWORD, so those agree. But the 3.x→4.0 upgrade guide reads WHEELS_RELOAD_PASSWORD, which is the name our deploy templates use. So if you paste the upgrade-guide line into a fresh app, env("WHEELS_RELOAD_PASSWORD", "") resolves to empty — and you'd hit the very "reloadPassword is empty" warning that line was meant to prevent. That's a genuine inconsistency on our side, not you misreading.

3. The load-order caveat in the upgrade guide doesn't apply to your fresh 4.0.2 app. In a newly generated app, application.env is populated at the very top of onApplicationStart() (the application.env = duplicate(this.env) line in public/Application.cfc) before config/environment.cfm or config/settings.cfm ever run. The "may not be populated" warning is scoped to people who hand-wired an older 3.x Application.cfc; the guide itself notes freshly-scaffolded apps are unaffected. So you don't need to worry about ordering — both forms work in your app.

And the thing you only half-named, which is the one that matters most: the generator hardcodes the random password as a literal into config/settings.cfm, and that file is committed (only .env is in the generated .gitignore). It's even echoed a second time in the plaintext comment right above the set() line. So yes — the scaffold is leaking a secret into git, which directly contradicts our own "don't commit secrets" guidance. Good catch.

For blast-radius context: the reload password gates ?reload= restarts and URL-based environment switching, and it's rate-limited (5 failed tries / 5 min per IP), so it's a moderate secret rather than a catastrophic one — but there's no reason for it to be in version control when .env already holds it.

What you can do right now (workaround)

In config/settings.cfm, replace the hardcoded line with the env-sourced form, using the name that matches your generated .env:

// Reload your application with ?reload=true&password=<the RELOAD_PASSWORD value from your .env>
set(reloadPassword = env("RELOAD_PASSWORD", ""));

Then:

• Delete the literal password from that comment line too, so it isn't committed either.
• Keep the actual random value only in .env (already git-ignored).

The random value is already in your .env from wheels new, so nothing else changes. The CLI/console keep working — wheels' reload-password detection checks .env for RELOAD_PASSWORD first and only falls back to a literal in settings.cfm, so sourcing it from .env is fully supported.

Stick with RELOAD_PASSWORD (not WHEELS_RELOAD_PASSWORD) for now, since that's what your generated .env contains — and because you control both sides in your own app, your config stays self-consistent regardless of what we standardize on later.

On your config/environment.cfm question: if you'd like your .env to drive the environment instead of the hardcoded set(environment="development"), the same pattern works — set(environment = env("WHEELS_ENV", "development"));. But that one's optional. The hardcoded development default is intentional there (it isn't a secret, and it's a convenient build-time default), so leaving it as-is is perfectly fine.

What we intend to fix (next patch release)

• Stop hardcoding the secret. The wheels new template will generate config/settings.cfm with set(reloadPassword = env("RELOAD_PASSWORD", "")) and write the random value only to .env — and the real value comes out of the comment line.
• Reconcile the variable name. The generated .env, the core-concepts page, the upgrade guide, and the deploy templates will all use one name, so copy-pasting any snippet works. (We're leaning toward the WHEELS_-prefixed form for consistency with WHEELS_ENV / WHEELS_DATASOURCE, and we'll update the scaffold's .env to match — but whichever we pick, all four sources will agree.)
• Standardize the docs on bare env() and drop the second accessor style so there's only one documented way.

Thanks again — this was a well-scoped report and it's prompting a real cleanup. I'll link the PRs here once they're up.

[teleotic]

OK. I will use the bare env() syntax going forward.

While we are on the topic, I should note that the same password is hard coded into lucee.json as the Lucee admin password. I'll comment on the pull request so the agents pick this up.

Thanks.

[bpamiri]

Update — fixed and merged in #2857 (squashed to develop as d4ce24e77).

What changed, mapping to what you raised:

• config/settings.cfm no longer hardcodes the reload password. wheels new now generates set(reloadPassword = env("WHEELS_RELOAD_PASSWORD", "")), so the random value lives only in the git-ignored .env — gone from the committed file and its comment.
• One name, one accessor. The generated .env, the "Environments and Configuration" page, the 3.x→4.0 guide, and the deployment guides now all use WHEELS_RELOAD_PASSWORD with the bare env() accessor — so the docs no longer disagree. (env() is the canonical form; application.wo.env(...) was just a more verbose call to the same helper, and the load-order caveat you saw in the upgrade guide only ever applied to hand-wired 3.x Application.cfc files, not fresh 4.0 apps.)
• Your second catch too: lucee.json was committing the same value as the Lucee Server Admin password. It now reads #env:WHEELS_RELOAD_PASSWORD#, which LuCLI resolves from .env at server start — so no committed file carries the secret.

Your actual question — which syntax: set(reloadPassword = env("WHEELS_RELOAD_PASSWORD", "")), with WHEELS_RELOAD_PASSWORD=... in .env. (config/environment.cfm keeping a hardcoded development is intentional — it isn't a secret, and a missing key failing closed to development is the safe default for local dev.)

Ships in: the next official patch release, 4.0.3.

Want to try it before then? It's already in the bleeding-edge channel (4.0.3-snapshot.1967). The stable wheels and bleeding-edge wheels-be packages both provide the wheels binary, so they're mutually exclusive — switching = uninstall one, install the other:

# macOS (Homebrew)
brew uninstall wheels && brew install wheels-be

# Windows (Scoop) — same idea as Homebrew
scoop uninstall wheels
scoop install wheels-be

# Debian/Ubuntu — apt swaps wheels → wheels-be automatically (Replaces/Conflicts)
echo "deb [signed-by=/usr/share/keyrings/wheels.gpg] https://apt.wheels.dev bleeding-edge main" \
  | sudo tee /etc/apt/sources.list.d/wheels-be.list
sudo apt update && sudo apt install wheels-be

# Fedora/RHEL
sudo dnf remove wheels && sudo dnf config-manager --add-repo https://yum.wheels.dev/wheels-be.repo && sudo dnf install wheels-be

wheels --version will report (bleeding-edge). Then wheels new testapp and inspect config/settings.cfm, .env, and lucee.json — no committed secret, all env-sourced. Switching back to stable is the same in reverse (brew uninstall wheels-be && brew install wheels, scoop uninstall wheels-be && scoop install wheels, etc.). Full channel docs are here: https://guides.wheels.dev/v4-0-0/start-here/release-channels/

Thanks again — your report turned into a clean sweep across the scaffold, CLI, and docs.