Introduction

Migrating or upgrading a ColdFusion platform is more than a technical milestone; it’s a chance to improve Security posture, Performance, Scalability, and maintainability. Adobe ColdFusion (and CFML apps in general) evolve rapidly: JVM requirements change, Deprecated tags/functions are removed, web server connectors are updated, and Security defaults tighten. Without thorough documentation, you risk regressions, extended downtime, or noncompliance with Audit requirements. A clear, well-structured record of your process becomes a reusable Playbook, accelerates future upgrades, and simplifies Troubleshooting.

---

Prerequisites / Before You Start

• Environments and access

  • Non-production environments: dev, QA/UAT, pre-prod/stage that mirror production topology.
  • Administrative access to CF Administrator, servers/VMs/containers, CI/CD pipelines, and databases.
  • Web Server access (IIS/Apache/Nginx) and DNS/Traffic management (F5, Cloudflare, etc.).

• Version alignment

  • Source ColdFusion version and update level (e.g., 2016 u15, 2018 u16, 2021 u10, 2023 u4).
  • Target version and JVM compatibility (e.g., ColdFusion 2023 supports Java 11 and 17).
  • OS and web server versions (Windows Server/IIS vs Linux/Apache).
  • JDBC driver versions (e.g., MySQL, SQL Server, Oracle), Solr, PDFg, or other services.

• Dependencies and third-party integrations

  • CFML libraries, Custom tags, CFCs, OSGi bundles, cfpm-installed packages.
  • External systems: SMTP, SFTP, REST/SOAP endpoints, Redis, Elasticsearch/Solr, Message queues.

• Backups and exports

  • Code repository snapshot/tag.
  • Database backups and schema snapshots.
  • ColdFusion Administrator settings:
    • For CF2021/2023: use cfsetup to export as JSON.
    • For older versions: generate a CAR file (ColdFusion Archive).
  • Web server Configuration backups (IIS config, Apache httpd.conf, vhosts).
  • JVM options (jvm.config) and ColdFusion service files (server.xml, neo-*.xml).

• Governance and planning

  • Defined change window and rollback plan.
  • Stakeholder list and RACI (who approves, who executes, who validates).
  • Performance baselines and test plans (load tests, smoke tests).
  • Compliance or Audit requirements (SOX, PCI, HIPAA), including documentation retention.

• Tooling

  • Git or other VCS for code and documentation.
  • Issue tracker (Jira, Azure Boards) for tasks and risks.
  • Optional: CommandBox/CFConfig for scripted Configuration; container tooling (Docker/Compose).

---

Documentation Blueprint

Repository Structure (suggested)

• 00-overview.md — scope, goals, timeline, contacts.
• 01-inventory.md — servers, versions, datasources, connectors, integrations.
• 02-compatibility.md — deprecated Features, code impact, test coverage.
• 03-build-target.md — environment build steps (IaaC, installers, cfpm).
• 04-configure-cf.md — CFAdmin/cfsetup or CAR usage; JVM; Security settings.
• 05-connectors-web.md — IIS/Apache connector steps; SSL/TLS settings.
• 06-data-and-integrations.md — datasources, credentials, secrets management.
• 07-testing.md — smoke, regression, performance, security test plans/results.
• 08-cutover-runbook.md — go-live steps, verification, rollback.
• 09-post-Migration.md — validations, known issues, acceptance signoff.
• 10-lessons-learned.md — retrospectives and improvement items.

Naming Conventions

• Use consistent environment suffixes: appname-cf2023-uat, appname-cf2023-prod.
• Timestamp and version each artifact: car-export_2018u16_2025-09-20.car.
• Keep secrets out of the repo; use placeholders or a vault reference.

What to Capture (example)

Item	What to record	Tool/Source	Example
CF Version	Version and update	CF Admin / cfusion/lib/updates	Adobe CF 2023 u4
JVM	Version and options	jvm.config / java -version	Java 17.0.9, -Xms4g -Xmx4g
Datasources	DSN, driver, URL	CF Admin / cfsetup export	jdbc:sqlserver://db01:1433;databaseName=ERP
Connectors	Sites mapped, connector version	wsconfig -list	IIS Site “MainSite” -> Tomcat AJP
Packages	cfpm packages	cfpm list	pdfg, image, zip
Security	Secure Profile, Sandbox	CF Admin / cfsetup	secure profile ON, sandbox OFF

---

Step-by-Step Migration and Documentation Guide

Each step includes what to do and what to document so your migration becomes a repeatable runbook.

1) Define Scope, Goals, and Success Criteria

• What to do
  • Set the target ColdFusion version and date.
  • List applications, sites, and Scheduled tasks in scope.
  • Define success KPIs: zero data loss, <15 min downtime, 15% performance gain, all tests pass.
• Document
  • A brief scope statement.
  • Risk tolerance, rollback trigger conditions, and signoff stakeholders.

2) Inventory the Current State

• What to do

  • Export ColdFusion settings:

    • CF2021/2023:

      cfsetup export -o cfserver-config.json

    • Older CF using CAR: create a CAR file from CF Admin.

  • List datasources, mail servers, caches, mappings, Scheduled tasks, PDFg/Solr usage.

  • Capture web server configs and connector mappings:

    • Windows:

      “C:\ColdFusion2023\cfusion\runtime\bin\wsconfig.exe” -list

    • Linux:

      /opt/coldfusion/cfusion/runtime/bin/wsconfig.sh -list

• Document

  • 01-inventory.md with tables for DSNs, connectors, packages, and JVM settings.
  • Attach exports (JSON, CAR) and web server backups.

3) Baseline Performance and Behavior

• What to do
  • Record key Performance metrics: response times, throughput, CPU/memory, GC behavior.
  • Run smoke tests and a small load test to set a baseline.
• Document
  • 07-testing.md baseline section with metrics and test scripts.
  • Any known production issues to verify after upgrade.

4) Compatibility Analysis

• What to do
  • Identify deprecated CFML tags/functions and security changes in target version.
  • Review application logs for use of Features like Flash Forms, Verity, old cfdocument fonts, or JavaLoader specifics.
  • Check JDBC driver compatibility and TLS requirements.
• Document
  • 02-compatibility.md mapping each finding to an action.
• Practical examples
  • Replace deprecated functions, e.g., structKeyExists vs isDefined, cfqueryparam usage.
  • Update cfhttp to modern TLS ciphers if needed.

5) Build the Target Environment

• What to do

  • Provision servers/containers matching production topology.
  • Install ColdFusion target version and updates.
  • Set JVM to the supported version and tune heap/GC.

• Practical example (Dockerfile skeleton)

  FROM adobecoldfusion:2023.0.4
  ENV CF_SETUP_ENABLED=true
  COPY cfserver-config.json /opt/coldfusion/cfsetup/cfserver-config.json
  RUN cfpm install pdfg image && \
  cfsetup import -f /opt/coldfusion/cfsetup/cfserver-config.json

• Document

  • 03-build-target.md with exact commands, versions, and AMIs/container tags used.
  • IaaC references (Terraform/Ansible) and parameter files.

6) Configure ColdFusion on the Target

• What to do

  • Apply CFAdmin settings via cfsetup (preferred) or CAR file.

    • Import using cfsetup:

      cfsetup import -f cfserver-config.json

  • Install required packages with cfpm:

    cfpm list
    cfpm install pdfg
    cfpm install image

  • Set JVM options in jvm.config (e.g., G1GC, heap sizes).

• Document

  • 04-configure-cf.md: what was imported, any manual tweaks (e.g., passwords re-entered).
  • Secure profile, session settings, serializations, request timeouts.

7) Configure Web Server Connectors

• What to do

  • Install/upgrade the web server connector; ensure SSL/TLS and cipher suites are compliant.

  • IIS example (add connector):

    “C:\ColdFusion2023\cfusion\runtime\bin\wsconfig.exe” -add -ws IIS -siteid 1

  • Apache example:

    /opt/coldfusion/cfusion/runtime/bin/wsconfig.sh -add -ws Apache -dir /etc/httpd/conf -bin /usr/sbin/httpd

• Document

  • 05-connectors-web.md: connector versions, mapped sites, verify virtual directories, and AJP/HTTP port usage.
  • Include steps for fallback (remove connector, restore backup configs).

8) Migrate Application Code and Dependencies

• What to do
  • Merge code changes for compatibility (tag/commit).
  • Adjust library paths, Java JARs, and OSGi bundles.
  • Validate scheduled tasks, CF mappings, and Custom tags.
• Document
  • Code release notes and change list in 03/04 sections or in repository release notes.
  • Mapping of old paths to new paths.

9) Datasources and External Integrations

• What to do

  • Create DSNs with correct drivers and connection strings; test connections.
  • Validate credentials via a vault or secrets manager; do not hardcode.
  • Verify SMTP, SFTP, REST/SOAP endpoints, and firewall rules.

• Practical example (DSN URL)

  jdbc:sqlserver://sql-prod:1433;databaseName=ERP;encrypt=true;trustServerCertificate=false

• Document

  • 06-data-and-integrations.md: DSN list, driver versions, test results, and timeout settings.
  • Note any schema changes or migration scripts.

10) Security Hardening

• What to do
  • Enable secure profile where supported; set minimum password policies.
  • Restrict RDS or disable entirely.
  • Configure Sandbox security (if applicable) and lock down CFIDE.
  • Set HTTP-only and secure cookies, HSTS, CSP headers at web server or app level.
• Document
  • Security Checklist with each control and verification screenshot/log.
  • Known exceptions with risk acceptance tickets.

11) Testing: Smoke, Regression, Performance

• What to do
  • Execute smoke tests after each Deployment step.
  • Run automated regression suite; include PDF generation, image manipulation, CFCHART, file I/O.
  • Repeat load tests; compare to baseline; check memory/GC.
• Document
  • 07-testing.md: pass/fail matrix, bug tickets, and performance graphs.
  • Capture logs from coldfusion-out.log, exception logs, and web Server logs.

12) Cutover and Rollback

• What to do
  • Schedule change window; announce to stakeholders.
  • Quiesce traffic or enable Maintenance page.
  • Switch DNS/traffic, or rotate autoscaling group/container tags.
  • Monitor health; if SLOs fail, rollback via documented steps.
• Sample rollback note
  • Keep old connectors and service snapshots; revert DNS or load balancer target groups.
• Document
  • 08-cutover-runbook.md: minute-by-minute plan, owners, and checkpoints.
  • Rollback triggers and exact commands.

13) Knowledge Transfer and Finalization

• What to do
  • Update on-call runbooks, diagrams, and CMDB.
  • Record “known differences” between versions and any one-off configurations.
• Document
  • 10-lessons-learned.md and distribute links to the team wiki.
  • Record final asset locations and retention policy for artifacts.

---

Risks, Common Issues, and How to Avoid Them

• Configuration drift

  • Risk: Hand-edited settings in one environment cause unpredictable behavior.
  • Avoid: Use cfsetup or Automation scripts; keep config JSON/CAR files under Version control.

• Connector mismatches

  • Risk: Old web server connectors cause 500 errors, stuck threads, or AJP protocol issues.
  • Avoid: Reinstall connectors matching the target CF, verify with wsconfig -list, and test TLS/HTTP or AJP settings.

• JVM incompatibilities

  • Risk: Upgrading to Java 17 while code depends on internal APIs/jar conflicts.
  • Avoid: Audit JARs, remove duplicates, test with the target JVM early, and set explicit endorsed dirs if needed.

• Deprecated CFML features

  • Risk: Removal of legacy tags or behavior changes breaking pages.
  • Avoid: Run compatibility scans, refactor or polyfill with modern CFScript/CFML, add feature toggles.

• Datasource driver changes

  • Risk: New JDBC drivers alter default encodings/isolation or require additional parameters.
  • Avoid: Confirm driver versions and parameters; test transactions and batch operations.

• Security tightening

  • Risk: Secure profile or sandbox prevents legitimate operations.
  • Avoid: Document required permissions; create targeted sandbox policies; whitelist only necessary tags/functions/paths.

• Performance regressions

  • Risk: GC changes or new default settings impact throughput.
  • Avoid: Carry over JVM tuning, profile under load, adjust G1GC or heap sizes, and verify datasource pool sizes.

• Time zones and locale differences

  • Risk: New servers have different TZ/locale, affecting date/time logic.
  • Avoid: Standardize TZ; capture it in inventory; run date/time regression tests.

---

Post-Migration Checklist

• Application function

  • All critical paths pass smoke tests: login, search, checkout, reports, admin pages.
  • PDF generation, Image processing, scheduled tasks, and email sending verified.

• Configuration integrity

  • CF Admin settings match expected cfsetup/CAR import; no unexpected diffs.
  • Datasources: test connection successful; queries return expected results.
  • JVM: -Xms/-Xmx, GC logs enabled if policy requires, correct Java version.

• Security validation

  • RDS disabled; CFIDE access restricted.
  • HTTPS enforced; HSTS set; secure/httponly cookies; CSP headers as designed.
  • No sensitive data in logs; secrets sourced from vault.

• Web server and connectors

  • Connector status healthy; no 500/503 spikes in logs.
  • Compression/caching rules working; URL rewrites correct.

• Observability

  • Monitoring and alerting hooked to the new instances (APM, logs, metrics, traces).
  • Dashboards updated; SLOs visible and thresholds tuned.

• Documentation and governance

  • All runbooks updated and stored in the central repository.
  • Change record closed with links to artifacts and test evidence.
  • Final signoff from Product owner and platform owner.

---

Sample Configuration Artifacts

cfsetup export/import

Export (source environment)

cfsetup export -o cfserver-config.json

Import (target environment)

cfsetup import -f cfserver-config.json

wsconfig examples

IIS: list and add connector (Windows)

“C:\ColdFusion2023\cfusion\runtime\bin\wsconfig.exe” -list
“C:\ColdFusion2023\cfusion\runtime\bin\wsconfig.exe” -add -ws IIS -siteid 1

Apache: list and add connector (Linux)

/opt/coldfusion/cfusion/runtime/bin/wsconfig.sh -list
/opt/coldfusion/cfusion/runtime/bin/wsconfig.sh -add -ws Apache -dir /etc/httpd/conf -bin /usr/sbin/httpd

cfpm Package management

cfpm list
cfpm install pdfg
cfpm install image
cfpm remove example-package

---

Documentation Tips and Best practices

• Keep documentation close to the code and config (same repo, adjacent folders).
• Use checklists for repeatability; mark each step with owner and timestamp.
• Store environment-specific overrides in secure parameters, not hardcoded files.
• Attach evidence: screenshots, log excerpts, and command outputs as appendices.
• Use bold emphasis for critical decisions and rollback points.
• Maintain a change log that states not only what changed, but why.

---

Example Runbook Excerpt (Cutover)

• H-60 min: Announce Maintenance; freeze deployments.
• H-45 min: Backup configuration and DB; verify last snapshot ID.
• H-30 min: Enable maintenance page; drain sessions.
• H-20 min: Deploy new CF servers; validate health checks.
• H-10 min: Switch connector/DNS to new target; flush CDN cache if needed.
• H+0 min: Execute smoke tests; monitor error rates and latency.
• H+15 min: If KPIs met, disable maintenance page; otherwise initiate rollback.

---

FAQ

How do I move ColdFusion Administrator settings safely between versions?

Use cfsetup for CF2021/2023 to export/import settings as JSON. For older versions, use CAR files from the Packaging & Deployment section. Always review security-sensitive values post-import and re-enter secrets through your vault.

Should I upgrade Java first or ColdFusion first?

Align with Adobe’s supported JVM for your target ColdFusion release. When moving to a new CF version, build a new environment with the correct JVM rather than in-place switching; it reduces risk and simplifies rollback.

Can I automate the entire migration?

Yes. Combine IaaC for servers, cfsetup for CFAdmin configuration, cfpm for packages, and CI/CD for code deployments. Add automated tests and health checks to the pipeline so each environment can be recreated consistently.

What if we plan to migrate from Adobe ColdFusion to Lucee?

Treat it as a Platform migration with more extensive compatibility testing. Audit proprietary features, Admin settings, and tags that differ. Tools like CommandBox and CFConfig can help script settings across engines, but thorough functional and Performance testing is essential.