Migration - Upgrades

How to Move ColdFusion Apps to a New Domain or Host

by Aaron Longnion
12 min read
Contents show

Why migrating a ColdFusion app to a new domain or host matters

Moving a ColdFusion (CFML) application to a new domain or server is often driven by Security hardening, Performance improvements, cost Optimization, cloud adoption, or Compliance requirements. A well-executed Migration can yield faster response times, reduced downtime, and easier Scaling. It’s also an opportunity to modernize components (e.g., Java, Tomcat, connectors), review data source configurations, tighten Security (lockdown of CF Administrator and CFIDE), and remove Technical debt. Done poorly, however, it can break data sources, task schedulers, URL rewrites, or session state. This guide walks you through a structured, low-risk approach that works for Adobe ColdFusion and Lucee, across IIS, Apache, or Nginx.

Prerequisites / Before You Start

  • Application inventory and documentation:

    • Code repositories and branches (Git, SVN) and Deployment process.
    • ColdFusion engine and version (e.g., Adobe CF 2018/2021/2023; Lucee 5/6).
    • Java version and vendor (Adoptium/Oracle/Azul), and compatibility with your CF engine.
    • Web server and connector technology (IIS with wsconfig/BonCode; Apache with mod_proxy_ajp/mod_jk; Nginx Reverse proxy).
    • Datasources (DSNs), database servers, credentials, JDBC drivers, and connection settings.
    • Caches (EHCache, Redis), session storage, client storage (registry/database/cookie).
    • Scheduled tasks, mappings, mail servers, Solr, PDF services, extensions/packages.
    • External dependencies: REST/SOAP endpoints, S3, SMTP, Payment gateways, SSH/SFTP, Message queues.
    • URL rewriting rules (IIS web.config, Apache .htaccess/httpd.conf, Nginx), and SEO redirects.

  • Backups and export artifacts:

    • Full code backup or repo snapshot/tag.
    • Database backups (hot + logical dump).
    • ColdFusion Administrator Configuration export:
      • Adobe CF: use the admin, Admin API, or CFConfig to export settings (DSNs, mail, mappings, security, sandboxing).
      • Lucee: export Server and Web context settings (CFConfig makes this easy).
    • Filesystem assets (user uploads, images, temp, generated PDFs/reports).
    • SSL keys/certificates or ACME Automation plan (Let’s Encrypt).
    • Web server configs and rewrite rules.
    • Scheduled tasks list and cron equivalents.

  • Version and platform alignment:

    • Confirm CF engine and Java Compatibility matrix.
    • OS differences (Linux vs. Windows) that affect paths, case-sensitivity, line endings, permissions (SELinux/ACLs).
    • Library and native dependency parity (e.g., ImageMagick, Ghostscript, wkhtmltopdf).

  • Access and change control:

    • Admin credentials for source and target environments (CF Admin, web server, DB).
    • DNS access, domain registrar, and CDN settings.
    • Maintenance window and rollback plan with RTO/RPO targets.
    • Monitoring and log aggregation ready on target (e.g., New Relic, ELK/EFK, CloudWatch).

  • Testing environments:

    • A staging environment that mirrors production to validate before cutover.
    • Test data and anonymized datasets as needed for QA.

Step-by-Step Migration guide

1) Freeze changes and Audit the app

  • Implement a short-lived code freeze to prevent drift during migration.
  • Generate a dependency list: CF packages/extensions, tag/function usage that might be deprecated, JDBC driver versions.
  • Identify hard-coded paths, domains, and endpoints in code and config. Plan to replace with environment variables or per-environment Application.cfc settings.
See also  How to Migrate ColdFusion Code to CFScript Syntax

Practical tip: search the codebase for strings like http://, https://, \, C:\, /var/, CFIDE, and DSN names.

2) Prepare the target host

  • Install OS updates and set time synchronization (NTP/chrony/Windows Time). Uniform timezones prevent timestamp drift in logs and scheduled tasks.
  • Install Java and confirm version alignment with your CF engine.
  • Install the CF engine:
    • Adobe CF: use the installer, choose “production profile,” and ensure the Administrator is secured.
    • Lucee: use Lucee installer or Tomcat + Lucee WAR. Consider CommandBox for lightweight servers and easy promotion.
  • Install add-on services if used:
    • Solr, PDFg, .NET Integration (Adobe), ImageMagick/Ghostscript, LibreOffice.
  • Harden the environment:
    • Apply the Adobe ColdFusion Lockdown guide or Lucee security Best practices.
    • Ensure CF Administrator is not exposed publicly. Restrict by IP or bind to localhost, and disable CFIDE on public virtual hosts.

3) Export and import ColdFusion Configuration

Option A: Use CFConfig (recommended for both Adobe CF and Lucee)

  • Export from the current server:

    box install CommandBox-cfconfig
    box cfconfig export from=/path/to/current/cf/home to=/backups/cfconfig.json

  • Import into the target server:

    box cfconfig import to=/path/to/new/cf/home from=/backups/cfconfig.json

  • Benefits: migrates DSNs, mail, mappings, scheduler tasks, caching, request limits, and more without manual clicks.

Option B: Manual or Admin API

  • For Adobe CF:
    • Recreate or export/import DSNs. Validate connection strings, pooling, timeouts, and advanced JDBC parameters.
    • Migrate scheduled tasks (name, URL, method, credentials, interval, start/stop).
    • Reconfigure mail server(s), loggers, request tuning (Max Threads/Requests), and Sandbox security if used.
  • For Lucee:
    • Migrate Server and Web context configs. Validate extensions (e.g., S3, Redis) are installed on the new host.

Don’t forget:

  • Mappings (this.mappings and Administrator-level).
  • Client/storage settings, including registry or database tables if used.
  • PDFg and Solr endpoints if they run separately.

4) Configure the web server and connector

IIS (Windows):

  • Adobe CF: use wsconfig.exe to create the connector:

    “C:\ColdFusion2023\cfusion\runtime\bin\wsconfig.exe” -add -site 1 -v -f

  • Lucee: install BonCode connector for IIS or use CommandBox + BonCode.

  • Lock down:

    • Remove/deny CFIDE and Administrator on public sites.
    • Configure Application Pool (.NET CLR v4, 64-bit, recycling policy tuned to your app).

Apache HTTPD (Linux):

  • Typical Reverse proxy to Tomcat/CF:

    <VirtualHost *:80>
    ServerName example.com
    Redirect permanent / https://example.com/

    <VirtualHost *:443>
    ServerName example.com
    SSLEngine On
    SSLCertificateFile /etc/letsencrypt/live/example.com/fullchain.pem
    SSLCertificateKeyFile /etc/letsencrypt/live/example.com/privkey.pem

    ProxyPreserveHost On
    ProxyPassMatch ^/(CFIDE|lucee|jakarta)/ – [F]
    ProxyPass / ajp://127.0.0.1:8009/
    ProxyPassReverse / ajp://127.0.0.1:8009/

  • Ensure Tomcat AJP is secure (loopback only; secret required).

Nginx:

  • Reverse proxy to CF running on localhost (HTTP or AJP via uwsgi module is not typical—prefer HTTP or stream config for AJP).
  • Add HSTS, gzip/brotli, and cache headers as needed.

Tomcat (if you manage it directly):

<Connector protocol=”AJP/1.3″
address=”127.0.0.1″
port=”8009″
secretRequired=”true”
secret=”StrongAJPSecret”
maxThreads=”200″
allowedRequestAttributesPattern=”.*” />

5) Move databases and storage

Database migrations:

  • MySQL/MariaDB:

    mysqldump -u user -p –routines –triggers –single-transaction dbname > dbname.sql
    mysql -u user -p -h newdbhost dbname < dbname.sql

  • PostgreSQL:

    pg_dump -Fc -h olddbhost -U user dbname > db.dump
    pg_restore -h newdbhost -U user -d dbname -c db.dump

  • SQL Server:

    • Use native BACKUP/RESTORE or export via SSMS. Re-map users/logins (sp_change_users_login or ALTER USER).

Validate on target:

  • Collation and encoding (UTF-8), timezones, isolation levels.
  • Database users and permissions; firewall rules.
  • Datasource connectivity from the new CF server, including Advanced JDBC params (e.g., useUnicode=true&characterEncoding=UTF-8).

File assets:

  • Linux:

    rsync -avz –delete –exclude=’logs/’ –exclude=’temp/’ /var/www/app/ user@newhost:/var/www/app/

  • Windows:

    robocopy C:\inetpub\wwwroot \newhost\c$\inetpub\wwwroot /MIR /XD logs temp

If using cloud storage (S3/Azure Blob), verify IAM roles/keys and endpoint regions.

6) Deploy code and configure per-environment settings

  • Preferred approach: deploy via CI/CD (Git tag, artifact, checksum) to ensure traceability.

  • Ensure writeable directories (uploads, temp, cache) have correct permissions for the CF service account.

  • Application.cfc updates:

    • Environment-driven configuration:

      component {
      this.name = “MyApp”;
      this.sessionManagement = true;
      this.sessionCookie = { httpOnly=true, secure=true, sameSite=”Lax” };
      this.mappings = {
      “/lib” = expandPath(“./lib”)
      };
      // Example: per-environment settings
      variables.env = structKeyExists(server.environment, “APP_ENV”) ? server.environment.APP_ENV : “prod”;
      if (variables.env == “staging”) {
      application.datasource = “MyApp_Stage”;
      application.baseUrl = “https://staging.example.com“;
      } else {
      application.datasource = “MyApp_Prod”;
      application.baseUrl = “https://www.example.com“;
      }
      }

    • If changing domain, review cookie domain attributes. Sessions will not carry over to a different domain unless you plan a dual-domain period with careful cookie handling.

  • Secrets management:

    • Use environment variables or an external secrets store (Vault, AWS Secrets Manager).
    • Avoid hard-coded credentials.
See also  How to Migrate from ColdFusion 2016 to ColdFusion 2023

7) SSL/TLS, redirects, and canonical URLs

  • Install certificates or automate Let’s Encrypt with certbot/Win-ACME.
  • Enforce HTTPS and canonical hostnames (www vs. apex).
  • Configure HSTS cautiously (start with a short max-age).
  • Review CSP, CORS, and SameSite cookie policies.

Example IIS redirect (web.config):







8) Validate in staging

  • Test DSNs, ORM (if used), scheduled tasks, file uploads, PDFs, image transforms, email sending (use a sandbox SMTP).
  • Verify URL rewrites and REST endpoints. Ensure CF Administrator and CFIDE are blocked externally.
  • Check logs: ColdFusion application.log, exception.log, server.log, and web server error/access logs.
  • Performance smoke tests. Warm caches and precompile templates if your engine supports it.

9) Plan and execute DNS cutover

  • Lower TTL to 300 seconds at least 24 hours before migration.
  • Choose a cutover pattern:
    • Blue/Green: run new host in parallel behind a switch or load balancer.
    • Big-bang: Maintenance page, content freeze, final data sync, switch DNS.
  • Session strategy:
    • Accept session reset at cutover, or
    • Introduce sticky sessions or session store (Redis/DB) shared during transition.
  • Final pre-cutover steps:
    • Freeze content uploads and transactional writes.
    • Perform final DB delta sync or switchover to new DB primary.
    • Validate SSL on the new host.

10) Post-cutover monitoring and rollback

  • Monitor error rates, response times, CPU/memory, and queue lengths.
  • Watch for 404/500 spikes and rewrite anomalies.
  • Have a time-boxed rollback plan (restore DNS, fail back to old host) if critical issues appear.
  • Communicate status to stakeholders.

Risks, Common Issues, and How to Avoid Them

  • Broken DSNs or JDBC mismatches:
    • Mitigation: test with the exact driver and connection strings in staging; include params like autoReconnect, characterEncoding, serverTimezone.
  • CFIDE or Administrator exposed publicly:
    • Mitigation: block via web server rules; bind admin to localhost; use IP restrictions and strong auth.
  • Path and case-sensitivity differences (Windows to Linux):
    • Mitigation: clean up file includes and image references; enable case-sensitive tests; refactor hard-coded paths.
  • Missing scheduled tasks:
    • Mitigation: export/import via CFConfig; validate next run times and credentials.
  • Email failures after cutover:
    • Mitigation: verify SMTP server, ports, TLS, and Authentication; test with a safe recipient list.
  • Session loss on domain change:
    • Mitigation: plan a session reset or a temporary dual-cookie strategy; communicate to users.
  • Connector misconfiguration (AJP/BonCode/wsconfig):
    • Mitigation: follow engine-specific guidance; keep AJP on loopback and require a secret; verify IIS site-id mapping.
  • SEO regressions:
    • Mitigation: replicate redirects; update canonical tags and sitemaps; check Google Search Console for errors.
  • Licensing and Features (Adobe CF):
    • Mitigation: ensure license keys and edition are applied; confirm feature parity (e.g., PDFg).

Post-Migration Checklist / Validation Steps

  • Application functionality:

    • Critical paths (login, checkout, forms, file uploads, reports).
    • Background jobs and CF scheduled tasks running on schedule.
    • API integrations and webhooks reachable from the new host.

  • Configuration and security:

    • DSNs test green in Administrator; correct credentials and pooling.
    • CFIDE/Administrator not exposed to the internet.
    • HTTPS enforced; HSTS, TLS versions, and strong ciphers configured.
    • CORS/CSP/SameSite policies validated.

  • Performance and reliability:

    • Log files free from recurring errors or deprecations.
    • Response times meet SLOs; caches warmed.
    • Resource usage stable (heap, CPU, disk I/O).
    • Connector and thread pool sizes tuned for expected load.

  • Data and storage:

    • Database collation/encoding verified; no time drift.
    • Uploaded files and generated content land in correct locations with proper permissions.
    • Backups and snapshots configured and tested.

  • Observability:

    • Monitoring dashboards and alerts active.
    • Log shipping to centralized system.
    • Uptime checks from multiple regions.

  • SEO and user experience:

    • 301 redirects working; no orphaned pages.
    • Canonical hostnames consistent.
    • Sitemaps updated; robots.txt correct.
See also  How to Migrate ColdFusion Applications Without Downtime

What to move: Quick reference table

Area Examples How to move
CF Admin settings DSNs, mail, mappings, scheduler CFConfig export/import; or Admin UI/API
Code and assets CFML, components, static files, uploads Git/CI/CD; rsync/robocopy; verify permissions
Web server vhosts, web.config/.htaccess, SSL Copy configs; reissue certs; test rewrites
Connectors IIS wsconfig/BonCode; Apache mod_proxy_ajp Recreate with supported tools and secure AJP/connector
External services SMTP, S3, Solr, PDFg, Redis Reconfigure endpoints, keys, firewall rules

Useful configuration snippets

CFConfig (Adobe CF or Lucee):

box cfconfig export from=/opt/coldfusion/cfusion to=/tmp/cfconfig.json
box cfconfig import to=/opt/coldfusion/cfusion from=/tmp/cfconfig.json

IIS App Pool via PowerShell (example):

Import-Module WebAdministration
New-WebAppPool -Name “MyAppPool”
Set-ItemProperty IIS:\AppPools\MyAppPool -Name managedRuntimeVersion -Value “v4.0”
Set-ItemProperty IIS:\AppPools\MyAppPool -Name enable32BitAppOnWin64 -Value False

Apache hardening for CFIDE:

<LocationMatch “^/(CFIDE|lucee|cfadmin)”>
Require all denied

Adobe wsconfig (list connectors):

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

Practical example: domain switch with minimal downtime

  • One week before: set up staging on new host; run full test plan; lower DNS TTL.
  • Day of cutover:
    • Enable maintenance banner on old site; freeze writes.
    • Final DB sync or promote new DB primary.
    • Deploy latest code to new host; warm caches.
    • Switch DNS to new IPs; purge CDN cache.
  • First 2 hours:
    • Monitor logs, error alerts, and business KPIs.
    • Validate scheduled tasks and email outputs.
    • Tweak connector or thread settings if saturation appears.
  • If critical failure: roll back DNS; unfreeze old site; diagnose offline.

Optimization tips after migrating

  • Use environment-specific Application.cfc and a central config to eliminate hard-coded values.
  • Introduce a build pipeline (CommandBox + cfpm/cfconfig + test runner) for consistent promotion.
  • Consider moving session storage to Redis or database for multi-node Scaling.
  • Enable GZIP/Brotli, HTTP/2 or HTTP/3, and review image optimization pipelines.
  • Regularly apply CF engine updates and Java security patches.

FAQ

How do I handle sessions when changing the domain?

Session cookies are bound to a domain. If you change the domain, sessions won’t carry over. Plan for a session reset at cutover or implement a temporary dual-domain window with duplicated Set-Cookie headers. If using a centralized session store (e.g., Redis), you still need matching cookie domains for browsers to send the cookie.

Can I move from Adobe ColdFusion to Lucee at the same time?

Yes, but treat it as a replatform rather than a lift-and-shift. Validate tag/function compatibility, admin settings, extensions, and PDF/Solr Features. Use a staging environment to run your full test suite. CFConfig helps with migrating many settings between engines, but some features are not 1:1.

Do I need downtime for the migration?

You can minimize downtime with blue/green deployments and a DNS or load balancer switch. However, if you can’t run dual-write or shared storage, you may need a short content freeze and a final DB sync window during cutover.

What’s the safest way to migrate DSNs and scheduled tasks?

Use CFConfig to export/import. After importing, verify each DSN with the “Verify” button in the Administrator and review scheduled task credentials, HTTP methods, and next run times. Test task endpoints manually to confirm expected responses.

How should I secure AJP or connectors?

Bind AJP to 127.0.0.1, set secretRequired=”true” with a strong secret, and block connector paths (CFIDE/administrator) at the web server. On IIS, map the connector only to intended sites and confirm the site-id. Always keep the connector modules up to date.

About the author

Aaron Longnion

Aaron Longnion

Hey there! I'm Aaron Longnion — an Internet technologist, web software engineer, and ColdFusion expert with more than 24 years of experience. Over the years, I've had the privilege of working with some of the most exciting and fast-growing companies out there, including lynda.com, HomeAway, landsofamerica.com (CoStar Group), and Adobe.com.

I'm a full-stack developer at heart, but what really drives me is designing and building internet architectures that are highly scalable, cost-effective, and fault-tolerant — solutions built to handle rapid growth and stay ahead of the curve.

View all posts

You may also like