Server Settings - Mappings
Configure ColdFusion and custom tag path mappings
Overview
Mappings in ColdFusion allow you to create logical paths that point to physical directories on your server. This abstraction enables cleaner code organization, easier path management, and better portability across different environments. Understanding how to properly configure and use mappings is essential for building maintainable ColdFusion applications.
This page covers ColdFusion mappings and the related custom tag paths. These settings affect how ColdFusion resolves paths when including templates, creating components, and invoking custom tags.
ColdFusion Mappings
What Are ColdFusion Mappings?
- Purpose: Create logical path aliases that point to physical directories
- Use Cases: Shared code libraries, component directories, include files
- Benefit: Change physical location without updating code
- Syntax: Logical path starts with forward slash (e.g., /myapp)
- Resolution: ColdFusion resolves logical path to physical directory
Creating a Mapping
- Logical Path: The virtual path name (must start with /)
- Example: /shared, /components, /lib
- Must be unique within the server
- Directory Path: The physical directory location
- Absolute path recommended (e.g., /var/www/shared)
- Can use drive letters on Windows (e.g., D:\shared)
- Can use UNC paths (\\server\share)
- No per-mapping options: A mapping is only a logical path and a directory path. Template change checking is server-wide (Server Settings > Caching)
Default ColdFusion Mappings
- /CFIDE: ColdFusion Administrator and related resources
- Should be secured in production (block external access)
- Adobe lists the /CFIDE mapping among settings a CAR archive never migrates
- /gateway: Points to the gateway/cfc directory, where event gateway application CFCs live
Using Mappings in Code
- Including Templates: <cfinclude template="/shared/utils.cfm">
- Creating Components: createObject("component", "/components/User")
- Extending Components: component extends="/components/Base"
- Custom Tag Modules: <cfmodule template="/customtags/mytag.cfm"> (cf_ tags are found through custom tag paths instead)
- Path Notation: Use dot notation for components (/lib/utils.cfc = lib.utils)
Best Practices for Mappings
- Use descriptive names that indicate purpose (/components, /includes, /api)
- Keep mappings consistent across dev, test, and production
- Enable Trusted Cache (Server Settings > Caching) in production for better performance
- Use mappings to organize shared code and components
- Document all custom mappings in deployment procedures
- Avoid overlapping or conflicting mapping names
- Use absolute paths to prevent ambiguity
Application-Specific Mappings
Configure mappings at the application level in Application.cfc for better portability and isolation.
Per-Application Mappings in Application.cfc
this.mappings structExample Application.cfc Mapping
Configure mappings dynamically based on the application's location:
component {
this.name = "MyApplication";
// Define application-specific mappings
this.mappings = {
// Map to application root directory
"/myapp": getDirectoryFromPath(getCurrentTemplatePath()),
// Map to components directory
"/components": expandPath("/myapp/cfc"),
// Map to includes directory (relative to app root)
"/includes": expandPath("/myapp/includes"),
// Map to shared resources (absolute path)
"/shared": "/var/www/shared"
};
function onApplicationStart() {
// Application initialization
return true;
}
}<cfcomponent>
<cfset this.name = "MyApplication">
<!--- Define application-specific mappings --->
<cfset this.mappings = {}>
<!--- Map to application root directory --->
<cfset this.mappings["/myapp"] = getDirectoryFromPath(getCurrentTemplatePath())>
<!--- Map to components directory --->
<cfset this.mappings["/components"] = expandPath("/myapp/cfc")>
<!--- Map to includes directory (relative to app root) --->
<cfset this.mappings["/includes"] = expandPath("/myapp/includes")>
<!--- Map to shared resources (absolute path) --->
<cfset this.mappings["/shared"] = "/var/www/shared">
<cffunction name="onApplicationStart" returnType="boolean">
<!--- Application initialization --->
<cfreturn true>
</cffunction>
</cfcomponent>- Use
expandPath()for paths relative to application root for better portability - Use
getDirectoryFromPath(getCurrentTemplatePath())to get the directory containing Application.cfc - Avoid hardcoded absolute paths unless necessary (reduces portability)
- Document all mappings in your application's README
When to Use Application vs Server Mappings
Server-Level Mappings
Use for shared libraries used by multiple applications on the same server. Examples: shared utility CFCs, common frameworks, cross-application resources.
Application-Level Mappings
Use for application-specific code organization. Preferred approach for better isolation, portability, and no need for server administrator access.
Custom Tag Paths
What Are Custom Tag Paths?
- Purpose: Directories where ColdFusion searches for custom tags
- Custom Tags: Reusable CFML templates invoked with <cf_tagname> syntax
- Locations: The calling page's directory, cfusion/CustomTags and its subdirectories, and directories you specify in the Administrator
- Default Path: cfusion/CustomTags
Configuring Custom Tag Paths
- Adding Paths: Enter absolute path to directory containing custom tags
- Multiple Paths: Can add multiple directories
- Name Conflicts: If several tags share a name, Adobe advises copying the tag to the calling page's directory or calling it with cfmodule and an explicit template path
Where ColdFusion Looks for cf_ Tags
- The same directory as the calling page
- The cfusion/CustomTags directory
- A subdirectory of cfusion/CustomTags (ColdFusion steps down through subdirectories until it finds the tag)
- A directory that you specify in the ColdFusion Administrator
- cfimport: Not part of this lookup; cfimport tags use their own prefix and taglib path
Application-Specific Custom Tag Paths
- Application.cfc Setting: this.customTagPaths
- Syntax: this.customTagPaths = "/path/to/tags";
- Multiple Paths: this.customTagPaths = "/path1,/path2";
- Scope: Applies only to that application
Best Practices for Custom Tags
- Use cfimport for better organization and namespacing
- Keep custom tags in version control
- Document tag attributes and usage
- Use unique names to avoid conflicts
- Consider using CFC-based custom tags for better OOP support
- Test tags in isolation before deploying
Modern Alternative: CFImport
- Better Approach: <cfimport prefix="mytags" taglib="/customtags">
- Namespacing: <mytags:tagname> prevents naming conflicts
- Clarity: Explicit about where tags come from
- Recommendation: Use cfimport instead of custom tag paths
ColdFusion Archives (.car) and Sourceless Deployment
The Mappings page has no archive file mappings. A .car file is a ColdFusion Archive managed under Packaging & Deployment > ColdFusion Archives. It archives site configuration (such as mappings, scheduled tasks, and server settings) plus files and directories for deployment to another server or for backup; it is not a compiled application served through a mapping. CAR migration is deprecated in ColdFusion 2025, with cfsetup as the replacement for moving settings. To deploy without source code, use cfcompile -deploy webroot directory-to-compile output-directory, which writes bytecode .cfm, .cfc, and .cfr files to a separate output directory that you deploy in place of the source.
Mapping Resolution and Precedence
Path Resolution Order
- Application-specific mappings (Application.cfc this.mappings)
- Server-level mappings (Administrator settings)
- Relative paths from current template directory
- Web root directory
First Match: First successful resolution is used
Mapping Conflicts
- Same Logical Path: Application-level overrides server-level
- Case Sensitivity: Linux/Unix is case-sensitive, Windows is not
- Overlap: More specific paths take precedence
- Example: /myapp/lib overrides /myapp
- Best Practice: Avoid conflicting mappings when possible
Path Resolution Issues
- Relative vs Absolute: Relative paths can be ambiguous
- Template Context: Relative paths resolve from current template location
- Include Context: Included templates inherit calling template's context
- Recommendation: Use mappings for clarity and consistency
Performance Impact of Mappings
Template Change Detection (Server-Wide)
- Not a mapping setting: Controlled by Trusted Cache on Server Settings > Caching
- Trusted Cache Off (Development): ColdFusion checks file modification time on each request
- Automatically reloads changed templates
- Small performance overhead (file system check)
- Convenient for development
- Trusted Cache On (Production): Cached templates are used without checking for changes
- Better performance (no file checks)
- Requires template cache clear or restart after changes
- Recommended for production
Mapping Overhead
- Resolution Cost: Mapping resolution is very fast
- Caching: Resolved paths are cached
- Impact: Minimal performance impact in practice
- Benefit: Performance cost is negligible compared to benefits
Network Paths
- UNC Paths: Mappings to network shares (\\server\share)
- Performance: Significantly slower than local paths
- Latency: Network latency affects every file access
- Reliability: Network issues can cause failures
- Recommendation: Avoid network paths if possible
- Alternative: Copy files to local disk during deployment
Best Practices for Performance
- Enable Trusted Cache in production
- Use local paths instead of network paths
- Keep mapping structures simple
- Monitor file system performance
- Use SSD storage for better I/O performance
Organizing Code with Mappings
Common Mapping Patterns
- /components: Application CFCs and business logic
- /model: Model layer components (MVC pattern)
- /services: Service layer components
- /utils: Utility functions and helpers
- /includes: Commonly included templates
- /api: API endpoints and handlers
- /lib: Third-party libraries and frameworks
Framework Mappings
- FW/1: /framework, /controllers, /views, /layouts
- ColdBox: /coldbox, /models, /handlers, /modules
- Fusebox: /fusebox, /circuits
- Best Practice: Follow framework conventions
Multi-Application Server Organization
- Shared Mappings: /shared for code used by all apps
- Application Mappings: /app1, /app2 for application-specific code
- Common Libraries: /lib for shared utilities
- Isolation: Use application-specific mappings when possible
Recommended Directory Structure
- Physical Layout:
- /var/www/myapp/ (webroot)
- /var/www/myapp/cfc/ (components)
- /var/www/myapp/includes/ (includes)
- /var/www/shared/ (shared across apps)
- Logical Mappings:
- /myapp → /var/www/myapp
- /components → /var/www/myapp/cfc
- /shared → /var/www/shared
Common Issues and Solutions
Mapping Not Found Errors
- Symptom: "Could not find mapping for path" error
- Causes:
- Mapping not defined in administrator or Application.cfc
- Typo in mapping name
- Case sensitivity on Linux/Unix
- Solutions:
- Verify mapping exists in administrator
- Check spelling and case
- Ensure "Enable Per App Settings" is enabled
File Not Found Despite Valid Mapping
- Symptom: Mapping resolves but file not found
- Causes:
- Physical path is incorrect
- File doesn't exist at physical location
- Permissions prevent access
- Case sensitivity on Linux/Unix
- Solutions:
- Verify physical directory path
- Check file exists in physical location
- Verify ColdFusion has read permissions
- Check file name case matches exactly
Templates Not Reloading
- Symptom: Changes to templates not reflected
- Causes:
- Trusted Cache enabled
- Template cache not cleared
- Browser caching
- Solutions:
- Disable Trusted Cache for development
- Clear template cache in administrator
- Clear browser cache
- Use query string to bust cache (?v=123)
Mapping Conflicts Between Applications
- Symptom: One application's mapping affects another
- Cause: Server-level mappings are global
- Solutions:
- Use application-specific mappings in Application.cfc
- Use unique mapping names per application
- Ensure "Enable Per App Settings" is enabled
Performance Issues with Mappings
- Symptom: Slow template loading
- Causes:
- Network paths (UNC) instead of local
- Trusted Cache disabled in production
- Slow file system (HDD, network storage)
- Solutions:
- Use local paths only
- Enable Trusted Cache in production
- Use SSD storage
- Monitor disk I/O
Security Considerations
Mapping Security Best Practices
- Never map to sensitive directories (system folders, password files)
- Restrict /CFIDE access to localhost or admin IPs only
- Use proper file system permissions on mapped directories
- Avoid mapping to directories above webroot when possible
- Document all mappings for security audits
- Regularly review and remove unused mappings
Web Server Configuration
- /CFIDE Protection: Block external access via web server rules
- Apache Example: <Location /CFIDE> Deny from all </Location>
- IIS: Use IP restrictions or authentication
- Nginx: Deny access in location block
File System Permissions
- ColdFusion service account needs read access to mapped directories
- Limit write access to only necessary directories
- Use principle of least privilege
- Regularly audit permissions