Brad Wood

August 05, 2021

Spread the word

Share your thoughts

Hot on the heels of our previous announcement of big new CFConfig features, we've got another release to let you know about!  

New Features

Here’s an overview of the new features.  This release should all be completely backwards compatible, but we’ve added a bunch of new behaviors so please report any issues you may have.  This release was all about relieving the pain of Lucee developers dealing with the duality of their server and web context.  Some config has to go in the server admin and some config has to go in the web admin.  CFConfig previously would only automatically import config into the server context which left you with a manual task to get your web config imported.  

High level features of this release are:

  • New env vars which are looked for to specify the cfconfig JSON file location
  • New keys in the server.json to control the JSON files
  • New file conventions on disk which are looked for
  • New variations of the cfconfig_settingName env vars

New server.json sytnax

  "cfconfig" : {
     // Replacement for top level cfconfigfile key
     "file" : "path/to/file.json",
     // Same as "file" but for consistency
     "server" : "path/to/file.json",
     // Will load into lucee/railo web context
     "web" : "path/to/file.json",
     // Replacement for top level CFConfigPauseTasks key
     "pauseTasks" : true
  // Backwards compat fallback
  "CFConfigFile" : "path/to/file.json"
  "CFConfigPauseTasks": true

We still support the two top level keys for backwards compat, but going forward, all CFConfig settings will go inside of the cfconfig object.  

Note, you would never need to use all the properties above at the same time. For an Adobe server, or a Lucee server in which you only care about importing settings into the server context, you can just use cfconfig.file . For a Lucee server in which you want to import settings into the server AND web context, you can use cfconfig.server and cfconfig.web.

Env Var syntax

The following environment variables can now be used to set the same JSON files as above.

# Default

# Force Lucee web context  (On adobe, just loaded normally)

# Force Lucee server context - same as default  (On adobe, just loaded normally)

The following environment variables can now be used to set individual settings into a server:

# Default

# Force Lucee web context  (On adobe, just loaded normally)

# Force Lucee server context - same as default  (On adobe, just loaded normally)

File Conventions

The following files will be looked for by convention inside your web root if none of the options above have provided a JSON file path to import.

# Default

# Force Lucee web context  (On adobe, just loaded normally)

# Force Lucee server context - same as default  (On adobe, just loaded normally)

In the event there are two or more JSON files being imported into the same context, the first file will be an overwrite as usual, but all subsequent files will import in the new “append” mode so they are additive.  

Lucee Password Handling

We’ve improved the logic to ensure Lucee server context passwords also get written to the web context and vice versa.  The logic has been greatly improved to “remember” any passwords set no matter where they came from (JSON files, env vars) and will apply them to password-less contexts only if those contexts don’t have a password set.  

Production Secure-By-Default Passwords

We’ve added a feature which will force a random password when none is set.  This will ONLY happen if the server profile is “production” and ( there is no password of any kind set or if the engine is Adobe and the password is the plaintext default of “commandbox” which is insecure).  If you are currently deploying to production with the default password of “commandbox”, that will no longer work :)  The random password will be output in the verbose server logs.  

ExportOnStop Web/Server Context Aware

If you have the exportOnStop setting enabled in CFConfig, Lucee’s server and web contexts will export into the matching JSON files, if they exist.   If there is more than one JSON file declared for a given context, the first will be used.


So for a basic use case of a Lucee server where you want server and web config at the same time, you can just put the following files in your web root

  • .cfconfig-web.json
  • .cfconfig-server.json

And for an Adobe server or a Lucee server where you only care about importing confugration into the server context, you can just stick with the following like before:

  • .cfconfig.json

All importing and exporting will default to the proper contexts.  All verbose server start logging has been improved to tell you which context the config files are being imported into as well so it’s clear what’s happening.  There is also debug logging which will tell you which JSON files were discovered and how (env var, file convention, server.json key, etc)

Add Your Comment

Recent Entries

ColdBox Mail Services 2.0 - Fluent Mail For All

ColdBox Mail Services 2.0 - Fluent Mail For All

We are so excited to bring you a major release of our cbmailservices module. This module has been around since our initial versions of ColdBox and it has now matured into a modern and fluent library for sending mail.

Luis Majano
Luis Majano
November 08, 2021
FORGEBOX 6 has landed!

FORGEBOX 6 has landed!

After several months of work, we are proud to announce the release of FORGEBOX 6. This has been a major undertaking spawning several months worth of work, a complete UI revamp for registered users, many bug fixes, multi-key API, and much more. We have also introduced our new Business Accounts with the ability for organizations to have a simple and human way of managing their final package releases and their teams.

Javier Quintero
Javier Quintero
October 26, 2021
CommandBox 5.4.2 Released!

CommandBox 5.4.2 Released!

There is a new update for CommandBox CLI available.  Version 5.4.2 is a patch update that contains a few bug fixes including two important ones. 

  • There is a fix for a regression introduced in 5.4.0 where updating the version of a CF engine doesn't work without forgetting the server first. 
  • There is also an important security impro...

Brad Wood
Brad Wood
October 07, 2021