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.
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.<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
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 extension4. Click Next to create the archive. The wizard reports Build Successful or Build Failed (click Details to see why)
myapp-production-20251027.car).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
- 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
- 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
- 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
- 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)
# 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- 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
- 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
- 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
- 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
- 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