Config Directory Migration (3.0.0)

Config Directory Migration (3.0.0)

Overview

In Wheels 3.0.0, we’ve made a significant change to improve the framework’s structure and make it more intuitive for developers. The configuration directory has been moved from /app/config to /config at the root level of your application.

Why This Change?

• Better Organization: Configuration files are now at the same level as the /app directory, making them easier to find and manage
• Industry Standards: This aligns with common conventions in modern web frameworks
• Clearer Separation: Application code (/app) is now clearly separated from configuration (/config)

Breaking Change

This is a breaking change that requires action when upgrading to Wheels 3.0.0. Your application will not work correctly until you complete the migration.

What’s Changed

• /app/config/ → /config/
• All configuration files (settings.cfm, routes.cfm, etc.) must be moved
• All references to the old path must be updated

Migration Methods

Method 1: Automated Migration (Recommended)

We provide a CommandBox recipe that automates most of the migration process:

# From your application root directory
box recipe https://raw.githubusercontent.com/wheels-dev/wheels/develop/cli/recipes/config-migration.boxr

The recipe will:

1. Back up any existing /config directory
2. Move /app/config to /config
3. Update your Application.cfc
4. Scan for references to the old path
5. Create a migration log

Method 2: Manual Migration

If you prefer to migrate manually:

1. Move the config directory

   mv app/config config

2. Update Application.cfc

   Find and replace all occurrences of:

   • app/config/ with config/
   • app\config\ with config\
   • /app/config with /config
   • \app\config with \config

3. Update your code

   Search your entire codebase for references to app/config and update them:

   # Find all files with references
   grep -r "app/config" app/ tests/

4. Update any custom scripts or deployment configurations

Common Files to Check

Make sure to update references in:

• Application.cfc
• Custom initialization code
• Deployment scripts
• Documentation
• Test files
• Any hardcoded paths in your models, controllers, or views

Verification

After migration, verify that:

1. Your application starts without errors
2. All configuration files are loaded correctly
3. Routes are working as expected
4. Database connections are established
5. All tests pass

Rollback

If you need to rollback:

1. The automated recipe creates backups:

   • Application.cfc.bak - Your original Application.cfc
   • config_backup_[timestamp] - Any existing /config directory

2. To rollback manually:

   # Move config back
   mv config app/config
   
   # Restore Application.cfc from backup
   mv Application.cfc.bak Application.cfc

Troubleshooting

Application Won’t Start

• Ensure /config directory exists at the root level
• Check that all .cfm files were moved from /app/config
• Verify Application.cfc has been updated
• Check for syntax errors in migrated configuration files

Routes Not Working

• Confirm /config/routes.cfm exists
• Check for any hardcoded paths in your route definitions
• Verify the file permissions are correct (readable by your web server)
• Clear any route caching: add ?reload=true to your URL

Missing Configuration

• Ensure all files from /app/config were moved, including:
  • /config/settings.cfm
  • /config/routes.cfm
  • /config/environment.cfm
  • /config/app.cfm
  • All environment-specific folders (development, testing, production, maintenance)
• Check for any custom configuration files you may have added

Tests Failing

• Update test setup files that reference the old config path
• Check test fixtures and helpers for hardcoded paths
• Ensure test database configurations are properly migrated
• Look for any expandPath() calls that reference the old path

Docker/Container Issues

• Update any Docker volume mounts from /app/config to /config
• Rebuild containers after making compose.yml changes
• Check container logs for configuration loading errors

Common Error Messages

“Could not find route”

• This usually means /config/routes.cfm is not being loaded
• Check the Application.cfc mapping is correct
• Verify the file exists and has proper permissions

“Invalid datasource”

• Ensure /config/settings.cfm contains your datasource configuration
• Check environment-specific settings files were migrated

“Component not found”

• This may indicate the config mapping in Application.cfc is incorrect
• Verify the mapping points to /config not /app/config

Additional Resources

• Configuration and Defaults
• Wheels 3.0.0 Release Notes
• Community Support

Need Help?

If you encounter issues during migration:

1. Check the migration log (config_migration.log)
2. Search existing issues on GitHub
3. Ask for help in the Wheels Community