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:
server set web.http.port=8080View the port:
server show web.http.portView the port with JMESPath:
server show jq:web.http.portRemove the saved setting:
server clear web.http.portEvery 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,
"profile": "prod",
"dockEnable": true,
"trayEnable": true,
"trayicon": "/path/to/trayicon.png",
"env" : {
"ANYTHING_HERE" : "you want",
"THESE_ARE_ADDED" : "As environment variables to the server"
}
"trayOptions": [
{
"label": "Foo",
"action": "openbrowser",
"url": "http://${runwar.host}:${runwar.port}/foobar.cfm",
"disabled": false,
"image": "/path/to/image.png"
},
{
"label":"Open VScode",
"action":"runAsync",
"command":"code .", //command is run relative to webroot, for box commands begin command with `box`
"disabled": false,
"image": "/path/to/image.png"
},
{
"label":"Open Webroot",
"action":"openfilesystem",
"path":"./", //path is relative to your webroot
"disabled": false,
"image": "/path/to/image.png"
}
],
"jvm": {
"heapSize": 512,
"minHeapSize": 256,
"args" : [ //can be a string or an array
"-XX:+UseG1GC",
"-XX:-CreateMinidumpOnCrash",
"--add-opens=java.base/java.net=ALL-UNNAMED"
],
"javaHome" : "/path/to/java/home",
"javaVersion" : "openjdk11"
},
"web": {
"host": "127.0.0.1",
"webroot": "src/cfml",
"directoryBrowsing": true,
"accessLogEnable": true,
"maxRequests":30,
"gzipEnable": true,
"gzipPredicate": "regex( '(.*).css' ) and request-larger-than( 500 )",
"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"
}
},
"rules": [
"path-suffix(/box.json) -> set-error(404)",
"path-prefix(.env) -> set-error(404)",
"path-prefix(/admin/) -> ip-access-control(192.168.0.* allow)",
"path(/sitemap.xml) -> rewrite(/sitemap.cfm)",
"disallowed-methods(trace)"
],
//3 ways to specify rulesFile
"rulesFile": "../secure-rules.json",
// Or...
"rulesFile": [
"../security.json",
"../rewrites.json",
"../app-headers.json"
],
// Or...
"rulesFile":"../rules/*.json",
"blockCFAdmin": false,
"blockSensitivePaths": true,
"blockFlashRemoting": true
},
"app": {
"logDir": "",
"libDirs": "",
"webConfigDir": "",
"serverConfigDir": "",
"webXML": "",
"WARPath": "",
"cfengine": "[email protected]",
"restMappings": "/rest/*,/api/*",
"serverHomeDirectory": "",
"sessionCookieSecure": true,
"sessionCookieHTTPOnly": true,
"webXMLOverride" : "path/to/web.xml",
"webXMLOverrideForce" : false
},
"runwar": {
"jarPath": "/path/to/runwar.jar",
"args" : [ //can be a string or an array
"--runwar-option",
"value",
"--runwar-option2",
"value2"
]
"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.
anything.jsonThe 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=adobe2016Info 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
stopcommand.
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"
}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 jvmInfo The property name and server config file path are interchangeable for the
server showandserver clearcommands for your convenience.
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.jsonFor 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.jsonThis 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.jsonAfter 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 adobe2016
restart adobe2016
stop lucee4server.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.
server.json outside the web rootTo 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=wwwWhen 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.jsonIf 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.