GitBook: [ortus-docs#8] No subject

Author: bdw429s

.gitbook/assets/box_icon (2) (2) (2) (2) (2) (2) (2) (1) (1).png

@@ -18,13 +18,13 @@ We highly encourage contribution to this book and our open source software. The
 
 ## Charitable Proceeds
 
-15% of the proceeds of this book will go to charity to support orphaned kids in El Salvador - [http://www.harvesting.org/](http://www.harvesting.org). Please donate and purchase the printed version of this book as every book sold can help a child for almost 2 months.
+15% of the proceeds of this book will go to charity to support orphaned kids in El Salvador - [http://www.harvesting.org/](http://www.harvesting.org/). Please donate and purchase the printed version of this book as every book sold can help a child for almost 2 months.
 
 ### Shalom Children's Home
 
-![](<.gitbook/assets/shalom (2) (2) (2) (2) (2) (2) (2) (1).jpg>)
+![](<.gitbook/assets/shalom (2) (2) (2) (2) (2) (2) (2) (1) (1).jpg>)
 
-Shalom Children’s Home ([http://www.harvesting.org/](http://www.harvesting.org)) is one of the ministries that is dear to our hearts located in El Salvador. During the 12 year civil war that ended in 1990, many children were left orphaned or abandoned by parents who fled El Salvador. The Benners saw the need to help these children and received 13 children in 1982. Little by little, more children came on their own, churches and the government brought children to them for care, and the Shalom Children’s Home was founded.
+Shalom Children’s Home ([http://www.harvesting.org/](http://www.harvesting.org/)) is one of the ministries that is dear to our hearts located in El Salvador. During the 12 year civil war that ended in 1990, many children were left orphaned or abandoned by parents who fled El Salvador. The Benners saw the need to help these children and received 13 children in 1982. Little by little, more children came on their own, churches and the government brought children to them for care, and the Shalom Children’s Home was founded.
 
 Shalom now cares for over 80 children in El Salvador, from newborns to 18 years old. They receive shelter, clothing, food, medical care, education and life skills training in a Christian environment. The home is supported by a child sponsorship program.
 

.gitbook/assets/image (2) (2) (2) (2) (2) (2) (2) (2) (2).png

@@ -10,7 +10,7 @@ These settings are used to configure CommandBox's endpoints.
 
 **string**
 
-The API Token provided to you when you signed up for [ForgeBox.io](https://www.forgebox.io). This will be set for you automatically when you use the `forgebox register` or `forgebox login` commands. This token will be sent to ForgeBox to authenticate you. Please do not share this secret token with others as it will give them permission to edit your packages!
+The API Token provided to you when you signed up for [ForgeBox.io](https://www.forgebox.io/). This will be set for you automatically when you use the `forgebox register` or `forgebox login` commands. This token will be sent to ForgeBox to authenticate you. Please do not share this secret token with others as it will give them permission to edit your packages!
 
 ```bash
 config set endpoints.forgebox.APIToken=my-very-long-secret-key

.gitbook/assets/image (8) (1) (1) (2) (2) (2) (2) (2) (2) (1).png

@@ -89,3 +89,51 @@ config show tabCompleteInline
 ```
 
 ![](<../.gitbook/assets/image (7).png>)
+
+## developerMode
+
+The `developerMode` setting reloads shell before each command to help testing changes to CommandBox core or modules.
+
+```
+config set developerMode=true
+```
+
+It will prevent you from needing to use the `reload` command, but it will cause a delay before each command.  Don't forget to turn this back off when you're done.
+
+## terminalWidth
+
+Terminal width can be overridden for entire CLI.  This will affect ASCII art, interactive job output, progress bars, and the table printer.
+
+```
+config set terminalWidth=150
+```
+
+## offlineMode
+
+The `offlineMode` setting will disable most external HTTP calls.  This can be useful for
+
+* testing production server starts to ensure they aren’t reliant on external calls
+* running `box` in a secure network which blocks or flags any external access
+
+```bash
+# enable offline mode
+config set offlineMode=true
+
+# go back to normal
+config set offlineMode=falses
+```
+
+&#x20;This setting is obeyed in the following parts of CommandBox:
+
+* commandbox-update-check module
+* installation endpoints
+  * forgebox
+  * http/https/cached+http/cached\_https
+  * git/git+ssh/git+https/github
+  * java
+  * lex
+  * jar
+  * CFLib
+  * S3
+* upgrade command
+* inside the progressable downloader class

.gitbook/assets/open_package (2) (2) (2) (2) (2) (2) (2) (1) (1).png

@@ -3,7 +3,7 @@
 CommandBox may also be used in production or continuous deployments, since it allows you to orchestrate your server environment. This eliminates dependency on hardware, and makes your CFML applications more portable, as a whole. 
 
 {% hint style="info" %}
-For advanced server configurations, be sure to check out the [`CFConfig` module](https://cfconfig.ortusbooks.com).
+For advanced server configurations, be sure to check out the [`CFConfig` module](https://cfconfig.ortusbooks.com/).
 {% endhint %}
 
 Since the startup of a CommandBox server allows you specify a host and server port, you can easily bind your server to a machine IP address and specify which port it should serve the application on. This allows you to proxy traffic to the application from IIS, Apache, or NGINX and even allows you to serve traffic directly on HTTP port 80 or 443, if you choose.

.gitbook/assets/run (1) (1) (1) (1) (2) (2) (2) (2) (2) (2) (1) (1).png

@@ -2,7 +2,7 @@
 
 ![](../.gitbook/assets/heroku.png)
 
-The [Heroku buildpack for CommandBox](https://github.com/ortus-solutions/heroku-buildpack-commandbox) will allow you to deploy your CFML applications directly to [Heroku](https://www.heroku.com) (or to [Dokku](http://dokku.viewdocs.io/dokku/) hosts) using CommandBox to manage your CFML engine. It allows you to specify your custom server configuration settings using the CommandBox server API, avoiding additional script and configuration files during the Heroku deployment process.
+The [Heroku buildpack for CommandBox](https://github.com/ortus-solutions/heroku-buildpack-commandbox) will allow you to deploy your CFML applications directly to [Heroku](https://www.heroku.com/) (or to [Dokku](http://dokku.viewdocs.io/dokku/) hosts) using CommandBox to manage your CFML engine. It allows you to specify your custom server configuration settings using the CommandBox server API, avoiding additional script and configuration files during the Heroku deployment process.
 
 ## Usage
 

.gitbook/assets/shalom (2) (2) (2) (2) (2) (2) (2) (1) (1).jpg

@@ -19,3 +19,13 @@ CommandBox's expressive CLI gets its power from commands. You can create your ow
 Customizing the internals of CommandBox is achieved via an event model known as interceptors. What this means is that at pre-defined points in the lifecycle of the shell, command execution, or web server starting, the CLI broadcasts events that you can listen to. This lets you provide custom error handling, special server handling, or modify command output. Interceptors are packaged up in modules and can be combined with custom commands and config settings for fully-configurable shell add-ons.
 
 [Read about **Developing Interceptors** here.](interceptors/)
+
+## Developer Mode
+
+The `developerMode` setting reloads shell before each command to help testing changes to CommandBox core or modules.
+
+```
+config set developerMode=true
+```
+
+It will prevent you from needing to use the `reload` command, but it will cause a delay before each command.  Don't forget to turn this back off when you're done.

about-this-book.md

@@ -40,7 +40,7 @@ config set server.defaults.trayEnable=false
 
 ## Full  Control
 
-CommandBox's embedded server does not require any prior installations of any CFML engine to work. It does not use Apache, IIS, or Nginx. A very lightweight Java web server called [Undertow](http://undertow.io) is used and a context is programmatically deployed via a WAR file.
+CommandBox's embedded server does not require any prior installations of any CFML engine to work. It does not use Apache, IIS, or Nginx. A very lightweight Java web server called [Undertow](http://undertow.io/) is used and a context is programmatically deployed via a WAR file.
 
 You should still have all the options you need to set up most local development servers quickly. The web-based administrator is available to you where you can edit any setting, add data sources, CF mappings, and mail servers. To see a list of all the parameters you can pass to the `server start` command, refer to the [CommandBox API Docs](http://apidocs.ortussolutions.com/commandbox/5.0.0/index.html?commandbox/system/modules\_app/server-commands/commands/server/start.html) or run `server start help` command directly from the CLI.
 

config-settings/endpoint-settings.md

@@ -84,5 +84,41 @@ server set runwar.args="--cache-servlet-paths=true"
 
 Standard Adobe ColdFusion installations have a similar cache of "real" paths from the servlet context that is tied to a setting in the administrator called "Cache Webserver paths" but that setting is not available and does not work on CommandBox servers for some reason..
 
+## Custom Log Pattern
 
+The Java logging library Log4j is used for servers' log files and console logs.  The default logging pattern is:
 
+```
+[%-5p] %c: %m%n
+```
+
+You can customize this with any valid Log4j pattern layout, which you can find here:
+
+{% embed url="https://logging.apache.org/log4j/1.2/apidocs/org/apache/log4j/PatternLayout.html" %}
+
+This would put the date/time into every log message:
+
+```
+server set runwar.args='--log-pattern "[%-5p] %d{dd MMM yyyy HH:mm:ss.SSS} %c: %m%n"'
+```
+
+This would log ONLY the message with no severity or category:
+
+```
+server set runwar.args='--log-pattern "%m%n"'
+```
+
+Note, the color coding of log lines in CommandBox is dependent upon the default Log4j pattern layout.
+
+## Disable Resource Manager Change Listener
+
+There is an XNIO file system watcher started for the web root and any virtual directories in your server. This change listener serves two purposes:
+
+* Cache invalidation for the servlet path lookup matching
+* Cache invalidation for welcome file lookups
+
+In normal operations you should have no issues with this, but it has been observed starting a server in a web root with a very large number of files (like over 200,000) can consume a lot of resources, and even cause out of memory errors.  The change listener in Undertow can be disabled with this setting:
+
+```
+server set runwar.args='--resource-manager-file-system-watcher=false'
+```

config-settings/misc-settings.md

@@ -49,6 +49,28 @@ server set JVM.args="-XX:MaxGCPauseMillis\=200"
 server show JVM.args
 ```
 
+JVM args can also be set an array of strings which prevents you from needing to escape or quote anything.  
+
+```
+{
+  "jvm" : {
+    "args" : [
+       "-XX:+UseG1GC",
+       "-XX:-CreateMinidumpOnCrash",
+       "--add-opens=java.base/java.net=ALL-UNNAMED"
+    ]
+  }
+}
+```
+
+Or via the CLI like so:
+
+```
+server set jvm.args=["-XX:+UseG1GC"]
+server set jvm.args=["-XX:-CreateMinidumpOnCrash"] --append
+server set jvm.args=["--add-opens=java.base/java.net=ALL-UNNAMED"] --append
+```
+
 ## Ad Hoc Runwar Options
 
 You can specify ad-hoc options for the underlying Runwar library using the `RunwarArgs` parameter.
@@ -63,3 +85,25 @@ In `server.json`
 server set runwar.args="--sendfile-enable false"
 server show runwar.args
 ```
+
+Runwar args can also be set an array of strings which prevents you from needing to escape or quote anything.  
+
+```
+{
+  "runwar" : {
+    "args" : [
+      "--runwar-option",
+      "value",
+      "--runwar-option2",
+      "value2"
+    ]
+  }
+}
+```
+
+Or via the CLI like so:
+
+```
+server set runwar.args=["--runwar-option","value"]
+server set runwar.args=["--runwar-option2","value2"] --append
+```

deploying-commandbox/README.md

@@ -40,6 +40,14 @@ server show web.SSL.enable
 server show web.SSL.port
 ```
 
+#### Setting SSL Enabled protocols
+
+You can customize what SSL protocols your HTTPS listener will respond to with the following XNIO option.  Supply a comma-delimited list of valid protocols.  
+
+```
+server set runwar.XNIOOptions.SSL_ENABLED_PROTOCOLS=TLSv1.3,TLSv1.2
+```
+
 ### HTTP/2
 
 HTTP/2 is a newer standard of HTTP supported by all modern browsers.  HTTP/2 is enabled by default any time you are using an HTTP/HTTPS listener, however all major browsers will only allow the server to negotiate HTTP/2 over an HTTPS connection.  HTTP/2 runs over the same port and only changes the exchange between the server and browser.  You can disable HTTP/2 support like so:

deploying-commandbox/heroku.md

@@ -33,10 +33,12 @@ To set an XNIO option that CommandBox doesn't already expose with a first-class
 
 ```bash
 server set runwar.XNIOOptions.WORKER_NAME=myWorker
+server set runwar.XNIOOptions.SSL_ENABLED_PROTOCOLS=TLSv1.3,TLSv1.2
 ```
 
 You can also set global XNIO objects that will apply to all servers.  Global options will be appended to server-level options.
 
 ```bash
 config set server.defaults.runwar.XNIOOptions.WORKER_NAME=myWorker
+config set server.defaults.runwar.XNIOOptions.SSL_ENABLED_PROTOCOLS=TLSv1.3,TLSv1.2
 ```

developing-for-commandbox/README.md

@@ -122,3 +122,62 @@ server log myServername --follow --rewrites
 ```
 
 Your rewrites log will be auto-rotated every 10MB. The amount of information that appears in the rewrites log will be affected by the `--debug` and `--trace` flags when you start the server.
+
+## Request Dumping
+
+There is a feature you can use to dump all the header details for an HTTP request and response in the form of an Undertow handler called `dump-request()`.  Just include the following server rule in your `server.json`
+
+```javascript
+{
+  "web" : {
+    "rules" : [
+      "dump-request()"
+    ]
+  }
+}
+```
+
+To fire only for certain requests, you can pair the handler with any predicate you wish:
+
+```
+{
+  "web" : {
+    "rules" : [
+      "regex('(.*).cfm') -> dump-request()"
+    ]
+  }
+}
+```
+
+Then start your server with the `--console` flag or tail the console with `server log --follow` and you'll see info like this for each request:
+
+```
+Request Dump:
+----------------------------REQUEST---------------------------
+               URI=/bar.cfm
+ characterEncoding=null
+     contentLength=-1
+       contentType=null
+            header=Accept=text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image/webp,image/apng,*/*;q=0.8,application/signed-exchange;v=b3;q=0.9
+            header=Accept-Language=en-US,en;q=0.9,nb;q=0.8,da;q=0.7
+            header=Accept-Encoding=gzip, deflate, br
+            header=User-Agent=Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/99.0.4844.84 Safari/537.36
+            header=Host=127.0.0.1:55599
+            locale=[en_US, en, nb, da]
+            method=GET
+          protocol=HTTP/1.1
+            scheme=http
+              host=127.0.0.1:55599
+        serverPort=55599
+          isSecure=false
+--------------------------RESPONSE--------------------------
+     contentLength=3
+       contentType=text/html;charset=UTF-8
+            header=Connection=keep-alive
+            header=Content-Type=text/html;charset=UTF-8
+            header=Content-Length=3
+            header=Date=Thu, 31 Mar 2022 22:55:19 GMT
+            status=200
+
+==============================================================
+```

embedded-server/README.md

@@ -14,7 +14,7 @@ One minor difference to keep in mind is Lucee server and Adobe ColdFusion use a
 5.3.4.80
 ```
 
-However, [CommandBox](https://commandbox.ortusbooks.com) and [ForgeBox](https://www.forgebox.io) use the [npm-flavored semantic versioning](https://commandbox.ortusbooks.com/package-management/semantic-versioning) (semver) which is slightly different.  Basically the build ID is moved to the end after a plus (+) sign.
+However, [CommandBox](https://commandbox.ortusbooks.com/) and [ForgeBox](https://www.forgebox.io/) use the [npm-flavored semantic versioning](https://commandbox.ortusbooks.com/package-management/semantic-versioning) (semver) which is slightly different.  Basically the build ID is moved to the end after a plus (+) sign.
 
 ```bash
 <major>.<minor>.<patch>[-<preReleaseID>]+<build>
@@ -76,7 +76,7 @@ server start [email protected]+48
 
 ## **Lucee Light builds on ForgeBox**
 
-Lucee has a modular core and comes bundled with a bunch of extensions that approximate the functionality that comes bundled with Adobe ColdFusion.  But that means you are loading the Hibernate libraries, PDF libraries or JDBC drivers even if you don't need them. There is a second type of Lucee server called "Lucee Light" which contains all the core engine, but with zero extensions.  People creating custom docker builds for example will start with Lucee Light and then add back only the extensions their app needs.  To get a feel for all the Lucee extensions available, see [this page](https://download.lucee.org) that lists all official extensions.
+Lucee has a modular core and comes bundled with a bunch of extensions that approximate the functionality that comes bundled with Adobe ColdFusion.  But that means you are loading the Hibernate libraries, PDF libraries or JDBC drivers even if you don't need them. There is a second type of Lucee server called "Lucee Light" which contains all the core engine, but with zero extensions.  People creating custom docker builds for example will start with Lucee Light and then add back only the extensions their app needs.  To get a feel for all the Lucee extensions available, see [this page](https://download.lucee.org/) that lists all official extensions.
 
 We're now publishing CF Engines to ForgeBox based on the Lucee Light builds which allows you to start up a Lucee Light server. These are under a ForgeBox package named `lucee-light` and we've also backfilled all the same versions that exist for the normal `lucee` engine.  Note, the three bullets points above apply to Lucee Light as well,  Just replace `lucee` with `lucee-light` and you're good to go.
 

embedded-server/configuring-your-server/experimental-features.md

@@ -27,11 +27,11 @@ You're well on your way now. While you wait for arrival you might want to secure
 
 ## 2. Unzip & First Run
 
-![Setup](<.gitbook/assets/open\_package (2) (2) (2) (2) (2) (2) (2) (1).png>)
+![Setup](<.gitbook/assets/open\_package (2) (2) (2) (2) (2) (2) (2) (1) (1).png>)
 
 Your CommandBox is sent to you via a zip archive. Decompress the archive to a location of your choice. The **No JRE Included** download will only have one file in it named `box`. For Windows users, this will be an `exe` file. For unix-based users, it will be an executable binary. The **With JRE Included** version will have a `jre` folder. You can move `box.exe`, but keep the `jre` folder in the same relative location as the executable so it can be found.
 
-![CommandBox Icon](<.gitbook/assets/box\_icon (2) (2) (2) (2) (2) (2) (2) (1).png>)
+![CommandBox Icon](<.gitbook/assets/box\_icon (2) (2) (2) (2) (2) (2) (2) (1) (1).png>)
 
 Now just double click the file from your GUI, or execute it via a console window. This will start a short, quick, one-time process of unpacking CommandBox into your user's home directory. Congratulations, CommandBox is now installed! You'll still run the same executable binary every time you want to use the CLI, but the extraction process won't need to happen again.
 
@@ -41,7 +41,7 @@ The green `CommandBox>` prompt is what we call the _interactive shell_. Type `ex
 
 ## 3. Setup & Usage
 
-![Start Using](<.gitbook/assets/run (1) (1) (1) (1) (2) (2) (2) (2) (2) (2) (1).png>)
+![Start Using](<.gitbook/assets/run (1) (1) (1) (1) (2) (2) (2) (2) (2) (2) (1) (1).png>)
 
 To open up the interactive shell at any time, just double click on the `box` executable. If you prefer to stay in your OS's native shell, then just place the `box` file in your system path and add it before any CommandBox commands like so:
 

embedded-server/configuring-your-server/jvm-args.md

@@ -11,7 +11,7 @@ What do you want to do with VSC?
 
 ## Installing VSCode
 
-This IDE has it's own domain. ( [https://code.visualstudio.com/](https://code.visualstudio.com) ) with downloads for **macOS**, **Windows** and **Linux** on the home page. :+1:
+This IDE has it's own domain. ( [https://code.visualstudio.com/](https://code.visualstudio.com/) ) with downloads for **macOS**, **Windows** and **Linux** on the home page. :+1:
 
 ![Visual Studio Code Snapshot](https://code.visualstudio.com/home/home-screenshot-win-lg.png)