michaelschiemer/deployment/docs/ENVIRONMENTS.md

Environment Configuration Guide

This guide covers how to configure and manage different deployment environments for the Custom PHP Framework.

Project Configuration

• Domain: michaelschiemer.de
• Email: kontakt@michaelschiemer.de
• PHP Version: 8.4

Available Environments

Development

• Purpose: Local development and testing
• Domain: development.michaelschiemer.de (or localhost)
• SSL: Self-signed certificates
• Debug: Enabled
• Database: Local container

Staging

• Purpose: Pre-production testing and validation
• Domain: staging.michaelschiemer.de
• SSL: Let's Encrypt or provided certificates
• Debug: Limited debugging
• Database: Staging database with production-like data

Production

• Purpose: Live production environment
• Domain: michaelschiemer.de
• SSL: Let's Encrypt with strict security
• Debug: Disabled
• Database: Production database with backups

Environment Files Structure

deployment/applications/environments/
├── .env.development
├── .env.staging
├── .env.production
├── .env.development.template
├── .env.staging.template
└── .env.production.template

Configuration Variables

Application Settings

# Application Environment
APP_ENV=production              # Environment name
APP_DEBUG=false                 # Debug mode (true only for development)
APP_URL=https://michaelschiemer.de  # Application URL

# Framework Settings
FRAMEWORK_VERSION=1.0.0         # Framework version
FRAMEWORK_ENV=production        # Framework environment

Database Configuration

# Database Connection
DB_CONNECTION=mysql
DB_HOST=db                      # Docker service name
DB_PORT=3306
DB_DATABASE=michaelschiemer
DB_USERNAME=app_user
DB_PASSWORD=*** SECURE PASSWORD ***  # Generate strong password
DB_ROOT_PASSWORD=*** SECURE PASSWORD ***  # Generate strong password

SSL and Security

# SSL Configuration
SSL_EMAIL=kontakt@michaelschiemer.de  # Let's Encrypt email
DOMAIN_NAME=michaelschiemer.de        # Primary domain

# Security Settings
SECURITY_LEVEL=high             # Security hardening level
FIREWALL_STRICT_MODE=true       # Enable strict firewall rules
FAIL2BAN_ENABLED=true          # Enable fail2ban protection

Performance and Caching

# Performance Settings
PHP_MEMORY_LIMIT=512M
PHP_MAX_EXECUTION_TIME=60
OPCACHE_ENABLED=true

# Caching
CACHE_DRIVER=redis
REDIS_HOST=redis
REDIS_PORT=6379

Email Configuration

# Email Settings
MAIL_MAILER=smtp
MAIL_HOST=smtp.mailgun.org
MAIL_PORT=587
MAIL_USERNAME=*** REQUIRED ***
MAIL_PASSWORD=*** REQUIRED ***
MAIL_FROM_ADDRESS=noreply@michaelschiemer.de
MAIL_FROM_NAME="Michael Schiemer"

Environment-Specific Configurations

Development Environment

# Development-specific settings
APP_ENV=development
APP_DEBUG=true
APP_URL=https://localhost

# Relaxed security for development
SECURITY_LEVEL=standard
FIREWALL_STRICT_MODE=false

# Development database
DB_DATABASE=michaelschiemer_dev
DB_PASSWORD=dev_password  # Simple password for dev

# Development mail (log emails instead of sending)
MAIL_MAILER=log

Staging Environment

# Staging-specific settings
APP_ENV=staging
APP_DEBUG=false
APP_URL=https://staging.michaelschiemer.de

# Production-like security
SECURITY_LEVEL=high
FIREWALL_STRICT_MODE=true

# Staging database
DB_DATABASE=michaelschiemer_staging
DB_PASSWORD=*** SECURE STAGING PASSWORD ***

# Email testing
MAIL_MAILER=smtp
MAIL_HOST=smtp.mailtrap.io  # Testing service

Production Environment

# Production settings
APP_ENV=production
APP_DEBUG=false
APP_URL=https://michaelschiemer.de

# Maximum security
SECURITY_LEVEL=high
FIREWALL_STRICT_MODE=true
FAIL2BAN_ENABLED=true

# Production database
DB_DATABASE=michaelschiemer_prod
DB_PASSWORD=*** VERY SECURE PRODUCTION PASSWORD ***

# Production email
MAIL_MAILER=smtp
MAIL_HOST=smtp.mailgun.org
MAIL_USERNAME=*** PRODUCTION MAIL USERNAME ***
MAIL_PASSWORD=*** PRODUCTION MAIL PASSWORD ***

Security Best Practices

Password Generation

Generate secure passwords using:

# Generate random password
openssl rand -base64 32 | tr -d "=+/" | cut -c1-25

# Generate application key
openssl rand -base64 32

Environment File Security

# Set restrictive permissions
chmod 600 .env.*

# Never commit to version control
# (Already in .gitignore)

# Use different passwords for each environment
# Never reuse production passwords in staging/dev

SSL Certificate Management

# Let's Encrypt (recommended for production)
SSL_PROVIDER=letsencrypt
SSL_EMAIL=kontakt@michaelschiemer.de

# Self-signed (development only)
SSL_PROVIDER=self-signed

# Custom certificates
SSL_PROVIDER=custom
SSL_CERT_FILE=/path/to/cert.pem
SSL_KEY_FILE=/path/to/key.pem

Database Configuration

Connection Settings

# MySQL/MariaDB settings
DB_CONNECTION=mysql
DB_CHARSET=utf8mb4
DB_COLLATION=utf8mb4_unicode_ci
DB_TIMEZONE=+00:00

# Connection pooling
DB_POOL_MIN=5
DB_POOL_MAX=20
DB_POOL_TIMEOUT=30

Backup Configuration

# Backup settings
BACKUP_ENABLED=true
BACKUP_FREQUENCY=daily
BACKUP_RETENTION_DAYS=30
BACKUP_STORAGE=local  # or s3, gcs, etc.

Monitoring and Logging

Monitoring Configuration

# Monitoring settings
MONITORING_ENABLED=true
HEALTH_CHECK_ENDPOINT=/health
METRICS_ENDPOINT=/metrics

# Log levels
LOG_LEVEL=info  # debug, info, warning, error
LOG_CHANNEL=stack

Performance Monitoring

# Performance settings
PERFORMANCE_MONITORING=true
SLOW_QUERY_LOG=true
QUERY_CACHE_ENABLED=true

# Memory and execution limits
PHP_MEMORY_LIMIT=512M
PHP_MAX_EXECUTION_TIME=60
NGINX_CLIENT_MAX_BODY_SIZE=50M

Configuration Management Commands

Using Make Commands

# Initialize configuration files
make init-config

# Edit environment configuration
make edit-config ENV=staging

# Validate configuration
make validate-config ENV=production

# Show safe configuration values
make show-config ENV=staging

Using Deploy Script

# Validate configuration during deployment
./deploy.sh staging --dry-run

# Force deployment with incomplete config
./deploy.sh staging --force

Environment Switching

Quick Environment Changes

# Deploy to different environments
make deploy ENV=development
make deploy ENV=staging
make deploy ENV=production

# Environment-specific shortcuts
make deploy-development
make deploy-staging  
make deploy-production

Configuration Validation

# Check configuration before deployment
make validate-config ENV=production

# Test deployment without changes
make deploy-dry ENV=production

Troubleshooting Configuration

Common Issues

1. Missing Template Values

   # Check for unfilled templates
   grep "*** REQUIRED" .env.production
   

2. Permission Issues

   # Fix permissions
   chmod 600 .env.*
   

3. Database Connection

   # Test database connection
   docker-compose exec php php console.php db:ping
   

4. SSL Certificate Issues

   # Check SSL configuration
   make deploy-dry ENV=production
   

Configuration Validation

The deployment system automatically validates:

• Required variables are set
• No template placeholders remain
• Secure passwords in production
• SSL configuration is valid
• Database connection settings

Getting Help

# Show deployment information
make info

# Display all available commands
make help

# Check deployment status
make status ENV=production

Next Steps

• Review the Quick Start Guide for deployment steps
• Check Troubleshooting Guide for common issues
• Test your configuration with dry-run deployments
• Set up monitoring and alerting for production environments