04-environment-application.mdc

---
description: 
globs: 
alwaysApply: false
---
# Environment & Application Configuration Standards

**Description**: Environment setup, application configuration, and deployment management standards for containerized applications. Apply when setting up environments, managing configurations, implementing secret management, or organizing project documentation.

**Key Focus Areas**: Development environments, configuration management, secret handling, environment separation, documentation structure

## Development Environment Standards

### Containerized Development Setup
- **Container-First Development**: All development should happen in containerized environments
- **Environment Parity**: Development, staging, and production environments should be as similar as possible
- **Reproducible Builds**: Ensure consistent builds across different developer machines
- **Dependency Isolation**: Use containers to isolate application dependencies
- **Version Consistency**: Lock dependency versions to ensure consistency

### Development Tools
- **Hot Reloading**: Enable live code reloading in development containers
- **Debug Ports**: Expose debugging ports only in development environment
- **Development Dependencies**: Separate development dependencies from production
- **Testing Framework**: Include testing frameworks and tools in development setup

## Configuration Management

### Configuration Hierarchy
1. **Default Values**: Hardcoded defaults in application code
2. **Configuration Files**: Environment-specific config files
3. **Environment Variables**: Runtime configuration via environment variables
4. **Secrets**: Sensitive data through secret management systems
5. **Command Line Arguments**: Override configuration at runtime

### Environment Variable Standards
- **Naming Convention**: Use consistent, descriptive environment variable names
- **Service URLs**: Use internal service names for inter-service communication
- **Feature Flags**: Support feature toggles through environment variables
- **Logging Configuration**: Configure logging levels and formats via environment
- **Monitoring Endpoints**: Define health check and metrics endpoints

### Configuration File Patterns
```yaml
# config/default.yml
app:
  name: myapp
  port: 3000
  host: 0.0.0.0

database:
  host: localhost
  port: 5432
  name: myapp

logging:
  level: info
  format: json

---
# config/production.yml
app:
  host: 0.0.0.0

database:
  host: ${DB_HOST}
  port: ${DB_PORT}
  name: ${DB_NAME}

logging:
  level: warn
```

### External Configuration
- **Configuration Management**: Use external configuration management systems for complex deployments
- **Environment Separation**: Maintain separate configurations for each environment
- **Configuration Validation**: Validate configuration at application startup
- **Hot Reloading**: Support configuration hot reloading where appropriate

## Secret Management

### Secret Handling Principles
- **Never Commit Secrets**: Never store secrets in version control
- **Least Privilege**: Grant minimal necessary access to secrets
- **Rotation**: Implement secret rotation policies
- **Encryption**: Encrypt secrets at rest and in transit
- **Audit Trail**: Maintain audit logs for secret access

### Docker Secrets Integration
- **Docker Secrets**: Use Docker secrets for production deployments
- **File-Based Secrets**: Reference secrets via file paths in containers
- **External Secret Management**: Integrate with enterprise secret management systems

### Environment-Specific Secrets
- **Development**: Use dummy secrets or local secret files
- **Staging**: Use staging-specific secrets with limited scope
- **Production**: Use enterprise secret management (HashiCorp Vault, AWS Secrets Manager, etc.)

### Secret File Patterns
```bash
# .env.example (template file)
DB_PASSWORD=your_secure_password_here
API_KEY=your_api_key_here
JWT_SECRET=your_jwt_secret_here

# .env.local (gitignored actual values)
DB_PASSWORD=actual_secure_password
API_KEY=actual_api_key
JWT_SECRET=actual_jwt_secret
```

## Environment Separation

### Environment Types
- **Development**: Local development with debug features enabled
- **Testing**: Automated testing environment with test data
- **Staging**: Production-like environment for final testing
- **Production**: Live environment serving real users

### Environment-Specific Configurations
```yaml
# Base docker-compose.yml
version: '3.8'
services:
  app:
    image: myapp:${APP_VERSION:-latest}
    environment:
      - APP_ENV=${APP_ENV:-production}

---
# docker-compose.dev.yml
version: '3.8'
services:
  app:
    build: .
    volumes:
      - .:/app:cached
    environment:
      - APP_ENV=development
      - DEBUG=true

---
# docker-compose.prod.yml
version: '3.8'
services:
  app:
    image: myapp:${APP_VERSION}
    deploy:
      replicas: 3
      resources:
        limits:
          memory: 512M
    environment:
      - APP_ENV=production
```

### Environment Validation
- **Configuration Checks**: Validate environment configuration at startup
- **Health Checks**: Implement comprehensive health checks for each environment
- **Smoke Tests**: Run smoke tests after deployment to each environment
- **Monitoring**: Implement environment-specific monitoring and alerting

## Documentation Structure

### Required Documentation Categories

#### `/docs/architecture/` - System Design
- **system-overview.md**: High-level system architecture
- **service-architecture.md**: Service communication and dependencies
- **docker-architecture.md**: Container and orchestration setup
- **database-design.md**: Data models and relationships
- **security-architecture.md**: Security patterns and implementations

#### `/docs/development/` - Developer Resources
- **getting-started.md**: Setup instructions for new developers
- **development-workflow.md**: Local development processes
- **coding-standards.md**: Code quality and style guidelines
- **testing-guide.md**: Testing strategies and frameworks
- **debugging-guide.md**: Common issues and solutions

#### `/docs/deployment/` - Operations
- **deployment-guide.md**: Step-by-step deployment procedures
- **environment-setup.md**: Environment configuration instructions
- **docker-setup.md**: Container orchestration setup
- **monitoring-setup.md**: Observability and monitoring configuration
- **disaster-recovery.md**: Backup and recovery procedures

#### `/docs/user-guides/` - End User Documentation
- **user-manual.md**: Complete user guide
- **api-documentation.md**: API reference and examples
- **troubleshooting.md**: Common user issues and solutions
- **feature-guides/**: Detailed feature documentation

#### `/docs/reference/` - Technical Reference
- **api-reference.md**: Complete API documentation
- **configuration-reference.md**: All configuration options
- **changelog.md**: Version history and changes
- **glossary.md**: Technical terms and definitions

### Documentation Standards
- **Keep Current**: Update documentation with every code change
- **Practical Examples**: Include working code examples and configurations
- **Environment-Specific**: Document differences between environments
- **Visual Aids**: Use diagrams and screenshots where helpful
- **Searchable**: Structure documentation for easy searching

### Documentation Automation
```yaml
# Example GitHub Actions for documentation
name: Documentation
on:
  push:
    paths: ['docs/**', '*.md']
jobs:
  deploy-docs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Deploy to GitHub Pages
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./docs
```

## Application Lifecycle Management

### Startup Procedures
- **Configuration Loading**: Load and validate configuration at startup
- **Health Checks**: Implement readiness and liveness probes
- **Dependency Checking**: Verify external service availability
- **Database Migrations**: Run database migrations automatically
- **Cache Warming**: Pre-populate caches if necessary

### Runtime Configuration
- **Feature Flags**: Implement feature flag systems for runtime control
- **Configuration Refresh**: Support configuration updates without restart
- **Graceful Degradation**: Handle external service failures gracefully
- **Circuit Breakers**: Implement circuit breaker patterns

### Shutdown Procedures
- **Graceful Shutdown**: Handle shutdown signals properly
- **Connection Cleanup**: Close database and external connections
- **Request Completion**: Allow in-flight requests to complete
- **Resource Cleanup**: Clean up temporary files and resources

This comprehensive approach ensures robust, scalable, and maintainable configuration management for containerized applications across all environments.