STLPWebsite/WORKFLOW.md

Production Workflow Guide

This guide explains the actual workflow for Starting Line Productions LLC website with both technical and non-technical users.

User Types

Technical Users / AI Agents

• Access: Local development environment (Docker port 5001)
• Method: Direct markdown file editing via git
• Tools: Text editor, git, Docker
• Example: You (Charles), AI agents working on documentation

Non-Technical Users

• Access: Production server only (via Admin UI)
• Method: Visual content editing through Grav Admin interface
• Tools: Web browser
• Example: Staff, business owner making content updates

Workflow Diagram

┌─────────────────────────────────────────────────────────────┐
│                    Git Repository                        │
│            (git@knownelement.com/STLPWebsite.git)       │
└────────────────────┬────────────────────────────────────────┘
                     │
        ┌────────────┴────────────┐
        │                         │
        ▼                         ▼
┌──────────────────┐   ┌─────────────────────────┐
│   Local Dev     │   │     Production        │
│  (Docker 5001) │   │   (Production URL)   │
└──────────────────┘   └──────────┬──────────────────┘
                            │
                    ┌───────┴───────┐
                    │               │
                    ▼               ▼
            ┌───────────┐   ┌───────────┐
            │  Website  │   │  Admin UI │
            │  Pages    │   │   Browser  │
            └───────────┘   └───────────┘

Workflows

Technical User Workflow (AI Agents, Charles)

Use this when: Adding new equipment pages, area documentation, structural changes

# 1. Work locally
cd /home/charles/Projects/STLPWebsite
docker compose up -d

# 2. Make changes
# Edit markdown files: config/www/user/pages/
# Test in browser: http://localhost:5001

# 3. Commit changes
git add .
git commit -m "feat(equipment): add CNC Lathe page"

# 4. Push to git repository
git push origin main

# 5. Deploy to production
# (SSH into production server)
ssh user@production-server.com
cd /var/www/grav
git pull origin main
rm -rf user/cache/*

Flow: Local Dev → Git Commit → Git Push → Production Pull

Non-Technical User Workflow (Staff, Business Owner)

Use this when: Updating existing content, changing text, minor edits

# 1. Access production admin UI
https://startinglineproductions.com/admin

# 2. Login with admin credentials
username: admin
password: [your-password]

# 3. Navigate to Pages
# Find the page you want to edit

# 4. Make changes using visual editor
# Edit content directly in browser
# Click "Save"

# 5. Changes are immediately visible on production

Flow: Admin UI → Production Filesystem → Visible on Site

Syncing Admin Changes to Git (Manual Process)

Use this when: Non-technical users have made changes via Admin UI and those changes need to be preserved in git

Why this is needed:

• Admin UI saves changes directly to production filesystem
• These changes are NOT in git repository
• If production server is lost or restored from git, admin changes will be LOST
• Technical user must periodically pull these changes and commit to git

When to run:

• After significant content updates via Admin UI
• Before major deployments or server migrations
• Weekly (recommended) as a backup procedure
• After non-technical users report making important changes

Steps:

# 1. SSH into production server
ssh user@production-server.com

# 2. Check what has changed
cd /var/www/grav
git status

# 3. Add all changed files (from admin edits)
git add user/pages/
git add user/config/  # If admin changed config

# 4. Review changes before committing
git diff --staged

# 5. Commit changes
git commit -m "feat: update content via Admin UI
- Updated [specific pages]
- Changed [specific sections]
- Modified by [staff member] via Admin"

# 6. Push to git repository
git push origin main

Example Scenario:

Day 1-5: Staff makes various content updates via Admin UI
  - Updates pricing on Resources page
  - Adds new project to Contact page
  - Changes phone number on Contact page
  - Edits equipment descriptions

Day 6: Charles (technical user) syncs to git
  - SSH into production
  - Runs git status (shows 4 changed files)
  - Reviews changes
  - Commits: "feat: weekly content updates via Admin UI"
  - Pushes to git repository

Result: All admin changes are now safely in git

Automated Sync (Optional Enhancement)

If you want to automate the sync process, you can:

Option 1: Cron Job (Simple)

Run a script periodically to check for changes and commit them.

Production Server Crontab:

# Check for admin changes and commit (daily at 6 AM)
0 6 * * * /var/scripts/sync-admin-changes.sh

Script: sync-admin-changes.sh

#!/bin/bash
cd /var/www/grav

# Check if there are uncommitted changes
if [ -n "$(git status --porcelain)" ]; then
    # Add all changes
    git add -A

    # Create automatic commit
    git commit -m "chore: auto-commit admin UI changes
Date: $(date)
Changes detected in user/pages or user/config"

    # Push to git
    git push origin main

    echo "Admin changes synced to git"
else
    echo "No changes detected"
fi

Pros: Automatic, no manual intervention Cons: Commits everything without review, could commit mistakes

Option 2: Manual Trigger (Recommended)

Run sync only when you know changes were made.

Add to bash aliases:

# Add to ~/.bashrc
alias sync-admin='ssh production-server.com /var/scripts/sync-admin.sh'

Sync script: sync-admin.sh

#!/bin/bash
cd /var/www/grav

echo "Checking for Admin UI changes..."
git status

read -p "Do you want to commit and push these changes? (y/n): " answer

if [ "$answer" == "y" ]; then
    git add -A
    echo "Enter commit message (Ctrl+C to cancel):"
    read message
    git commit -m "$message"
    git push origin main
    echo "Changes synced to git"
else
    echo "Sync cancelled"
fi

Usage:

# After staff makes changes, run:
sync-admin

# Review changes, enter commit message, confirm

Pros: Human review before committing, safe Cons: Requires manual trigger

Troubleshooting Sync Issues

Issue 1: Git Conflicts

Problem: Both technical user (local git) and non-technical user (admin UI) edited the same file.

Scenario:

1. Charles adds new content to CNC Mill page locally
2. Commits and pushes to git
3. Staff edits same CNC Mill page via Admin UI
4. Charles tries to pull from production to sync changes
5. Git reports conflict

Solution:

# On production server
cd /var/www/grav

# Pull local changes (this will show conflict)
git pull origin main

# Open conflicted file
vim user/pages/04.equipment/01.cnc/01.cnc-mill/default.md

# Look for conflict markers:
# <<<<<<< HEAD
# Admin UI version
# =======
# Git version
# >>>>>>> origin/main

# Manually resolve conflict (keep what you want)
# Remove conflict markers

# Save and exit

# Add resolved file
git add user/pages/04.equipment/01.cnc/01.cnc-mill/default.md

# Commit resolution
git commit -m "fix: resolve merge conflict in CNC Mill page
- Merged admin UI changes with git changes
- Kept both [specific content]"

# Push resolution
git push origin main

Prevention:

• Communicate with staff before making major changes
• Check git status on production before editing (if you're technical user)
• Use different files when possible

Issue 2: Admin Changes Not Persisting

Problem: Staff makes changes via Admin UI but they disappear.

Possible Causes:

1. Cache Issue

# Clear cache on production
ssh production-server.com
cd /var/www/grav
rm -rf user/cache/*

2. Permissions Issue

# Fix permissions
chown -R www-data:www-data user/
find user -type d -exec chmod 775 {} \;
find user -type f -exec chmod 664 {} \;

3. Plugin Conflict

# Check logs
tail -50 user/logs/grav.log

# Disable conflicting plugin (temporarily)
mv user/plugins/problematic-plugin user/plugins/problematic-plugin.disabled

Issue 3: Git History Lost

Problem: Admin UI changes are not being synced, git repository is outdated.

Consequence: If production server crashes, all admin UI changes are lost.

Solution:

• Sync admin changes to git regularly (at least weekly)
• Implement automated sync if frequent admin edits
• Monitor git status on production

Best Practices

For Technical Users (You, AI Agents)

1. Always test locally before pushing to production
2. Check production git status before pulling (to see if admin made changes)
3. Communicate with staff when making structural changes
4. Sync regularly to capture admin UI changes
5. Document any manual interventions

For Non-Technical Users (Staff)

1. Use Admin UI for content updates only (not structural changes)
2. Report any issues or errors immediately
3. Notify technical user when making significant content updates
4. Understand that Admin UI changes are not automatically backed up to git

For Business Owner

1. Technical User: Handles all major updates, new pages, structural changes
2. Staff Updates: Content updates via Admin UI are synced periodically to git
3. Weekly Backup: Technical user syncs admin changes to git weekly
4. Monthly Review: Review what changes have been made via Admin UI

Quick Reference

Technical User Commands

# Local development
docker compose up -d
docker exec stlp-grav rm -rf user/cache/*

# Git workflow
git add .
git commit -m "message"
git push origin main

# Sync admin changes from production
ssh production-server.com
cd /var/www/grav
git status                    # Check what changed
git add user/pages/           # Add admin changes
git commit -m "feat: sync admin changes"
git push origin main

# Deploy to production
ssh production-server.com
cd /var/www/grav
git pull origin main
rm -rf user/cache/*

Non-Technical User Actions

1. Open browser
2. Go to: https://startinglineproductions.com/admin
3. Login
4. Navigate to Pages
5. Edit content
6. Click Save
7. Changes are live

Sync Frequency Recommendations

Activity	Frequency	Who
Minor content updates (price changes, text edits)	Weekly	Technical user syncs
Major content updates (new equipment, area changes)	Immediately after	Technical user syncs
Emergency content updates	Immediately after	Technical user syncs
Regular sync (backup)	Weekly (e.g., Monday 9 AM)	Automated or manual

Communication Protocol

Before Making Changes

Technical User:

• Check: Are any staff actively using Admin UI?
• Notify: "I'm updating X page, avoid editing it for 30 minutes"

Non-Technical User:

• Check: Is technical user making updates today?
• Notify: "I'm updating X page via Admin UI"

After Making Changes

Technical User:

• Notify: "I've updated X page, please review"
• Sync: Pull from production if staff made changes

Non-Technical User:

• Notify: "I've updated X page via Admin UI, please sync to git"
• Technical user performs sync

Emergency Procedures

Production Site Down

If production site crashes:

1. Quick Check:

   ssh production-server.com
   cd /var/www/grav
   rm -rf user/cache/*
   

2. If still down: Restore from git

   cd /var/www/grav
   git pull origin main
   rm -rf user/cache/*
   

3. If git has issue: Restore from backup

   # Find most recent backup
   ls -lh /var/backups/grav/
   
   # Restore
   tar -xzf /var/backups/grav/grav_backup_YYYYMMDD.tar.gz
   

Lost Admin UI Changes

If admin changes were not synced and server lost:

1. Check backups:

   ls -lh /var/backups/grav/
   

2. Restore from backup:

   cd /var/www/grav
   tar -xzf /var/backups/grav/grav_backup_recent.tar.gz
   

3. Sync to git:

   git add -A
   git commit -m "restore: restore from backup after server failure"
   git push origin main
   

Summary

Key Points:

• Technical users work in local dev (Docker), push to git, deploy to production
• Non-technical users work in production Admin UI only
• Admin UI changes are NOT in git - must be manually synced
• Sync admin changes to git regularly (at least weekly)
• Use communication to avoid conflicts
• Implement automated sync if frequent admin edits

Critical Rule:

Admin UI changes MUST be synced to git to prevent data loss This is a manual process unless automated

---

For more details:

• See AGENTS.md for technical guidelines
• See DEPLOYMENT.md for production deployment
• See README.md for general project information