Merge branch 'master' of https://github.com/lucee/lucee-docs

michaeloffner · michaeloffner · commit 9be6b3babc31 · 2025-02-19T16:27:50.000+01:00
diff --git a/docs/00.home/homepage.md b/docs/00.home/homepage.md
@@ -20,6 +20,14 @@ To find out more about getting involved as a developer with Lucee, checkout our
 
 **New!** We have added a whole series of detailed [[Recipes]] showing you how to take advantage of the wide range of features in Lucee.
 
+## Deploying Lucee
+
+[[deploying-lucee-server-apps]] - How to configure and deploy Lucee 
+
+[[locking-down-lucee-server]] - Security best practices for Lucee
+
+[[config]] - All about Lucee's configuration file
+
 ## Lucee 6.2
 
 Lucee 6.2 is our upcoming next major release, currently at the Release Candidate stage, including enhanced Java and Maven integration, Jakarta Servlet support and better runtime performance, up to 50% faster than Lucee 5.4.
diff --git a/docs/04.guides/12.deploying-lucee-server-apps/04.locking-down-lucee-server/page.md b/docs/04.guides/12.deploying-lucee-server-apps/04.locking-down-lucee-server/page.md
@@ -14,10 +14,19 @@ Make sure the WEB-INF directory is locked down. You will need to configure your
 
 To disable detailed error messages in Lucee, log in to the Lucee server administrator and go to Settings -> Error -> and select "error-public.cfm" from the drop down options. This will only display an extremely generic and uninformative error message to the end-users.
 
+```
+{
+    "errorGeneralTemplate": "/lucee/templates/error/error-public.cfm",
+    "errorMissingTemplate": "/lucee/templates/error/error-public.cfm"
+}
+```
+
 ### Ensure All Administrators for All Contexts Have Passwords Assigned and Use Captcha ###
 
 In the Lucee Server Administrator, go to Security -> Password. From this screen you can set the passwords of all existing web contexts and enable captcha's to prevent brute-forcing password breaking attempts on your Lucee Server & Web Administrators
 
+The Lucee Admin can be disabled by setting the env var `LUCEE_ADMIN_ENABLED=false` which is **recommended** for production/internet facing servers
+
 ### Reduce Request Timeouts as Low as Possible ###
 
 To change the Request Timeout value, log in to the Lucee server administrator and go to Settings -> Application -> Request Timeout. It is recommended you change it from 50 seconds to about 10 or so. Experiment with this to make sure the request timeouts do not effect needed functionality that may exist in your application.
diff --git a/docs/04.guides/12.deploying-lucee-server-apps/page.md b/docs/04.guides/12.deploying-lucee-server-apps/page.md
@@ -7,6 +7,8 @@ related:
 - running-lucee-system-properties
 - locking-down-lucee-server
 - relocating-web-inf
+- cookbook-check-for-changes
+- config
 forceSortOrder: '22'
 ---
 
@@ -16,57 +18,92 @@ forceSortOrder: '22'
 
 [[locking-down-your-lucee-stack]]
 
-There is a `/deploy` folder under the `/lucee-server/` folder which can be used to drop in updates to Lucee.
+## The deploy folder
 
-The `/deploy` folder is polled every 60 seconds by Lucee's Controller thread.  It looks for (`.lex`) file and (`.lco`) files.
+There is a `/deploy` folder under the `/lucee-server/` folder which can be used to customize Lucee .
 
-If Lucee finds an extension `.lex` (in the `/deploy` folder), it installs it (copying it to the `/installed` folder, among other things).
+The `/deploy` folder is polled on startup and every 60 seconds by Lucee's Controller thread.  It looks for `.lex` files (extensions), `.lco` files (lucee updates) and `.json` files for CFconfig snippets.
 
-If Lucee finds a `.lco` jar (in the `/deploy` folder), it copies it to the `/patches` folder, then it forces the engine to reload that core version immediately.
+This is the simplest way to configure / install your Lucee instance at startup or on the fly, without needing to restart it.
 
-However, if there is already a newer Lucee core version in the `/patches/` folder, any older version will simply be ignored. In that case, you need to delete any newer `.lco` files from `/patches/` folder beforehand.
+### .json - CFConfig.json
 
-`/deploy` is polled every 60 seconds, `/patches` is only checked at startup.
+Since Lucee 6.1.1, if Lucee finds a `*.json` (in the `/deploy` folder) it will be automatically imported and applied to your running `CFconfig` configuration. [LDEV-4994](https://luceeserver.atlassian.net/browse/LDEV-4994)
+
+You can also configure Lucee to [[cookbook-check-for-changes|monitor the server's .CFConfig.json file for changes]].
 
-The `/deploy` folder is just a shortcut way to install the `.lco` version into the patches folder of a running Lucee server without needing to restart it.
+### .lex - Extensions
 
-The `/patches` folder is where Lucee's core `.lco` jars are kept.  When Lucee starts, it determines which `*.lco` in that folder is the latest version and it loads that version. 
+If Lucee finds an extension `.lex` in the `/deploy` folder, it will be installed (copying it to the `/installed` folder, among other things).
 
 Extensions (`.lex`) can also be dropped in the `/lucee-server/context/extensions/available` folder and they can be installed using environment or JVM arguments without Lucee reaching out to the update provider.
 
-## Firewalled Servers
+### .lco - Lucee core updates
 
-`.lco` updates either via the Lucee Admin update page, or by dropping into the `/deploy` folder, may require dynamically downloading any updated jar files from the update server. As such they may fail attempting to download the new files.
+If Lucee finds a `.lco` jar in the `/deploy` folder, it copies it to the `/patches` folder, then it forces the engine to reload that core version immediately.
 
-To update firewalled servers, or to upgrade without Lucee downloading bundles (which is slightly slower), do the following
+However, if there is already a newer Lucee core version in the `/patches/` folder, any older version will simply be ignored. In that case, you need to delete any newer `.lco` files from `/patches/` folder beforehand.
 
-1. Stop the server
-2. Download the (fat) lucee.jar (see below) from [https://download.lucee.org/](https://download.lucee.org/)
-3. Delete or change the file extension for the fat jar in the `lucee/lib` folder, i.e `5.4.3.2.jar`
-4. Copy the updated `lucee.jar` into that `lucee\lib` folder 
-5. Start the server
+`/deploy` is polled every 60 seconds, `/patches` is only checked at startup.
+
+The `/patches` folder is where Lucee's core `.lco` jars are kept.  When Lucee starts, it determines which `*.lco` in that folder is the latest version and it loads that version.
 
-## Lucee Distributions 
+### Lucee Distributions 
 
 available from [https://download.lucee.org/](https://download.lucee.org/)
 
-- **Lucee.jar** (aka the far jar) which includes lucee core and loader, java bundles, the base set of extensions, admin and docs
+- **Lucee.jar** (aka the fat jar) which includes Lucee core and loader, java bundles, the standard base set of extensions, admin and docs
 - **Lucee-light.jar** which includes the lucee core and loader, java bundles, admin and docs
-- **Lucee-zero.jar** which includes just the lucee core and loader, java bundles (since 6.0.0.492)
-- **lucee.lco** just the core lucee engine, which can be used to update an existing Lucee installation
+- **Lucee-zero.jar** which includes just the Lucee core and loader, java bundles (since 6.0.0.492)
+- **lucee.lco** just the core Lucee engine, which can be used to update an existing Lucee installation
 
-## Customized Installs
+### Customized Installs
 
-If you want to deploy a very targeted / customised install, start with Light or Zero and optionally add the extension(s) you want to use in the deploy folder, or set `LUCEE_EXTENSIONS` env var
+If you want to deploy a very targeted / customised install, start with Light or Zero and optionally add the extension(s) and `CFconfig.json` you required into the deploy folder, or set `LUCEE_EXTENSIONS` env var
 
-## Warming up installs
+### Warming up installs
 
-You can pre warm a lucee installation, by setting the env var `LUCEE_ENABLE_WARMUP` to true, when set, Lucee will deploy and then exit
+You can pre warm a lucee installation, by setting the env var `LUCEE_ENABLE_WARMUP` to true, when set, Lucee will deploy itself, including processing any files found in the `/deploy` folder and then exit
 
-## Admin and Docs extensions
+### Admin and Docs extensions
 
 You will see extensions, Lucee Admin and Lucee Docs, these simply install mappings to make them available. The admin is tightly coupled to the Lucee Version, so they aren't separately deployed
 
-## AWS Lambdas / Serverless
+The Lucee Admin can be disabled by setting the env var `LUCEE_ADMIN_ENABLED=false` which is **recommended** for production/internet facing servers
+
+### Console Logging
+
+Since Lucee [6.2.0.310 / LDEV-3420](https://luceeserver.atlassian.net/browse/LDEV-3420), you can override the default logging configuration in `.CFconfig.json`, to redirect all logs to the console, which is very useful, especially with Docker.
+
+Setting the env var `LUCEE_LOGGING_FORCE_APPENDER=console` globally overrides all logging configuration, to log out the console, using the existing configured log levels.
+
+You can override the configured, per log file log levels using the env var `LUCEE_LOGGING_FORCE_LEVEL=INFO`
+
+### Error Templates
+
+By default, Lucee is configured to show detailed error messages, revealing server paths etc, which is great for developing.
+
+This **should be disabled for production servers** by the following `.CFconfig.json` directives, or supply your own templates.
+
+```
+{
+    "errorGeneralTemplate": "/lucee/templates/error/error-public.cfm",
+    "errorMissingTemplate": "/lucee/templates/error/error-public.cfm"
+}
+```
+
+### Firewalled Servers
+
+`.lco` updates either via the Lucee Admin update page, or by dropping into the `/deploy` folder, may require dynamically downloading any updated jar files from the update server. As such they may fail attempting to download the new files.
+
+To update firewalled servers, or to upgrade without Lucee downloading bundles (which is slightly slower), do the following
+
+1. Stop the server
+2. Download the (fat) lucee.jar (see below) from [https://download.lucee.org/](https://download.lucee.org/)
+3. Delete or change the file extension for the fat jar in the `lucee/lib` folder, i.e `5.4.3.2.jar`
+4. Copy the updated `lucee.jar` into that `lucee\lib` folder 
+5. Start the server
+
+### AWS Lambdas / Serverless
 
 [Fuseless: Tools for running Serverless CFML Lambda Functions](https://fuseless.org/)
diff --git a/docs/recipes/README.md b/docs/recipes/README.md
@@ -36,7 +36,7 @@ Cache a Query for the current request in Lucee.
 
 How to add per-application caches via Application.cfc in Lucee.
 
-## [Check for changes in your configuration file automatically](/docs/recipes/check-for-changes.md)
+## [Untitled](/docs/recipes/check-for-changes.md)
 
 Automatically check for changes in your configuration file with Lucee.
 
diff --git a/docs/recipes/check-for-changes.md b/docs/recipes/check-for-changes.md
@@ -1,6 +1,6 @@
 <!--
 {
-  "title": "Check for changes",
+  "title": "Automatic monitoring and applying CFConfig changes",
   "id": "cookbook-check-for-changes",
   "description": "Automatically check for changes in your configuration file with Lucee.",
   "keywords": [
@@ -17,13 +17,21 @@
 }
 -->
 
-# Check for changes in your configuration file automatically
+## Check for changes in your configuration file automatically
 
 Lucee can automatically check for changes in your configuration files from the complete server or a single web context.
 
 This is useful if you are doing scripted deploys and/or synchronization from, for example, a master instance to many slave instances of Lucee.
 
-## Check for Changes in ALL the contexts
+### Check for Changes - CFconfig.json (6+)
+
+```
+{
+ "checkForChanges": true
+}
+```
+
+### Check for Changes in ALL the contexts (pre 6.0)
 
 To enable this for a whole Lucee server, find the Lucee server XML file in:
 
@@ -37,13 +45,15 @@ Now it's simple to add the following:
 
     <cfLuceeConfiguration hspw="xxx" salt="xx" check-for-changes="true" version="4.2">
 
+### Restart Lucee
+
 Now that you have made the change, you can either restart Lucee server from the administrator at:
 
     http://localhost:8888/lucee/admin/server.cfm?action=services.restart
 
-Or actually make any change in the Server Admin for the configuration to be picked up. This should now allow it to pick up any changes you have written to the lucee-server.xml file.
+Or actually make any change in the Server Admin for the configuration to be picked up. This should now allow it to pick up any changes you have written to the `CFconfig.json` / `lucee-server.xml` file.
 
-## Check for changes in an individual context
+### Check for changes in an individual context
 
 If you only want an individual context to check for changes, you can do the same configuration but you would have to go to:
 
@@ -55,4 +65,4 @@ And add the same changes from above:
 
 Lucee will now check for any changes in the Lucee configuration files every minute, and if there is a change, reload it and enable those changes.
 
-A very handy little feature for those automated deployments!
+A very handy little feature for those automated deployments and local development!
diff --git a/docs/recipes/index.json b/docs/recipes/index.json
@@ -134,9 +134,9 @@
   },
   {
     "file": "check-for-changes.md",
-    "title": "Check for changes in your configuration file automatically",
+    "title": "Untitled",
     "path": "/docs/recipes/check-for-changes.md",
-    "hash": "1871271c6d6c1d999fc25d9bfcce2f6e",
+    "hash": "2e272e2ddcbd6c86dcb419c053f395b1",
     "keywords": [
       "Configuration",
       "Check for changes",
@@ -279,7 +279,7 @@
     "file": "environment-variables-system-properties.md",
     "title": "Environment Variables / System Properties for Lucee",
     "path": "/docs/recipes/environment-variables-system-properties.md",
-    "hash": "fe71bc9bf80a7ce10455be2cca4f42bf",
+    "hash": "8ba721f6825e05601dd28869c5864bb6",
     "keywords": [
       "Environment",
       "Environment Variables",
@@ -1084,7 +1084,7 @@
     "file": "supercharge-your-website.md",
     "title": "Supercharge your website",
     "path": "/docs/recipes/supercharge-your-website.md",
-    "hash": "16de007fd5dfccb78faba68082ad2b00",
+    "hash": "ee475a28a0d9793adf735f6b78b65092",
     "keywords": [
       "Supercharge website",
       "Performance",
diff --git a/docs/recipes/supercharge-your-website.md b/docs/recipes/supercharge-your-website.md
@@ -18,7 +18,15 @@
 
 # Supercharge your website
 
-This document explains how you can improve the performance of your website in a very short time with Lucee.
+How to improve performance of your production Lucee website using never inspect templates.
+
+## Background
+
+By default, when a source file has changed, Lucee will detect that change and recompile it, before executing it.
+
+This is great when you are developing, but it's usually not needed for production servers, as you can imagine, checking every files for changes, does slow down performance.
+
+For production servers, if you know your server does not produce or change any source files, using Inspect Templates `NEVER` avoids that overhead.
 
 ## Example:
 
@@ -27,20 +35,48 @@ This document explains how you can improve the performance of your website in a
 writeDump(now());
 ```
 
-Run the above index.cfm, and you get a timestamp. Whenever we call our file, Lucee checks once at every request if a file has changed or not (for files currently residing in the template cache). If a file has changed, Lucee recompiles it, and executes it. Checking the files at every request takes time. If you have a published server, and you know your server does not produce or change any files, you can simply avoid that check that happens all the time.
+Run the above `index.cfm`, and you get a timestamp. Now change that file and call it again, the changes are automatically picked up.
+
+Whenever we call our file, by default, Lucee checks once at every request if a file has changed or not (for files currently residing in the template cache).
 
-## Using Admin
+## Setting InspectTemplates to NEVER using the Lucee Admin
 
 - Go to _Admin -> Performance/ Caching -> Inspect Templates (CFM/CFC) -> Never_
 
 - The default is "Once", checking any requested files one time within each request. You should check "Never" to avoid the checking at every request.
 
-- Change the index.cfm and run it again. No changes happen in the output because Lucee does not check if the file changed or not. Now, let's see the faster execution and less performance memory being used.
+- Change the `index.cfm` and run it again. No changes happen in the output because Lucee does not check if the file changed or not. Now, you'll see the faster execution and less performance memory being used.
 
-- You can clear the cache by code using `pagePoolClear()`. This clears all template cache so that Lucee will check again if the template has changed. On the next request, Lucee will check initially for the file.
+- You can flag all cached templates to be checked once for changes using [[function-inspectTemplates]]. This is more efficent than [[function-pagepoolclear]] which clears the entire template cache,  requiring every single template to be recompiled.
 
 - Another option to clear the template cache is to use clear cache via the admin by clicking the button in _Admin -> Settings -> Performance/ Caching -> Page Pool Cache_.
 
+Remember, the Lucee Admin is simply a GUI which edits `CFconfig.json`. It's written in CFML and if you want to do something the admin does, have a look at the source code.
+
+## Setting InspectTemplates to NEVER using CFconfig.json
+
+```
+{ 
+  "inspectTemplate": "never"
+}
+```
+
+The `inspectTemplates` setting can also be configured per mapping, by default mappings inherit the server default.
+
+```
+{
+  "mappings": {
+    "/testbox": {
+      "physical": "d:\\work\\TestBox",
+      "primary": "physical",
+      "topLevel": "true",
+      "readOnly": "false",
+      "inspectTemplate": "never"
+    }
+  }
+}
+```
+
 ## Footnotes
 
 Here you can see these details on video also:
