wheels env setup
Setup a new environment configuration for your Wheels application.
Synopsis
wheels env setup [name] [options]
Description
The wheels env setup
command creates and configures new environments for your Wheels application. It generates environment-specific configuration files, database settings, and initializes the environment structure.
Arguments
name
Environment name (e.g., staging, qa, production)
Required
Options
--base
Base environment to copy from
development
--database
Database name
wheels_[name]
--datasource
CF datasource name
wheels_[name]
--debug
Enable debug mode
false
--cache
Enable caching
Based on name
--reload-password
Password for reload
Random
--skip-database
Skip database creation
false
--force
Overwrite existing environment
false
--help
Show help information
Examples
Setup basic environment
wheels env setup staging
Setup with custom database
wheels env setup qa --database=wheels_qa_db --datasource=qa_datasource
Copy from production settings
wheels env setup staging --base=production
Setup with specific options
wheels env setup production --debug=false --cache=true --reload-password=secret123
Skip database setup
wheels env setup testing --skip-database
What It Does
Creates Configuration Directory:
/config/[environment]/ └── settings.cfm
Generates Settings File:
Database configuration
Environment-specific settings
Debug and cache options
Security settings
Sets Up Database (unless skipped):
Creates database
Configures datasource
Tests connection
Updates Environment Registry:
Adds to available environments
Sets up environment detection
Generated Configuration
Example config/staging/settings.cfm
:
<cfscript>
// Environment: staging
// Generated: 2024-01-15 10:30:45
// Database settings
set(dataSourceName="wheels_staging");
// Environment settings
set(environment="staging");
set(showDebugInformation=true);
set(showErrorInformation=true);
// Caching
set(cacheFileChecking=false);
set(cacheImages=false);
set(cacheModelInitialization=false);
set(cacheControllerInitialization=false);
set(cacheRoutes=false);
set(cacheActions=false);
set(cachePages=false);
set(cachePartials=false);
set(cacheQueries=false);
// Security
set(reloadPassword="generated_secure_password");
// URLs
set(urlRewriting="partial");
// Custom settings for staging
set(sendEmailOnError=true);
set(errorEmailAddress="[email protected]");
</cfscript>
Environment Types
Development
Full debugging
No caching
Detailed errors
Hot reload
Testing
Test database
Debug enabled
Isolated data
Fast cleanup
Staging
Production-like
Some debugging
Performance testing
Pre-production validation
Production
No debugging
Full caching
Error handling
Optimized performance
Custom
Create specialized environments:
wheels env setup performance-testing --base=production --cache=false
Database Configuration
Automatic Setup
wheels env setup staging
# Creates: wheels_staging database
# Datasource: wheels_staging
Custom Database
wheels env setup staging \
--database=staging_db \
--datasource=myapp_staging
Database URL
wheels env setup production \
--database-url="mysql://user:pass@host:3306/db"
Environment Variables
The command sets up support for:
# .env.staging
WHEELS_ENV=staging
WHEELS_DATASOURCE=wheels_staging
WHEELS_DEBUG=true
WHEELS_CACHE=false
DATABASE_URL=mysql://localhost/wheels_staging
Configuration Inheritance
Environments can inherit settings:
// config/staging/settings.cfm
<cfinclude template="../production/settings.cfm">
// Override specific settings
set(showDebugInformation=true);
set(cacheQueries=false);
Validation
After setup, the command validates:
Configuration file syntax
Database connectivity
Directory permissions
Environment detection
Environment Detection
Configure how environment is detected:
// config/environment.cfm
if (cgi.server_name contains "staging") {
set(environment="staging");
} else if (cgi.server_name contains "qa") {
set(environment="qa");
} else {
set(environment="production");
}
Best Practices
Naming Convention: Use clear, consistent names
Base Selection: Choose appropriate base environment
Security: Use strong reload passwords
Documentation: Document environment purposes
Testing: Test configuration before use
Advanced Configuration
Multiple Databases
wheels env setup reporting \
--database=wheels_reporting \
--read-database=wheels_replica
Load Balancing
wheels env setup production \
--servers=web1,web2,web3 \
--load-balancer=nginx
Feature Flags
// In settings.cfm
set(features={
newCheckout: true,
betaAPI: false,
debugToolbar: true
});
Troubleshooting
Database Creation Failed
Check database permissions
Verify connection settings
Use
--skip-database
and create manually
Configuration Errors
Check syntax in settings.cfm
Verify file permissions
Review error logs
Environment Not Detected
Check environment.cfm logic
Verify server variables
Test detection rules
Migration
From Existing Environment
# Export existing config
wheels env export production > prod-config.json
# Import to new environment
wheels env setup staging --from-config=prod-config.json
Use Cases
Multi-Stage Pipeline: dev → staging → production
Feature Testing: Isolated feature environments
Performance Testing: Dedicated performance environment
Client Demos: Separate demo environments
A/B Testing: Multiple production variants
Notes
Environment names should be lowercase
Avoid spaces in environment names
Each environment needs unique database
Restart application after setup
Test thoroughly before using
See Also
wheels env - Environment management overview
wheels env list - List environments
wheels env switch - Switch environments
wheels config - Configuration management
Last updated
Was this helpful?