STLPWebsite/DEPLOYMENT.md

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.

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

# 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:

# 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

   git add .
   git commit -m "feat(area): add new equipment page"
   

3. Push to repository

   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

   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

rm -rf user/cache/* user/logs/*

2. Permission Errors

Problem: Files not writable Solution: Fix permissions

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

# 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

# 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)

# 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

# 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:

# 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:

# 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:

# 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

# 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