michaelschiemer/deployment/applications/environments

Environment Configuration Guide

This directory contains environment templates for different deployment environments of the Custom PHP Framework.

Environment Templates

.env.production.template

Production environment template with security-focused configurations:

• APP_DEBUG=false
• Strict session fingerprinting
• Xdebug disabled
• Production logging levels
• Strong password requirements

.env.staging.template

Staging environment template for testing:

• APP_DEBUG=true
• Moderate security settings
• Xdebug enabled for debugging
• Verbose logging
• Test API configurations

Usage

1. Copy the appropriate template:

   cp .env.production.template .env.production
   # or
   cp .env.staging.template .env.staging
   

2. Fill in required values:

   • Replace all *** REQUIRED *** placeholders with actual values
   • Generate strong passwords for database credentials
   • Configure API keys and service credentials
   • Set proper domain names and SSL certificate paths

3. Security Considerations:

   • Never commit actual .env.production or .env.staging files to version control
   • Use strong, unique passwords for each environment
   • Rotate credentials regularly
   • Enable appropriate session fingerprinting for security

Environment-Specific Settings

Development → Staging Changes

• Enable Xdebug but remove IDE configurations
• Use staging database and credentials
• Enable detailed logging for debugging
• Use test API endpoints where available

Staging → Production Changes

• Disable all debug features (APP_DEBUG=false, XDEBUG_MODE=off)
• Enable strict security settings
• Use production database with strong credentials
• Set warning-level logging only
• Configure production SSL certificates
• Use production API keys and webhooks

Required Values by Environment

Production Requirements

• Database: Strong passwords, production database name
• APIs: Production webhook secrets, SMTP credentials
• SSL: Valid SSL certificate paths
• Monitoring: Production-grade logging configuration

Staging Requirements

• Database: Separate staging database credentials
• APIs: Test/staging API keys where available
• SSL: Test certificates or self-signed certificates
• Monitoring: Verbose logging for debugging

Environment Variable Categories

Core Application

• APP_ENV, APP_DEBUG, APP_URL, APP_DOMAIN

Database Configuration

• DB_HOST, DB_DATABASE, DB_USERNAME, DB_PASSWORD, DB_ROOT_PASSWORD

Security & Session

• Session fingerprinting settings
• SSL certificate paths
• Authentication configurations

External Services

• SMTP configuration for emails
• Third-party API credentials
• Webhook secrets

Performance & Caching

• OPcache settings
• Redis configuration
• Worker process limits

Monitoring & Logging

• Log levels and channels
• Error reporting settings
• Analytics configuration

Deployment Integration

These environment files are used by:

• Docker Compose overlays (docker-compose.production.yml, docker-compose.staging.yml)
• Ansible deployment playbooks
• Application deployment scripts

Security Best Practices

1. Credential Management:

   • Use strong, unique passwords for each environment
   • Consider using a password manager or secrets management service
   • Rotate credentials regularly

2. Environment Isolation:

   • Keep staging and production completely separate
   • Use different database servers and API keys
   • Monitor access to production credentials

3. File Permissions:

   • Set restrictive permissions on environment files (600)
   • Ensure only necessary users can read the files
   • Never include in version control

4. SSL/TLS Configuration:

   • Use valid SSL certificates in production
   • Enable HTTPS everywhere
   • Configure proper cipher suites

Troubleshooting

Common Issues

• Missing required values: Check for *** REQUIRED *** placeholders
• Database connection failures: Verify database credentials and host
• SSL certificate errors: Check certificate paths and permissions
• API failures: Verify API keys and endpoint configurations

Environment-Specific Debugging

• Staging: Enable verbose logging and Xdebug
• Production: Check application logs and monitoring systems
• Both: Verify environment variable loading in application

Integration with Deployment

The environment templates integrate with:

1. Docker Compose overlays for environment-specific container configuration
2. Ansible playbooks for automated environment setup
3. Application deployment scripts for environment validation and deployment