docs(deployment): create comprehensive production deployment guide
- 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 <crush@charm.land>
This commit is contained in:
Charles N Wyble
406
DEPLOYMENT.md
Normal file
406
DEPLOYMENT.md
Normal file
@@ -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
|
||||
Reference in New Issue
Block a user