How To Move ColdFusion From Windows To Linux Servers

Contents show

Why migrate ColdFusion from Windows to Linux servers

Moving Adobe ColdFusion (or Lucee) workloads from Windows to Linux can reduce Licensing costs, improve resource utilization, simplify Automation, and align with Containerization and DevOps practices. Linux distributions such as RHEL/Rocky/Alma, CentOS Stream, Ubuntu, or Debian provide stable, well-supported platforms for Java application servers like ColdFusion’s Tomcat runtime. A well-planned Migration preserves application behavior while unlocking opportunities for standardization (systemd, logrotate, package managers), improved Security (SELinux, AppArmor), and scalable web stacks (Apache httpd or Nginx).

Prerequisites / Before You Start

Inventory, scope, and stakeholders

List all ColdFusion instances (dev/test/stage/prod) and versions.
Identify all applications, webroots, CF mappings, Custom tags, CFCs, Scheduled tasks, Web services, and external integrations (SMTP, SFTP, Payment gateways, REST/SOAP).
Document current web server (IIS), bindings (hostnames, ports, SNI/TLS), URL rewrite rules, and application pools.
Record database backends (SQL Server, Oracle, MySQL, PostgreSQL), JDBC drivers, connection strings, and credentials.
Enumerate OS-level dependencies: fonts, Ghostscript, ImageMagick, wkhtmltopdf/cfhtmltopdf prerequisites, LibreOffice (if used), Solr/Tika collections, PDFg service.
Confirm any Windows-specific paths, scripts, or COM components.

Versions and compatibility

ColdFusion version target (e.g., CF2018/2021/2023) and matching Java/JDK version. Confirm support matrix from your vendor:
- CF2018 typically supports Java 11 with certain updates.
- CF2021 supports Java 11; CF2023 supports Java 17.
Linux distro version and kernel. Ensure corporate Standards and supportability.
Web Server choice: Apache httpd 2.4 (recommended) or Nginx (front-end Reverse proxy). Adobe’s connector supports Apache httpd directly; Nginx typically proxies to Tomcat HTTP/AJP.
JDBC driver versions compatible with your databases (e.g., Microsoft JDBC driver for SQL Server, Oracle JDBC, MySQL Connector/J, PostgreSQL JDBC).

Backups and rollback plan

Full VM snapshots or bare-metal backups of Windows servers.
Export ColdFusion Administrator settings:
- Use a CAR (ColdFusion Archive) package where possible.
- Export Scheduled tasks; note that passwords may not export.
Backup application code, CFIDE/Custom tags, shared libraries, and JVM arguments.
Database backups and verified restore procedures.
SSL/TLS keys and certificates, Java keystore files, truststores.
Rollback plan: DNS TTL lowered ahead of cutover, change windows for backout.

Access, Security, and Infrastructure

Provision Linux hosts with appropriate CPU/RAM/disk/IO. Consider dedicated volumes for logs.
Administrative access: SSH with sudo, Configuration management (Ansible, Puppet, Chef).
Network access rules: database ports, SMTP, SFTP, Solr, internal APIs, and firewall rules (iptables/firewalld/ufw).
SELinux/AppArmor posture and exceptions you might need.
Monitoring and logging strategy (systemd-journald, logrotate, external collectors).

Step-by-step Migration guide

1) Assess and export from Windows

In ColdFusion Administrator:
- Package and Deployment: create a CAR containing datasources, mappings, Mail, Caching, and other settings. Note: some secrets are not included; record them securely.
- Export scheduled tasks if supported by your version; otherwise, screenshot or script them via Admin API.
Export JVM settings: heap sizes, GC flags, custom -D system properties. Located in jvm.config or set via Admin.
Collect:
- web.xml and server.xml from the Tomcat runtime
- URL rewrite rules from IIS (web.config)
- Any custom certificates in cacerts/truststores
- Application logs to establish baseline errors
Confirm code portability: search for Windows-style paths (C:\…), backslashes, UNC shares (\server\share), and case-insensitive file references.

2) Prepare the Linux host

Set timezone and locale:

sudo timedatectl set-timezone America/New_York
sudo localectl set-locale LANG=en_US.UTF-8
Install base packages:
- RHEL/Rocky/Alma:
  
  sudo dnf install -y httpd unzip tar fontconfig freetype libX11 libXext libXi libXrender libXtst \
  ghostscript cups-libs openssl curl policycoreutils-python-utils
- Ubuntu/Debian:
  
  sudo apt update
  sudo apt install -y apache2 unzip tar fontconfig ghostscript libxrender1 libxtst6 libxi6 ca-certificates
Create application user and directories:

sudo useradd -r -m -d /opt/coldfusion -s /sbin/nologin cf
sudo mkdir -p /var/www/myapp /opt/coldfusion/backups

3) Install Java (if not using the bundled JRE)

Use a supported JDK matching your ColdFusion release (e.g., Temurin/OpenJDK 11 or 17):

sudo dnf install -y java-11-openjdk-headless

or

sudo apt install -y openjdk-11-jre-headless
Verify:

java -version

4) Install ColdFusion on Linux

Run the installer as root or with sudo; choose “Server Configuration.”

chmod +x ColdFusion_2021_WWEJ_linux_x64.bin
sudo ./ColdFusion_2021_WWEJ_linux_x64.bin
Optional silent install (create installer.properties):

INSTALLER_UI=silent
USER_INSTALL_DIR=/opt/ColdFusion
CHOSEN_FEATURE_LIST=core
ADMIN_USERNAME=cfadmin
ADMIN_PASSWORD=StrongPasswordHere

sudo ./ColdFusion_2021_WWEJ_linux_x64.bin -f installer.properties

5) Apply updates and modules

Use the Administrator “Server Updates” or command-line package manager where available (CF2021+):

sudo /opt/ColdFusion/cfusion/bin/cfpm.sh list
sudo /opt/ColdFusion/cfusion/bin/cfpm.sh update

Example: install PDFg or other modules

sudo /opt/ColdFusion/cfusion/bin/cfpm.sh install pdfg

6) Configure ColdFusion as a service

The installer typically creates a systemd service. Validate and enable:

sudo systemctl daemon-reload
sudo systemctl enable coldfusion
sudo systemctl start coldfusion
sudo systemctl status coldfusion
Adjust JVM heap and GC in jvm.config (e.g., /opt/ColdFusion/cfusion/bin/jvm.config). Example:

-Xms2g
-Xmx2g
-XX:+UseG1GC
-Dfile.encoding=UTF-8
-Djava.awt.headless=true

7) Integrate with Apache httpd

Install the ColdFusion web server connector:

cd /opt/ColdFusion/cfusion/runtime/bin
sudo ./wsconfig.sh

Follow prompts to select Apache, specify httpd config paths, and set instance.
Validate that mod_jk or Adobe’s connector module is present and that httpd includes it (on RHEL, /etc/httpd/conf.modules.d; on Debian, /etc/apache2/mods-available).

Example Apache virtual host:

<VirtualHost *:80>
ServerName app.example.com
DocumentRoot /var/www/myapp

# Static assets
<Directory /var/www/myapp>
    Options -Indexes +FollowSymLinks
    AllowOverride All
    Require all granted
</Directory>

# ColdFusion connector (mod_jk)
JkMount /*.cfm worker1
JkMount /*.cfc worker1
JkMount /cfide/* worker1

ErrorLog  /var/log/httpd/myapp_error.log
CustomLog /var/log/httpd/myapp_access.log combined

On Debian/Ubuntu:

sudo a2enmod proxy proxy_ajp rewrite headers
sudo a2ensite 000-default
sudo systemctl restart apache2
Security note: If using AJP, ensure a shared secret and bind to localhost only. In Tomcat’s server.xml (ColdFusion runtime):

<Connector protocol=”AJP/1.3″ port=”8009″ address=”127.0.0.1″
secretRequired=”true” secret=”ChangeThisSecret!” />

8) Migrate application code and assets

Copy code from Windows to Linux (use rsync or scp). Normalize line endings if needed:

rsync -avz –progress user@oldwin:/inetpub/wwwroot/myapp/ /var/www/myapp/
Set ownership and permissions:

sudo chown -R apache:apache /var/www/myapp # RHEL

or

sudo chown -R www-data:www-data /var/www/myapp # Debian/Ubuntu
Install fonts and third-party binaries needed by cfdocument/cfimage/cfpdf:

sudo dnf install -y dejavu-fonts liberation-fonts

or

sudo apt install -y fonts-dejavu fonts-liberation

9) Import ColdFusion Administrator settings

Use your CAR file to import datasources, mappings, Mail server, caching, and other settings via CF Admin.
Re-enter passwords for datasources and scheduled tasks if not carried over.
Verify Java keystores for outbound SSL (SOAP/REST/LDAP/SMTP over TLS). Import internal CA if needed:

sudo keytool -importcert -keystore /opt/ColdFusion/jre/lib/security/cacerts \
-storepass changeit -alias internal-ca -file internalCA.crt

10) Configure datasources and drivers

Place JDBC drivers in /opt/ColdFusion/cfusion/lib (or as recommended).
Test datasource connections in CF Admin.
Update connection strings for Linux hostnames or IPs.
Ensure firewall rules allow DB access from the new Linux servers.

11) Recreate scheduled tasks, indices, and services

Scheduled tasks: import or recreate with correct URLs and credentials. Confirm “publish” directories and path separators.
Solr/Tika (if used): install/start services or use the bundled Solr. Rebuild collections or copy index data if compatible.
PDFg or cfhtmltopdf: verify headless dependencies. Some HTML-to-PDF engines rely on X libraries; consider xvfb-run for headless rendering.

sudo dnf install -y xorg-x11-server-Xvfb
xvfb-run -a cfhtmltopdf …

12) URL rewrites and canonicalization

Convert IIS URL Rewrite rules (web.config) to Apache mod_rewrite:

RewriteEngine On
RewriteCond %{HTTPS} !=on
RewriteRule ^ https://%{HTTP_HOST}%{REQUEST_URI} [R=301,L]
Test SEO-sensitive routes, extensionless URLs, and 301/302 behaviors.

13) Harden and tune the platform

SELinux (RHEL-like):

sudo semanage fcontext -a -t httpd_sys_content_t “/var/www(/.*)?”
sudo restorecon -R /var/www
sudo setsebool -P httpd_can_network_connect 1
UFW/firewalld:

sudo firewall-cmd –add-service=http –add-service=https –permanent
sudo firewall-cmd –reload
Apache worker tuning (example for modest traffic):

StartServers 2
ServerLimit 16
ThreadLimit 64
ThreadsPerChild 64
MaxRequestWorkers 1024
MaxConnectionsPerChild 0
JVM memory and GC tuning per workload; monitor GC logs.

14) Logging and rotation

Confirm ColdFusion logs in /opt/ColdFusion/cfusion/logs.
Configure logrotate:

/opt/ColdFusion/cfusion/logs/*.log {
daily
rotate 14
compress
missingok
copytruncate
}

15) Functional, Performance, and security testing

Smoke tests: critical pages, login flows, reports, scheduled tasks.
Compare logs and error rates to Windows baseline.
Load test with a representative scenario; watch CPU, memory, GC pauses, Apache workers, and DB throughput.
Security test: TLS ciphers, headers, file permissions, and connector AJP secret.

16) Cutover and DNS

Lower DNS TTL 24–48 hours ahead of migration.
Plan a Maintenance window if necessary.
Switch traffic via DNS or load balancer. Keep Windows instance on standby until validation passes.

Risks, common issues, and how to avoid them

Case sensitivity on Linux
- Issue: File names that worked on Windows fail on Linux (e.g., include “Header.cfm” vs “header.cfm”).
- Mitigation: Normalize case, enforce via CI checks, and scan code for case mismatches.
Path separators and absolute paths
- Issue: Windows paths (C:\ or backslashes) break on Linux.
- Mitigation: Use expandPath(), getDirectoryFromPath(), server.os.name checks, or environment variables; refactor hardcoded paths.
Line endings (CRLF vs LF)
- Issue: Shell scripts and some parsers fail with CRLF.
- Mitigation: Convert using dos2unix during Deployment.
Permissions and ownership
- Issue: ColdFusion or Apache cannot read/write directories.
- Mitigation: Correct ownership (apache/www-data), set appropriate umask, Audit write directories (uploads, cache, temp).
SELinux/AppArmor denials
- Issue: Access blocked despite correct Unix permissions.
- Mitigation: Review Audit logs (ausearch/avc), apply semanage fcontext and setsebool, or adjust policy.
AJP connector security
- Issue: Unsecured AJP exposed to the network (Ghostcat risk).
- Mitigation: Bind AJP to 127.0.0.1, enforce secret, or use HTTP proxy if preferred.
Missing libraries for PDF/image Features
- Issue: cfdocument/cfpdf/cfimage failures due to fonts or X libs.
- Mitigation: Install font packages, Ghostscript, and Xvfb; test report generation.
JDBC driver differences
- Issue: Different driver defaults cause behavior changes.
- Mitigation: Pin driver versions, set explicit connection properties (e.g., sendStringParametersAsUnicode, encryption, timeouts).
Timezone and locale differences
- Issue: Date/time or sorting behavior changes.
- Mitigation: Align OS and JVM timezones/locales; set application-level formatting explicitly.
Scheduled task behavior
- Issue: Missed or duplicated runs around cutover.
- Mitigation: Disable on Windows before enabling on Linux; coordinate with cron-based alternatives if used.

Post-migration Checklist

Application validation
- Critical paths, Authentication/authorization, file uploads/downloads.
- Reporting and PDF/image generation.
- Email sending, integrations (REST/SOAP), and Payment gateways.
ColdFusion Administrator
- All datasources “OK” with successful test connections.
- Mappings, custom tag paths, JVM arguments, Caching (EHCache/Redis) configured.
- Scheduled tasks enabled and executing as expected.
Web and security
- Apache virtual hosts active, HTTPS working with correct certificates and intermediates.
- AJP or proxy configuration secured (local bind and secrets).
- URL rewrites behaving as intended; no redirect loops.
OS and platform
- SELinux context applied; no AVC denials during normal traffic.
- logrotate rotating CF and Apache logs; disk space monitored.
- systemd services enabled on boot; reboot test completed.
- Firewalls opened for required services only.
Monitoring and observability
- System metrics (CPU, memory, disk, network), Apache status, JVM heap/GC monitoring.
- Log shipping configured to SIEM/observability platform.
- Alerting thresholds adjusted based on new baselines.
Backups and DR
- Application and configuration backups scheduled.
- Database backup routines validated.
- Keystores and secrets vaulted securely.

Windows-to-Linux mapping Quick reference

Area	Windows (typical)	Linux (typical)
Web server	IIS	Apache httpd (or Nginx as Reverse proxy)
Webroot	C:\inetpub\wwwroot\myapp	/var/www/myapp
Service manager	Services.msc	systemd (systemctl)
Firewall	Windows Firewall	firewalld/iptables/ufw
Paths	C:\path\to\file	/path/to/file
Case sensitivity	Case-insensitive	Case-sensitive
Log rotation	Manual or Task Scheduler	logrotate
Environment variables	System/User variables	/etc/environment, systemd Environment=

Useful configuration examples

systemd service override for ColdFusion JVM options

Create override for coldfusion service:

sudo systemctl edit coldfusion

Add:

[Service]
Environment=”JAVA_TOOL_OPTIONS=-Xms2g -Xmx2g -XX:+UseG1GC -Dfile.encoding=UTF-8 -Djava.awt.headless=true”

Then:

sudo systemctl daemon-reload
sudo systemctl restart coldfusion

Nginx as a reverse proxy in front of Apache or ColdFusion HTTP connector

server {
listen 443 ssl http2;
server_name app.example.com;
ssl_certificate /etc/ssl/certs/app.crt;
ssl_certificate_key /etc/ssl/private/app.key;

location / {
    proxy_pass http://127.0.0.1:8080;  # if using HTTP connector
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-Proto https;
    proxy_set_header X-Forwarded-For $remote_addr;
    proxy_read_timeout 120s;
}

}

Simple Health check endpoint (Application.cfc)

component {
this.name = “HealthCheckApp”;
remote string function healthcheck() httpmethod=”GET” returnformat=”plain” {
return “OK”;
}
}

Then test:

curl -I https://app.example.com/healthcheck.cfc?method=healthcheck

FAQ

How long does a typical ColdFusion Windows-to-Linux migration take?

Scope drives timeline. A small single-application instance can be moved in a few days including testing. Complex estates with many datasources, scheduled tasks, and third-party dependencies often require several weeks to plan, stage, test, and execute the cutover with rollback options.

Can I migrate directly to Lucee during the move to Linux?

Yes, but treat it as a platform change with full regression testing. Lucee is largely compatible but not identical to Adobe ColdFusion. Prioritize a like-for-like move first, then plan a separate Modernization to Lucee if desired.

Do I need Apache httpd, or can ColdFusion serve traffic directly?

ColdFusion’s embedded Tomcat can serve HTTP directly on higher ports, but production best practice is to front it with a hardened web server (Apache or Nginx). This enables TLS termination, static asset handling, compression, caching, and flexible routing.

What is the best way to handle IIS URL Rewrite rules on Linux?

Translate them to Apache mod_rewrite or implement equivalent Nginx directives. For complex rules, migrate and test incrementally. Tools and community examples can help, but manual review is often necessary.

How do I minimize downtime during cutover?

Lower DNS TTL beforehand, perform a full dry run in staging, use blue/green or parallel run strategies, and switch traffic via load balancer or DNS. Disable scheduled tasks on the old server just before enabling them on Linux to avoid duplicate executions.