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.

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