When I first started working with ColdFusion, setting up a new server was a fairly time-consuming process involving running an installer wizard then clicking through a bunch of admin UI screens to get the data sources, mail servers, file system mappings, regional and many other settings configured to my liking, based on a lengthy checklist in Word.

Despite the advent of docker we still do manual installations, but even these are mercifully much simpler these days.

Over the years it's become progressively easier to configure server runtime behaviours at the application level using Application.cfc. Mail servers, for example, can now easily be specified there.

Then along came Brad's amazing Commandbox/CFConfig utility, which allowed all of the remaining settings still needing to be tweaked at the server level to be imported from a json file with a single command (well, almost all, as we'll see shortly).

Having recently upgraded to Lucee 6, however, I've found that installing a server is even simpler.

JSON configuration

Previously, Lucee's config was mainly stored in XML files, but following CFConfig's lead it has now moved to a much clearer and more comprehensive JSON format.

{
  "dotNotationUpperCase": false,
  "listenerType": "modern",
  "locale": "en_GB",
  "mode": "single",
  "mappings": {
    "/testbox": {
      "physical": "C:\\dev\\testbox"
    }
}

The entirety of your desired server state can be described in a file named <luceeInstallationDirectory>/lucee-server/context/.CFConfig.json which will be loaded when the server starts. To avoid restarts, you can also have Lucee check for changes periodically, or you can manually drop a new version of the file into the /lucee-server/deploy directory where it will be picked up and processed within a few seconds.

It also supports placeholders for sensitive values stored in system properties or environment variables.

"pw": "{env:LUCEE_ADMIN_PASSWORD}"

Single mode

It's over a decade since we switched from ColdFusion 9 to Lucee, a move we have never regretted. But one thing that has tended to baffle anyone making that transition is the "server contexts" vs "web contexts" distinction. The idea was to accommodate environments hosting multiple web applications each requiring different server configurations. To me this always seemed like unnecessary complexity, particularly as more and more configuration could be specified in code at the application level.

Although most settings could be defined globally in the server context and inherited by each web context, scheduled tasks always needed to be created in the individual web contexts, leading to confusion over where these definitions were stored. Similarly logs had to be tracked down in the separate WEB-INF directories.

Lucee 6 finally jettisons all of this complexity with its "single mode" setting. The default for new installations (and the only option from Lucee 7), this basically means that the .CFConfig.json file is the only place to look for configuration. If you prefer to use an admin UI then, like ColdFusion, there will just be one. No more "server admin" vs "web admin".

To be clear, you can still host multiple applications/websites on the same server instance but they will share the same global configuration.

Commandbox servers

For my own projects I make extensive use of another of Brad's phenomenal creations: Commandbox. In combination with CFConfig, it allows different CFML servers to be installed, configured and run simultaneously based on JSON definitions.

With my Lucee 6 and 7 commandbox servers, however, I have decided to drop CFConfig in favour of simply copying Lucee's "native" .CFConfig.json as part of the startup script. The main benefit I see in doing this is that it allows the required Lucee extensions to be more clearly expressed in the config file.

Although (as Brad was understandably keen to remind me on Slack!) CFConfig is superior to Lucee's .CFConfig.json in many respects, the one thing that has always frustrated me somewhat is its lack of support for Lucee extensions. There are easy ways around this and I eventually settled on defining them as an env var in my server.json.

"env":{
        "LUCEE_EXTENSIONS":"7E673D15-D87C-41A6-8B5F1956528C605F;name=MySQL;version=9.0.0,FAD1E8CB-4F45-4184-86359145767C29DE;name=Hibernate ORM Engine;version=3.5.5.89,8D7FB0DF-08BB-1589-FE3975678F07DB17;name=Compress Tags;version=1.0.0.15,37C61C0A-5D7E-4256-8572639BE0CF5838;name=ESAPI extension;version=2.2.4.15,66E312DD-D083-27C0-64189D16753FD6F0;name=PDF Extension;version=1.2.0.10,B737ABC4-D43F-4D91-8E8E973E37C40D1B;Image extension,version=2.0.0.26"
}

But as you can see this isn't very readable. I also think this belongs with the other Lucee-specific configuration details, rather than the commandbox/web server settings.

Lucee's .CFConfig.json does include extensions and is much easier to read.

"extensions": [
  {
    "id": "7E673D15-D87C-41A6-8B5F1956528C605F",
    "name": "MySQL",
    "version": "9.0.0"
  },
  {
    "id": "FAD1E8CB-4F45-4184-86359145767C29DE",
    "name": "Hibernate ORM Engine",
    "version": "3.5.5.89"
  },
  {
    "id": "8D7FB0DF-08BB-1589-FE3975678F07DB17",
    "name": "Compress Tags",
    "version": "1.0.0.16"
  },
  {
    "id": "37C61C0A-5D7E-4256-8572639BE0CF5838",
    "name": "ESAPI extension",
    "version": "2.2.4.18"
  },
  {
    "id": "66E312DD-D083-27C0-64189D16753FD6F0",
    "name": "PDF Extension",
    "version": "1.2.0.10"
  },
  {
    "id": "B737ABC4-D43F-4D91-8E8E973E37C40D1B",
    "name": "Image Extension",
    "version": "2.0.0.26"
  }
]

To have commandbox import the Lucee configuration file on start up, you just need to define a script in your server.json:

"scripts":{
      "onServerStart":"cp server-lucee6.config.json \\${serverinfo.serverHomeDirectory}/WEB-INF/lucee-server/context/.CFConfig.json"
 }

This example copies the config file from the application root to the correct location inside the dynamically created Lucee server home directory each time the server starts.

Lucee documentation of .CFConfig.json