Overview
The ColdBox starter App for ColdFusion is a pre-configured, production-ready application skeleton built on the ColdBox MVC framework. It gives you a clean, opinionated foundation for building CFML applications with modern conventions, including routing, dependency injection, logging, testing, environment Configuration, and server Automation. Whether you’re moving from legacy CFML or starting fresh with ColdBox, this starter accelerates setup, reduces boilerplate, and helps you follow Best practices across development, staging, and production.
This Download is valuable because it eliminates the repetitive tasks of wiring up an MVC folder structure, configuring your ColdFusion (CFML) server, and integrating testing and logging. You get a working app out of the box that runs on Adobe ColdFusion or Lucee, powered by CommandBox for rapid local development or Docker-based deployments.
What You’ll Get
- A complete ColdBox MVC project structure (handlers, views, layouts, models, modules)
- Pre-wired Configuration:
- Router and conventions in config/ColdBox.cfc and config/Router.cfc
- Dependency Injection via WireBox
- Logging via LogBox
- Environment support via .env (with cbdotenv) and CFConfig Integration
- Build and dev tooling:
- CommandBox box.json with scripts and dependencies
- TestBox test harness for unit/Integration tests
- Example code:
- A main handler, view, and layout to demonstrate Request flow
- Sample routes and Error handling
- Supporting files:
- .env.example for environment variables
- README with usage instructions
- .gitignore tailored for CFML and CommandBox
- Optional REST scaffolding (if you choose the REST template variant)
- Optional Docker-friendly layout for containerized deployments
Files you can expect to see:
- Application.cfc (app bootstrap)
- box.json (CommandBox package metadata)
- config/ (ColdBox, routes, environments)
- handlers/ (controller actions)
- models/ (services/DAOs)
- layouts/ and views/ (UI templating)
- tests/ (TestBox specifications)
- .env.example and optional .cfconfig.json (Server config)
Supported Environments
- CFML Engines:
- Lucee 5.3+ and Lucee 6.x
- Adobe ColdFusion 2018, 2021, and 2023
- Operating Systems:
- Windows, macOS, Linux
- Tooling:
- CommandBox (required for easiest install/run)
- Git (recommended)
- Docker (optional, via CommandBox Docker images)
Tip: For a frictionless developer experience, use CommandBox to spin up embedded CF servers, manage dependencies, run tests, and script tasks.
Download Options
Option A: Scaffold via CommandBox (Recommended)
- Requires CommandBox to be installed.
- Fastest way to get an app running with dependencies resolved.
Commands:
-
Create a new app folder and scaffold:
coldbox create app name=MyColdBoxApp –install -
Or choose a specific template (e.g., REST):
coldbox create app name=MyApi –skeleton=rest –install -
Start a server:
server start –open
This will download the ColdBox platform, install dependencies, and start a server at a local URL (e.g., http://127.0.0.1:port).
Option B: Clone the Template from GitHub
- Use this if you prefer direct Git control over the starter template repo.
Steps:
- Clone:
git clone https://github.com/coldbox-templates/coldbox-template-app.git MyColdBoxApp - Install dependencies:
cd MyColdBoxApp
box install - Start the server:
box server start –open
Option C: Use Docker with CommandBox
- Great for parity with production and CI.
Example:
- From project root:
docker run –rm -p 8080:8080 -v “$PWD”:/app ortussolutions/commandbox:latest
Then open http://localhost:8080
Installation and First Run
Follow this step-by-step flow to install, configure, and run:
- Install CommandBox
- Download from the Ortus Solutions site and add it to your PATH.
- Verify:
box –version
- Create or clone the Starter App
- CommandBox scaffold:
coldbox create app name=MyColdBoxApp –install - Or Git clone:
git clone https://github.com/coldbox-templates/coldbox-template-app.git MyColdBoxApp
cd MyColdBoxApp
box install
- Provide environment settings
- Copy .env.example to .env
- Update keys such as APP_ENV, APP_NAME, and DB credentials (if applicable)
- If using CFConfig, verify .cfconfig.json or add one via:
box install commandbox-cfconfig
- Start a local CF server
- Use Lucee (default):
box server start –open - Or specify an engine:
box server start cfengine=adobe@2023 –open
box server start cfengine=lucee@6 –open
- Verify routing
- Visit the home page and a sample route (e.g., / or /main/index)
- Check logs in the /logs directory or server console output
- Run tests (optional)
- Execute TestBox specs:
box testbox run - View test reports in the console or configured output folder
Configuration Essentials
Environment Variables with cbdotenv
- The starter includes .env support so secrets and environment-specific values are not hard-coded.
- Common keys:
- APP_ENV=development|staging|production
- APP_NAME=MyColdBoxApp
- DB_CONNECTION, DB_HOST, DB_DATABASE, DB_USER, DB_PASSWORD
- Ensure never to commit .env to source control.
WireBox (DI/IoC)
- Register services and components in models/
- Use property injection or getInstance() for clean, testable code:
property name=”userService” inject=”UserService”;
LogBox (Logging)
- Configure appenders and categories in config/ColdBox.cfc
- Route errors to file or console; adjust levels per environment.
Router and Interceptors
- Define routes in config/Router.cfc
- Add interceptors (e.g., request logging, auth) in config/ColdBox.cfc
CFConfig (Server configuration as Code)
- Keep Adobe ColdFusion or Lucee settings in Version control.
- Export/import Server config:
cfconfig export to=.cfconfig.json
cfconfig import from=.cfconfig.json
How to Use the Starter App
Build Your First Feature
- Create a handler:
coldbox create handler name=Users - Add an action:
function list(event, rc, prc) { prc.users = userService.list(); event.setView(“users/list”); } - Create a view:
views/users/list.cfm (render prc.users) - Map a route:
addRoute( pattern=”/users”, handler=”Users”, action=”list” ); - Refresh the page and validate output.
Add a REST Endpoint (if using REST template)
- Add route:
addRoute( pattern=”/api/users/:id?”, handler=”api.Users” ); - Return JSON from a handler action using event.renderData(type=”json”, data=yourData)
Testing with TestBox
- Create a spec in /tests/specs
- Example:
describe(“Users Service”, function(){
it(“lists users”, function(){
expect( userService.list() ).toBeArray();
});
}); - Run:
box testbox run
Best practices
Security and Secrets
- Store secrets in .env and externalized secret managers where appropriate.
- Enable HTTPS and secure cookies in production.
- Sanitize inputs and validate all request parameters.
Config by Environment
- Use APP_ENV to switch configs.
- Enable verbose logging only in development.
- Keep database credentials and API keys out of source control.
Project Structure and Modularity
- Keep controllers thin; push logic into services (models/).
- Leverage modules for reusable Features (e.g., Authentication, APIs).
- Use WireBox for clean dependency management.
Performance and Caching
- Cache frequently used data using WireBox singletons or cacheBox.
- Profile Performance and review slow logs regularly.
CI/CD and Containers
- Use CommandBox for repeatable builds.
- Add automated testing in your pipeline via box testbox run.
- Use Docker images for consistent environments across teams.
Benefits and Use Cases
- Faster project kickoff: Skip scaffolding and boilerplate; start coding Features immediately.
- Consistent Architecture: The ColdBox MVC conventions produce predictable, maintainable CFML code.
- Built-in tooling: Integrated testing (TestBox), logging (LogBox), and DI (WireBox) streamline development and Debugging.
- Environment agility: .env and CFConfig let you switch between development, staging, and production without manual clicks in an admin console.
- Scalable patterns: Whether you’re building a small CRUD app or a large REST API, the starter app scales with clear routing, interceptors, and modular services.
- Great for teams: Onboarding new developers is easier when a standard structure and common scripts are already in place.
Common use cases:
- RESTful APIs and Microservices on Lucee or Adobe ColdFusion
- Data-driven web apps with MVC separation
- Modernization of legacy CFML apps into a framework-based structure
- Rapid prototypes that can evolve into production systems
Key Takeaways
- The ColdBox starter App delivers a ready-to-run CFML MVC foundation with routing, DI, logging, testing, and environment management.
- CommandBox provides a one-command scaffold and server for instant productivity.
- Strong environment separation via .env and CFConfig improves Security and maintainability.
- The starter supports Lucee and Adobe ColdFusion, on Windows/macOS/Linux, and plays well with Docker.
- Following best practices (modularity, testing, caching, and CI/CD) ensures long-term stability and performance.
FAQ
How do I switch between Lucee and Adobe ColdFusion locally?
When starting the server, specify the engine:
- Lucee 6: box server start cfengine=lucee@6 –open
- Adobe CF 2023: box server start cfengine=adobe@2023 –open
You can also set a default in your server.json for convenience.
Can I use a database with the starter app?
Yes. Add your DSN details to .env (or manage via CFConfig), then configure your ORM or Database access layer (e.g., Quick/qb or native cfquery). Keep credentials out of source control and use environment-specific values.
Is there a REST-specific starter template?
Yes. When creating the app, choose the REST skeleton:
coldbox create app name=MyApi –skeleton=rest –install
It scaffolds RESTful handlers, routes, and JSON responses.
How do I run automated tests?
Use TestBox:
- Write specs in /tests/specs
- Run them with:
box testbox run
Integrate into CI for automated quality gates.
Can I deploy with Docker?
Yes. Use CommandBox Docker images for consistent environments. You can mount your app, specify the CF engine, and externalize .env variables for production-grade deployments.
