ColdFusion Migration Patterns

Approaches that work, tested in hundreds of migrations

Proven migration patterns and step-by-step guides for upgrading legacy ColdFusion versions, modernizing architecture, and transitioning to cloud infrastructure.

Need expert help? Convective is an Adobe Solution Partner with 26+ years of ColdFusion experience. We've migrated 100+ applications with zero downtime.

Talk to our migration team →

Pattern 1: Legacy Version Migration (CF 11 → CF 2025)

Complexity: HighDuration: 6-12 monthsRisk: Medium-High

Overview

Migration strategy for applications on end-of-life ColdFusion 11, moving directly to ColdFusion 2025 (the current release) in two phases. Adobe documents the ColdFusion 2025 migration wizard as supporting settings migration from ColdFusion 2016, 2018, 2021, and 2023, so ColdFusion 11 Administrator settings must be recreated by hand (Adobe ColdFusion FAQ). Stepping through an intermediate release is not required, and ColdFusion 2018 and 2021 are past the end of Adobe support (Adobe EOL matrix).

Recommended Approach: Two-Phase Migration to ColdFusion 2025

Phase 1: Code Remediation on CF 2025

Duration: 2-4 months

  • Install ColdFusion 2025 (JDK 21) on an isolated test server
  • Run the Code Analyzer there against the CF 11 codebase
  • Fix incompatibilities: removed and deprecated tags and functions, security issues
  • Test all application workflows on CF 2025

Phase 2: Configuration and Cutover

Duration: 2-4 months

  • Recreate CF 11 Administrator settings (datasources, mappings, mail, scheduled tasks) on CF 2025; the migration wizard does not import CF 11 settings
  • Once configured, export settings with cfsetup for repeatable builds of staging and production
  • Apply the ColdFusion 2025 Lockdown Guide
  • Deploy to staging, monitor for issues
  • Production cutover with rollback plan

Detailed Migration Steps

1

Code Analysis & Inventory

# Run Adobe's Code Analyzer against the CF 11 codebase
# on the target version: ColdFusion Administrator >
#  Debugging & Logging > Code Analyzer
# It flags unsupported and deprecated features
# Third-party options: Fixinator (security), CFLint (code quality)

# Review report: compatibility issues, deprecated features
# Prioritize: Critical > High > Medium > Low
2

Fix Compatibility Issues

<!-- Replace deprecated tags -->
<!-- OLD: <cfchart> with Flash -->
<cfchart format="flash">

<!-- NEW: Use HTML5 charting (format="flash" is removed in CF 2025) -->
<cfchart format="html">
3

Environment Setup

# Install CF 2025 on a test server (installer from Adobe's downloads page;
# default UNIX install directory: /opt/coldfusion2025)

# Copy application code
rsync -av /var/www/myapp/ /opt/coldfusion2025/cfusion/wwwroot/myapp/

# Recreate datasources and other settings in the CF Administrator
# Match production settings exactly

# Configure the web server connector
cd /opt/coldfusion2025/cfusion/runtime/bin
./wsconfig -ws apache -dir <apache_config_directory>
4

Testing & Validation

  • Functional testing: All user workflows
  • Integration testing: External systems, APIs
  • Performance testing: Load test at 150% expected load
  • Security testing: Run security scan, penetration test
  • UAT: User acceptance testing with stakeholders
5

Production Deployment

# Deployment checklist:
1. Backup current CF 11 installation
2. Backup database (full backup + transaction logs)
3. Document rollback procedure
4. Schedule maintenance window (off-peak hours)
5. Deploy CF 2025 with blue-green deployment
6. Monitor logs, error rates, performance metrics
7. Keep CF 11 running for 24h rollback window
8. Gradual traffic shift: 10% → 50% → 100%

Risk Mitigation

Risk: Data Loss

Mitigation: Multiple backups, test restore procedures, maintain transaction logs, verify data integrity post-migration

Risk: Extended Downtime

Mitigation: Blue-green deployment, parallel environments, gradual traffic shift, 24/7 on-call team during cutover

Risk: Undiscovered Bugs

Mitigation: Comprehensive testing suite, staged rollout, real-time monitoring, feature flags for quick disable

Success Criteria

  • All automated tests passing (100%)
  • Error rate below baseline (<0.1%)
  • Performance equal or better than CF 11
  • Zero data loss or corruption
  • Successful rollback test completed

Pattern 2: Monolith to Microservices

Complexity: Very HighDuration: 12-18 monthsRisk: High

Overview

Decompose monolithic ColdFusion application into microservices using strangler fig pattern, maintaining business continuity throughout transformation.

Strangler Fig Pattern

Incrementally replace monolith functionality with microservices, routing traffic through API gateway.

Architecture Evolution

Phase 1: Monolith + API Gateway
┌─────────────┐
│   Clients   │
└──────┬──────┘
       │
┌──────▼──────────────┐
│    API Gateway      │
│  (NGINX/Kong)       │
└──────┬──────────────┘
       │
┌──────▼──────────────┐
│  Monolith (CF)      │
│  All Features       │
└─────────────────────┘

Phase 2: Hybrid (Gradual Migration)
┌─────────────┐
│   Clients   │
└──────┬──────┘
       │
┌──────▼──────────────┐
│    API Gateway      │
│   (Route Split)     │
└──┬────────────────┬─┘
   │                │
┌──▼────────┐  ┌───▼──────────┐
│ Monolith  │  │ Microservice │
│ (Reduced) │  │ User Auth    │
└───────────┘  └──────────────┘

Phase 3: Full Microservices
┌─────────────┐
│   Clients   │
└──────┬──────┘
       │
┌──────▼──────────────┐
│    API Gateway      │
└──┬──┬──┬──┬──┬──┬──┘
   │  │  │  │  │  │
   │  │  │  │  │  └─► Notifications
   │  │  │  │  └────► Reporting
   │  │  │  └───────► Payments
   │  │  └──────────► Inventory
   │  └─────────────► Orders
   └────────────────► User Auth

Migration Steps

1

Domain Analysis & Service Identification

  • Map business capabilities and bounded contexts
  • Identify loosely coupled domains (auth, payments, inventory)
  • Analyze data dependencies and shared database tables
  • Prioritize services: high value + low coupling first
2

Extract First Service (Example: Authentication)

// 1. Create REST API in monolith
component rest="true" restpath="/auth" {
  remote struct function login(required string email, required string password)
    httpmethod="POST" restpath="/login" {
    // Authentication logic
    var user = userService.authenticate(email, password);
    return {success: true, token: createJWT(user)};
  }
}

// 2. Deploy as separate CF instance on different port
// 3. Configure API Gateway routing
location /api/auth {
  proxy_pass http://auth-service:8501;
}

// 4. Update monolith to call auth service
var authResult = httpService.post("/api/auth/login", {
  email: form.email,
  password: form.password
});
3

Database Decomposition

-- Strategy 1: Database per Service (Preferred)
-- Extract auth tables to separate database
CREATE DATABASE auth_service;
-- Migrate users, roles, permissions tables

-- Strategy 2: Shared Database with Views (Interim)
-- Create views for service-specific data
CREATE VIEW auth_users AS
  SELECT id, email, password_hash FROM users;

-- Strategy 3: Event Sourcing for Data Sync
-- Publish events when data changes
component {
  function createUser(userData) {
    transaction {
      queryExecute("INSERT INTO users...");
      eventBus.publish("user.created", userData);
    }
  }
}
4

Implement Service Communication

// Synchronous REST calls
component {
  function getOrderDetails(orderId) {
    // Call inventory service
    var inventory = http.get("http://inventory-svc/api/stock/" & orderId);

    // Call payment service
    var payment = http.get("http://payment-svc/api/payment/" & orderId);

    return {order: orderData, inventory: inventory, payment: payment};
  }
}

// Asynchronous messaging (RabbitMQ)
component {
  function processOrder(orderData) {
    // Save order
    var orderId = saveOrder(orderData);

    // Publish event
    rabbitMQ.publish("orders.created", {
      orderId: orderId,
      items: orderData.items,
      customerId: orderData.customerId
    });
  }
}

Success Criteria

  • Each service independently deployable
  • Service failures don't cascade to others
  • Response times within SLA (<200ms P95)
  • Data consistency maintained across services
  • Monitoring and observability for each service

Pattern 3: On-Premises to Cloud/Container

Complexity: MediumDuration: 3-6 monthsRisk: Medium

Overview

Migrate on-premises ColdFusion deployment to cloud infrastructure (AWS/Azure/GCP) using containerization and Kubernetes orchestration.

Migration Steps

1

Containerize Application

# Dockerfile for ColdFusion 2025
FROM adobecoldfusion/coldfusion2025:2025.0.14

# Copy application code
COPY ./app /app

# Copy custom configuration
COPY ./config/server.xml /opt/coldfusion/cfusion/runtime/conf/server.xml

# JVM heap and GC settings go in jvm.config
COPY ./config/jvm.config /opt/coldfusion/cfusion/bin/jvm.config

# Required: the image will not start without accepting the EULA
ENV acceptEULA=YES
# Supply the admin password at runtime (for example a Kubernetes secret),
# not in the Dockerfile: docker run -e password=...

# Expose ports
EXPOSE 8500

# Health check
HEALTHCHECK --interval=30s --timeout=10s \
  CMD curl -f http://localhost:8500/healthcheck.cfm || exit 1

# No CMD override: keep the image's default startup. Its entrypoint
# (/opt/startup/start-coldfusion.sh start) starts ColdFusion, then
# tails coldfusion-out.log, which keeps the container running
# (verified in Adobe's coldfusion2025:2025.0.14 image)
2

Kubernetes Deployment

# deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: coldfusion-app
spec:
  replicas: 3
  selector:
    matchLabels:
      app: coldfusion
  template:
    metadata:
      labels:
        app: coldfusion
    spec:
      containers:
      - name: coldfusion
        image: myregistry/coldfusion-app:latest
        ports:
        - containerPort: 8500
        resources:
          requests:
            memory: "4Gi"
            cpu: "2"
          limits:
            memory: "8Gi"
            cpu: "4"
        env:
        - name: DB_HOST
          valueFrom:
            secretKeyRef:
              name: db-credentials
              key: host
3

Database Migration

  • Option 1: AWS RDS/Azure SQL - Managed database service
  • Option 2: Database containers in Kubernetes with persistent volumes
  • Option 3: Hybrid - Keep on-prem DB initially, VPN connection
# Database migration steps
1. Create RDS instance matching on-prem version
2. Setup read replica from on-prem to RDS
3. Monitor replication lag (should be <1 second)
4. Cutover: Promote RDS to primary
5. Update application datasources to RDS endpoint
4

Session Management for Cloud

// Use Redis for distributed sessions
// Configure in CF Administrator: Server Settings > Memory Variables
// Session Storage: Redis (host redis.default.svc.cluster.local,
// port 6379, password from your secret store)
// Redis sessions cannot be combined with J2EE session variables

// Application.cfc
this.sessionManagement = true;

// Or, without Redis, use sticky sessions in the load balancer
// (with Redis sessions, Adobe says to disable sticky sessions)
// NGINX Ingress annotation
metadata:
  annotations:
    nginx.ingress.kubernetes.io/affinity: "cookie"
    nginx.ingress.kubernetes.io/session-cookie-name: "cf-sticky"

Success Criteria

  • Auto-scaling based on CPU/memory (min 2, max 10 pods)
  • Zero-downtime deployments with rolling updates
  • Database connectivity and performance equivalent to on-prem
  • Session persistence across pod restarts
  • Cost optimization: 30-40% reduction vs on-prem

Pattern 4: Windows to Linux Migration

Complexity: Low-MediumDuration: 1-3 monthsRisk: Low

Overview

Migrate ColdFusion from Windows Server to Linux for cost savings, performance improvements, and container compatibility.

Key Considerations

File Paths

Windows: C:\ColdFusion2025\cfusion\wwwroot\

Linux: /opt/coldfusion2025/cfusion/wwwroot/

Fix: Use expandPath() for all file operations

Case Sensitivity

Windows: Case-insensitive file system

Linux: Case-sensitive (myFile.cfm ≠ MyFile.cfm)

Fix: Audit all file includes, verify case consistency

Line Endings

Windows: CRLF (\r\n)

Linux: LF (\n)

Fix: Convert with dos2unix utility

Migration Steps

1

Pre-Migration Audit

# Find hardcoded Windows paths
grep -r "C:\\" /var/www/myapp/
grep -r "D:\\" /var/www/myapp/

# Find case-sensitivity issues
find /var/www/myapp -name "*.cfm" | sort | uniq -di

# Check for Windows-specific functions
grep -r "createObject.*WScript" /var/www/myapp/
grep -r "COM|ActiveX" /var/www/myapp/
2

Code Modifications

// BAD: Hardcoded paths
filePath = "C:\uploads\files\";

// GOOD: Cross-platform
filePath = expandPath("/uploads/files/");

// BAD: Case-insensitive include
<cfinclude template="MyTemplate.cfm">

// GOOD: Match exact filename case
<cfinclude template="mytemplate.cfm">

// Replace Windows-specific COM (COM/DCOM is removed in CF 2025)
// OLD:
fileSystem = createObject("COM", "Scripting.FileSystemObject");

// NEW: Use CF native functions
directoryList(path, true, "query");
3

Linux Server Setup

# Install ColdFusion 2025 on Ubuntu 22.04
sudo ./ColdFusion_2025_WWEJ_linux64.bin

# Set proper permissions
# (default install directory: /opt/coldfusion2025)
sudo chown -R cfuser:cfuser /opt/coldfusion2025
sudo chmod -R 755 /opt/coldfusion2025/cfusion/wwwroot

# Configure the Apache connector with the Web Server
# Configuration Tool in cfusion/runtime/bin
cd /opt/coldfusion2025/cfusion/runtime/bin
sudo ./wsconfig.sh -ws apache -dir /etc/apache2 -v

# Start ColdFusion as the runtime user (never root)
/opt/coldfusion2025/cfusion/bin/coldfusion start

Benefits Achieved

  • Cost Savings: 40-60% lower licensing costs (no Windows Server CALs)
  • Performance: 15-25% faster due to Linux optimizations
  • Container Ready: Easier Docker/Kubernetes deployment
  • Security: Smaller attack surface, faster security patches

AI-Augmented Migration Workflows

AI tools can dramatically accelerate migration planning and execution by automating code analysis, compatibility scanning, and modernization recommendations. Use local AI models to protect proprietary code during migration.

How AI Enhances Each Pattern

1

Version Migration with AI

Code Inventory

Scan entire codebase in minutes vs days for deprecated tags and compatibility issues

Compatibility Analysis

Cross-reference against CF 2025 deprecation list, suggest modern alternatives

Test Generation

Auto-generate unit tests to validate migration success

Speedup: 10x faster planning
2

Microservices with AI

Domain Analysis

Identify bounded contexts and service candidates automatically

Dependency Mapping

Trace database queries and data flows to map dependencies

API Design

Generate REST API specifications for extracted services

Speedup: 5x faster decomposition
3/4

Cloud/Linux with AI

Path Analysis

Detect hardcoded Windows paths, suggest cross-platform alternatives

Case Sensitivity

Find case-sensitivity issues in includes and file operations

IaC Generation

Generate Kubernetes manifests and Terraform configs

Speedup: 8x faster platform audit

Local AI Setup

Critical Security: Never upload production code or database schemas to cloud AI services. Use local models only.

Code-Tuned Models

Choose a current open-weight model trained for code; rankings change every few months

Large Context Window

Lets the model read whole CFCs and related files together

Sized to Your Hardware

Match model size to available GPU memory so code never leaves your network

Ollama

Easy local deployment with GPU support

Recommended Toolchain

Continue.dev

VS Code extension for AI code analysis

AI + Code Analyzer

Export results, feed to AI for prioritization

AI + Git Diff

Review commits for compatibility issues

For a complete guide with example prompts and workflows, see AI Code Migration.

Get Professional Migration Help

While this guide provides the technical steps, many organizations choose professional migration services to:

  • Minimize risk and downtime
  • Leverage proven migration frameworks
  • Access Adobe partner resources
  • Ensure security and compliance
ColdFusion Migration Patterns - Step-by-Step Migration Guides | CFGuide