← Back to ColdFusion Administrator Reference

Packaging & Deployment - ColdFusion Archives

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

Last updated: October 27, 20258 min read

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.

What Gets Archived

ColdFusion Archives can include various server settings and application components.

Application Files

CFM/CFC templates, images, CSS, JavaScript, and other static assets within the selected directory structure.

Datasources

JDBC datasource configurations including connection strings, pooling settings, and authentication (passwords can be excluded for security).

Mappings

ColdFusion and custom tag path mappings that define logical paths to physical directories.

Mail Settings

SMTP server configurations including server addresses, ports, authentication, and default settings.

Scheduled Tasks

Automated task definitions including URLs, schedules, intervals, and execution parameters.

Event Gateways

Event gateway instances, configurations, and related CFC listeners for asynchronous processing.

Web Services

SOAP web service connections, WSDL URLs, and service mappings.

REST Services

RESTful web service configurations, endpoints, and authentication settings.

Document Settings

PDF generation settings, font configurations, and document service parameters.

Custom Settings

Application-specific settings, custom Java settings, and environment variables.

Creating Archives

Configure archive creation settings to bundle applications and configurations.

Archive Name

PurposeUnique identifier for the archive file

Formatapplicationname-environment-version.car

Examplemyapp-production-v2.3.1.car
ecommerce-staging-20251027.car

Best Practice: Use consistent naming conventions that include application name, environment, version, or date for easy identification and rollback capability.

Archive Description

PurposeDocument what the archive contains and its purpose

Example"Production release v2.3.1 - includes new checkout flow, security patches, and updated datasource configurations"

Documentation Tips:

Include version numbers and release dates
List major features or changes included
Note any special deployment instructions
Document dependencies or prerequisites

Application Root Directory

PurposeBase directory containing application files to include

FormatAbsolute path to webroot or application directory

Example/var/www/myapp
C:\inetpub\wwwroot\ecommerce

Security: Exclude sensitive files like database passwords, private keys, and environment-specific configurations before archiving.

Select Components to Archive

PurposeChoose which settings and configurations to include

OptionsDatasources, Mappings, Mail Settings, Scheduled Tasks, Event Gateways, Web Services, REST Services, Document Settings

Selection Strategy:

Full Migration: Include all components for complete server migration
Application Deployment: Include only application-specific settings
Configuration Backup: Include settings but exclude application files
Selective Sync: Include only changed components for updates

Include Password Information

PurposeDetermine whether to include sensitive password data

DefaultDisabled (recommended for security)

When to EnableOnly for secure, encrypted archives in controlled environments

Security Critical: Never include passwords in archives that will be transferred over unsecured networks, stored in source control, or accessed by multiple users. Manually configure passwords after deployment instead.

Deploying Archives

Extract and deploy CAR files to configure target servers.

Select Archive File

PurposeChoose CAR file to deploy from filesystem or upload

OptionsBrowse Server: Select from existing CAR files on server
Upload: Upload CAR file from local machine

Deployment Tips:

Verify archive integrity before deployment
Review archive description to confirm correct version
Test deployment on staging environment first
Keep backup of current configuration before deploying

Deployment Directory

PurposeTarget directory where application files will be extracted

DefaultOriginal archive directory path

Example/var/www/production/myapp
C:\inetpub\wwwroot\live\ecommerce

Warning: Deployment will overwrite existing files in the target directory. Always backup current application before deploying archives.

Select Components to Deploy

PurposeChoose which archived components to extract and apply

StrategyFull Deployment: Deploy all components for new installation
Code Only: Deploy application files without changing settings
Settings Only: Deploy configurations without touching code
Selective: Deploy specific components as needed

Deployment Scenarios:

Production Update: Deploy code only, keep existing datasource configurations
New Environment: Deploy all components for complete setup
Configuration Sync: Deploy settings only to standardize environments
Hotfix: Deploy application files only for quick patches

Overwrite Existing Settings

PurposeDetermine whether to replace existing configurations

OptionsOverwrite: Replace all existing settings
Skip Existing: Keep current settings, add only new ones
Merge: Combine archived and existing settings (where supported)

Caution: Overwriting can disrupt production configurations. Review differences between archived and current settings before deploying with overwrite enabled.

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:

Never include passwords in archives (configure manually post-deployment)
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

Archive Creation Example

Programmatic archive creation using CFML for automation:

Creating Archives Programmatically

<cfscript>
  // Archive creation for deployment automation
  archiveName = "myapp-production-v#application.version#.car";
  archivePath = "/opt/archives/#archiveName#";
  appRoot = expandPath("/");

  // Create archive using admin API
  adminAPI = createObject("component", "cfide.adminapi.extensions");
  adminAPI.login("admin", "adminpassword");

  archiveSettings = {
    archiveName: archiveName,
    description: "Production deployment v#application.version# - #dateFormat(now(), 'yyyy-mm-dd')#",
    directory: appRoot,
    includeDatasources: true,
    includeMappings: true,
    includeMailSettings: true,
    includeScheduledTasks: true,
    includePasswords: false, // Security: never include passwords
    saveToPath: archivePath
  };

  // Create the archive
  try {
    adminAPI.createArchive(argumentCollection=archiveSettings);
    writeOutput("Archive created successfully: #archiveName#");

    // Log archive creation
    writeLog(
      file="deployment",
      type="information",
      text="Archive created: #archiveName# - Size: #numberFormat(getFileInfo(archivePath).size / 1024 / 1024, '0.00')# MB"
    );
  }
  catch (any e) {
    writeLog(
      file="deployment",
      type="error",
      text="Archive creation failed: #e.message#"
    );
    rethrow;
  }
</cfscript>

<!--- Archive creation for deployment automation --->
<cfset archiveName = "myapp-production-v#application.version#.car">
<cfset archivePath = "/opt/archives/#archiveName#">
<cfset appRoot = expandPath("/")>

<!--- Create archive using admin API --->
<cfset adminAPI = createObject("component", "cfide.adminapi.extensions")>
<cfset adminAPI.login("admin", "adminpassword")>

<cftry>
  <cfset adminAPI.createArchive(
    archiveName = archiveName,
    description = "Production deployment v#application.version# - #dateFormat(now(), 'yyyy-mm-dd')#",
    directory = appRoot,
    includeDatasources = true,
    includeMappings = true,
    includeMailSettings = true,
    includeScheduledTasks = true,
    includePasswords = false,
    saveToPath = archivePath
  )>

  <cfoutput>Archive created successfully: #archiveName#</cfoutput>

  <!--- Log archive creation --->
  <cflog
    file="deployment"
    type="information"
    text="Archive created: #archiveName# - Size: #numberFormat(getFileInfo(archivePath).size / 1024 / 1024, '0.00')# MB">

  <cfcatch type="any">
    <cflog
      file="deployment"
      type="error"
      text="Archive creation failed: #cfcatch.message#">
    <cfrethrow>
  </cfcatch>
</cftry>

Automation Benefits:

Consistent archive creation process
Integration with CI/CD pipelines
Automated versioning and naming
Audit trail through logging

Common Issues & Solutions

Archive Deployment Fails

Symptom: Archive extraction fails with permissions errors or missing directories

Solutions:

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:

Manually configure datasource passwords (not included in archive for security)
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
Use relative paths instead of absolute paths where possible
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 archive into smaller components (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

Containerization GuideModern deployment with Docker and containers Server Settings - MappingsConfigure ColdFusion and custom tag path mappings Data & Services - Data SourcesDatasource configuration and management ColdFusion Administrator ReferenceComplete administrator guide and settings reference