[ColdBox 4.0.0] What docs / files do I really need?

I’m getting started with ColdBox 4 and finally got a chance to try CommandBox as well.

Downloaded / setup a new project with CommandBox and installed a few modules.

CommandBox rocks BTW!

I then poked around to see what was downloaded and I have a few questions on what files I need to keep and / or deploy.

  • box.json ? Will CommandBox update a package? If so i’m guessing I need to keep these?

  • /modules/modulename/apidocs ? Looks like I could ignore these

  • /modules/modulename/*.md files ? Looks like I could ignore these

  • /modules/modulename/modulename- ? it would be nice if this one had an extension so it could easily be filtered as I’m guessing the number will change if updated?

  • /modules/modulename/config ? this one was in the cbsecurity module

Mainly I need to know what I can ignore, what I need to save to source control and then what I should / shouldn’t filter out when deploying to production…


> box.json ? Will CommandBox update a package? If so i’m guessing I need to keep these?

If you want CommandBox to still help you install, uninstall, update, or list dependencies you’ll need the box.json. Unless you use CommandBox on your production server, there’s no need to deploy it there though. This file behaves pretty similar to package.json in the NPM world

> /modules/modulename/apidocs ? Looks like I could ignore these

Yes, those are just for your development reference.

/modules/modulename/*.md files ? Looks like I could ignore these

Yes, just readmes and such.

> /modules/modulename/modulename- ? it would be nice if this one had an extension so it could easily be filtered as I’m guessing the number will change if updated?

That’s something our build server places to tag the date and time it was built. I would be ok with giving it some sort of extension to be able to ignore it easier. Perhaps Luis can chime in since he set that part up.

> /modules/modulename/config ? this one was in the cbsecurity module

Well, it depends on the value of your rulesFile setting. Of course, the SQL file will never need to be left, it’s just an example. The json and xml files are mutually exclusive-- you only use one or the other. Honestly, I sort of dislike how that module is set up. It was one of the first we converted, but I’ve come to the conclusion that you shouldn’t have t ever modify the core code of a module to get it working since reinstalling or updating it would blow away your changes. We probably need to do some more work on the security module to let it pick up config from your main ColdBox config file. In that case, the entire config folder would just be examples and could be ignored.

Excellent - thanks for the great explanation! I haven’t dug into the CommandBox docs yet but I was thinking last night it needed some sort of flag to filter the fluff out.


A quick clarifying question based on your statement:

Also, I should note that in this perfect world, you also do not commit these modules to your source control-- just your app’s box.json. Then you type “install” or “install --production” to build everything out for you.

Let’s say I build an app and expect it to work with cbstorages 1.0.0 but 1.1.0 is up on Forgebox does box.json work like node.js for auto downloading up to a certain minor/major version point eg: 1.x.x as described below based on the use of ~ and ^ flags?


In the simplest terms, the tilde matches the most recent minor version (the middle number). ~1.2.3 will match all 1.2.x versions but will miss 1.3.0.

The caret, on the other hand, is more relaxed. It will update you to the most recent major version (the first number). ^1.2.3 will match any 1.x.x release including 1.3.0, but will hold off on 2.0.0.

or is your box.json auto locked into your defined version from forgebox? Based on the docs that’s what it appears be unless you specify “x” for latest, but I thought I’d clarify that the use of ~ and ^ are not supported?

//FROM : [http://commandbox.ortusbooks.com/content/packages/boxjson.html](http://commandbox.ortusbooks.com/content/packages/boxjson.html)
// dependencies, a shortcut for latest version is to use the * string
    "Dependencies" : {
        "coldbox" : "x" // latest version from ForgeBox
        "slug" : "version", // a specific version from ForgeBox
        "slug" : "local filepath", //disallowed from forgebox registration
        "slug" : "URL",
        "slug" : "Git/svn endpoint"



Currently, CommandBox will download whatever version is on ForgeBox and ForgeBox currently only supports a single version (latest).

We are in the process of updating ForgeBox right now to support multiple versions of the same package and will also update CommandBox when that is finished to install the version that matches the range specified in your box.json using the standardized semantic versioning rules.

On that note, we probably should be saving the dependency versions in box.json with a ~ or ^ but we haven’t added it yet since the version is largely ignored right now.

So in short, no, but soon! :slight_smile:

If anyone would really like to see this (or any other major CommandBox feature) done sooner than later, we would love to have some corporate sponsorship and or community help with CommandBox.



ColdBox Platform Evangelist
Ortus Solutions, Corp

E-mail: brad@coldbox.org
ColdBox Platform: http://www.coldbox.org
Blog: http://www.codersrevolution.com