I've been just giddy testing the new Multi-server support in our latest CommandBox 3.1.0 beta.  I never knew starting up a ColdFusion 9 server could be so exciting.  Well it is when you just have to type:

CommandBox> start [email protected]

That's it. You don't need a single thing installed prior other than CommandBox.  Everything necessary will be downloaded and, depending on your internet connection speeds, you'll have a new server running in less than 60 seconds.  Don't worry, it's not limited to ColdFusion 9.  We also are supporting Adobe ColdFusion 10, 11, and 2016 as well as Railo Server 4.2 and Lucee Server 5.0 rc!

If you didn't see my post from a few days ago, I reviewed all the new features that are part of the CommandBox 3.1.0 beta release.  Take a minute to review them here as what I'm writing here builds on it (at least the semver and ForgeBox stuff)

http://www.codersrevolution.com/blog/exciting-new-features-in-the-commandbox-310-bleeding-edge

Ok, Done?  Great.  Let's review the new server features.  Remember, this is all in beta so you're taking your life in your own hands to test this out.  :)

Overview

Starting up a CFML web server has been one of the main features of CommandBox.  

CommandBox> cd /var/www/mySite
CommandBox> server start

The first version ran on Railo and started Railo servers.  After we switched CommandBox to run on Lucee, the internal servers were Lucee.  The internal CLI and servers that you start have a separate server context and settings, but they share the same jars so the servers you can start are always limited to the version of Lucee that ships with CommandBox.  

This has all changed now with some amazing changes Denny Valiant has help us with.  CommandBox can now start up any WAR file.  If you're not familiar with WARs, there just a J2EE standard for zipping an entire java app so you can deploy it.  This allows us to start any ColdFusion engine that we can create a WAR file for, which is pretty much all of them.  This means that you can test your code on pretty much any CFML engine you want and you don't have to worry about installing any of them.  As long as you have CommandBox, you're just seconds away from starting up the engine of your choice-- or several engines at the same time.

Supported Engines

Here are the CF engines you can currently start:

  • Adobe ColdFusion 2016.0.0+297996
  • Adobe ColdFusion 11.0.0+289974
  • Adobe ColdFusion 10.0.12+286680
  • Adobe ColdFusion 9.0.2+282541
  • Lucee Server 4.5.2.018 (embedded, so no download needed)
  • Lucee Server 5.0.0-SNAPSHOT+243
  • Railo Server 4.2.1+008

Note that since Lucee 5 is a pre-release build, it won't get used by default unless you specifically tell CommandBox that you're willing to accept a pre-release server.  This is a little Semver "feature" that might not be super obvious at first.  The following semver range will match Lucee 5.0.0 because it has a pre-release identifier in it.  Otherwise, you'll only match stable versions.  

CommandBox> start [email protected]

We can add new engines at any time. Once they are put on ForgeBox, they'll be immediately available for installation.  See Custom Engines below for more.

Syntax

There are two new parameters to the server start command as well as two matching server config settings.

  • CFEngine - This can be any valid endpoint ID.  Since we've loaded the cf engines into ForgeBox, you can use the format [email protected] where the version is optional.
  • WARPath - Let's say you don't want to start a CF engine at all, or you have a custom war local on your hard drive.  Specify the path to any valid compressed or exploded WAR here.  Mutually exclusive with cfengine.

We decided to use ForgeBox to store the registry of what CF engines you can start a server with.  This works great with our new semver support since you can specify just the engine name and get the latest stable version.  Or you can specify a version range just like you would for any other ForgeBox entry when using the "install" command

Here are some examples:

# Start the default engine
CommandBox> start

# Start the latest stable Railo engine
CommandBox> start cfengine=railo

# Start a specific engine and version
CommandBox> start [email protected]

# Start the most recent Adobe server that starts with version "11"
CommandBox> start [email protected]

# Start the most recent adobe engine that matches the range
CommandBox> start cfengine="[email protected]>9.0 <=11"

All the standard semver rules apply, and the best matching engine version will be downloaded and installed for you.  All downloads only happen once and the engines are stored in your CommandBox artifacts folder.  You can see them using the standard artifacts commands:

CommandBox> artifacts list
CommandBox> artifacts clean --force

Starting a WAR is pretty straightforward.  If you've unzipped the WAR into a folder, simply use the following:

CommandBox> start WARPath=/var/www/myExplodedWAR

Note, the war doesn't even need to include a CF engine.  It can be any Java J2EE applicationo.

Configuration

The CFEngine and WARPath start parameters also have matching properties in your server.json file. 

CommandBox> server set app.cfengine=adobe
CommandBox> server set app.WARPath=/var/www/my-app

Would create the following server.json:

{
    "app":{
        "cfengine":"adobe",
        "WARPath":"/var/www/my-app"
    }
}

This means you can package up an app and send to anyone to be able to start it with the exact CF server it needs to run without having to worry about what they have installed on their computer already.

We also have a nice new feature that allows you to default any server.json property at a global CommandBox level.  Just set a config setting under server.defaults that matches the same JSON in your server.json.

CommandBox> config set [email protected]pshot

Now all servers will start with Lucee 5 by default unless otherwise told otherwise!

Custom CF Engines

Not happy with the list of engine versions we've given you so far?   Want to create your own super-custom CF engine build and share it with the world?  No worries, because the CFEngine parameter can be any valid endpoint ID.  That means it can be an HTTP URL, a Git repo, a local folder path to your company's network share, or a custom ForgeBox entry you've created.  As long as that endpoint resolves to a package that contains these files, you're good:

  1. box.json
  2. Engine.[zip|war] (file name doesn't matter)

We'll download the package, unzip it and use the WAR/zip file as the cf engine for your app.  Normally, the artifacts cache isn't used for non-ForgeBox packages, but we'll only download the CF Engine once per server and then assume the file hasn't changed.  You'll need to forget the server to trigger a new download.  If you want to play with an existing WAR, grab it from your CommandBox artifacts cache, unzip the package, then unzip the war/zip fille, modify it and then zip it all back up the way it came. 

Here's an example of starting up a web server using a direct download link to a package containing a WAR file:

CommandBox> start cfengine=http://downloads.ortussolutions.com/adobe/coldfusion/9.0.2/cf-engine-9.0.2.zip

Test, Please

This is a huge feature for us and involves a lot of major changes to the CommandBox core.  Props go to Denny Valiant for his work on this.  Please help us test by grabbing the bleeding edge of CommandBox and kicking the tires.  Also, remember that CommandBox 3.1.0 beta is using our Staging ForgeBox server, so the list of packages may be a little out of date.  Also, any packages you publish with our new publish command won't exist on the site once we go live.

http://integration.stg.ortussolutions.com/artifacts/ortussolutions/commandbox/3.1.0/

Hit us up on the mailing list or CFML Slack with questions.