Packaging & Deployment - ColdFusion Archives

Create, deploy, and manage CAR files for application deployment and migration

Overview

ColdFusion Archives (CAR files) provide a comprehensive packaging solution for deploying applications, migrating configurations between servers, and maintaining consistent environments. Archives bundle application code, settings, datasources, mappings, and other configurations into a single deployable unit that can be extracted on any ColdFusion server.

CAR files are essential for managing multi-server deployments, staging environments, disaster recovery, and maintaining configuration consistency across development, testing, and production environments.

Deprecated in ColdFusion 2025: Adobe deprecated CAR (ColdFusion Archive) migration in the 2025 release and names cfsetup as the alternative (see the deprecated features list). CAR still works in ColdFusion 2025, but plan new automation around cfsetup, which exports and imports Administrator settings as JSON.
Path allow-lists (ColdFusion 2025 Update 5 and later): CAR creation and deployment honor allow-lists in <cf_home>/cfusion/lib/pathfilter.json. By default, no CAR file can be deployed from any path; list allowed source paths under car.deploypath, or deployment fails and the error is logged in car_deploy.log. Associated files and directories not listed under car.associatedfiles are skipped when building the archive and logged in car_archive.log. (Source: ColdFusion (2025 release) Update 5)

What Gets Archived

ColdFusion Archives can include various server settings and application components.

Server Settings

Settings, Caching, Basic Security, Variables, Java and JVM, Logging, Mail, Debugging, Charting, Custom Tag Paths, Watcher Settings, Server Monitor Settings, System Probes, Update Settings, Web Sockets, Web Service, PDF Service, Remote Inspection Settings, and Solr Server Settings.

Mappings and Data

ColdFusion Mappings, Data Sources, and NoSQL Data Sources.

Extensions and Services

Java Applets, CFX Tags, REST Services, and Cloud Settings.

Associated Files and Directories

Application files and directories you associate with the archive definition.

Source: Adobe: ColdFusion Archives page

Building an Archive

Archive definitions are listed on Packaging and Deployment > ColdFusion Archives.

Build Steps

Steps1. Locate the archive definition and click the Build Archive icon to open the Archive Wizard
2. Review the archive summary and click Next
3. On Choose Archive File Location, enter the full path and file name. The file must have a .car extension
4. Click Next to create the archive. The wizard reports Build Successful or Build Failed (click Details to see why)
UNIXTo run the archive as a privileged user, select Run This Archive As A Specific User and enter that system account's user name and password. If they do not match, the build fails
Archive SettingsThe Archive Settings page configures system settings that apply to all archive and deployment operations
Best Practice: Use a consistent file naming convention that includes the application name, environment, and version or date (for example, myapp-production-20251027.car).
Security: Archives can contain data source definitions and other sensitive settings. Store CAR files outside the web root and restrict who can read them.

Deploying Archives

You can deploy a CAR file to the same ColdFusion server or to a ColdFusion server on a different computer.

Deployment Tips

  • Test deployment on a staging environment first
  • Back up the current configuration and application files before deploying
  • Review environment-specific settings (data source hosts, mapping paths) after deploying

Archive Management Best Practices

Version Control

Best Practices:
  • Use semantic versioning for archive names (v2.3.1)
  • Include date stamps for time-based tracking (YYYYMMDD)
  • Tag archives with environment identifiers (dev, staging, prod)
  • Maintain archive inventory with descriptions and deployment dates
  • Keep archives for at least 3 previous versions for rollback capability

Security Considerations

Security Best Practices:
  • Treat archives as sensitive; they can contain data source and other configuration details
  • Encrypt CAR files when transferring over networks
  • Store archives in secure, access-controlled locations
  • Use separate archives for different environments
  • Exclude sensitive files (.env, credentials, private keys)
  • Review archive contents before distribution
  • Implement access controls for archive creation and deployment

Storage and Retention

Storage Recommendations:
  • Store archives outside webroot to prevent unauthorized downloads
  • Use dedicated archive repository with backup
  • Implement retention policy (e.g., keep 90 days of archives)
  • Archive critical production deployments to long-term storage
  • Document archive locations in disaster recovery plans
  • Compress old archives to save storage space

Deployment Workflow

Recommended Workflow:
  • 1. Create: Build archive from source environment (development)
  • 2. Test: Deploy to staging environment and verify functionality
  • 3. Backup: Create archive of current production configuration
  • 4. Deploy: Extract archive to production environment
  • 5. Configure: Manually set environment-specific settings (passwords, URLs)
  • 6. Verify: Test critical functionality post-deployment
  • 7. Monitor: Watch logs and metrics for issues
  • 8. Document: Record deployment details and any issues

Automating with cfsetup

Adobe's Administrator API reference lists no method for building CAR files (see the Administrator API reference). For scripted migrations, use the cfsetup command-line tool, located in <cf_home>/config/cfsetup, to export settings from one instance and import them into another. Exported files are password protected with a passphrase you supply on export and again on import. (Source: Adobe: CFSetup configuration tool)

Export and Import Settings with cfsetup
# On the source server: export all settings to a JSON file
# (cfsetup asks for a passphrase to protect the exported file)
cfsetup export all settings.json <cf_home>|<alias>

# On the target server: import the settings
cfsetup import all settings.json <cf_home>|<alias>

# Before importing, update any file paths in the JSON so they are valid on the
# target server. Import backups go to ColdFusion_Home/cfusion/lib/cfsetup_backup

# Some changes (for example, passwords and sandboxes) take effect only after a restart
Automation Benefits:
  • Settings files can be stored in version control (keep secrets out of the repo)
  • Integration with CI/CD pipelines
  • Repeatable server builds across environments

Common Issues & Solutions

Archive Deployment Fails

Symptom: Archive extraction fails with permissions errors or missing directories
Solutions:
  • On ColdFusion 2025 Update 5 or later, confirm the CAR's source path is listed under car.deploypath in pathfilter.json, and check car_deploy.log
  • Verify ColdFusion has write permissions to target deployment directory
  • Ensure deployment directory exists before extraction
  • Check disk space availability on target server
  • Verify archive file is not corrupted (check file size, integrity)
  • Review ColdFusion logs for specific error messages
  • Try extracting to different directory to isolate permission issues

Datasources Not Working After Deployment

Symptom: Application cannot connect to database after archive deployment
Solutions:
  • Re-enter datasource passwords if they did not carry over
  • Update connection strings for target environment
  • Verify database server is accessible from new environment
  • Check JDBC driver is installed on target server
  • Update host names, ports, and database names for environment
  • Test datasource connection in administrator

Mappings Point to Wrong Directories

Symptom: ColdFusion mappings reference non-existent directories after deployment
Solutions:
  • Update mapping paths for target server directory structure
  • Create directory structure to match source environment
  • Exclude mappings from archive and configure manually per environment
  • Document mapping requirements in deployment guide
  • Use environment variables for path configuration

Archive Too Large to Upload

Symptom: Cannot upload CAR file through administrator due to size restrictions
Solutions:
  • Transfer archive via FTP/SFTP instead of HTTP upload
  • Increase maximum POST size in administrator settings
  • Split the archive definition into smaller archives (code vs. settings)
  • Exclude large static assets from archive (deploy separately)
  • Use command-line tools for server-to-server transfer
  • Compress archive or exclude unnecessary files

Related Resources

Packaging & Deployment - ColdFusion Archives | ColdFusion Administrator | CFGuide