[Coldbox 4.1.0] What are best practices for deploying a Coldbox app as a subfolder in a webroot?

I’m working on my second Coldbox app, and this one is to be deployed as a subfolder under a CFML application that isn’t a Coldbox app. What are some best practices for ensuring all the pathing and mappings work correctly? I’m running into some issues deploying as-is.

I can provide whatever error messages or code samples will help.

BONUS: I work on the app locally as its own webroot, to further complicate things. I’d like that to keep working, too.

Thanks in advance!

I used to develop using custom host entries and creating individual sites with Apache, to make sure the environment was as close to production as possible. If I needed to test with a Windows environment, I would spin up a Parallels VM ( I’m a Mac fan ) so I could test using IIS and point my custom host entry at the IP of the VM. For apps that ran in sub-directories, I would just use a <Location /my/subapp > block in Apache that matched the production path and run the app in that path.

Now days, though, I regularly develop using the CommandBox embedded server. Assuming your directory structure and naming matches down to the app you’re working on, you can simply start the embedded server from the relative root to that project and ensure your production path setup matches your dev environment.

Another option is to use Docker or Vagrant to set up a near-replica of your production environment. A few projects I work on regularly that are set up that way. If you’re deploying on ACF, you will almost definitely need to set up a container-based or VM-based development environment, or use IIS or Apache locally, with custom hosts.


Please provide the errors you’re getting. For the most part, as long as the /coldbox mapping is set up, the app should “just work”. The only thing you really need to watch out for when running ColdBox out of a sub directory, is if you have any coldbox calls to remote proxies that aren’t in the web root, you need to set the app mapping in the Application.cfc. That’s just to help Coldbox find the root of the app when it starts up on the first request.

Ideally, you’d develop with your web root set up the same as it will be on production. Otherwise, your relative URLs to the web root might all be different for things like JS or CSS assets.



ColdBox Platform Evangelist
Ortus Solutions, Corp

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

After a little experimenting, this is a snippet from my Application.cfc:


this.mappings[’/coldbox’] = COLDBOX_APP_ROOT_PATH & ‘/coldbox’;
this.mappings[’/layouts’] = COLDBOX_APP_ROOT_PATH & ‘/layouts’;

this.mappings[’/includes’] = COLDBOX_APP_ROOT_PATH & ‘/includes’;
this.mappings[’/interceptors’] = COLDBOX_APP_ROOT_PATH & ‘/interceptors’;


Coldbox makes sense. Layouts was confusing because Views don’t need a mapping. Maybe this is a bug? I’ll have to dig into it more.

Includes and Interceptors are necessary because I reference them in my Coldbox config. I could probably get around two mappings by making one “app” or “approot” mapping and using that when I define things like interceptors.

My next task will be a to implement an easy way to reference my static assets, like you mentioned. I’ll probably take advantage of the environment settings for that.

Does this make sense?

Is there documentation for how some of these variables get used that are included in the default Application.cfc? I’m referencing: COLDBOX_APP_ROOT_PATH, COLDBOX_APP_MAPPING, COLDBOX_CONFIG_FILE, COLDBOX_APP_KEY. Some of them seem clear, but I’d like to read an official explanation for all the ramifications for changing or using them.

Hi Miles

You can define Layout/Views handlers, modules, models location inside the config/coldbox.cfc