Introduction
The ColdFusion to Lucee Migration Project Template is a downloadable, ready-to-run starter kit that accelerates moving CFML applications from Adobe ColdFusion (ACF) to Lucee Server. It provides a structured project skeleton, automated Configuration via cfconfig, Docker and CommandBox run modes, compatibility shims, and a curated Checklist to reduce risk and cost. Whether you’re migrating a legacy CFML app or building a hybrid environment, this template gives you a pragmatic pathway to test, refactor, and deploy quickly—without guessing which settings or extensions you’ll need in Lucee.
This resource is valuable because it turns a complex Migration into a guided process. It addresses Common pitfalls (datasource setup, Application.cfc differences, Scheduled tasks, mail, PDF, caching, ORM), and includes scripts and examples that are immediately runnable, so you can validate your application on Lucee within hours, not weeks.
What You’ll Get
– Project skeleton with app, config, and Infrastructure folders
– Docker and Docker Compose files for Lucee + Tomcat + NGINX (optional)
– CommandBox server.json for local non-Docker workflows
– cfconfig JSON files to import server and web context settings
– Sample Application.cfc templates for Lucee
– Compatibility “shim” functions and tag wrappers for common differences
– TestBox test harness and examples to validate functionality
– CFLint and formatting Configuration (lint rules + scripts)
– Migration Checklist and PDF quick guide (configuration map and gotchas)
– Scripts to install Lucee extensions (PDF, Spreadsheet, ORM helpers, S3)
– Example datasource.config, mail.config, caching.config, logging.config
– CI-ready examples (GitHub Actions / GitLab CI YAML) for automated tests
– README with step-by-step run instructions
File types included:
- PDF: Migration Quick Guide (12–20 pages)
- JSON: cfconfig server and web-context files
- CFC/CFM: Application.cfc variants, shims, test specs
- Dockerfile / docker-compose.yml
- server.json (CommandBox)
- Shell/Batch scripts for setup (install-extensions, import-config, run-tests)
Overview
Lucee is a high-Performance, open-source CFML engine. Migrating from Adobe ColdFusion to Lucee often involves aligning admin settings, installing Lucee extensions, adjusting Application.cfc, and testing feature parity (PDF generation, image handling, Query of Queries, scheduler, mail, Security). This template walks you through the full workflow:
- Provision a Lucee runtime via Docker or CommandBox
- Import your ColdFusion Administrator settings into Lucee with cfconfig
- Drop in your CFML code, run automated tests, and generate a compatibility report
- Apply compatibility shims and best-practice refactors (e.g., cfscript, null support)
- Deploy to the target environment (Docker, Tomcat, or CommandBox-based)
Supported environments:
- Lucee 5.4.x and 6.x
- Java 11 or 17
- Tomcat 9+ (via Docker or standalone)
- CommandBox 5.9+ / 6.x
- Adobe ColdFusion source apps from CF11 through 2023
- Databases: MySQL/MariaDB, PostgreSQL, SQL Server, Oracle (via JDBC)
Benefits
– **Faster migration**: Prebuilt configs and scripts eliminate repetitive setup.
– **Reduced risk**: Known differences (PDF, mail, admin settings) are documented and patched with shims.
– **Automation-first**: cfconfig, TestBox, and CI examples keep your migration repeatable and testable.
– **Performance**: Lucee’s fast startup, aggressive caching, and lightweight runtime can improve throughput.
– **Cost control**: Lucee is Open source; moving off ACF Licensing can reduce expenses.
How to Download
– Download the ZIP: your-organization.com/downloads/cf-to-lucee-migration-template.zip
– Or clone the repository: git clone https://your-organization.com/cf-to-lucee-migration-template.git
Note: Replace with your actual download link or repository URL.
How to Use
1) Prerequisites
– Java 11 or 17 installed and on PATH
– One of:
– Docker Desktop (latest) and Docker Compose
– OR CommandBox 5.9+ (box CLI)
– Git (optional but recommended)
– Database access (JDBC credentials)
– SMTP details (for mail Features)
2) Choose Your Runtime Mode
– Docker-based (recommended for parity with production)
– docker-compose.yml provisions Lucee + (optional) NGINX Reverse proxy
– CommandBox-based (fast local Iteration without Docker)
– server.json spins up Lucee with cfconfig imports
3) Project Structure
– /app: Place your existing CFML application here (cfm, cfc, assets)
– /config:
– cfconfig-server.json and cfconfig-web.json
– datasources.json, mail.json, caching.json, logging.json
– /Infrastructure:
– Dockerfile, docker-compose.yml, nginx.conf
– /scripts:
– install-extensions.*, import-config.*, run-tests.*
– /test:
– TestBox example specs
– /support/shims:
– Wrapper functions and tag replacements for known differences
4) Configure Your Settings
– Set environment variables (Docker Compose .env or shell):
– LUCEE_ADMIN_PASSWORD
– DB_HOST, DB_NAME, DB_USER, DB_PASSWORD
– MAIL_HOST, MAIL_USER, MAIL_PASSWORD
– Update /config/datasources.json with JDBC details and connection pool parameters (max connections, validation query).
– Update /config/mail.json with SMTP host, port, TLS/SSL, auth.
– Optional: configure caching.json (Ehcache/In-memory), logging.json (rolling files), and mappings.
5) Import Admin Settings with cfconfig
– For CommandBox:
– box server start directory=./ (starts once, then stops)
– box cfconfig import from=/config/cfconfig-server.json to=server
– box cfconfig import from=/config/cfconfig-web.json to=web
– For Docker:
– The entrypoint script runs cfconfig import automatically on first boot
– Alternatively, exec into the container and run the same cfconfig import commands
This step replicates core CFAdmin settings into Lucee Admin (server and web context).
6) Install Lucee Extensions
Commonly needed:
– PDF extension (for cfdocument)
– Spreadsheet extension (for Excel)
– Image tools (if you rely on cfimage)
– S3 resource extension (s3:// support)
– ORM/Hibernate helpers (if using ORM)
– ESAPI or Security-related libraries
Run:
- CommandBox: box install commandbox-cfconfig; box lucee-extensions install pdf spreadsheet s3
- Docker: /scripts/install-extensions.sh inside the container
7) Prepare Application.cfc
Apply the provided Application.cfc template:
– Define this.datasources for Lucee (preferred over CFAdmin-only DSN)
– Set this.sessionManagement, this.scriptProtect, this.clientManagement as needed
– Enable null support if you plan to refactor for strict null behavior
– Use this.mappings and this.customTagPaths for portability
Tip: Keep security in mind—set cookie SameSite, Secure, and HttpOnly flags for sessions.
8) Run the App
– Docker:
– docker compose up –build
– Access your app at http://localhost:8080 (or via NGINX on 80/443 if configured)
– CommandBox:
– box server start
– Visit the printed URL, typically http://127.0.0.1:XXXX
Check logs for datasource connectivity, mail, and extension load messages.
9) Validate with Tests and Linters
– Run TestBox suite:
– box testbox run (CommandBox)
– Or npm run test if you wrapped commands in package.json
– Run CFLint and formatter:
– scripts/run-lint.sh
Analyze compatibility findings (Query of Queries differences, case sensitivity, tag attribute parity, implicit struct/array behavior).
10) Apply Compatibility Shims and Refactors
– Use /support/shims to patch function differences
– Replace deprecated or ACF-only tags with Lucee equivalents
– Review PDF output fidelity and adjust cfdocument settings
– Update mail parameters (TLS, auth, timeouts)
– Confirm Scheduled tasks import and behavior (server vs web context)
– For ORM, verify ormsettings (datasource, dialect) and rebuild Hibernate
11) Prepare for Production
– Set environment-specific configs (prod vs stage) with separate cfconfig files
– Enable trusted cache and template caching where safe
– Configure log rotation and Error handling
– Harden Lucee Admin (passwords, disable remote admin, lock down endpoints)
– Integrate into CI/CD using the sample YAML files
Best practices
– Keep config as code: **cfconfig JSON** checked into Version control
– Prefer per-application settings in Application.cfc for portability
– Pin extension versions to avoid unexpected behavior
– Enable **queryparam** consistently for SQL security and performance
– Audit null support and date/timezone handling to avoid subtle bugs
– Use **mappings** and **customTagPaths** explicitly rather than relying on server-global paths
– Separate server and web context configurations; know what lives where
– Document deviations: when a feature behaves differently than ACF, note the plan (shim, refactor, or extension)
Common Differences Addressed
– PDF rendering fidelity and fonts on Lucee vs ACF
– Spreadsheet generation requiring the Lucee extension
– Query of Queries case sensitivity and function support
– Image processing library differences
– Scheduler API and task persistence
– Admin settings separation: server context vs web context
– Application.cfc scope defaults, null support, and implicit variable creation
Pros and cons
Pros
– Open-source engine with strong performance
– Config-as-code approach reduces manual admin work
– Easy local spin-up via Docker or CommandBox
– Extensions ecosystem covers most enterprise Features
Cons
- Some ACF-only features require rework or extensions
- PDF/layout parity may need tuning
- Admin context split can confuse newcomers
- Requires testing to align behaviors (e.g., QoQ, date math)
Use Cases
– Converting a legacy Adobe ColdFusion app to Lucee to reduce Licensing costs
– Running a hybrid stack: ACF in production, Lucee in test during phased migration
– Greenfield CFML apps that want a modern Docker/CI pipeline from day one
– Performance-focused workloads that benefit from Lucee’s fast startup and caching
Security and Performance Notes
– Set **Secure**, **HttpOnly**, and **SameSite** on session cookies
– Turn off Debugging in production and restrict admin endpoints
– Configure JDBC validation queries and connection pool sizes
– Use template and function caching strategically
– Add a WAF or Reverse proxy (NGINX) for TLS and Rate limiting if needed
Troubleshooting
– If cfconfig import fails: verify Admin passwords and context selection (server vs web)
– If datasources don’t appear: confirm the correct cfconfig target and JDBC drivers
– If PDF is blank or corrupted: install PDF extension, verify fonts, and test a minimal template
– If scheduled tasks don’t run: check which context they are defined in and time zone settings
– If QoQ errors occur: review SQL functions supported by Lucee’s QoQ engine
Key Takeaways
– The template provides a **repeatable, automated** migration workflow from ColdFusion to Lucee.
– Use **cfconfig** to move admin settings and keep them versioned.
– Install required **Lucee extensions** early (PDF, Spreadsheet, Image, S3, ORM helpers).
– Adjust **Application.cfc** for datasources, mappings, and null support.
– Validate using **TestBox** and **CFLint** to catch differences before production.
FAQ
How close is Lucee’s compatibility with Adobe ColdFusion?
High for core CFML, but some features differ. PDF, Image processing, QoQ, and admin behaviors can require extensions or minor refactors. The template’s shims and checklist help bridge common gaps.
Can I migrate without Docker?
Yes. The CommandBox server.json provides a non-Docker workflow. You can also deploy Lucee to an existing Tomcat. Docker is recommended for consistency across environments, but it’s optional.
What about ORM/Hibernate support?
Lucee supports ORM, but configuration can differ slightly from ACF. Use the provided ormsettings examples, verify datasource and dialect, and rebuild your mappings. Test entity Lifecycle events and lazy loading.
How do I move my ColdFusion Admin settings?
Export or recreate them in cfconfig JSON and import into Lucee’s server/web contexts. The template includes sample cfconfig files for datasources, mail, logging, caching, and scheduled tasks.
Will my PDF and Excel features work the same?
They usually work after installing Lucee’s PDF and Spreadsheet extensions, but layout fidelity and advanced features may need tuning. Start with the sample templates included and adjust fonts, margins, and rendering options.
