Update configuration.md

Author: zspitzer

docs/recipes/configuration.md

@@ -11,6 +11,7 @@
   ],
   "related": [
     "function-configimport",
+    "function-configtranslate",
     "tag-application",
     "maven"
   ]
@@ -21,18 +22,22 @@
 
 This guide outlines best practices for configuring Lucee across different environments. While Lucee includes an
 administrator frontend (`<your-website>/lucee/admin.cfm`), this guide focuses on configuring Lucee using
-environment variables, configuration files, and `Application.cfc`. 
+environment variables, configuration files, and `Application.cfc`.
 
-The goal is to explore various configuration possibilities rather than providing one definitive approach. 
+The goal is to explore various configuration possibilities rather than providing one definitive approach.
 
-Since Lucee 6, configuration has shifted to JSON files (`.CFConfig.json`), replacing the older XML-based configurations. 
+Since Lucee 6, configuration has shifted to JSON files (`.CFConfig.json`), replacing the older XML-based configurations.
+
+The [[function-configtranslate]] function can be used to translate an Lucee 5 style `lucee-server.xml` or `lucee-web.xml.cfm` file to `CFConfig.json`.
+
+Lucee will automatically perform this translation if you upgrade a Lucee 5 instance to 6, this will only happen when there is no `CFConfig.json` file but an `.xml` is found.
 
 This guide focuses on Lucee 6 and onwards.
 
 ## Single Mode vs Multi Mode
 
 Lucee runs within a Servlet Engine (such as Tomcat), allowing you to manage multiple websites (or web contexts)
-within a single engine. 
+within a single engine.
 
 For example, you can host `lucee.org` and `whatever.org` on one Servlet Engine, each
 in its own web context.
@@ -54,9 +59,9 @@ by providing just one server configuration. Lucee 7 will exclusively support sin
 - **New Installations**: Lucee will run in single mode by default.
 
 You can toggle between "multi" and "single" modes using the Lucee administrator or by adjusting the server
-configuration file (`.CFConfig.json`). 
+configuration file (`.CFConfig.json`).
 
-In the administrator, you can merge all the settings from web contexts into a single server configuration. 
+In the administrator, you can merge all the settings from web contexts into a single server configuration.
 
 Simply switching the mode flag without merging will result in losing web context configurations (though Lucee keeps them in place).
 
@@ -118,7 +123,7 @@ The location of the `lucee-server` directory can be customized using the `LUCEE_
 variable or the `-Dlucee.server.dir` system property.
 
 At startup, Lucee reads this configuration, applying the settings and resolving resources (e.g., extensions,
-[[maven|Maven endpoints]], etc.). 
+[[maven|Maven endpoints]], etc.).
 
 A good approach is to configure Lucee through the administrator, then take the resulting `.CFConfig.json` file as a base for future installations / dpeloyments.
 
@@ -140,32 +145,32 @@ LUCEE_WEB_DIR="<whatever>/config/web/{web-context-label}/"
 
 ## Update Configuration
 
-When starting a new Lucee version without an existing configuration, Lucee will automatically generate a base configuration. 
+When starting a new Lucee version without an existing configuration, Lucee will automatically generate a base configuration.
 
 If you place a configuration in the server directory, Lucee will use that one instead.
 
-In Lucee 6.0 (no longer the case for Lucee 6.1.1), placing an empty configuration file may cause problems because Lucee 
-requires certain default settings to operate properly. 
+In Lucee 6.0 (no longer the case for Lucee 6.1.1), placing an empty configuration file may cause problems because Lucee
+requires certain default settings to operate properly.
 
-For instance, Lucee needs the virtual filesystem for "zip" to 
+For instance, Lucee needs the virtual filesystem for "zip" to
 read zip files.
 
-Starting with Lucee 6.1.1, you can update existing configurations by placing a configuration file in the `lucee-server/deploy` 
-folder. 
+Starting with Lucee 6.1.1, you can update existing configurations by placing a configuration file in the `lucee-server/deploy`
+folder.
 
-Lucee will automatically pick up the file at startup or within a minute after startup, applying the configuration 
-updates. 
+Lucee will automatically pick up the file at startup or within a minute after startup, applying the configuration
+updates.
 
-Only the configurations you add will be applied—Lucee does not overwrite the entire configuration. You can also 
-change the location of the deploy folder using the `LUCEE_SERVER_DIR` environment variable. See the **Server Configuration** 
+Only the configurations you add will be applied—Lucee does not overwrite the entire configuration. You can also
+change the location of the deploy folder using the `LUCEE_SERVER_DIR` environment variable. See the **Server Configuration**
 section for details.
 
 ## Pitfalls in Multi Mode Environments
 
 ### Logging in Server and Web Contexts
 
-In **multi mode**, logs are created for both the server and each web context. Most logs are generated in 
-the web context, but some global logs may appear in the server context. Log configurations in the server config 
+In **multi mode**, logs are created for both the server and each web context. Most logs are generated in
+the web context, but some global logs may appear in the server context. Log configurations in the server config
 are not inherited by web contexts and must be set separately.
 
 ### Event Gateway
@@ -174,27 +179,27 @@ Event gateways can only be defined in the web context.
 
 ## Runtime Configuration (`Application.cfc`)
 
-Lucee allows many settings to be defined dynamically at runtime via `Application.cfc`. These settings can include 
+Lucee allows many settings to be defined dynamically at runtime via `Application.cfc`. These settings can include
 datasources, caches, and other configurations.
 
 For every setting available in the Lucee administrator, there is often an equivalent setting in `Application.cfc`.
 
-If so, the Lucee administrator shows this below the setting as a "tip". You can also export an `Application.cfc` file 
+If so, the Lucee administrator shows this below the setting as a "tip". You can also export an `Application.cfc` file
 with the administrator settings that are supported.
 
 ## Startup Listener
 
-Lucee also supports startup listeners, which are triggered at startup. These listeners allow you to manipulate 
-the configuration of your environment further. 
+Lucee also supports startup listeners, which are triggered at startup. These listeners allow you to manipulate
+the configuration of your environment further.
 
 For example, you can use the [[function-configimport]] function to dynamically import configurations during startup.
 
 For more details, consult [Lucee Startup Listeners](https://github.com/lucee/lucee-docs/blob/master/docs/recipes/startup-listeners-code.md).
 
 ## Best Practices
 
-- **Early Configuration**: Set configurations in the server configuration rather than at runtime in `Application.cfc` 
+- **Early Configuration**: Set configurations in the server configuration rather than at runtime in `Application.cfc`
 whenever possible.
 - **Single Mode**: If you only have one website, use single mode to simplify management. Lucee 7 will remove multi mode.
-- **Use Placeholders for Sensitive Data**: Store sensitive information such as passwords, API keys, and database credentials 
+- **Use Placeholders for Sensitive Data**: Store sensitive information such as passwords, API keys, and database credentials
 in environment variables or system properties using placeholders.