A practical, actionable guide for CFML developers and DevOps engineers, the CommandBox Script Cookbook for ColdFusion is a downloadable bundle of recipes, templates, and code samples that demonstrate how to automate local development, server provisioning, environment Configuration, and CI/CD tasks with the CommandBox CLI. Whether you run Adobe ColdFusion or Lucee, this resource accelerates setup, standardizes team workflows, and reduces repetitive manual steps with reusable scripts.
—
Overview
The Cookbook focuses on leveraging the CommandBox CLI as the backbone of your CFML workflows: spinning up servers, installing dependencies from ForgeBox, running TestBox tests, wiring cfconfig for environment Automation, and orchestrating tasks on Windows, macOS, and Linux. It’s designed for both greenfield projects and Legacy ColdFusion applications that need modern, scriptable operations.
Who it’s for:
- ColdFusion developers adopting CommandBox for the first time
- Teams migrating to Lucee or building Docker images
- DevOps engineers standardizing server.json, box.json, and .env driven pipelines
- Agencies and freelancers seeking repeatable project scaffolding
—
What You’ll Get
Inside the Download, you’ll find:
- PDF reference guide (70–120 pages) with annotated examples and patterns
- Script library (organized by topic), including:
- Project scaffolding and templates
- Server provisioning with server.json and profiles
- Environment Configuration using cfconfig and dotenv
- Package scripts, watch tasks, and interceptors
- Test and quality workflows (TestBox, linting hooks)
- CI/CD examples (GitHub Actions, GitLab CI, Azure Pipelines, Jenkins)
- Docker build recipes and multi-stage images
- Example projects:
- Lucee baseline + Adobe ColdFusion baseline
- API-first “headless” starter
- Reusable templates:
- box.json boilerplates with versioned scripts
- server.json variants for local, staging, and production
- .env.sample and properties files for multi-environment provisioning
- Cheatsheets:
- CommandBox CLI Quick reference
- ForgeBox and semver tips
- cfconfig key map by engine/version
—
Supported Environments
- Operating systems: Windows, macOS, Linux (Cross-platform)
- Engines: Lucee 5/6, Adobe ColdFusion 2018/2021/2023
- CI providers: GitHub Actions, GitLab CI, Azure Pipelines, Jenkins, Bitbucket Pipelines
- Containerization: Docker, Docker Compose, optional Podman
- Package ecosystem: ForgeBox modules and private packages
Pros:
- Unified, scriptable workflows
- Portable setups via server.json and .env files
- Strong community ecosystem (modules, recipes)
- Works offline after initial dependency cache
Cons:
- Initial Learning curve for box.json scripts and cfconfig mappings
- Team adoption requires standardizing naming and folder conventions
—
How to Download and Install
H3: Download Options
- From ForgeBox: Search for “CommandBox script Cookbook” and download the ZIP or install via slug if available.
- From GitHub Releases (common for cookbooks): Download the latest release ZIP.
- From your organization’s artifact repository: Use the provided URL or package manager.
Tip: If the cookbook is published as a ForgeBox package, you can install assets into your current directory using a CommandBox shell.
H3: Quick Start (CommandBox)
- Install CommandBox:
- Windows: choco install commandbox or download the installer from the official site
- macOS: brew install commandbox
- Linux: Use the official install script or package for your distro
- Open a shell and start CommandBox: run “box”
- Create a project folder: mkdir my-cfml-app && cd my-cfml-app
- Initialize a package: box init
- Add cookbook files:
- If packaged: box install cookbook-slug
- If ZIP: unzip contents into your project, preserving the folder hierarchy
- Verify: ensure box.json, server.json, and scripts folders exist
—
How to Use the Cookbook
H3: Core Files and Their Roles
- box.json: Declares package metadata and script aliases; central to repeatable commands
- server.json: Defines server specifics (engine, JVM args, webroot, rewrites, SSL, etc.)
- .env / .env.*: Environment variables, secrets, and feature flags loaded via dotenv
- cfconfig.json / cfconfig.*.json: Engine configuration snapshots for Lucee/ACF
- /scripts: Reusable CommandBox scripts (tasks, setup, CI hooks)
- /templates: Scaffolding for new apps or modules
H3: Typical Workflows
Local development
- Copy .env.sample to .env and fill in variables (ports, datasources, secrets)
- Run “box install” to pull dependencies from ForgeBox
- Start your engine: “box server start” (reads server.json)
- Import engine config: “box cfconfig import from=cfconfig.local.json”
- Watch and reload on changes: “box watch run=‘test’”
- Run tests: “box testbox run spec=tests/”
Provision a new environment
- Prepare a cfconfig.{env}.json and .env.{env}
- Execute: “box cfconfig import from=cfconfig.prod.json to=server” and “box server start”
- Seed data or run migrations (with cfmigrations module): “box migrate up”
CI/CD pipeline
- Install CommandBox in your CI runner (cache the ~/.CommandBox artifacts)
- Execute tasks: “box install”, “box testbox run”, “box cfconfig import”, “box server start headless=true”, “box package version”
- Build Docker image using provided Dockerfile and pass environment args
H3: Useful Scripts (Examples)
- setup: bootstraps project, installs modules, applies cfconfig, generates SSL cert
- clean: clears artifacts, tmp files, and CommandBox server cache
- test: runs TestBox specs and exports JUnit reports
- package: bumps version (semver), tags, and publishes to ForgeBox (if configured)
- lint: runs CFML linter (e.g., CFLint) and fails on threshold breaches
- docker: builds and tags images with engine and version metadata
—
Best practices
- Prefer server.json profiles: Keep server.local.json, server.staging.json, server.prod.json to avoid branching config
- Externalize secrets: Store keys in .env (use dotenv) or CI secrets; never commit to VCS
- Snapshot engine config: Use cfconfig export after local tuning; review diffs before import
- Version your scripts: Maintain semver in box.json and pin module versions in dependencies
- Cache wisely in CI: Cache .CommandBox, /artifacts, and module directories to accelerate builds
- Use ForgeBox namespaces: Distinguish private modules with clear naming and scopes
- Embrace interceptors and watch tasks: Automate repetitive tasks on file changes
- Keep templates minimal: Provide sane defaults; allow overrides via environment variables
- Log everything: Print effective config at startup; mask secrets
—
Benefits and Use Cases
Time Savings and repeatability
- Automated setup reduces Onboarding from hours to minutes
- One-command tasks unify developer and CI environments
Improved reliability and Performance
- Engine configuration via cfconfig ensures consistent settings across machines
- Cached dependencies and optimized scripts shorten feedback loops
Scalable team workflows
- Standardized box.json scripts codify conventions, easing code reviews and handoffs
- ForgeBox packages allow modular reuse across multiple projects
Cloud and containers
- Ready-to-use Docker recipes streamline container builds, multi-stage images, and environment promotion
- Works with Lucee and Adobe ColdFusion, enabling mixed fleets
Common scenarios
- Migrating legacy CFML apps to CommandBox servers
- Creating headless API services with scripted deployments
- Building CI pipelines that run TestBox and publish artifacts
- Provisioning ephemeral review apps per pull request
—
Step-by-Step: From Zero to Running Server
- Install CommandBox (Windows/macOS/Linux as noted above).
- Create a new folder and open it in a terminal.
- Initialize package metadata: run “box init” and answer prompts.
- Copy cookbook assets into your folder (ZIP extract or ForgeBox install).
- Duplicate environment samples:
- Copy .env.sample to .env and update ports, DSNs, and feature flags
- Choose an engine in server.json (e.g., Lucee@5 or ACF@2023)
- Install dependencies: “box install” to pull modules from ForgeBox.
- Load config: “box cfconfig import from=cfconfig.local.json”.
- Start the server: “box server start” and confirm the URL in output.
- Run tests: “box testbox run”; view results in console or generated report.
- Optional Docker build:
- Build image: “docker build -t myapp:latest .”
- Run: “docker run -p 8080:8080 —env-file .env myapp:latest”
If anything fails, run “box server log” and “box info” to inspect environment variables, engine versions, and module paths.
—
Key Takeaways
- The cookbook is a practical set of CommandBox recipes for automating ColdFusion/Lucee workflows.
- Core assets include a PDF guide, script library, server.json/box.json templates, cfconfig snapshots, and CI/CD examples.
- It runs Cross-platform and integrates smoothly with ForgeBox, TestBox, dotenv, and Docker.
- Adopt environment-driven configurations, versioned scripts, and caching to maximize reliability and speed.
—
FAQ
How do I find the download if I don’t have a direct link?
Search on ForgeBox for “CommandBox script Cookbook” or check your team’s documentation for a GitHub Releases URL. If it’s a private package, your organization will provide access instructions.
Does this work with both Adobe ColdFusion and Lucee?
Yes. The examples include server.json and cfconfig variants for Lucee 5/6 and Adobe CF 2018/2021/2023. Choose the engine in server.json or via environment variables.
Can I use the cookbook in CI without a desktop install?
Absolutely. Install CommandBox in your CI runner, cache the .CommandBox directory, and run the same package scripts (install, test, cfconfig import, server start) headlessly.
What if my team already has custom scripts?
You can integrate your scripts by merging them into box.json under the “scripts” section. Namespacing (e.g., “team:setup”) helps avoid collisions with cookbook-provided scripts.
Is Docker required?
No. Docker examples are included for teams that containerize, but all recipes run fine on bare metal or VMs across Windows, macOS, and Linux.
