We are pleased to announce the final release of CommandBox 3.5.0.  This is a minor release, with 53 completed tickets-- most of which are server enhancements focused on making server management and configuration easy across any engine.  This version has been in release candidate for a few weeks and has received a lot of testing.  As a minor release, there are no compatibility-breaking changes to any of the public APIs, but there has been some necessary restructuring of the back end bits related to starting servers that could possibly have an effect on you if you have any scripts or custom modules based on the previous folder structure of some server installs.  We recommend all users upgrade to this new version, but take a minute to review the changes so you can fully utilize the new features.

Installation

You can download the latest CommandBox binary directly from our download page.  If you use the Debian or RPM packages, we've also updated our binary repos.  And for Mac users, HomeBrew should reflect the new version as soon as the Brew folk accept our pull request.

Docs

You can read the 3.5.0 API docs here for any commands that changed:

http://apidocs.ortussolutions.com/commandbox/current

The new 3.5 docs are also written and available in GitBook

http://ortus.gitbooks.io/commandbox-documentation/content/

New Stuff

Here's an overview of all the new changes you have to look forward to in CommandBox 3.5.0.  For a more comprehensive overview, please read the blog post that announced the release candidate.

https://www.ortussolutions.com/blog/commandbox-35-release-candidate-ready-for-testing

CLI Shell

We also made the following improvements to the CLI shell environment

  • You don't need to escape an equals sign that's part of a quoted parameter value
  • cp command will create destination directories
  • Windows paths that start with \ or / will be treated as absolute (like DOS works)
  • All OS's will expand ~ to the current user's home directory

Tail Command

The tail command used to only take a file as input, but now you can pipe raw text in as well.

CommandBox> forgebox search | tail lines=50

When tailing a file, you can specify the --follow flag and any new text added to the file will live stream to your console until you press Ctrl-C to stop.  This is perfect for tailing application logs while your code is running to see new entries.

CommandBox> tail myFile.log --follow
CommandBox> system-log | tail --follow

The server log command also has a new --follow flag added to it which will live stream a running server's console log to the shell until you press Ctrl-C to stop it.

CommandBox> server log --follow

Package Management

The artifact storage location is now customizable thanks to Chris Schmitz, allowing you to store your artifacts on another drive, or even a network share so your coworkers can all use the same "local" copies.

CommandBox> config set artifactsDirectory=/path/to/artifacts

CommandBox will always re-download snapshot versions of packages to make sure you get a fresh version.  

CommandBox> install myPackage@1.2.3-snapshot

When you try to install a package and CommandBox is offline, instead of giving up, we'll now look in your local artifacts cache for a satisfying version.  If we find a package that works in your artifacts, we'll install it instead.  

Server Starting

We added a few new ways to start up a server.  You can use the --debug flag when starting a server to see additional information and the foreground process also waits for the server to start before finishing.  Now when starting in debug mode this output will stream to the console as it becomes available instead of showing up all at the end.  This is great to troubleshoot errors that are happening on server start as well as finding the slow parts of the startup sequence.

CommandBox> server start --debug

By default, your servers fire up in a new process that runs independently from the CLI.  There is now a new flag called --console that will start the server up in the foreground and stream the console output to the CLI for you to watch.   The start command will not end and will keep streaming the console output until you press Ctrl-C to stop it.  You can also use --debug alongside the console flag for even more information.

CommandBox> server start --console
CommandBox> server start --console --debug

Server Welcome Files

If you have an app that uses a default welcome file other than index.cfm, you can control that now.

CommandBox> server set web.welcomeFiles="go.cfm,main.cfm,index.cfm,index.html"

Better SES URLs

This is one that you take for granted if you've always used Adobe ColdFusion, but for any CF server not running on Adobe's custom version of Tomcat, you can't use SES URLs in a subfolder like this without adding custom mappings to your web.xml:

site.com/myFolder/index.cfm/home/login

We've added just a dash of servlet fairy dust that now makes this possible.  Note, if you want to hide the index.cfm with URL rewrites, you'll need a custom rewrite config for it to work in a subfolder.

Server Configuration

All server engines and versions have been standardized to install into the same reliable directory structure to make it easier for you to script config file replacements.  

  • For Adobe CF WARs, the xml config files are located in the WAR here: /WEB-INF/cfusion/lib/neo.*.xml
  • For the Lucee server context, the xml config file is located in the WAR here: /WEB-INF/lucee-server/context/lucee-server.xml
  • For the Lucee web context, the xml config file is located in the WAR here: /WEB-INF/lucee-web/lucee-web.xml.cfm

To find the folder where your WEB-INF lives (as well as lots of other information about your server) you can use the server info command to get useful properties about a starting or started server.

# Find the "home" directory for a server (where the WEB-INF lives)
CommandBox> server info property=serverHomeDirectory

# Find the out log file
CommandBox> server info property=consoleLogPath

# Get all possible values as JSON
CommandBox> server info --JSON

Combining these allows you to do some nice one-liners like scripting out the copying of config settings when the server starts up.  Read more about this here:

https://ortus.gitbooks.io/commandbox-documentation/content/embedded_server/copy-configs.html

Custom Server Home

Until now you've had to live with the special directory that CommandBox uses to install your servers into.  Now you can get full control over where the server goes which is perfect for creating a folder "seeded" with config files that you want the server to use when it first starts.  This trick (with some clever Git ignores) will also allow you to commit changes to your config files back to the repo while ignoring the rest of the engine.

  • Customize Lucee's server context folder with the serverConfigDir setting
  • Customize Lucee's web context folder with the webConfigDir setting
  • Customize where the entire WAR explodes to for any server with the serverHomeDirectory setting

This is very powerful since it gives you full control over the server deployment.  Read more about this here.

https://ortus.gitbooks.io/commandbox-documentation/content/embedded_server/custom-server-home.html

Release Notes

Bug

  • [COMMANDBOX-236] - `box reload` doesn't clear background colors from buffer on Windows
  • [COMMANDBOX-248] - tab completion doesn't always work on paths
  • [COMMANDBOX-500] - CommandBox timeout is shorter than runwar timeout when starting Adobe servers
  • [COMMANDBOX-505] - BOM interferes with commandbox.properties
  • [COMMANDBOX-507] - Staring server with defautlPort in box.json, adds optional keys back in.
  • [COMMANDBOX-509] - Ignore equals in a quoted parameter
  • [COMMANDBOX-522] - Improve error message when endpoint fails installing server
  • [COMMANDBOX-526] - Use hostname for "coldbox reinit"
  • [COMMANDBOX-533] - Error starting CommandBox in some instances
  • [COMMANDBOX-539] - "run" expressions contain line break on Linux
  • [COMMANDBOX-542] - Regression in piping input from OS console
  • [COMMANDBOX-543] - Piping a file of commands with a BOM into box fails
  • [COMMANDBOX-544] - package set doesn't always set what you expect
  • [COMMANDBOX-545] - The `commandbox-home` when used in symbolic link mode fails on mac

New Feature

Improvement