# Production Deployment Documentation

Complete documentation for deploying the Custom PHP Framework to production.

---

## Quick Navigation

**New to deployment? Start here:**
1. [Quick Start Guide](QUICKSTART.md) - Get running in 30 minutes
2. [Deployment Checklist](DEPLOYMENT_CHECKLIST.md) - Printable checklist

**Need detailed information?**
- [Complete Deployment Workflow](DEPLOYMENT_WORKFLOW.md) - Step-by-step deployment process
- [Production Deployment Guide](PRODUCTION_DEPLOYMENT.md) - Comprehensive infrastructure guide
- [Production Logging](production-logging.md) - Logging configuration and best practices

**Want automation?**
- [Ansible Deployment](ANSIBLE_DEPLOYMENT.md) - Infrastructure as Code with Ansible

**Need secure access?**
- [WireGuard VPN Setup](WIREGUARD-SETUP.md) - Secure VPN access to production services

---

## Documentation Structure

### 1. [QUICKSTART.md](QUICKSTART.md)
**Best for**: First-time deployment, getting started quickly

**Content**:
- 10-step deployment process (~30 minutes)
- Minimal configuration required
- Immediate verification steps
- Basic troubleshooting

**Use when**: You want to get the application running in production as fast as possible.

---

### 2. [DEPLOYMENT_CHECKLIST.md](DEPLOYMENT_CHECKLIST.md)
**Best for**: Ensuring nothing is missed, compliance verification

**Content**:
- Pre-deployment checklist
- Step-by-step deployment verification
- Post-deployment security hardening
- Maintenance schedules (weekly, monthly, quarterly)
- Emergency contacts template
- Deployment sign-off form

**Use when**: You want a printable, check-off-items-as-you-go guide.

---

### 3. [DEPLOYMENT_WORKFLOW.md](DEPLOYMENT_WORKFLOW.md)
**Best for**: Understanding the complete deployment lifecycle

**Content**:
- Phase 1: Initial Server Setup (one-time)
- Phase 2: Initial Deployment
- Phase 3: Ongoing Deployment (updates)
- Phase 4: Monitoring Setup
- Two deployment options: Manual/Script-Based and Ansible-Based
- Automated deployment scripts
- Zero-downtime deployment
- Rollback procedures

**Use when**: You need detailed explanations of each deployment phase or want to understand deployment options.

---

### 4. [PRODUCTION_DEPLOYMENT.md](PRODUCTION_DEPLOYMENT.md)
**Best for**: Comprehensive infrastructure reference

**Content**:
- Complete infrastructure setup
- SSL/TLS configuration with Let's Encrypt
- Secrets management with Vault
- Environment configuration
- Docker deployment
- Database migrations
- Monitoring and health checks (all endpoints documented)
- Logging configuration
- Security considerations
- Troubleshooting guide
- Maintenance procedures

**Use when**: You need deep technical details about any production infrastructure component.

---

### 5. [production-logging.md](production-logging.md)
**Best for**: Production logging configuration and optimization

**Content**:
- ProductionLogConfig options (production, highPerformance, withAggregation, debug, staging)
- Environment-based configuration
- Log rotation and retention policies
- Structured JSON log format
- Metrics and monitoring integration
- Performance tuning (buffer sizes, sampling rates, aggregation)
- Troubleshooting guides
- Best practices

**Use when**: You need to configure or troubleshoot production logging.

---

### 6. [ANSIBLE_DEPLOYMENT.md](ANSIBLE_DEPLOYMENT.md)
**Best for**: Automated, multi-server deployments

**Content**:
- Complete Ansible project structure
- Ansible roles (common, docker, ssl, application)
- Playbooks (site.yml, deploy.yml, rollback.yml, provision.yml)
- Ansible Vault for secrets
- CI/CD integration (GitHub Actions)
- Comparison: Script-Based vs Ansible
- Hybrid approach recommendation

**Use when**: You're scaling to multiple servers or want infrastructure as code.

---

### 7. [WIREGUARD-SETUP.md](WIREGUARD-SETUP.md)
**Best for**: Secure VPN access to production services

**Content**:
- Complete WireGuard VPN setup guide
- Server installation via Ansible
- Client configuration and management
- Connection testing and troubleshooting
- Security best practices
- Monitoring and maintenance

**Use when**: You need secure access to internal services (Prometheus, Grafana, Portainer) or want to restrict access via VPN.

---

## Which Guide Should I Use?

### Scenario 1: First-Time Deployment
**Path**: QUICKSTART.md → DEPLOYMENT_CHECKLIST.md

1. Follow [QUICKSTART.md](QUICKSTART.md) for initial deployment
2. Use [DEPLOYMENT_CHECKLIST.md](DEPLOYMENT_CHECKLIST.md) to verify everything
3. Keep [PRODUCTION_DEPLOYMENT.md](PRODUCTION_DEPLOYMENT.md) handy for troubleshooting

**Time Required**: ~1 hour

---

### Scenario 2: Enterprise Deployment
**Path**: PRODUCTION_DEPLOYMENT.md → ANSIBLE_DEPLOYMENT.md → DEPLOYMENT_CHECKLIST.md

1. Review [PRODUCTION_DEPLOYMENT.md](PRODUCTION_DEPLOYMENT.md) for infrastructure understanding
2. Implement with [ANSIBLE_DEPLOYMENT.md](ANSIBLE_DEPLOYMENT.md) for automation
3. Verify with [DEPLOYMENT_CHECKLIST.md](DEPLOYMENT_CHECKLIST.md)

**Time Required**: ~4 hours (initial setup), ~30 minutes (ongoing deployments)

---

### Scenario 3: Single Server, Team Collaboration
**Path**: DEPLOYMENT_WORKFLOW.md → DEPLOYMENT_CHECKLIST.md

1. Follow [DEPLOYMENT_WORKFLOW.md](DEPLOYMENT_WORKFLOW.md) for comprehensive process
2. Use automated scripts (deploy-production.sh)
3. Verify with [DEPLOYMENT_CHECKLIST.md](DEPLOYMENT_CHECKLIST.md)

**Time Required**: ~2 hours

---

### Scenario 4: Logging Issues
**Path**: production-logging.md

1. Consult [production-logging.md](production-logging.md) for logging configuration
2. Check troubleshooting section
3. Adjust ProductionLogConfig based on needs

**Time Required**: ~30 minutes

---

### Scenario 5: Adding Monitoring
**Path**: PRODUCTION_DEPLOYMENT.md (Monitoring section)

1. Jump to Monitoring section in [PRODUCTION_DEPLOYMENT.md](PRODUCTION_DEPLOYMENT.md)
2. Follow Prometheus/Grafana setup
3. Configure alerts

**Time Required**: ~1 hour

---

## Deployment Methods Comparison

| Feature | Quick Start | Script-Based | Ansible |
|---------|-------------|--------------|---------|
| **Setup Time** | 30 min | 2 hours | 4 hours |
| **Ongoing Deployment** | 15 min | 10 min | 5 min |
| **Multi-Server** | Manual | Manual | Automated |
| **Rollback** | Manual | Script | Automated |
| **Team Collaboration** | Docs | Scripts + Docs | Playbooks |
| **Infrastructure as Code** | No | Partial | Yes |
| **Idempotency** | No | Partial | Yes |
| **Best For** | Single server, quick start | Single server, repeatable | Multiple servers, scaling |

---

## Prerequisites Summary

All deployment methods require:

### Server Requirements
- Ubuntu 22.04+ (or Debian 11+)
- 4GB RAM minimum (8GB recommended)
- 40GB disk space minimum
- Root or sudo access

### Network Requirements
- Domain name configured
- DNS pointing to server IP
- Ports 22, 80, 443 accessible
- Static IP address recommended

### Tools Required
- SSH client
- Git
- Text editor (nano, vim, or VS Code with Remote SSH)

### Knowledge Requirements
- Basic Linux command line
- SSH and file permissions
- Docker basics
- DNS and domain configuration
- (Optional) Ansible for automation

---

## Common Tasks

### Initial Deployment
```bash
# Follow Quick Start Guide
cat docs/deployment/QUICKSTART.md

# Verify with checklist
cat docs/deployment/DEPLOYMENT_CHECKLIST.md
```

### Deploy Update
```bash
# Manual method
cd /home/appuser/app
git pull origin main
docker compose -f docker-compose.production.yml build
docker compose -f docker-compose.production.yml up -d
php console.php db:migrate

# Automated script method
./scripts/deployment/deploy-production.sh

# Zero-downtime method
./scripts/deployment/blue-green-deploy.sh
```

### Rollback
```bash
# Manual rollback (see DEPLOYMENT_WORKFLOW.md)
docker compose -f docker-compose.old.yml up -d
php console.php db:rollback 1

# Automated rollback
./scripts/deployment/blue-green-rollback.sh
```

### Health Check
```bash
# Quick health check
curl -f https://yourdomain.com/health/summary

# Detailed health check
curl -f https://yourdomain.com/health/detailed | jq

# Specific category
curl -f https://yourdomain.com/health/category/database
```

### View Logs
```bash
# Application logs
docker compose -f docker-compose.production.yml logs -f php

# System logs
tail -f /var/log/app/app.log

# Nginx logs
tail -f /var/log/nginx/error.log
```

### Database Backup
```bash
# Manual backup
docker compose exec database mysqldump -u app_user -p app_production > backup.sql

# Automated backup (configured in QUICKSTART.md)
/home/appuser/backup-production.sh
```

### SSL Certificate Renewal
```bash
# Test renewal
certbot renew --dry-run

# Force renewal
certbot renew --force-renewal

# Automatic renewal is configured via cron/systemd timer
```

---

## Troubleshooting Quick Reference

### Issue: Containers won't start
**Solution**: Check logs
```bash
docker compose -f docker-compose.production.yml logs php
```

**Common causes**: Database credentials, port conflicts, permissions

**Full guide**: [PRODUCTION_DEPLOYMENT.md - Troubleshooting](PRODUCTION_DEPLOYMENT.md#troubleshooting)

---

### Issue: Health checks failing
**Solution**: Check specific health check
```bash
curl http://localhost/health/category/database
```

**Common causes**: Database not migrated, cache not writable, queue not running

**Full guide**: [DEPLOYMENT_WORKFLOW.md - Troubleshooting](DEPLOYMENT_WORKFLOW.md#troubleshooting)

---

### Issue: SSL certificate problems
**Solution**: Verify certificate
```bash
openssl x509 -in /etc/letsencrypt/live/yourdomain.com/fullchain.pem -noout -dates
```

**Common causes**: DNS not propagated, port 80 blocked, wrong domain

**Full guide**: [PRODUCTION_DEPLOYMENT.md - SSL/TLS](PRODUCTION_DEPLOYMENT.md#ssltls-configuration)

---

### Issue: Application errors
**Solution**: Check application logs
```bash
docker compose -f docker-compose.production.yml logs -f php
tail -f /var/log/app/app.log
```

**Common causes**: Environment configuration, missing migrations, permission issues

**Full guide**: [production-logging.md - Troubleshooting](production-logging.md#troubleshooting)

---

## Security Considerations

All deployment methods include security best practices:

- ✅ HTTPS enforced (SSL/TLS)
- ✅ Firewall configured (UFW)
- ✅ SSH key-only authentication
- ✅ Fail2Ban for intrusion prevention
- ✅ Security headers (CSP, HSTS, X-Frame-Options)
- ✅ CSRF protection
- ✅ Rate limiting
- ✅ WAF (Web Application Firewall)
- ✅ Vault for secrets management
- ✅ Regular security updates

**Detailed security guide**: [PRODUCTION_DEPLOYMENT.md - Security](PRODUCTION_DEPLOYMENT.md#security-considerations)

---

## Monitoring and Health Checks

### Available Endpoints

```
GET /health/summary        - Quick health summary
GET /health/detailed       - Full health report with all checks
GET /health/checks         - List registered health checks
GET /health/category/{cat} - Health checks by category

GET /metrics               - Prometheus metrics
GET /metrics/json          - JSON metrics
```

### Health Check Categories
- `DATABASE` - Database connectivity and performance
- `CACHE` - Cache system health (Redis/File)
- `SECURITY` - SSL certificates, rate limiting, CSRF
- `INFRASTRUCTURE` - Disk space, memory, queue status
- `EXTERNAL` - External service connectivity

**Full monitoring guide**: [PRODUCTION_DEPLOYMENT.md - Monitoring](PRODUCTION_DEPLOYMENT.md#monitoring-and-health-checks)

---

## Support and Resources

### Internal Documentation
- [Framework Guidelines](../claude/guidelines.md)
- [Security Patterns](../claude/security-patterns.md)
- [Database Patterns](../claude/database-patterns.md)
- [Error Handling](../claude/error-handling.md)

### External Resources
- [Docker Documentation](https://docs.docker.com/)
- [Let's Encrypt Documentation](https://letsencrypt.org/docs/)
- [Nginx Documentation](https://nginx.org/en/docs/)
- [Ansible Documentation](https://docs.ansible.com/) (for automation)

### Getting Help

1. **Check documentation** (this directory)
2. **Review application logs** (`docker compose logs`)
3. **Check health endpoints** (`/health/detailed`)
4. **Review metrics** (`/metrics`)
5. **Consult troubleshooting guides** (in each document)

---

## Contribution

This documentation should be updated after each deployment to reflect:
- Lessons learned
- Process improvements
- Common issues encountered
- New best practices discovered

**Deployment feedback template**: See [DEPLOYMENT_CHECKLIST.md - Continuous Improvement](DEPLOYMENT_CHECKLIST.md#continuous-improvement)

---

## Version History

| Version | Date | Changes | Author |
|---------|------|---------|--------|
| 1.0 | 2025-01-15 | Initial comprehensive deployment documentation | System |
| | | Complete with Quick Start, Workflow, Ansible, Checklists | |

---

**Quick Links**:
- [Quick Start](QUICKSTART.md) - Fastest path to production
- [Checklist](DEPLOYMENT_CHECKLIST.md) - Ensure nothing is missed
- [Complete Workflow](DEPLOYMENT_WORKFLOW.md) - Detailed deployment process
- [Production Guide](PRODUCTION_DEPLOYMENT.md) - Comprehensive reference
- [Logging Guide](production-logging.md) - Production logging configuration
- [Ansible Guide](ANSIBLE_DEPLOYMENT.md) - Infrastructure automation
- [WireGuard VPN](WIREGUARD-SETUP.md) - Secure VPN access to production

---

**Ready to deploy? Start with [QUICKSTART.md](QUICKSTART.md) →**