478 lines
13 KiB
Markdown
478 lines
13 KiB
Markdown
# 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) →**
|