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 →Migration Patterns
Legacy Version Migration
CF 11 → CF 2025
Monolith to Microservices
Strangler fig pattern
On-Prem to Cloud
Kubernetes & containers
Windows to Linux
Platform migration
Pattern 1: Legacy Version Migration (CF 11 → CF 2025)
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
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
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">
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>
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
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
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 AuthMigration Steps
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
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
});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);
}
}
}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
Overview
Migrate on-premises ColdFusion deployment to cloud infrastructure (AWS/Azure/GCP) using containerization and Kubernetes orchestration.
Migration Steps
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)
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: hostDatabase 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
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
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
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/
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");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
Version Migration with AI
Scan entire codebase in minutes vs days for deprecated tags and compatibility issues
Cross-reference against CF 2025 deprecation list, suggest modern alternatives
Auto-generate unit tests to validate migration success
Microservices with AI
Identify bounded contexts and service candidates automatically
Trace database queries and data flows to map dependencies
Generate REST API specifications for extracted services
Cloud/Linux with AI
Detect hardcoded Windows paths, suggest cross-platform alternatives
Find case-sensitivity issues in includes and file operations
Generate Kubernetes manifests and Terraform configs
Local AI Setup
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
VS Code extension for AI code analysis
Export results, feed to AI for prioritization
Review commits for compatibility issues
For a complete guide with example prompts and workflows, see AI Code Migration.
Related Resources
- AI Code Migration - Complete AI-assisted migration workflow
- ColdFusion Version Comparison - Compare CF 11 vs CF 2025 features and performance
- When to Use ColdFusion - Should you migrate or re-platform?
- Platform Comparison - Evaluate migration to alternative platforms
- Case Studies - Real-world migration success stories (Gov CF 11→2025)
- Containerization Guide - Migrate to Docker and Kubernetes
- Hosting Providers - Choose hosting for migrated CF environment
- Problems & Solutions - Troubleshoot common migration issues
- Performance Framework - Optimize after 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