Blog

Brad Wood

December 15, 2017

Spread the word


Share your thoughts

Welcome back to another installment of the 12 days of (CommandBox) Christmas.  One thing I love about this season is the traditions that our family does over and over each year.  Another thing worth doing over and over the same way is staring your CommandBox servers!  That's why we have server.json-- your key to repeatable, consistent server starts.

What is server.json?

Just like the recipe your grandma used every year for the Christmas ham, your server.json file is the recipe for how you'd like CommandBox to start up your servers.  This ensures that not only you get the same settings applied every time, but that the other developers on your team can also get the same local environment.  And all this with no traditional server installations, IIS, Apache, or Tomcat!

The server.json file lives by default in your web root and will get picked up automatically when you start up a server in that directory. 

{
    "name":"mySite",
    "openBrowser":"false",
    "app":{
        "cfengine":"lucee@5"
    },
    "jvm":{
        "heapSize":"1024"
    }
}

Have more than one server you like to start for testing the same site?  No worries-- you can actually name the files anything you want and just point the start command at the file you want it to use.

server start mySiteAdobe11.json

Not too excited about storing the json file in your web root?  That's cool-- put it wherever you like, and use a relative or absolute path to tell CommandBox where the webroot is in relation to the file.  

{
    "name":"mySite",
    "web":{
        "webroot":"www/"
    }
}

You'll likely want to commit your server.json file to your source control repo.  Remember, that all file paths can be relative to the location of the JSON file to keep it portable.  This means that all a new developer needs to do in order to get up and running on their first day (after installing CommandBox) is create an empty folder and run:

git clone https://yourRepoUrl.git
box install
box start

Servlet settings

You can control any settings that would normally be a part of Tomcat (or in this case, Undertow) and the JVM.  These include:

  • Java heap size
  • What version of Java to use
  • Custom JVM args
  • Default welcome files (like index.cfm)

Web server settings

CommandBox has a well-featured Java-based web server built in which means you probably don't need IIS or Apache for your local development. In your server.json you can control the following:

  • URL rewrites
  • HTTP/HTTPS/AJP ports
  • SSL certs
  • Virtual directories
  • Custom error pages for 404, 500, etc
  • Enable/disable directory browsing
  • Host name
  • Basic auth

ColdFusion Server

You can also choose what CF engine you want to be used as well as the version.

  • Adobe CF
  • Lucee Server
  • Railo
  • Any Java-based WAR! (Like Jenkins, OpenBD, etc)
  • You'll get the latest CF engine, but specify a version like
    • adobe@11
    • lucee@4.5
    • adobe@10.0.21+300068

If you're wondering about the settings you set in the web based administrator for your server, we have a module for that called CFConfig.  Stay tuned and we'll cover that soon in another blog.

But wait, there's more!

I've only mentioned the basics here to get to started.  For a full list of every property you can place in your server.json file, check out our comprehensive docs.  

https://commandbox.ortusbooks.com/embedded-server/server.json

Also remember that CommandBox has full tab completion built in.  You can edit your server.json file manually with a text editor or IDE, or you can also manage it from the CLI with the server show, server set, and server clear commands.  This is great for automation or just quick edits from the command line.  To see all the possible values you can type, enter "server set" from the interactive shell and hit the tab key.  Autocomplete will kick in and show you all the possibilities.  Continue to use tab completion as you type to make sure you're spelling everything right!

Modules

CommandBox modules can also look for properties of their own in your server.json file.  There's no limit to what you can store in the JSON file and no restrictions on how it can be used.  One example is the commandbox-fusionreactor module which will look for your FusionReactor license and settings there.  You can check the documentation for modules such as this one and they will tell you what properties to create.

 

Add Your Comment

(2)

Dec 02, 2020 23:51:34 UTC

by Roberto Marzialetti

this link in post is broken: https://ortus.gitbooks.io/commandbox-documentation/content/embedded_server/serverJSON/serverjson.html

Dec 03, 2020 00:05:57 UTC

by Brad Wood

Thanks for the note Roberto. The current link is https://commandbox.ortusbooks.com/embedded-server/server.json and I have updated the post above to reflect that.

Recent Entries

ColdBox 7.2.0 Released

ColdBox 7.2.0 Released

ColdBox, a widely used development platform for ColdFusion (CFML), has unveiled version 7.2. Packed with compelling new features, bug fixes, and enhancements, this release is designed to empower developers by boosting productivity, refining scheduled task capabilities, and enhancing the overall reliability and efficiency of application development. This article will delve into the key highlights of ColdBox 7.2 and elucidate how these advancements can positively impact developers in their daily coding endeavors.

Luis Majano
Luis Majano
November 20, 2023
Into the Box 2023 Series on CFCast

Into the Box 2023 Series on CFCast

Excitement is in the air as we unleash the highly anticipated ITB 2023 series exclusively for our valued CFCast subscribers – and the best part? It's FREE for CFCast members! Now is the perfect time if you haven't joined the CFCast community yet. Plus, we've got an incredible End-of-Year deal that's too good to miss

Maria Jose Herrera
Maria Jose Herrera
November 20, 2023
Ortus Deals are Finally Here!

Ortus Deals are Finally Here!

The much-anticipated Ortus End-of-the-Year Sale has arrived, and it's time to elevate your development experience! Whether you're a seasoned developer, a tech enthusiast, or someone on the lookout for top-notch projects, Ortus has something special in store for you. Brace yourself for incredible discounts across a wide array of products and services, including Ortus annual events, books, cutting-edge services, and more.

Maria Jose Herrera
Maria Jose Herrera
November 15, 2023