From c0ba97df946ed19c7b19932dfc9fa507aa8a7e31 Mon Sep 17 00:00:00 2001 From: Charles N Wyble Date: Tue, 13 Jan 2026 16:46:32 -0500 Subject: [PATCH] docs(deployment): create comprehensive production deployment guide MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Document production server requirements and prerequisites - Explain three deployment options (manual, automated script, Docker) - Provide clear step-by-step instructions for each method - Include testing checklists for both local and production - Add troubleshooting guide for common deployment issues - Document rollback procedures (git revert and backup restore) - Include automation options (webhook, CI/CD) - Add monitoring and health check recommendations - Document backup strategy and retention policy - Include security considerations for production - Provide quick reference for common commands This guide ensures reliable and safe production deployments. 💘 Generated with Crush Assisted-by: GLM-4.7 via Crush --- DEPLOYMENT.md | 406 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 406 insertions(+) create mode 100644 DEPLOYMENT.md diff --git a/DEPLOYMENT.md b/DEPLOYMENT.md new file mode 100644 index 0000000..eaf8407 --- /dev/null +++ b/DEPLOYMENT.md @@ -0,0 +1,406 @@ +# Production Deployment Guide + +This guide covers deploying the Starting Line Productions LLC website to production. + +## Prerequisites + +### Production Server Requirements +- SSH access to production server +- Docker installed (optional - can use direct PHP) +- Git installed +- Web server (nginx, Apache, etc.) +- PHP 8.1+ (if not using Docker) + +### Access +- SSH credentials to production server +- Git repository access (git@knownelement.com:StartingLineProductions.com/STLPWebsite.git) +- Write access to Grav web root + +## Deployment Options + +### Option 1: Manual Git Pull (Recommended) + +Use this option for simple, controlled deployments. + +```bash +# SSH into production server +ssh user@your-production-server.com + +# Navigate to Grav root +cd /var/www/grav + +# Backup current installation (optional but recommended) +tar -czf backup_$(date +%Y%m%d).tar.gz user/ + +# Pull latest changes +git pull origin main + +# Clear cache +rm -rf user/cache/* user/logs/* + +# Set permissions +chown -R www-data:www-data user/ +find user -type d -exec chmod 775 {} \; +find user -type f -exec chmod 664 {} \; + +# Test in browser +``` + +### Option 2: Automated Script + +Use the provided deployment script for automated deployment with backups. + +```bash +# Copy script to production server +scp deploy-production.sh user@your-server.com:/tmp/ + +# SSH into production server +ssh user@your-production-server.com + +# Make script executable +chmod +x /tmp/deploy-production.sh + +# Run deployment +sudo /tmp/deploy-production.sh +``` + +**What the script does:** +1. Creates timestamped backup of current installation +2. Pulls latest changes from git repository +3. Sets correct permissions for Grav +4. Clears cache and logs +5. Updates plugins (if using GPM) + +### Option 3: Docker Deployment + +If production uses Docker for consistency with development: + +```bash +# SSH into production server +ssh user@your-production-server.com + +# Navigate to project directory +cd /var/www/STLPWebsite + +# Pull latest code +git pull origin main + +# Rebuild and restart containers +docker compose down +docker compose pull +docker compose up -d + +# Clear cache +docker exec stlp-grav rm -rf /config/www/user/cache/* +``` + +## Development Workflow + +### Local Development (Current Workflow) + +1. **Make changes locally** + - Edit markdown files in `/config/www/user/pages/` + - Edit configuration in `/config/www/user/config/` + - Test changes in browser at http://localhost:5001 + +2. **Commit changes** + ```bash + git add . + git commit -m "feat(area): add new equipment page" + ``` + +3. **Push to repository** + ```bash + git push origin main + ``` + +4. **Deploy to production** + - SSH into production server + - Run: `git pull origin main` + - Clear cache: `rm -rf user/cache/*` + +### Admin UI Editing (Future Workflow) + +When non-technical users need to edit content: + +1. **Use local admin UI** + - Access: http://localhost:5001/admin + - Login with admin credentials + - Edit content using visual interface + - Changes automatically update markdown files + +2. **Commit admin changes** + ```bash + git add user/pages/ + git commit -m "feat: update homepage content via admin" + git push origin main + ``` + +3. **Deploy to production** + - SSH into production server + - Run: `git pull origin main` + +## Testing Before Deployment + +### Local Testing Checklist + +Before deploying to production, verify: + +- [ ] All pages load without errors +- [ ] Navigation links work correctly +- [ ] Images display properly +- [ ] Forms submit (contact, booking) +- [ ] Mobile responsiveness tested +- [ ] Clear cache: `docker exec stlp-grav rm -rf /config/www/user/cache/*` + +### Production Testing Checklist + +After deployment to production: + +- [ ] Homepage loads +- [ ] Navigation works +- [ ] All pages are accessible +- [ ] No 404 errors +- [ ] No PHP errors in logs +- [ ] Forms can be submitted +- [ ] Site speed is acceptable +- [ ] SSL certificate valid (if HTTPS) + +## Troubleshooting + +### Common Issues + +#### 1. Changes Not Visible + +**Problem:** Deployed but changes not showing +**Solution:** Clear cache +```bash +rm -rf user/cache/* user/logs/* +``` + +#### 2. Permission Errors + +**Problem:** Files not writable +**Solution:** Fix permissions +```bash +chown -R www-data:www-data user/ +find user -type d -exec chmod 775 {} \; +find user -type f -exec chmod 664 {} \; +``` + +#### 3. Git Pull Fails + +**Problem:** Can't pull due to conflicts +**Solution:** Resolve conflicts +```bash +# Stash local changes (if any) +git stash + +# Pull remote changes +git pull origin main + +# Resolve conflicts if needed +vim user/pages/conflict.md + +# Commit resolution +git add . +git commit -m "fix: resolve merge conflicts" +``` + +#### 4. Plugin Errors + +**Problem:** Plugin causes site to break +**Solution:** Disable plugin +```bash +# Disable problematic plugin +rm -rf user/plugins/problem-plugin + +# Reinstall via GPM (if using Docker) +docker exec stlp-grav php bin/gpm install problem-plugin +``` + +## Rollback Procedure + +If deployment causes issues: + +### Quick Rollback (Git) + +```bash +# SSH into production server +cd /var/www/grav + +# View previous commit +git log --oneline -5 + +# Revert to previous commit +git revert HEAD +# OR +git reset --hard HEAD~1 + +# Clear cache +rm -rf user/cache/* user/logs/* +``` + +### Restore from Backup + +```bash +# SSH into production server +cd /var/www/grav + +# Remove broken user directory +rm -rf user/ + +# Restore from backup +tar -xzf /var/backups/grav/grav_backup_YYYYMMDD_HHMMSS.tar.gz + +# Clear cache +rm -rf user/cache/* user/logs/* + +# Set permissions +chown -R www-data:www-data user/ +``` + +## Automation Options + +### Webhook Deployment + +For automatic deployment when pushing to git: + +1. **Set up webhook on Git repository** +2. **Configure webhook URL:** `https://your-server.com/webhook.php` +3. **Create webhook handler script** (simple PHP or bash) +4. **Script runs:** `git pull`, clear cache, set permissions + +### CI/CD Pipeline + +For more complex deployments: + +1. **Use GitLab CI/CD or GitHub Actions** +2. **Pipeline stages:** + - Test: Validate syntax and links + - Build: Compile assets (if needed) + - Deploy: SSH to production, pull changes +3. **Deploy on:** Manual approval or automatic on main branch + +## Monitoring + +### Health Checks + +Implement these health checks for production: + +```bash +# Check site is responding +curl -f https://startinglineproductions.com/ || alert "Site down!" + +# Check for PHP errors +grep -i "error" /var/www/grav/user/logs/grav.log | tail -10 + +# Check disk space +df -h | grep /var/www + +# Check Git status (ensure clean) +cd /var/www/grav +git status +``` + +### Log Monitoring + +Monitor these logs: + +- **Grav log:** `/var/www/grav/user/logs/grav.log` +- **Nginx log:** `/var/log/nginx/access.log` +- **PHP error log:** `/var/log/php/error.log` + +## Backup Strategy + +### Automated Backups + +Set up cron jobs for automated backups: + +```bash +# Daily backup of user directory (2 AM) +0 2 * * * /usr/bin/tar -czf /var/backups/grav/grav_$(date +\%Y\%m\%d).tar.gz /var/www/grav/user/ + +# Weekly backup of entire Grav installation +0 3 * * 0 /usr/bin/tar -czf /var/backups/grav/grav_full_$(date +\%Y\%m\%d).tar.gz /var/www/grav/ +``` + +### Retention Policy + +- Keep daily backups for 7 days +- Keep weekly backups for 4 weeks +- Keep monthly backups for 6 months +- Offsite backup recommended + +## Security Considerations + +### Production Security + +- **SSH Keys:** Use SSH keys instead of passwords +- **Firewall:** Restrict SSH to specific IPs +- **Git Access:** Use deploy keys with restricted permissions +- **File Permissions:** Never make files world-writable +- **Updates:** Keep Grav and plugins updated + +### Environment Variables + +Set these in production: + +```bash +# Grav environment +GRAV_ENV=production +GRAV_DEBUG=0 + +# Database (if using) +DB_HOST=localhost +DB_USER=grav_user +DB_PASS=secure_password +DB_NAME=grav_db +``` + +## Support + +For deployment issues: + +1. Check logs: `/var/www/grav/user/logs/` +2. Review this guide +3. Check AGENTS.md for architecture details +4. Contact technical support + +## Quick Reference + +### Common Commands + +```bash +# Local development +docker compose up -d # Start Grav +docker exec stlp-grav rm -rf user/cache/* # Clear cache +docker logs stlp-grav # View logs + +# Git operations +git add . # Stage changes +git commit -m "message" # Commit changes +git push origin main # Push to remote +git pull origin main # Pull from remote + +# Production deployment +git pull origin main # Pull changes +rm -rf user/cache/* user/logs/* # Clear cache +chown -R www-data:www-data user/ # Set permissions +``` + +### File Locations + +| Type | Location | +|-------|----------| +| Pages | `user/pages/` | +| Config | `user/config/` | +| Cache | `user/cache/` (ignored by git) | +| Logs | `user/logs/` (ignored by git) | +| Themes | `user/themes/` | +| Plugins | `user/plugins/` | + +--- + +**Last Updated:** January 13, 2026 +**Version:** 1.0