docs(workflow): create comprehensive workflow guide for two-user system
- Document technical user workflow (local dev, git, push, deploy) - Document non-technical user workflow (admin UI only) - Explain why manual sync of admin changes is needed - Provide clear step-by-step sync procedures - Add scenarios and examples for typical situations - Include automated sync options (cron and manual trigger) - Document conflict resolution procedures - Add troubleshooting for common issues - Include best practices for both user types - Add communication protocols and emergency procedures Critical: Admin UI changes are NOT in git - must be manually synced to prevent data loss. This guide explains how and when to sync. 💘 Generated with Crush Assisted-by: GLM-4.7 via Crush <crush@charm.land>
This commit is contained in:
Charles N Wyble
510
WORKFLOW.md
Normal file
510
WORKFLOW.md
Normal file
@@ -0,0 +1,510 @@
|
||||
# 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
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```bash
|
||||
# 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:**
|
||||
|
||||
```bash
|
||||
# 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:**
|
||||
```bash
|
||||
# Check for admin changes and commit (daily at 6 AM)
|
||||
0 6 * * * /var/scripts/sync-admin-changes.sh
|
||||
```
|
||||
|
||||
**Script: sync-admin-changes.sh**
|
||||
```bash
|
||||
#!/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:**
|
||||
```bash
|
||||
# Add to ~/.bashrc
|
||||
alias sync-admin='ssh production-server.com /var/scripts/sync-admin.sh'
|
||||
```
|
||||
|
||||
**Sync script: sync-admin.sh**
|
||||
```bash
|
||||
#!/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:**
|
||||
```bash
|
||||
# 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:**
|
||||
|
||||
```bash
|
||||
# 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**
|
||||
```bash
|
||||
# Clear cache on production
|
||||
ssh production-server.com
|
||||
cd /var/www/grav
|
||||
rm -rf user/cache/*
|
||||
```
|
||||
|
||||
2. **Permissions Issue**
|
||||
```bash
|
||||
# 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**
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```bash
|
||||
# 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:**
|
||||
```bash
|
||||
ssh production-server.com
|
||||
cd /var/www/grav
|
||||
rm -rf user/cache/*
|
||||
```
|
||||
|
||||
2. **If still down:** Restore from git
|
||||
```bash
|
||||
cd /var/www/grav
|
||||
git pull origin main
|
||||
rm -rf user/cache/*
|
||||
```
|
||||
|
||||
3. **If git has issue:** Restore from backup
|
||||
```bash
|
||||
# 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:**
|
||||
```bash
|
||||
ls -lh /var/backups/grav/
|
||||
```
|
||||
|
||||
2. **Restore from backup:**
|
||||
```bash
|
||||
cd /var/www/grav
|
||||
tar -xzf /var/backups/grav/grav_backup_recent.tar.gz
|
||||
```
|
||||
|
||||
3. **Sync to git:**
|
||||
```bash
|
||||
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
|
||||
Reference in New Issue
Block a user