michaelschiemer/deployment/README.md

# Custom PHP Framework Deployment System

Complete deployment automation system for the Custom PHP Framework with infrastructure provisioning and application deployment.

## Project Information
- **Domain**: michaelschiemer.de
- **Email**: kontakt@michaelschiemer.de
- **PHP Version**: 8.4
- **Framework**: Custom PHP Framework

## 🚀 Quick Start

```bash
# First-time setup
./setup.sh

# Deploy to staging
make deploy-staging

# Deploy to production
make deploy-production
```

## Architecture

The deployment system uses a hybrid approach combining:
- **Ansible** for infrastructure provisioning (security, Docker, Nginx, SSL)
- **Docker Compose** for application deployment (PHP 8.4, database, assets)
- **Automation Scripts** for orchestrated deployment workflows

## Directory Structure

```
deployment/
├── deploy.sh                   # Main deployment orchestrator
├── setup.sh                    # First-time environment setup
├── Makefile                    # Convenient deployment commands
├── docs/                       # Documentation
│   ├── QUICKSTART.md          # Quick start guide
│   ├── ENVIRONMENTS.md        # Environment configuration
│   └── TROUBLESHOOTING.md     # Troubleshooting guide
├── infrastructure/             # Ansible infrastructure provisioning
│   ├── inventories/           # Environment-specific inventories
│   │   ├── development/       # Development inventory
│   │   ├── staging/           # Staging inventory
│   │   └── production/        # Production inventory
│   ├── roles/                 # Reusable Ansible roles
│   │   ├── base-security/     # Security hardening
│   │   ├── docker-runtime/    # Docker and PHP 8.4 setup
│   │   ├── nginx-proxy/       # Nginx reverse proxy with SSL
│   │   └── monitoring/        # System monitoring
│   ├── playbooks/             # Infrastructure playbooks
│   ├── group_vars/            # Environment variables
│   └── site.yml               # Main infrastructure playbook
└── applications/              # Docker Compose application deployment
    ├── docker-compose.*.yml   # Environment overlays
    ├── environments/          # Environment configurations
    │   ├── .env.production.template  # Production settings template
    │   └── .env.staging.template     # Staging settings template
    └── scripts/               # Application deployment scripts
        ├── deploy-app.sh      # Main application deployment script
        └── health-check.sh    # Post-deployment health validation
```

## Features

### 🔒 Security First
- Automated security hardening with fail2ban and UFW firewall
- SSL certificates with Let's Encrypt integration
- IP-based authentication for admin routes
- OWASP security event logging
- Secure password generation and management

### ⚡ Performance Optimized
- PHP 8.4 with OPcache and performance tuning
- Nginx reverse proxy with optimization
- Database connection pooling and query optimization
- Asset optimization with Vite build system
- Health checks and monitoring

### 🛠️ Developer Friendly
- One-command deployment with `make deploy-staging`
- Dry-run mode for testing deployments
- Comprehensive logging and error handling
- Database backups and rollback capabilities
- Multi-environment support

### 🌍 Production Ready
- Zero-downtime deployments
- Automated database migrations
- Health checks and validation
- Emergency stop/restart procedures
- Monitoring and alerting setup

## Available Commands

### Main Deployment Commands

```bash
make deploy-staging           # Deploy to staging
make deploy-production        # Deploy to production
make deploy-dry ENV=production # Dry run deployment
make infrastructure ENV=staging # Deploy only infrastructure
make application ENV=staging  # Deploy only application
```

### Management Commands

```bash
make status ENV=staging       # Check deployment status
make health ENV=production    # Run health checks
make logs ENV=staging         # View application logs
make backup ENV=production    # Create database backup
make restore ENV=production   # Restore from backup
```

### Configuration Commands

```bash
make init-config             # Initialize configuration files
make edit-config ENV=staging # Edit environment configuration
make validate-config ENV=prod # Validate configuration
make show-config ENV=staging # Show safe configuration values
```

### Emergency Commands

```bash
make emergency-stop ENV=staging    # Emergency stop all services
make emergency-restart ENV=prod    # Emergency restart services
make rollback ENV=production       # Emergency rollback
```

## Environment Configuration

The system supports three environments:

- **Development**: Local development with relaxed security
- **Staging**: Pre-production testing with production-like settings
- **Production**: Live production with maximum security and performance

Each environment has its own:
- Docker Compose overlay configuration
- Environment variables file
- Ansible inventory
- SSL certificate configuration

## Deployment Flow

1. **Validation**: Prerequisites, configuration, and test validation
2. **Infrastructure**: Ansible deploys security, Docker, Nginx, SSL
3. **Application**: Docker Compose deploys PHP app, database, assets
4. **Health Checks**: Comprehensive deployment validation

## Safety Features

- **Production Confirmations**: Double confirmation for production deployments
- **Automated Backups**: Database backups before deployment
- **Dry Run Mode**: Test deployments without making changes
- **Health Validation**: Verify deployment success before completion
- **Rollback Capability**: Emergency rollback procedures
- **Error Handling**: Comprehensive error handling and logging

## Getting Started

1. **First-Time Setup**:
   ```bash
   ./setup.sh
   ```

2. **Configure Environments**:
   ```bash
   make init-config
   make edit-config ENV=staging
   ```

3. **Test Deployment**:
   ```bash
   make deploy-dry ENV=staging
   ```

4. **Deploy to Staging**:
   ```bash
   make deploy-staging
   ```

5. **Deploy to Production**:
   ```bash
   make deploy-production
   ```

## Documentation

- [**Quick Start Guide**](docs/QUICKSTART.md) - Get up and running quickly
- [**Environment Configuration**](docs/ENVIRONMENTS.md) - Detailed environment setup
- [**Troubleshooting Guide**](docs/TROUBLESHOOTING.md) - Common issues and solutions

## Migration from Old System

The old deployment configurations have been preserved in `.deployment-backup/` for reference. The new system provides:

- **Improved Security**: Modern security practices and automated hardening
- **Better Organization**: Clear separation between infrastructure and application
- **Enhanced Automation**: One-command deployments with comprehensive validation
- **Multi-Environment**: Proper staging and production environment management
- **Modern Stack**: PHP 8.4, latest Docker practices, and optimized configurations

## Support

For deployment issues or questions:
1. Check the [Troubleshooting Guide](docs/TROUBLESHOOTING.md)
2. Run diagnostics: `make status ENV=your-environment`
3. Review logs: `make logs ENV=your-environment`
4. Test with dry-run: `make deploy-dry ENV=your-environment`

---

**Domain**: michaelschiemer.de | **Email**: kontakt@michaelschiemer.de | **PHP**: 8.4