# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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:

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

# Generate application key
openssl rand -base64 32
```

### Environment File Security

```bash
# 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

```bash
# 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

```bash
# 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

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

## Monitoring and Logging

### Monitoring Configuration

```bash
# 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

```bash
# 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

```bash
# 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

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

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

## Environment Switching

### Quick Environment Changes

```bash
# 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

```bash
# 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**
   ```bash
   # Check for unfilled templates
   grep "*** REQUIRED" .env.production
   ```

2. **Permission Issues**
   ```bash
   # Fix permissions
   chmod 600 .env.*
   ```

3. **Database Connection**
   ```bash
   # Test database connection
   docker-compose exec php php console.php db:ping
   ```

4. **SSL Certificate Issues**
   ```bash
   # 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

```bash
# 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](QUICKSTART.md) for deployment steps
- Check [Troubleshooting Guide](TROUBLESHOOTING.md) for common issues
- Test your configuration with dry-run deployments
- Set up monitoring and alerting for production environments