michael/michaelschiemer

Fork 0

Files

Michael Schiemer 6deca7838e chore: remove test trigger file

2025-10-31 04:14:18 +01:00

13 KiB

Raw Blame History

Production Deployment Documentation

Complete documentation for deploying the Custom PHP Framework to production.

New to deployment? Start here:

Quick Start Guide - Get running in 30 minutes
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

Need secure access?

WireGuard VPN Setup - Secure VPN access to production services

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.

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

Follow QUICKSTART.md for initial deployment
Use DEPLOYMENT_CHECKLIST.md to verify everything
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

Review PRODUCTION_DEPLOYMENT.md for infrastructure understanding
Implement with ANSIBLE_DEPLOYMENT.md for automation
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

Follow DEPLOYMENT_WORKFLOW.md for comprehensive process
Use automated scripts (deploy-production.sh)
Verify with DEPLOYMENT_CHECKLIST.md

Time Required: ~2 hours

Scenario 4: Logging Issues

Path: production-logging.md

Consult production-logging.md for logging configuration
Check troubleshooting section
Adjust ProductionLogConfig based on needs

Time Required: ~30 minutes

Scenario 5: Adding Monitoring

Path: PRODUCTION_DEPLOYMENT.md (Monitoring section)

Jump to Monitoring section in PRODUCTION_DEPLOYMENT.md
Follow Prometheus/Grafana setup
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

External Resources

Getting Help

Check documentation (this directory)
Review application logs (docker compose logs)
Check health endpoints (/health/detailed)
Review metrics (/metrics)
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
WireGuard VPN - Secure VPN access to production

Ready to deploy? Start with QUICKSTART.md →

13 KiB Raw Blame History

Production Deployment Documentation

Quick Navigation

Documentation Structure

1. QUICKSTART.md

2. DEPLOYMENT_CHECKLIST.md

3. DEPLOYMENT_WORKFLOW.md

4. PRODUCTION_DEPLOYMENT.md

5. production-logging.md

6. ANSIBLE_DEPLOYMENT.md

7. WIREGUARD-SETUP.md

Which Guide Should I Use?

Scenario 1: First-Time Deployment

Scenario 2: Enterprise Deployment

Scenario 3: Single Server, Team Collaboration

Scenario 4: Logging Issues

Scenario 5: Adding Monitoring

Deployment Methods Comparison

Prerequisites Summary

Server Requirements

Network Requirements

Tools Required

Knowledge Requirements

Common Tasks

Initial Deployment

Deploy Update

Rollback

Health Check

View Logs

Database Backup

SSL Certificate Renewal

Troubleshooting Quick Reference

Issue: Containers won't start

Issue: Health checks failing

Issue: SSL certificate problems

Issue: Application errors

Security Considerations

Monitoring and Health Checks

Available Endpoints

Health Check Categories

Support and Resources

Internal Documentation

External Resources

Getting Help

Contribution

Version History

13 KiB

Raw Blame History