Why moving from ColdFusion 10 to 2023 matters

Adobe ColdFusion 10 reached end-of-life years ago. Remaining on it exposes your applications to unpatched Security vulnerabilities, outdated cryptography, and dependencies that modern operating systems and web servers no longer support. The 2023 release delivers long-term platform support, modern Java compatibility (Java 11, with Java 17 supported on recent updates), a faster Tomcat engine, improved Security, modular Features via the package manager, and better tooling for DevOps. A well-planned upgrade boosts Performance, reduces risk, and positions your CFML apps for the next several years.

Prerequisites / Before You Start

Inventory and environment

• Document your current environment:
  • Operating system and version (and whether it’s 32-bit or 64-bit).
  • Web server and version (IIS, Apache, Nginx via AJP/JK/BonCode).
  • Java version used by CF10 (likely 1.6/1.7).
  • ColdFusion edition (Standard/Enterprise) and whether it is single instance or multi-instance.
  • Datasource vendors/versions (SQL Server, Oracle, MySQL, PostgreSQL, etc.).
  • Libraries and native dependencies (JDBC, ODBC bridges, PDFg, Solr, .NET Integration, ImageMagick/Ghostscript, C++ redistributables).
  • Scheduled tasks, event gateways, remote endpoints, and mail servers.
  • Licensing status (CF10 keys won’t work on 2023; plan for new licenses or trial keys for testing).

Backups and exports

• Full filesystem backup of ColdFusion 10:
  • CF root (cfusion and any additional instances).
  • Configuration files: jvm.config, server.xml, web.xml, neo-*.xml (datasources, mail, logging, etc.).
  • Webroot(s), Custom tags, CFCs, mappings, custom fonts, certs/keystores.
• Database backups and snapshot permissions.
• Web server Configuration backups:
  • IIS: applicationHost.config, site-level web.configs.
  • Apache: httpd.conf, conf.d/, ssl.conf, vhost files.
• Export artifacts:
  • ColdFusion Archive (CAR) files from CF10 if you have them for structured settings.
  • Export Scheduled tasks (XML) if managed via Admin.
  • Copy a list of CF Admin settings (screenshots and/or Admin API outputs).

Compatibility and code readiness

• Note Deprecated tags/functions you rely on.
• Identify old JDBC drivers (e.g., jTDS for SQL Server) to replace with modern vendors’ drivers.
• Set aside time for re-indexing Solr collections (index formats changed significantly).
• Plan for 64-bit. ColdFusion 2023 is 64-bit; ensure OS and web server are 64-bit.

Testing and change management

• Set up a separate test environment to perform a side-by-side Migration.
• Define a rollback plan:
  • Retain the old server intact behind a Maintenance toggle or DNS switch-back.
  • Ensure you can restore prior connectors quickly.
• Communication plan for stakeholders.
• Maintenance window(s) and load testing schedules.

Security and Compliance

• Target Java 11 (minimum) or Java 17 (if using a CF2023 update that supports it).
• Prepare to re-enter secrets (DSN passwords, mail passwords). Encrypted values in CF10 configs cannot be reused.
• Download:
  • ColdFusion 2023 installer (same edition as you intend to run).
  • ColdFusion 2023 Add-on Services (if you use PDFg, Solr, or certain gateways).
  • Lockdown Tool for ColdFusion 2023.
  • Latest ColdFusion 2023 cumulative updates.

Step-by-step Migration guide

1. Choose a side-by-side install strategy

Avoid in-place upgrades. Install ColdFusion 2023 in parallel on the same server (different ports) or, ideally, on a new server/VM/container. This reduces downtime and risk, allows easy comparisons, and prevents legacy files from contaminating the new install.

• Choose ports that do not conflict (e.g., built-in Tomcat HTTP port 8500).
• Keep CF10 service running during the migration window for reference.

2. Install ColdFusion 2023 and update it

• Run the installer as administrator (Windows) or with sudo (Linux).
• Pick the profile:
  • Developer or Production Server profile depending on target use.
• After installation, immediately apply the latest updates via the Administrator or command line to ensure security and compatibility.

Example (Windows Service restart):

net stop ColdFusion2023
net start ColdFusion2023

3. Install required modules and add-on services

ColdFusion 2023 uses a modular approach. Use the ColdFusion Package Manager (cfpm) to install Features you need.

List modules:

cfpm.bat list

Install modules (examples):

cfpm.bat install sqlserver
cfpm.bat install mysql
cfpm.bat install pdf
cfpm.bat install s3
cfpm.bat install redis
cfpm.bat install elasticsearch // if provided
cfpm.bat install graphqL // feature availability depends on version/update

If you rely on PDFg (cfhtmltopdf with the external service), Solr search, or certain event gateways, run the separate “ColdFusion 2023 Add-on Services” installer. After installation, configure service endpoints in the Administrator.

4. Configure the JVM and memory

ColdFusion 2023 runs on Java 11 (with optional Java 17 depending on updates). Tune jvm.config for heap and GC:

Edit {cf_root}/cfusion/bin/jvm.config:

Common production starting point, adjust for your system size

-Djava.awt.headless=true
-Xms4g
-Xmx4g
-XX:+UseG1GC
-XX:MaxGCPauseMillis=200
-XX:+UseStringDeduplication
-XX:+HeapDumpOnOutOfMemoryError
-XX:HeapDumpPath=/opt/coldfusion/cfusion/logs/heapdump.hprof
-Duser.timezone=UTC

Restart the CF2023 service to apply.

5. Migrate configuration settings

You have several options:

• Migration Wizard: On first Admin login, CF2023 may detect earlier versions on the same machine and offer to import settings. This is convenient but verify everything manually afterward.
• Manual re-creation: Recommended for clarity and cleanliness.
  • Re-create mappings, datasources, mail servers, caches, REST services, WS-Security, etc.
  • Re-enter all passwords and secrets.
• CAR files: If you have CF10 CARs, import carefully. Schemas differ; expect to re-check every imported setting.
• cfsetup CLI: ColdFusion 2023 can import/export Admin settings to JSON. You cannot export from CF10 with cfsetup, but once you finalize settings on 2023, export them to version-control your configuration going forward.

Example (on 2023):

cfsetup export -o c:\configs\cf2023-admin.json
cfsetup import -i c:\configs\cf2023-admin.json

Note: Test cfsetup exports/imports in a non-production instance first.

6. Re-create datasources using modern JDBC drivers

CF10 often used older drivers (e.g., jTDS for SQL Server). In CF2023:

• Use vendor-supported drivers:
  • SQL Server: Microsoft JDBC driver (shipped with CF2023 via cfpm sqlserver).
  • Oracle: Oracle JDBC Thin.
  • MySQL: Connector/J 8.x.
  • PostgreSQL: Official JDBC.
• Connection strings and options may change. For SQL Server, integrated security or encryption defaults may require:
  • encrypt=true; trustServerCertificate=false; hostNameInCertificate=…
• Test each DSN with the “Verify” button.
• Check transaction isolation, stored procedure support, and connection pooling options.

Example (SQL Server additional settings):

;encrypt=true;
;trustServerCertificate=false;
;loginTimeout=30;

7. Reinstall and rebind web server connectors

Do not copy old connectors. Use the 2023 wsconfig tool to create new connectors.

• IIS (Windows):

  • Remove old CF10 isapi_redirector or handlers from IIS Manager.

  • Run wsconfig.exe from {cf_root}\cfusion\runtime\bin\:

    wsconfig.exe -list
    wsconfig.exe -remove -ws 1
    wsconfig.exe -add -ws iis -siteid 1 -instance cfusion -coldfusion C:\ColdFusion2023

  • Verify that the ISAPI filter/handler is configured on your site(s) and application pool identities are correct.

• Apache (Linux):

  • Use wsconfig.sh:

    sudo /opt/coldfusion2023/cfusion/runtime/bin/wsconfig.sh -add -ws apache -dir /etc/httpd/conf
    sudo systemctl restart httpd

• If you use BonCode for AJP/HTTP bridging, deploy a fresh configuration targeting the new CF2023 port.

8. Migrate scheduled tasks, event gateways, and integrations

• Scheduled Tasks:
  • Export from CF10 if possible and import on CF2023; otherwise, recreate.
  • Update “Run as” credentials and SSL/TLS endpoints (older TLS 1.0/1.1 endpoints may fail).
• Event Gateways:
  • Reconfigure JMS, SMS, Socket, or Directory watchers. Some gateways moved to Add-on Services; ensure they’re running.
• Mail:
  • Re-enter SMTP settings with proper TLS. Test with a sample cfmail.

9. Update Application.cfc and Security settings

Review application-level settings:

• Revisit Session management and timeouts.
• Evaluate enabling secure profile options in CF Admin (XSS script protection, client variable storage, session cookie flags).
• Review the need for null support (this.nullSupport). Enabling nulls can break Legacy code expecting empty strings; keep disabled unless you’re ready to adapt code.

Example Application.cfc snippet:

component {
this.name = “MyApp2023”;
this.sessionManagement = true;
this.sessionTimeout = createTimeSpan(0,0,30,0);
this.scriptProtect = “all”;
this.secureJSON = true;
this.useUUIDForSessionKeys = true;
this.setClientCookies = true;
}

10. Test and fix code compatibility

• Use the ColdFusion 2023 Code Analyzer from the Administrator to scan your codebase for Deprecated tags/functions and compatibility issues.
• Common areas to review:
  • Deprecated functions and attributes.
  • Changes in cfhttp/cfmail defaults regarding TLS and ciphers.
  • PDF processing changes; cfdocument Performance/formatting can differ.
  • Solr search: Collections need re-indexing; APIs may change.
  • SQL differences due to new JDBC drivers (parameter binding, date/time handling).
• Create automated tests for critical paths: login, checkout, File upload, scheduled processes, and reporting.

11. Migrate search (Solr) and re-index

• Install the Search/Solr module or Add-on Service for 2023.
• Recreate collections and re-index content; do not copy Solr indexes from CF10.
• Validate search queries and analyzers.

12. Harden with the Lockdown Tool

• Run the official Lockdown Tool for 2023 to apply best-practice hardening:
  • Restrict Administrator access path.
  • Remove sample apps.
  • Limit RDS and Debugging features.
  • Enforce secure cookies and headers.
• Review results and adapt to your environment (load balancers, reverse proxies).

13. Cutover and DNS/traffic switch

• Choose low-traffic window.
• Disable CF10 connectors or remove site bindings.
• Point IIS/Apache sites to the new connector (or flip load balancer targets).
• Monitor logs and metrics closely.

Key differences from CF10 you’ll notice

• Java 11+ runtime, G1GC by default recommended.
• Tomcat engine upgrade, better performance and HTTP handling.
• Modern JDBC drivers and stricter TLS defaults.
• Modular features (cfpm) and Add-on Services separation.
• Improved Admin APIs and cfsetup CLI for configuration as code.
• New language features in CFML, improved JSON handling, REST, cloud connectors, caching, and GraphQL (depending on updates).

Risks, Common Issues, and How to Avoid Them

• Legacy JDBC parameters break with new drivers
  • Symptom: DSN verification fails or queries error out.
  • Avoid: Recreate DSNs, remove unsupported params (e.g., selectMethod), and enable proper encryption settings.
• TLS/SSL negotiation failures
  • Symptom: cfhttp/cfmail to older endpoints fail due to TLS 1.0/1.1 deprecation.
  • Avoid: Ensure endpoints support TLS 1.2+, update JCE policies (bundled in modern JDKs), and specify modern cipher suites if needed.
• Passwords and secrets don’t migrate
  • Symptom: Admin shows blank secrets; services fail to authenticate.
  • Avoid: Plan to re-enter all secrets; keep a secure runbook of credentials.
• Connector misconfiguration
  • Symptom: 500 errors through IIS/Apache, but CF works on its internal port.
  • Avoid: Reinstall connectors with wsconfig, ensure application pools have rights to connector directories, confirm handler mappings.
• Memory and GC regressions under load
  • Symptom: Slow requests or OutOfMemoryError after going live.
  • Avoid: Right-size -Xms/-Xmx, use G1GC, monitor heap/metaspace. Load-test before cutover.
• Solr/index incompatibility
  • Symptom: Search returns nothing or errors.
  • Avoid: Recreate collections and re-index using 2023 services only.
• File path and permission differences
  • Symptom: cfdocument/cffile errors, image functions fail.
  • Avoid: Grant service account access to required folders, temp directories, fonts, and certificates.
• 32-bit to 64-bit surprises
  • Symptom: Native libraries or ODBC bridges fail.
  • Avoid: Replace with 64-bit drivers and supported alternatives.

Post-Migration Checklist

• Functional validation
  • Smoke test critical pages and workflows.
  • Verify logins, sessions, file uploads, downloads, and PDF generation.
  • Validate scheduled tasks execution and timings.
• Data connectivity
  • Verify each datasource with sample queries.
  • Check connection pooling and failover behaviors.
• Integrations
  • Test SMTP (TLS), LDAP/AD, S3/Azure blob (if used), Redis cache, and REST endpoints.
  • Confirm Payment gateways or external APIs with sandbox/test transactions.
• Search and reporting
  • Confirm Solr collections populated and queries return expected results.
  • Validate report generation (PDF/Excel/CSV) and font embedding.
• Performance and stability
  • Review Server logs: {cf_root}/cfusion/logs/.
  • Monitor heap usage, GC logs, thread counts, and response times under load.
• Security
  • Confirm Lockdown Tool changes, Admin access restrictions, secure cookies, and headers.
  • Validate that RDS is disabled in production.
• Backups and Disaster recovery
  • Update backup jobs to include new directories.
  • Export a cfsetup JSON of your final 2023 config for source control.
• Documentation
  • Record final jvm.config, connector settings, DSN configurations, and any code changes.
• Decommissioning
  • When stable, stop and archive CF10.
  • Remove old connectors and firewall rules.

Example configurations and commands

wsconfig examples

IIS (site ID 2) binding:

“C:\ColdFusion2023\cfusion\runtime\bin\wsconfig.exe” -add -ws iis -siteid 2 -instance cfusion -coldfusion “C:\ColdFusion2023”

Apache (RHEL/CentOS):

sudo /opt/coldfusion2023/cfusion/runtime/bin/wsconfig.sh -add -ws apache -dir /etc/httpd/conf
sudo systemctl restart httpd

JVM tuning in jvm.config

-Djava.awt.headless=true
-Xms4096m
-Xmx4096m
-XX:+UseG1GC
-XX:MaxGCPauseMillis=200
-XX:+UseStringDeduplication
-Dfile.encoding=UTF-8
-Duser.timezone=UTC

cfpm useful commands

cfpm.bat list available
cfpm.bat install sqlserver mysql postgres oracle pdf s3 redis
cfpm.bat remove

Practical migration timeline (example)

• Day 1–3: Inventory, backups, environment build.
• Day 4–6: Install CF2023, apply updates, configure JVM, install modules.
• Day 7–10: Re-create Admin settings, DSNs, connectors; migrate scheduled tasks.
• Day 11–15: Code analyzer, fix incompatibilities, re-index Solr, Performance tuning.
• Day 16: Lockdown, security tests.
• Day 17–18: Load testing and dry-run cutover.
• Day 19: Production cutover and hypercare.
• Day 20+: Decommission CF10 after stability window.

Tips for larger/clustered environments

• Multi-instance or Enterprise:
  • Use the Instance Manager to create additional instances.
  • Keep configurations consistent with cfsetup exports.
  • Stagger upgrades node by node behind the load balancer.
• Containers:
  • Consider Adobe’s official CF2023 Docker images.
  • Bake settings via environment variables and cfsetup during image build.
  • Externalize logs and enable health probes.

Reference table: What not to copy from CF10

• Do copy
  • Application code (.cfm/.cfc), Web assets
  • Custom tag libraries
  • Certificates and keystores (convert formats if needed)
  • Fonts/resources used by PDF
  • Backup copies of neo-*.xml for reference only (not reuse)
• Do not copy
  • Old connectors or isapi_redirector binaries
  • Old /runtime or /lib jars from CF10
  • Old Solr indexes
  • Encrypted passwords from neo-*.xml
  • jvm.config and server.xml without review/adaptation

Validation Steps (quick run list)

• Homepage renders via web server (not just CF internal port)
• Admin accessible only from approved IPs
• All DSNs verified and used in a test operation
• cfmail test completes without TLS error
• Scheduled tasks run at expected times
• Search returns expected results
• PDF generation produces correct fonts and layout
• GC logs show stable pause times under load
• No new errors in exception.log/application.log
• Security scan passes (headers, SSL, cookies) and Lockdown Checklist satisfied

FAQ

Can I perform an in-place upgrade from ColdFusion 10 to 2023?

No. ColdFusion 2023 is a separate installation. Perform a side-by-side install, configure and test, then switch traffic. This method is safer, reduces downtime, and avoids leftover artifacts from CF10.

Will my CF10 CAR files import cleanly into 2023?

Sometimes, but not always. Schemas and features changed. You can try the Migration Wizard or import CARs, but you must validate every setting afterward. Many teams choose to recreate settings manually and then export a cfsetup JSON for future reproducibility.

Do I need to re-enter datasource and mail passwords?

Yes. Encrypted secrets from CF10 cannot be reused because hashing/encryption formats differ. Plan to manually re-enter all sensitive values during the migration.

Which Java version should I use with ColdFusion 2023?

Use Java 11 as the baseline. ColdFusion 2023 also supports Java 17 on recent updates. Align with Adobe’s supported matrix for your exact update level and keep Java patched with security updates.

What about Solr search collections from CF10?

Do not copy old indexes. Install the Solr service/module for 2023, recreate collections, and perform a full re-index. Index formats and versions have changed significantly since CF10.