If a server isn't starting, the first thing to run is the server log command. It will show you the console log for that server. Note, this dumps the entire log file to the console, which may be very large. We recommend using the tail or --follow tricks below.
Tailing and Following logs
If the log is very large, use the tail command to just see the last few lines of it.
To get a live stream of the console log from a running server, use the --follow flag and the command will continue streaming new lines to the console until you press Ctrl-C to stop.
You can also look at your server's access log (if enabled) and rewrite log (if enabled).
Start server in console mode
You can use the --console flag to the server start command to start a server in the foreground. The console log will be live-streamed to the CLI and the log will continue streaming as long as the server is running. Press Ctrl-C to stop the server and stop streaming the log file.
Debug Logging
You can get additional information about a server start with the --debug flag. When debug is set, the start command will not exit immediately, but wait for the server to come up and live stream the debugging information and server logs to the console while the server is coming up.
Maximum logging! (trace)
You may still really be having issues getting your server to start up correctly due to a setting not getting picked up, rewrites not working, or maybe a jar not loading. You can "drink from the firehose" so to speak by turning on trace level logging. This works best when starting the server via the console so you can watch the logging as it streams past.
Welcome Files
The default welcome files are the usual index.cfm, index.htm, index.html, etc but you can override this with the welcomeFiles setting in your server.json by providing a comma-delimited list of files that you would like CommandBox to look for when a user hits a directory on a running server.
server set web.welcomeFiles='go.cfm,main.cfm,index.html'
This setting is a complete override of the defaults, so you need to specify the full list.
Directory Browsing
By default, a CommandBox server will not show the contents of a directory that doesn't have an index file. You can enable directory browsing for a single server with
And you can enable it for all servers by default with
server log
server log serverName
server set web.directoryBrowsing=true
config set server.defaults.web.directoryBrowsing=true
server log | tail
server log | tail lines=100
server log --follow
server log --follow -access
server log --follow --rewrite
server start --console
server start --debug
server start --debug --console
server start --trace --console
Embedded Server
One of the most useful features of CommandBox is the ability to start an ad-hoc server quickly and easily. Any folder on your hard drive can become the web root of a server. To start up the server, cd into a directory containing some CFML code, and run the start command. An available port will be chosen by default and in a few seconds, a browser window will open showing the default document (index.cfm).
To stop the embedded server, run the stop command from the same directory.
OS Integration
You can start as many embedded server instances as you want. Each running server will add an icon in your system tray with the logo of your currently running engine. Click on it for options:
Stop Server
Open Browser
Open Admin
Disable the tray icon
If you don't want the tray integration, then you can turn it off in your server.json with this setting.
Or turn it off at a global level in your config settings.
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 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 or run server start help command directly from the CLI.
Environment Variables
Any ComandBox environment variables present in the shell will automatically be passed to the environment of the server process. This means, given an example like this:
The CFML code running that server process will be able to "see" the foo environment variable.
GZip Compression
The web server in CommandBox is capable of enabling GZIp compression to reduce the size of HTTP responses. To enable GZip compress on your CommandBox server, add a web.gzipEnable setting in your server.json file.
CommandBox> cd C:\sites\test
CommandBox> start
CommandBox> stop
server set web.gzipEnable=true
Basic Authentication
CommandBox's web server supports enabling Basic Auth on your sites.
server set web.basicAuth.enabled=true
server set web.basicAuth.users.brad=pass
server set web.basicAuth.users.luis=pass2
That will create the following data in your server.json, which will be picked up the next time you start your server.
By Default, your servers start using the same version of Java that the CommandBox CLI is using. For people needing to run Adobe ColdFusion 9, or who just want to do some testing on different JREs, you can point each of your servers at a custom JRE and CommandBox will use it when starting the server.
if you already have a JRE downloaded somewhere on your hard drive, you can manually point the server at it, or you can simply tell CommandBox which version of java you'd like, at it will automatically download that version of OpenJDK for your server to use (if it's not already downloaded)
Manual Java Config
Configuring Your Server
CommandBox allows you full control over the servers you start. This includes the port and host, custom JVM args, URL rewriting, web aliases, custom error pages, and custom welcome files.
Ways to provide configuration
Configuration can be set at several different levels:
Custom Error Pages
You can customize the error page that CommandBox servers return. You can have a setting for each status code including a default error page to be used if no other setting applies.
Create an errorPages object inside the web object in your server.json where each key is the status code integer or the word default and the value is a relative (to the web root) path to be loaded for that status code.
This is what you server.json might look like:
server set trayEnable=false
config set server.defaults.trayEnable=false
set foo=bar
server start
Passed as parameters to the server start command
Stored in a server.json file for that server
Global defaults in the server.defaults config setting
Internal defaults from the ServerService
Settings will be used in that order. Also, any parameters passed to the start command will automatically be saved to your server.json file unless you pass the --noSaveSettings flag.
File path handling
A lot of settings used to start a server involve file paths. Paths starting with a drive letter like C:/, a UNC network path like \\, or a leading slash like / are considered absolute paths and will not be expanded. Try to avoid absolute paths if you want to make your server config portable.
Paths that start with a file/folder name like foo/bar.jar or ../../lib/my.jar are relative and the root folder that they are relative to depends on where there are specified.
If the path is passed as a parameter to the start command, the path is relative to the current working directory
If the path is in the server.json file, it is relative to the folder containing the JSON file. (Remember the server.json doesn't have to be in the web root!)
If the path is in a global server.defaults config setting, it is relative to the web root of the server.
Point CommandBox to an existing java install like so:
To set the default version of Java for all the servers you start on your machine, use the global config setting defaults.
Automatic Java Download
To let CommandBox take over and acquire Java for you, pass an installation endpoint ID to the start command
or set it in your server.json
or set a default for all servers
To review what possible IDs you can use to dial in your exact Java version, read the docs on our Java endpoint. You don't need to manually install Java-- CommandBox will do that for you. You just need to provide the ID so CommandBox knows what you want.
Java Namespace
To make it easier for you to manage the Java installations CommandBox makes for you, we have a namespace of commands you can use. The Java versions CommandBox installs automatically for your servers to use are stored in a folder under your CommandBox home. CommandBox manages this folder for you. You can change where the system Java installation go like so:
java search
Search the AdoptOpenJDk API for available versions of Java for you to use.
You can filter the version, jvm, os, CPU arch, type, and release. Most of those parameters default to match your local system. For instance, running this command on Windows will only return Windows versions. To open up the search, pass nothing to that filter.
java list
List the installed Java installations for you to start servers with. If you have set a global default Java version it will be marked in the list.
java setDefault
You may change the global default Java version for your servers with this command.
The ID follows the format from the Java endpoint. If the version you set as the default isn't installed yet, CommandBox will install it for you the next time a server starts or you can use the --install flag.
java install
You can pre-install a Java version so it's ready to go the next time you start a server with this command. This differs from the normal package install command in that it doesn't install to the current working directory, but into the core server JRE folder that CommandBox manages for you. Use the --setDefault flag to also set the newly installed Java version as the global default for all servers.
java uninstall
You can remove a java installation so it doesn't take up space on your hard drive. Use the FULL ID that shows in the java list command to uninstall.
Note, the download will still be in your artifacts cache. Also, if you start a server up again that asks for a Java installation you've uninstalled, CommandBox will simply re-install it again.
You can set error pages via the server set command like this:
Accessing error variables
If your error page points to a CFM file, you can get access to the original path being accessed for 404s and the error that was thrown for 500s. To see all the request headers that are available, use the following snippet of code:
An example of getting the original missing path in a 404 would look like this:
server set jvm.javaHome="C:\Program Files\Java\jdk1.8.0_25"
config set server.defaults.jvm.javaHome="C:\Program Files\Java\jdk1.8.0_25"
server start javaVersion=openjdk8
server set jvm.javaVersion=openjdk8
config set server.defaults.jvm.javaVersion=openjdk8
config set server.javaInstallDirectory=C:/path/to/JREs/
java search version=openjdk8
java search version=openjdk8 os=
java list
server java setDefault openjdk11
server java install openjdk11 --setDefault
server java uninstall openjdk9_jre_x64_windows_hotspot_jdk-9.0.4+11
req = getPageContext().getRequest();
names = req.getAttributeNames();
while( names.hasMoreElements() ) {
name = names.nextElement();
writeDump( name & ' = ' & req.getAttribute( name ) );
}
var originalPath = getPageContext().getRequest().getAttribute( "javax.servlet.error.request_uri" );
Server Processes
It's important to note that each server you start opens a new Java process on your host operating system. This allows each server to have it's own settings and configuration independent of any other server. Start as many as you need and simply stop them when you're done. Just keep in mind each server gets its own heap space so keep an eye on your available RAM.
Server Runs Independant of CLI
The embedded server instances are also a separate process from the actual CommandBox CLI process, which also runs on Java. This means you can open the interactive shell, start a few servers, then quit the shell, yet the servers will still continue to run. You can use the CLI to issue a stop
Working with server.json
Interacting with the server.json file uses the commands server set, server show, and server clear, which work the same as the package set/show/clear commands.
Set the port for your server:
View the port:
Remove the saved setting:
command in the servers web root, or just right click on the tray icon.
There is currently no way to have servers start automatically when your computer boots, though there's nothing preventing you from setting up a local script to run the start commands for you.
WEB-INF
You may be used to having your server's WEB-INF folder living in your web root. The CommandBox embedded server still has a dedicated WEB-INF folder for each server you start, but it lives under the main CommandBox installation directory in your user folder. Changes you make to the WEB-INF such as adding jars or new tas will be persisted until you issue a server forget command.
server set web.http.port=8080
server show web.http.port
server clear web.http.port
JVM Args
The following JVM Args are supported when starting the embedded server.
heapSize
You can set the max heap size the server is allowed to have (-Xmx) by passing the heapSize parameter to the start command. This parameter defaults to megabytes but you can specify any valid suffix.
In server.json
minHeapSize
You can set the starting heap size for the server (-Xms) by passing the minHeapSize parameter to the start command. This parameter defaults to megabytes but you can specify any valid suffix.
In server.json
Ad Hoc JVM Args
You can specify ad-hoc JVM args for the server with the JVMArgs parameter.
In server.json
Ad Hoc Runwar Options
You can specify ad-hoc options for the underlying Runwar library using the RunwarArgs parameter.
In server.json
Multi-Engine Support
You can specify the CFML engine via the command line arguments:
This will start an Adobe ColdFusion 9 server in your webroot. That's it!
By default, CommandBox uses the cfengine slug to search for the engine on ForgeBox. The format is slug@version where the version is optional. Ortus Solutions maintains the versions of the engines available on ForgeBox.
Supported engines are:
Packaging Your Server
server.json allows you to package up an app that requires special start settings such as rewrites, JVM args, or heap size, and anyone can run it with the same settings you do by simply typing server start. Make sure to not deploy the server.json file to your production server where it may be web-accessible.
Storing server.json outside the web root
REST Servlet
The built in REST implementation in Adobe ColdFusion and Lucee is usually something you either love or hate. If you love it, you can enable it and customize the paths so it doesn't collide with your app's routes. if you hate it, you can turn it off. The REST servlet will be disabled unless you include a setting like so:
Note that the above setting will take over any URLs starting with /rest or api and you cannot use those routes or folders in your code. This is why it's handy to be able to modify or remove these. On a typical server, this is done via the web.xml, but CommandBox will do it all for you with just the setting above.
start heapSize=1024
External Web Server
You can place CommandBox downstream behind another external web server if you wish. Here is an overview of how to do that.
Microsoft IIS
Apache HTTP
Nginx
server set app.restMappings=/rest/*,/api/*
Adobe ColdFusion 9 **
Adobe ColdFusion 10
Adobe ColdFusion 11
Adobe ColdFusion 2016
Adobe ColdFusion 2018
Railo 4.2
Lucee 4.5
Lucee 5
Here are some examples:
Engines are downloaded and stored in your CommandBox artifacts folder. You can view your engines and clear them using the standard artifacts commands:
** Note: Adobe ColdFusion 9 does not support the latest Java 8. To run ColdFusion 9 you must use an older version of CommandBox 3.x on Java 7 or run CommandBox 4.x on Java 8 update 92 or earlier. Several people are doing this, but beware your mileage may vary.
ColdFusion Admin settings
While Lucee asks for a password the first time running the admin, ColdFusion requires a username and password when CommandBox sets it up. The default username and password for the Adobe ColdFusion servers used are:
Username: admin
Password: commandbox
WAR Support
Additionally, CommandBox can start any WAR given to it using the WARPath argument.
If you run a regular start command inside of a folder that has a /WEB-INF/web.xml file, CommandBox will treat that folder as a WAR.
Custom Engines
The cfengine parameter can accept any valid CommandBox 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:
box.json
Engine.[zip|war] (file name doesn't matter)
CommandBox will download the package, unzip it and use the WAR/zip file as the engine for your app.
Normally, the artifacts cache isn't used for non-ForgeBox packages, but CommandBox will only download the engine once per server and then assume the file hasn't changed. You will need to forget the server to trigger a new download.
Here's an example of starting up a web server using a direct download link to a package containing a WAR file:
server.json Configuration
You can set the cfengine and other related configuration options in your server.json to use them every time you start your app.
These commands would create the following server.json
Just a reminder that starting a server with any command line arguments will save the arguments to your server.json by default.
This command would add adobe@9 to your server.json. If this is not what you want, you can append saveSettings=false or even --!saveSettings when you start your server and CommandBox will not save the arguments you specify to your server.json.
To help with this, you can store your server.json file outside of the web root and use the web.webroot property in it to point to the location of the web root. This can be an absolute path or a relative path to the location of the JSON file.
When you start the server, you can run the start command from the same directory that the server.json file lives, or specifiy the path to the JSON file like so:
Determining the web root
If there is no web root in your server.json, CommandBox will use the folder that the JSON file is stored in. If there is no JSON file at all, the current working directory is used.
server set web.webroot=www
start /path/to/server.json
server set JVM.heapSize=1024
server set JVM.heapSize=2G
server show JVM.heapSize
start minHeapSize=1024
server set JVM.minHeapSize=1024
server set JVM.minHeapSize=2G
server show JVM.minHeapSize
start JVMArgs="-XX:MaxGCPauseMillis\=200"
server set JVM.args="-XX:MaxGCPauseMillis\=200"
server show JVM.args
start RunwarArgs="--sendfile-enable false"
server set runwar.args="--sendfile-enable false"
server show runwar.args
CommandBox> start cfengine=adobe@9
# 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 cfengine=adobe@11
# Start the most recent adobe engine that matches the range
CommandBox> start cfengine="adobe@>9.0 <=11"
CommandBox> artifacts list
# Removes all adobe servers currently in the artifacts
# These servers will need to be re-downloaded the next time they are started
CommandBox> artifacts remove adobe
CommandBox stores information about each of the servers you've ever started inside ~/.CommandBox/servers.json so it can remember settings from one run to the next.
List your server
You can see an overview of your servers and what state they're in with the server list command.
If you have many servers, you can provide parameters to help filter the results from server list
To list only the servers that have been started in a given directory, use the --local flag.
You can take a quick look at the what's been happening with the server log command or use the server status command to see more detailed information including the arguments used previously to start/stop the server.
Multiple Servers
Servers are uniquely identified by their full path, but they also have a short name which defaults to the immediate folder containing their web root. The stop, start, etc commands can be run in the web root for a server, or in any working directory as long as you reference the server's short name.
Another handy shortcut is the server cd command that will change the current working directory of the interactive shell to the web root of a named server.
Info Server name is the first parameter to all server commands and tab completion works too, making it as easy as possible for you.
Get Server Information
You can get information about a server using the server info command. Add the --JSON flag to get the data back in a JSON format. The property parameter will allow you to retrieve a single value for scripting mashups.
Forgetting Servers
If you want to wipe all configuration, logs, and WEB-INF files for a server, use the server forget command. This will also remove any administrator settings you may have saved including data sources, mail servers, and server mappings.
You can forget all your servers at once too if you want to start with a clean slate. This command will stop and forget all servers.
URL Rewrites
Once you start using the embedded server for your development projects, you may wish to enable URL rewriting. Rewrites are used by most popular frameworks to do things like add the index.cfm back into SES URLs.
You may be used to configuring URL rewrites in Apache or IIS, but rewrites are also possible in CommandBox's embedded server via a .
Server Port and Host
The start command will scan your system and find a random port that is not currently in use to start the server on. This ensures that multiple embedded servers can run at the same time on the same host without collisions. Ensure any redirects in your applications take the port into account.
Any Port in the Storm
You may want to set a specific port to use-- even port 80 if nothing else is using it. Pass the HTTP port parameter to the start command like so:
Server.json
Every time you start a server, the settings used to start it are saved in a server.json file in the web root. Any parameters that aren't supplied to the start command are read from this file (if it exists) and used as defaults. Here are the possible properties for a server.json file:
/server.json
Using Multiple server.json Files
With the advent of , you may want to regularly start up the same web site with different settings (such as different CF engine's). To help with this, you can have more than one JSON file.
Create anything.json
The default server configuration file is server.json, but you can actually call the file anything you want as long as you use the file's path (or unique name) when starting the server.
Adding Custom Libs
If you have custom jar files that you want to be available to a server, we recommend you use the this.javaSettings functionality in your Application.cfc to load those jars. If that isn't an option for you, or you want to include libs for a JDBC drivers then we offer a feature for you to specify a list of directories for which CommandBox will load jars from. This prevents you from worrying about getting your jars inside the WEB-INF/lib which starts fresh anytime you forget a server.
To load in your jar files, the first method is to use the libDirs parameter to the server start command.
And the way to specify this in a portable manner in your `server.json` is like so:
Starting as a Service
When using CommandBox on a staging or production server, you may wish to start up servers as a service when the OS comes online. Here is a guide on each major OS type.
Windows
See screencast here:
Aliases
CommandBox allows you to create web aliases for the web server that are similar to virtual directories. The alias path is relative to the web root, but can point to any folder on the hard drive. Aliases can be used for static or CFM files.
To configure aliases for your server, create an object under web called aliases. The keys are the web-accessible virtual paths and the corresponding values are the relative or absolute path to the folder the alias points to.
Here's what your server.json might look like.
Here's how to create aliases from the server set command:
server list
site1 (starting)
https://127.0.0.1:8081
C:\site1
site1 (running)
https://127.0.0.1:8082
C:\site2
site3 (stopped)
https://127.0.0.1:8083
C:\site3
info On Adobe ColdFusion servers, .cfm files will be run automatically from inside an aliases directory. On Railo and Lucee servers, you'll need to create a CF mapping that maps the alias name and path for .cfm files to work.
server set web.aliases./foo = bar
server set web.aliases./js = C:\static\shared\javascript
Default Rules
We've already added the required jars and created a default rewrite XML file that will work out-of-the-box with the ColdBox MVC Platform. To enable rewrites, start your server with the --rewritesEnable flag.
info The default rewrite file can be found in ~\.CommandBox\cfml\system\config\urlrewrite.xml
Custom Rules
If you want to customize your rewrite rules, just create your own XML file and specify it when starting the server with the rewritesConfig parameter. Here we have a simple rewrite rule that redirects /foo to /index.cfm
customRewrites.xml
Then, fire up your server with its custom rewrite rules:
In server.json
You can place your custom rewrite rule wherever you like, and refer to it by using either a relative path or an absolute path. CommandBox will start looking relative to where the server.json file resides.
or
Apache mod_rewrite-style rules
If you're coming from Apache, Tuckey supports a large subset of the mod_rewrite style rules like what you would put in .htaccess. You can simply put your rules in a file named .htacess and point the web.rewrites.config property to that file.
Note: The name of the file matters with mod_rewrite-style rules. It must be called.htaccess. With xml rewrites, the filename is not important, only the content.
info For more information on custom rewrite rules, consult the Tuckey docs.
SES URLs
Your servers come ready to accept SES-style URLs where any text after the file name will show up in the cgi.path_info. If rewrites are enabled, the index.cfm can be omitted.
SES URLs will also work in a sub directory, which used to only work on a "standard" Adobe CF Tomcat install. Please note, in order to hide the index.cfm in a subfolder, you'll need a custom rewrite rule.
Logging
The Tuckey Rewrite engine has debug and trace level logging that can help you troubleshoot why your rewrite rules aren't (or are) firing. To view these logs, simply start your server with the --debug or --trace flags. Trace shows more details than debug. These options work best when starting in --console mode so you can watch the server logs as you hit the site. Alternatively, you can follow the server's logs with the server log --follow command.
Additional Tuckey Settings
The Tuckey Rewrite library that CommandBox uses under the hood. It has some extra settings that CommandBox allows you to use.
Watch rewrite file for changes
To monitor your custom rewrite file for changes without needing to restart the server, use this setting.
Internal Tuckey status page
To enable the inbuilt Tuckey status page, use the following setting. Note, debug mode needs to be turned on for the Tuckey status page to work. Also, you'll need to customize your rewrite file if you use a path other than /tuckey-status.
It is also possible to save the default port in your server.json. Add a web.http.port property, or issue the following command:
Now every time you start your server, the same port will be used.
If the server won't start or is unreachable, make sure it's port is free with your operating system's netstat command. On Unix-based OS's:
HTTPS
You can start your server to listen for SSL connections too.
This will enable SSL without an approved SSL certificate. If you need an official certificate so you don't have to confirm your SSL connection you can add these entries
Although free certificates are available (e.g LetsEncrypt) this is not very convenient, because these certs are valid only for three months. Automatic renewal it is difficult if your dev site is not accessible from the web. For a few dollars a year (< 10) you can apply for a domain validated certificate from companies like Comodo, RapidSSL, Trustwave, Digicert, Geotrust and others or a reseller for these certs. For a domain validated certificate you need a valid domain which is under your control which means (depending on provider):
mail is sent to domain owner
or mail is sent to well-known administrative contact in the domain, e.g. (admin@, postmaster@, etc.)
or you can publish a DNS TXT record
So, now you have a valid domain, you have to generate a SSL key and a SSL Certificate Signing Request. With the CSR you can apply for the certificate. Generating a key and CSR with openSSL
This will generate output and some questions, and will finally result in a key file named dev_mydomain_com.key and a certificate signing request (csr) named dev_mydomain_com.csr
You have to enter Country Name, State and City. Organization Name is preferably the same as the domain owner. Organizational Unit Name will not be checked, so enter something simple such as ICT Common Name is the hostname for your site, such as dev.mydomain.com You can skip Email Adress and optional company name. For development you don't need a challenge password, which means your key file is NOT protected. But don't give this key to others or protect it with a challenge password. If you protect your key you have to server set web.SSL.keyPass=MyChallengePassword Now you have a CSR, which you can submit at your SSL provider. They will send you a certificate file (*.csr), and probably one or more intermediate certificates. Create a new my.csr file and copy everything from your certificate file into it, and append the intermediate certificate(s). Now you have a valid my.csr certificate file and a key file. Place both files in a location accessible for your commandbox and enter the corresponding paths to web.SSL.certFile and web.SSL.keyFile
AJP
You can start your server to listen for AJP connections too.
A Gracious Host
Your application may rely on a specific host name other than the default of 127.0.0.1. You can set the host to anything you like, but you must add a host file entry that resolves your host name to an IP address assigned to your network adapter (usually 127.0.0.1)
If you have multiple IP addresses assigned to your PC, you can bind the server to a specific IP using the host parameter.
A server configuration can only have one host entry. If you require your server to be available on multiple IP addresses of the machine it runs on, you can set the host to 0.0.0.0. This will effectively bind the server to all network interfaces (including local).
Or save in server.json
Customize URL that opens for server
By default, CommandBox will open your browser with the host and port of the server. You can customize the exact URL that opens. This setting will be appended to the current host and port.
Or you can completely override the URL if your setting starts with http://.
Let's say we want to test our app in Lucee 4, Lucee 5 and Adobe 2016. Let's start 3 servers. Note we give each server a unique name. This will come in handy when we want to start/stop the servers by name later.
Info It's important to always use a name when starting more than one server. Otherwise, the settings will override each other and only the last server will be saved. Also, you will only be able to stop the last server via the stop command.
You can have full control over the name of the JSON files by using the serverConfigFile parameter, but when CommandBox sees us use the name parameter, it will automatically create a file called server-{name}.json. In this case, we'll have 3 new files:
server-lucee4.json
server-lucee5.json
server-adobe2016.json
Interacting with non-standard JSON file names
If you run the server show command, you'll see it returns {}. This is because it looks for a file called server.json by default. Not to worry, you can still programmatically manipulate your JSON files like so:
Info The property name and server config file path are interchangeable for the server show and server clear commands for your convenience.
Use server JSON files to control servers
Now that you have 3 JSON files-- one for each server, you can use the path to the JSON file (absolute or relative to your CWD) to control each server.
For your convenience, if you pass in a path to an existing JSON for the server name, we'll use it as the serverConfigFile parameter.
This trick works on any server commands
Use server names to control servers
After you've started a server at least once, you can use its server name to control it as well which is a great shortcut. CommandBox will recognize the server name and remember where the server JSON for that server name is stored. Then it will pull the correct web root from the JSON file.
Remember, paths to the start command are relative to your current working directory and paths in your server.json file are relative to the folder that the server.json file lives in. Absolute paths work the same everywhere.
Global Custom Libs
Have a bunch of servers and they ALL need the same jars, you can add your `libDirs` to the global server defaults config settings. Your global lib directories won't be overwritten by server-level config dirs, but instead appended to. Relative paths in your config settings are relative to the respective web root of the server. CommandBox will also ignore missing lib dirs to give you some flexibility in this.
server start libDirs=path/to/libs,another/path/to/libs
server set app.libDirs=path/to/libs,another/path/to/libs
server start
MacOS
Coming soon...
Ubuntu (init.d)
Coming soon...
CentOS/RHEL (system.d)
Create a .service file
as follows:
Start the service
Give the service about a minute to load up, then check its status
Once you've verified the service is running as expected, enable the service to load at boot
server set web.rewrites.enable=true
server show web.rewrites.enable
<?xml version="1.0" encoding="utf-8"?>
<urlrewrite>
<!-- this will redirect the user from /foo to /index.cfm -->
<rule>
<from>^/foo$</from>
<to type="redirect">/index.cfm</to>
</rule>
<!-- internally redirect the requested URL from /gallery to /index.cfm?page=gallery with query string appended -->
<rule>
<from>^/gallery</from>
<to type="passthrough" qsappend="true">/index.cfm?page=gallery</to>
</rule>
</urlrewrite>
server set web.rewrites.enable=true
server set web.rewrites.config=customRewrites.xml
server show web.rewrites.enable
server show web.rewrites.config
server set web.rewrites.enable=true
server set web.rewrites.config=/my/custom/path/customRewrites.xml
server set web.rewrites.enable=true
server set web.rewrites.config=~\.CommandBox\cfml\system\config\customRewrites.xml
RewriteEngine on
RewriteRule ^/foo/ /
# Defend your computer from some worm attacks
RewriteRule .*(?:global.asa|default\.ida|root\.exe|\.\.).* . [F,I,O]
# Redirect Robots to a cfm version of your robots.txt
RewriteRule ^/robots\.txt /robots.cfm
# Change your default cfm file to index.cfm
RewriteRule ^/default.cfm /index.cfm [I,RP,L]
RewriteRule ^/default.cfm((\?.+)|())$ /index.cfm$1 [I,RP,L]
RewriteRule ^/News.html((\?.+)|())$ /News/index.cfm$1 [I,RP,L]
# redirect mozilla to another area
RewriteCond %{HTTP_USER_AGENT} ^Mozilla.*
RewriteRule ^/no-moz-here$ /homepage.max.html [L]
site.com/index.cfm/home/login
site.com/myFolder/index.cfm/home/login
start --debug
server log --follow
server set web.rewrites.configReloadSeconds=30
server set web.rewrites.statusPath=/tuckey-status
start port=8080
server set web.http.port=8080
server show web.http.port
$> netstat -pan | grep 80
start SSLEnable=true SSLPort=443
server set web.SSL.enable=true
server set web.SSL.port=8080
server show web.SSL.enable
server show web.SSL.port
server set web.SSL.certFile=/path/to/dev_mydomain_ext.crt
server set web.SSL.keyFile=/path/to/dev_mydomain_ext.key
You are about to be asked to enter information that will be incorporated
into your certificate request.
What you are about to enter is what is called a Distinguished Name or a DN.
There are quite a few fields but you can leave some blank
For some fields there will be a default value,
If you enter '.', the field will be left blank.
-----
Country Name (2 letter code) [AU]:NL
State or Province Name (full name) [Some-State]:YourState
Locality Name (eg, city) []:YourCity
Organization Name (eg, company) [Internet Widgits Pty Ltd]:YourCompany
Organizational Unit Name (eg, section) []:IT
Common Name (e.g. server FQDN or YOUR name) []:dev.mydomain.com
Email Address []:
Please enter the following 'extra' attributes
to be sent with your certificate request
A challenge password []:
An optional company name []:
start AJPEnable=true AJPPort=8009
server set web.AJP.enable=true
server set web.AJP.port=8009
server show web.AJP.enable
server show web.AJP.port
start host=mycoolsite.local
start host=192.168.10.15 port=80
start host=0.0.0.0 port=80
server set web.host=mycoolsite.local
server show web.host
server set openBrowserURL=/bar.cfm
server set openBrowserURL=http://127.0.0.1:59715/test.cfm
# Show all properties
server show server-lucee5.json
# Show one property
server show server-lucee5.json name
# named args are required to set properties
server set serverConfigFile=server-lucee5.json jvm.heapSize=1024
# Clear properties
server clear server-lucee5.json jvm
# Open your Lucee 5 site in the browser
server log server-lucee5.json
# cd into the web root for your Adobe 2016 web
server cd /path/to/server-adobe2016.json
config set servers.defaults.app.libDirs=/path/to/global/libs
nano /usr/lib/systemd/system/mySite.service
[Unit]
Description=mySite Service
[Service]
ExecStart=/usr/bin/box server start /var/www/mySiteAPI/server.json
Type=forking
[Install]
WantedBy=multi-user.target
systemctl start mySite.service
systemctl status mySite.service
systemctl enable mySite.service
Offline Server Starts
Sometimes you may wish to start a server on a computer that doesn't have access to the Internet. However, you may notice that running a command such as the following will throw an error trying to connect to ForgeBox:
That is because 5.x is a semver range and not a specific version. CommandBox must connect to ForgeBox to see what versions of the CF engine lucee can be found to use the latest one.
Be More Specific
If you know that a CF engine is already downloaded in your server's artifacts directory, start your server with a specific major, minor, and patch version to skip the ForgeBox check.
NOTE: If this fails, check the location of the folder structure below the artifacts folder for it's exact path.
e.g. /artifacts/lucee/5.0.0+252/lucee.zip - The box command for this would be: start [email protected]+252
This follows the pattern:
/artifacts/[server-type]/[server-version]/[server-type].zip
Useful if you've manually downloaded the file from forgebox and need to rename it.
Fail Safe
If CommandBox needs to connect to ForgeBox to resolve a version number and ForgeBox is unavailable, it will look in your local artifacts cache to try and find a cached version of that CF engine that satisfies your semver range. This means you may not get the latest version of that CF Engine, but at least your server will start up.
FusionReactor is a popular tool for monitoring performance and gathering metrics for ColdFusion and Java J2EE applications. You may wish to use FusionReactor with the servers you start up via CommandBox. We've created a CommandBox module that will add FusionReactor support to your CommandBox servers which you can view here on ForgeBox.
The CommandBox FusionReactor module is a separate project that you can optionally install by typing this:
That's it-- now every server you start with the start command will automatically have the JVM args added to it to load up FusionReactor.
Usage
There's nothing special you have to do in order for FusionReactor to load. A random port will be chosen for FusionReactor to use so you can have more than one server running at a time and each of them will have their own FusionReactor instance running. When you start a server, you should see some output similar to this:
To open FusionReactor in your browser, you can run the following command:
If you right click on the tray icon for this server, you'll see there is a new menu item at the bottom called Open Fusion Reactor that will do the same thing.
Licensing
FusionReactor is a commercial product and requires a license to use. If your company has a license for you to use on your PC, then you can register your CommandBox FusionReactor license with this command:
If you don't have a license, you can sign up for a trial and purchase a license from the website.
Custom Port
By default, the module always picks a random port to start FusionReactor on. You can also set your FusionReactor port on a per-server basis, or at a global level for all servers (if using the fancy which prevents port conflicts by binding each site to its own IP). The default behavior will still be to pick a random port if you don't specify one.
FusionReactor will bind the port on whatever host address is used for your server.
Disable the module
You may want to turn the FusionReactor functionality on or off based on your testing or for specific sites. There is now an enable flag for just that. It can be set per server and for all servers as well.
Per-server License Key
You can set a license key per server if you wish like so:
Managing Versions
The module is regularly updated to use the latest version of FusionReactor. Note however that your license key may not be for the latest FR version. When the internal default version of FR is updated for a major release, the version of the actual FR module will also have a "major" version increment. This is so you can always run upgrade --system and you won't have to worry about suddenly getting a major FR upgrade one day that doesn't work with your license key.
If you want to upgrade your CommandBox FusionReactor module to a new major release, just re-run the installation command.
Custom Version of FusionReactor
If you have an older FR license you want to use, you can specify the version of FR you'd like like so:
The installID setting can be any valid CommandBox endpoint installation ID, which means you can point to a custom HTTP URL, or ForgeBox slug, etc.
Debugger Libs
As of version 4.0 of this module, the debugger libs will be added automatically for you based on your OS. To disable the debugger libs use the following setting:
Provide External reactor.conf File
There are a handful of JVM args we can use to set things like license key or password, but there are many many settings inside of FusionReactor that have no corresponding method to externalize them. These are stored in a file called conf/reactor.conf inside of the FusionReactor home directory. If you want to script out settings such as
E-mail servers
Notification settings
Profiler settings
Then you can make a copy of a reactor.conf file that contains the settings you want the point this module at the file to be copied over when starting the server so FR will pick it up and use it. Just need in mind that this setting will override any manual setting changes you make in the FR web admin every time you start the server.
Start up a test server with the FR module installed
Navigate to the FR admin, login, and set your desired settings
Copy the populated reactor.conf file somewhere for later use
Point your server.json to the new file. Remember, non-absolute paths are relative to the directory the server.json lives in.
Now, a fresh new server will have these settings.
Note: the reactor.conf file may contain passwords or other sensitive information. It is in a java properties file format, so feel free to edit it and remove items you don't want. Also, take care when committing it to a source repo or making it web accessible so you don't reveal information. There is currently no support for environment variable expansions in this file, but perhaps we'll add it if it's useful.
Additional JVM args
The CommandBox FusionReactor module has passthrough settings for every documented JVM arg. Here are the remaining ones we haven't covered. If you want to know what some of these do, read on them.
Here's the module setting, followed by the JVM arg it creates. Remember, you can use environment variables in your server.json to control these dynamically on a per-server basis!
By default, FusionReactor is only available on the FR port, and not the HTTP or HTTPS port. If you want to hit FusionReactor's web UI through your main web server on the standard HTTP port, then enable the external server setting.
******************************************
* CommandBox FusionReactor Module Loaded *
******************************************
FusionReactor will be available at the URL http://127.0.0.1:2871
fr open
fr register "myLicenseKey"
// Server specific port
server set fusionreactor.port=8088
// global default port
config set server.defaults.fusionreactor.port=8088
server set fusionreactor.enable=false
config set server.defaults.fusionreactor.enable=false
server set fusionreactor.licenseKey=XXXXX-XXXXX-XXXXX-XXXXX-XXXXX
// Server specific version
server set fusionreactor.debugEnable=false
// global default version
config set server.defaults.fusionreactor.debugEnable=false
install commandbox-fusionreactor
server start
fr open
cp "`server info property=FRHomeDirectory`conf/reactor.conf" ./reactor.conf
server set fusionreactor.reactorconfFile=reactor.conf
server stop
server forget --force
server start
// Server specific version
server set fusionreactor.externalServerEnable=true
// global default version
config set server.defaults.fusionreactor.externalServerEnable=true
Server Logs
Your CF engine (Lucee, Adobe, etc) or Java app may have application logs of its own and their locations will vary based on what you have running. In any case, they will most likely be located under the server home directory.
CF App server logs
You can find out where your server home is by running:
You can also get the full path to your servlet's "out" log with this command:
This log file is the equivalent of your catalina.out file on a typical Lucee/Tomcat install or the equivalent of your coldfusion-out.log file on a typical ColdFusion install.
The Servlet's "out" log can be tailed with this command:
Your console "out" log will auto-rotate every 10MB to keep it from getting too big. Don't use the --debug or --trace flag on a production server or you'll get a lot of logging information! Without those flags, the "out" log doesn't log anything for each request. With debug enabled, you'll get basic information for each request that comes in as well as whether a rewrite rule fired, and with trace, you'll get a ton of information about every request as well as every local path resolution by the path resource manager.
Lucee Server's Log Files
There are many log files for Lucee. For the guide below, I'm assuming you haven't set a custom serverConfigDir or webConfigDir for your servers. If you have, adjust the paths for the server and web context to be whatever it is you've configured. Here are the three locations you'll find log file and is pretty much the same for Lucee 4 and Lucee 5.
Lucee's server context log files - The server context is located under the server home which you can find with the command server info property=serverHomeDirectory. Open that directory and then navigate to WEB-INF/lucee-server/context/logs/.
Lucee's web context log files - The web context is also located under the server home. Open that directory and then navigate to WEB-INF/lucee-web/logs/.
So, to give real examples-- a Lucee server I just looked at on my machine has the three folders of log files I just covered above in these locations:
Adobe ColdFusion's Log Files
Since Adobe doesn't have the separation of server and web contexts, it only has two log locations which are as follows on all versions.
ColdFusion server log files - The remaining log files are located under the server home which you can find with the command server info property=serverHomeDirectory. Open that directory and then navigate to WEB-INF\cfusion\logs/.
So, to give real examples-- a ColdFusion server I just looked at on my machine has the two folders of log files I just covered above in these locations:
Access Log
CommandBox servers use a powerful Java-based web server which we've tested to have throughput just as good as Apache or IIS. You can enable "access" logs which output one line for each HTTP request (even for static assets like JS or image files) in the same "common" format that Apache web server uses.
View the location of this log or tail the log contents like so:
Your access log will be auto-rotated every day.
Rewrite Log
CommandBox servers use the java-based Tuckey rewrite engine for easy URL rewriting. There's a lot of good debugging information available to help figure out why your rewrites aren't working. You can enable a separate rewrite log to view this information. Keep in mind this can generate a lot of logging output.
View the location of this log or tail the log contents like so:
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.
server info property=serverHomeDirectory
server info property=consolelogPath
server log --follow
server log myServerName --follow
