michael/michaelschiemer
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore: Update deployment configuration and documentation

Browse Source 
- Update Gitea configuration (remove DEFAULT_ACTIONS_URL)
- Fix deployment documentation
- Update Ansible playbooks
- Clean up deprecated files
- Add new deployment scripts and templates
This commit is contained in:
Michael Schiemer
2025-10-31 21:11:11 +01:00
parent cf4748f8db
commit 16d586ecdf
92 changed files with 4601 additions and 10524 deletions
Download Patch File Download Diff File Expand all files Collapse all files

495
docs/deployment/README.md
View File

@@ -1,477 +1,66 @@
# Production Deployment Documentation
# Deployment Documentation
Complete documentation for deploying the Custom PHP Framework to production.
**Hinweis:** Die Haupt-Deployment-Dokumentation befindet sich jetzt im `deployment/` Ordner.
---
## Quick Navigation
## 📖 Haupt-Dokumentation
**New to deployment? Start here:**
1. [Quick Start Guide](QUICKSTART.md) - Get running in 30 minutes
2. [Deployment Checklist](DEPLOYMENT_CHECKLIST.md) - Printable checklist
**Für aktuelle Deployment-Informationen siehe:**
**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
- **[deployment/README.md](../../deployment/README.md)** - Haupt-Deployment-Dokumentation
- **[deployment/QUICK_START.md](../../deployment/QUICK_START.md)** - Schnellstart-Guide
- **[deployment/DEPLOYMENT_COMMANDS.md](../../deployment/DEPLOYMENT_COMMANDS.md)** - Command-Referenz
- **[deployment/CODE_CHANGE_WORKFLOW.md](../../deployment/CODE_CHANGE_WORKFLOW.md)** - Code-Deployment-Workflow
---
## Documentation Structure
## 📚 Spezifische Themen-Dokumentation
### 1. [QUICKSTART.md](QUICKSTART.md)
**Best for**: First-time deployment, getting started quickly
Die folgenden Dokumente behandeln spezifische Deployment-Themen:
**Content**:
- 10-step deployment process (~30 minutes)
- Minimal configuration required
- Immediate verification steps
- Basic troubleshooting
### VPN & Security
- **[WIREGUARD-SETUP.md](WIREGUARD-SETUP.md)** - WireGuard VPN Setup (komplett)
- **[WIREGUARD-FUTURE-SECURITY.md](WIREGUARD-FUTURE-SECURITY.md)** - Zukünftige Security-Überlegungen
- **[PRODUCTION-SECURITY-UPDATES.md](PRODUCTION-SECURITY-UPDATES.md)** - Security-Updates
**Use when**: You want to get the application running in production as fast as possible.
### Configuration & Setup
- **[database-migration-strategy.md](database-migration-strategy.md)** - Database Migration Strategy
- **[logging-configuration.md](logging-configuration.md)** - Logging Configuration
- **[production-logging.md](production-logging.md)** - Production Logging Best Practices
- **[secrets-management.md](secrets-management.md)** - Secrets Management mit Vault
- **[ssl-setup.md](ssl-setup.md)** - SSL/TLS Setup mit Let's Encrypt
- **[SSL-PRODUCTION-SETUP.md](SSL-PRODUCTION-SETUP.md)** - Production SSL Setup
- **[env-production-template.md](env-production-template.md)** - Environment Template
- **[production-prerequisites.md](production-prerequisites.md)** - Production Prerequisites
### Automation (Veraltet - siehe deployment/ansible)
- **[ANSIBLE_DEPLOYMENT.md](ANSIBLE_DEPLOYMENT.md)** - ⚠️ Veraltet, siehe `deployment/ansible/README.md`
- **[deployment-automation.md](deployment-automation.md)** - ⚠️ Veraltet, siehe `deployment/ansible/`
---
### 2. [DEPLOYMENT_CHECKLIST.md](DEPLOYMENT_CHECKLIST.md)
**Best for**: Ensuring nothing is missed, compliance verification
## 🚀 Schnellstart
**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
**Für aktuelle Deployment-Informationen:**
**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
# Haupt-Dokumentation
cat deployment/README.md
# Verify with checklist
cat docs/deployment/DEPLOYMENT_CHECKLIST.md
# Schnellstart
cat deployment/QUICK_START.md
# Commands
cat deployment/DEPLOYMENT_COMMANDS.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
```
**Für spezifische Themen:**
- VPN Setup: `docs/deployment/WIREGUARD-SETUP.md`
- Database Migrations: `docs/deployment/database-migration-strategy.md`
- Logging: `docs/deployment/production-logging.md`
- SSL Setup: `docs/deployment/ssl-setup.md`
---
## 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) →**
**Haupt-Deployment-Dokumentation:** Siehe [deployment/](../../deployment/) Ordner