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:

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

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.

server set web.webroot=www

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:

start /path/to/server.json

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.

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

{
    "name": "",
    "openBrowser": true,
    "openBrowserURL" : "http://localhost/admin/login",
    "startTimeout": 240,
    "stopsocket": 50123,
    "debug": false,
    "trace": false,
    "console": false,    
    "trayEnable": true,
    "trayicon": "/path/to/trayicon.png",
    "trayOptions": [
        {
            "label": "Foo",
            "action": "openbrowser",
            "url": "http://${runwar.host}:${runwar.port}/foobar.cfm",
            "disabled": false,
            "image": "/path/to/image.png"
        }
    ],
    "jvm": {
        "heapSize": 512,
        "minHeapSize": 256,
        "args": "",
        "javaHome" : "/path/to/java/home"
    },
    "web": {
        "host": "127.0.0.1",
        "webroot": "src/cfml",
        "directoryBrowsing": true,
        "accessLogEnable": true,
        "maxRequests":30,
        "gzipEnable": true,
        "aliases": {
            "/foo": "../bar",
            "/js": "C:/static/shared/javascript"
        },
        "errorPages": {
            "404": "/path/to/404.html",
            "500": "/path/to/500.html",
            "default": "/path/to/default.html"
        },
        "welcomeFiles": "index.cfm,main.cfm,go.cfm",
        "HTTP": {
            "enable": true,
            "port": 8080
        },
        "SSL": {
            "enable": false,
            "port": 443,
            "certFile": "",
            "keyFile": "",
            "keyPass": ""
        },
        "AJP": {
            "enable": false,
            "port": 8009
        },
        "rewrites": {
            "enable": true,
            "logEnable": true,
            "config": "/path/to/config.xml",
            "statusPath": "/rewriteStatus",
            "configReloadSeconds": 60
        },
        "basicAuth": {
            "enable": true,
            "users": {
                "userName1": "password1",
                "userName2": "password2"
            }
        }
    },
    "app": {
        "logDir": "",
        "libDirs": "",
        "webConfigDir": "",
        "serverConfigDir": "",
        "webXML": "",
        "WARPath": "",
        "cfengine": "lucee@5.x",
        "restMappings": "/rest/*,/api/*",
        "serverHomeDirectory": "",
        "sessionCookieSecure": true,
        "sessionCookieHTTPOnly": true
    },
    "runwar": {
        "args": "",
        "XNIOOptions": {
            "WORKER_NAME": "MyWorker"
        },
        "UndertowOptions": {
            "ALLOW_UNESCAPED_CHARACTERS_IN_URL": true
        }
    }
}

With the advent of Multi-server functionality, 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.

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.

start cfengine=lucee@4 name=lucee4
start cfengine=lucee@5 name=lucee5
start cfengine=adobe@2016 name=adobe2016

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

{
    "app":{
        "cfengine":"lucee@4"
    },
    "name":"lucee4"
}

server-lucee5.json

{
    "app":{
        "cfengine":"lucee@5"
    },
    "name":"lucee5"
}

server-adobe2016.json

{
    "app":{
        "cfengine":"adobe@2016"
    },
    "name":"adobe2016"
}

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:

# 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

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.

start serverConfigFile=server-lucee4.json

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.

start server-lucee4.json
stop server-lucee4.json
start server-adobe2016.json

This trick works on any server commands

# 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

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.

start lucee4
start lucee5
start adobe2106

restart adobe2016
stop lucee4