michaelschiemer/docs/deployment

Production Deployment Documentation

Complete documentation for deploying the Custom PHP Framework to production.

---

Quick Navigation

New to deployment? Start here:

1. Quick Start Guide - Get running in 30 minutes
2. Deployment Checklist - Printable checklist

Need detailed information?

• Complete Deployment Workflow - Step-by-step deployment process
• Production Deployment Guide - Comprehensive infrastructure guide
• Production Logging - Logging configuration and best practices

Want automation?

• Ansible Deployment - Infrastructure as Code with Ansible

---

Documentation Structure

1. 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

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

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

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

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

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.

---

Which Guide Should I Use?

Scenario 1: First-Time Deployment

Path: QUICKSTART.md → DEPLOYMENT_CHECKLIST.md

1. Follow QUICKSTART.md for initial deployment
2. Use DEPLOYMENT_CHECKLIST.md to verify everything
3. Keep 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 for infrastructure understanding
2. Implement with ANSIBLE_DEPLOYMENT.md for automation
3. Verify with 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 for comprehensive process
2. Use automated scripts (deploy-production.sh)
3. Verify with DEPLOYMENT_CHECKLIST.md

Time Required: ~2 hours

---

Scenario 4: Logging Issues

Path: production-logging.md

1. Consult 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
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

# Follow Quick Start Guide
cat docs/deployment/QUICKSTART.md

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

Deploy Update

# 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

# 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

# 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

# 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

# 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

# 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

docker compose -f docker-compose.production.yml logs php

Common causes: Database credentials, port conflicts, permissions

Full guide: PRODUCTION_DEPLOYMENT.md - Troubleshooting

---

Issue: Health checks failing

Solution: Check specific health check

curl http://localhost/health/category/database

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

Full guide: DEPLOYMENT_WORKFLOW.md - Troubleshooting

---

Issue: SSL certificate problems

Solution: Verify certificate

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

---

Issue: Application errors

Solution: Check application logs

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

---

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

---

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

---

Support and Resources

Internal Documentation

• Framework Guidelines
• Security Patterns
• Database Patterns
• Error Handling

External Resources

• Docker Documentation
• Let's Encrypt Documentation
• Nginx Documentation
• Ansible Documentation (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

---

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 - Fastest path to production
• Checklist - Ensure nothing is missed
• Complete Workflow - Detailed deployment process
• Production Guide - Comprehensive reference
• Logging Guide - Production logging configuration
• Ansible Guide - Infrastructure automation

---

Ready to deploy? Start with QUICKSTART.md →