From 90bde214969c66a96e6c3b26a8bee3005defa445 Mon Sep 17 00:00:00 2001 From: Charles N Wyble Date: Tue, 13 Jan 2026 16:46:44 -0500 Subject: [PATCH] docs(git-sync): create comprehensive git-sync plugin guide MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Document Grav Git Sync plugin for automatic two-way synchronization - Include installation instructions via GPM and Git - Provide complete configuration examples (basic, dev, production) - Explain SSH key setup for production server - Detail automatic mode workflow (production) and manual mode (development) - Document conflict resolution (automatic and manual) - Add best practices for configuration and communication - Include troubleshooting guide for common issues - Add monitoring and email notification configuration - Provide advanced configuration (multiple branches, selective sync) - Compare Git Sync vs manual sync approaches Critical: Git Sync plugin automates sync process, eliminating need for manual sync procedures. Admin UI changes are automatically committed and pushed to git repository. 💘 Generated with Crush Assisted-by: GLM-4.7 via Crush --- GIT-SYNC.md | 619 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 619 insertions(+) create mode 100644 GIT-SYNC.md diff --git a/GIT-SYNC.md b/GIT-SYNC.md new file mode 100644 index 0000000..f81c0d5 --- /dev/null +++ b/GIT-SYNC.md @@ -0,0 +1,619 @@ +# Git Sync Plugin Configuration + +This document explains how to configure and use the Grav Git Sync plugin for automatic two-way synchronization. + +## Overview + +The Git Sync plugin automatically syncs changes between: +- **Grav Admin UI** (non-technical user edits) +- **Git Repository** (source control and backup) +- **Multiple environments** (development, staging, production) + +## Installation + +### via GPM (Grav Plugin Manager) + +```bash +# SSH into production server +ssh user@production-server.com +cd /var/www/grav + +# Install plugin via GPM +php bin/gpm install git-sync + +# Enable plugin +php bin/plugin:enable git-sync +``` + +### via Git (Manual) + +```bash +# SSH into production server +cd /var/www/grav/user/plugins + +# Clone plugin +git clone https://github.com/trilbymedia/grav-plugin-git-sync git-sync + +# Enable plugin +cd /var/www/grav +php bin/plugin:enable git-sync +``` + +## Configuration + +### Basic Configuration + +Edit: `/var/www/grav/user/plugins/git-sync/git-sync.yaml` + +```yaml +enabled: true + +# Git Repository Configuration +repository: 'git@knownelement.com:StartingLineProductions.com/STLPWebsite.git' + +# Git Branch +branch: main + +# Sync Configuration +sync: + mode: 'auto' # auto, manual + remote: 'origin' + commit_message: 'Update from Grav Admin UI' + author_name: 'Grav Admin' + author_email: 'admin@startinglineproductions.com' + +# Auto-commit Configuration +auto_commit: + enabled: true + delay: 30 # Seconds after edit before committing + +# Auto-pull Configuration +auto_pull: + enabled: true + interval: 300 # Check for remote changes every 5 minutes + +# Auto-push Configuration +auto_push: + enabled: true + delay: 60 # Seconds after commit before pushing + +# File Patterns +files: + include: + - 'user/pages/**/*' + - 'user/config/**/*' + exclude: + - 'user/cache/**/*' + - 'user/logs/**/*' + - 'user/tmp/**/*' + - 'user/backup/**/*' + +# Notification +notification: + enabled: true + email: + to: 'charles@startinglineproductions.com' + subject: 'Git Sync Notification' +``` + +### Environment-Specific Configuration + +#### Development (Local Docker) + +Edit: `config/www/user/plugins/git-sync/git-sync.yaml` + +```yaml +enabled: true +repository: '/home/charles/Projects/STLPWebsite' +branch: main +sync: + mode: 'manual' # Don't auto-sync in development +auto_commit: + enabled: false +auto_pull: + enabled: false +auto_push: + enabled: false +``` + +#### Production + +Edit: `/var/www/grav/user/plugins/git-sync/git-sync.yaml` + +```yaml +enabled: true +repository: 'git@knownelement.com:StartingLineProductions.com/STLPWebsite.git' +branch: 'main' +sync: + mode: 'auto' # Auto-sync all changes +auto_commit: + enabled: true + delay: 30 +auto_pull: + enabled: true + interval: 300 +auto_push: + enabled: true + delay: 60 +``` + +## SSH Key Configuration + +For Git Sync to work, the web server (www-data user) needs SSH access to the Git repository. + +### Setup SSH Key for Production + +```bash +# SSH into production server as root +ssh root@production-server.com + +# Switch to web server user +su - www-data + +# Generate SSH key +ssh-keygen -t ed25519 -C "www-data@production-server.com" -N "" -f ~/.ssh/grav_sync + +# Display public key +cat ~/.ssh/grav_sync.pub + +# Copy this public key to your Git repository deploy keys +# Example for GitLab: https://gitlab.com/namespace/project/-/settings/repository +# Example for GitHub: https://github.com/user/repo/settings/keys +# Example for Gitea: https://git.knownelement.com/StartingLineProductions.com/STLPWebsite/settings/keys +``` + +### Test SSH Connection + +```bash +# As www-data user +su - www-data + +# Test SSH connection to git repository +ssh -i ~/.ssh/grav_sync -T git@git.knownelement.com + +# You should see: Welcome to Gitea! +# Or similar repository server greeting +``` + +### Add SSH Key to Git Repository + +Add the public key as a **Deploy Key** to the repository: +- **Title:** `grav-sync-production` +- **Key:** Paste contents of `~/.ssh/grav_sync.pub` +- **Permissions:** Read/Write (needed for both pull and push) + +## Usage + +### Automatic Mode (Production) + +When configured with `mode: 'auto'`, the plugin will: + +1. **Watch for changes** in Admin UI +2. **Auto-commit** after 30 seconds of no edits +3. **Auto-push** to git repository after 60 seconds +4. **Auto-pull** every 5 minutes to check for remote changes + +**Workflow:** +``` +1. Non-technical user edits via Admin UI +2. Plugin detects change +3. Plugin waits 30 seconds (auto_commit.delay) +4. Plugin commits change with message: "Update from Grav Admin UI" +5. Plugin waits 60 seconds (auto_push.delay) +6. Plugin pushes to git repository +7. Changes are now in git (safe and backed up) + +... Meanwhile ... + +8. Technical user commits locally +9. Technical user pushes to git repository +10. Plugin detects new remote commit (every 5 minutes) +11. Plugin pulls changes automatically +12. Changes are visible in Admin UI +``` + +### Manual Mode (Development) + +When configured with `mode: 'manual'`, changes must be triggered manually via Admin UI. + +**Manual Sync Options:** + +1. **Admin UI Button:** + - Go to: `/admin/plugins/git-sync` + - Click "Sync Now" button + - Pull from remote + - Push to remote + +2. **Git CLI (for technical users):** + ```bash + cd /home/charles/Projects/STLPWebsite + git add . + git commit -m "feat: new equipment page" + git push origin main + ``` + +## Conflict Resolution + +### Automatic Merging + +If there are no conflicting changes, Git Sync will automatically merge: + +``` +Remote: Added new CNC Mill page +Local: Added new pricing table to same page + +Git Sync: + 1. Pulls remote changes + 2. Merges automatically (no conflicts) + 3. Commits merge + 4. Pushes to repository +``` + +### Manual Conflict Resolution + +If both users edit same section of same file, Git Sync will: + +1. **Detect conflict** +2. **Notify user** via email and Admin UI notification +3. **Pause auto-sync** until conflict is resolved +4. **Show conflict** in Admin UI + +**Resolving Conflicts:** + +**Option 1: Via Admin UI** +``` +1. Go to: /admin/plugins/git-sync +2. See conflict notification +3. Click on conflicted file +4. Review both versions (<<<<<< HEAD and >>>>>>> origin/main) +5. Choose which changes to keep +6. Remove conflict markers +7. Click "Resolve Conflict" +8. Git Sync commits resolution and pushes +``` + +**Option 2: Via SSH** +```bash +# SSH into production server +ssh user@production-server.com +cd /var/www/grav + +# Check git status (will show conflicts) +git status + +# View conflicts +git diff --name-only --diff-filter=U + +# Edit conflicted file +vim user/pages/conflict.md + +# Look for conflict markers: +# <<<<<<< HEAD +# Admin UI version +# ======= +# Git version +# >>>>>>> origin/main + +# Manually resolve conflict (keep what you want) +# Remove conflict markers + +# Add resolved file +git add user/pages/conflict.md + +# Commit resolution +git commit -m "fix: resolve merge conflict in conflict.md +- Resolved by [your name] +- Kept both [specific changes]" + +# Push resolution +git push origin main + +# Notify Git Sync conflict is resolved +# (Auto-sync will resume) +``` + +## Best Practices + +### Configuration + +1. **Different settings for dev and production:** + - Development: Manual mode, no auto-sync + - Production: Auto mode, continuous sync + +2. **Reasonable delays:** + - auto_commit.delay: 30-60 seconds + - auto_push.delay: 60-120 seconds + - auto_pull.interval: 300-600 seconds (5-10 minutes) + +3. **Exclude temp files:** + - Always exclude: cache/, logs/, tmp/, backup/ + - Use files.include for what to sync + - Use files.exclude for what to NOT sync + +### Communication + +1. **Notify before major changes:** + - Technical user: "I'm updating X structure, don't edit related files" + - Non-technical user: "I'm updating X content, please don't touch this file" + +2. **Check conflicts regularly:** + - Visit `/admin/plugins/git-sync` daily + - Check for conflict notifications + - Resolve conflicts promptly + +3. **Review sync history:** + - Check git log periodically + - Ensure commits are meaningful + - Monitor for unexpected changes + +### Security + +1. **SSH Key Security:** + - Use deploy key (read/write only for this repo) + - Don't use personal SSH key + - Key has no passphrase (required for automation) + - Key owned by www-data user (web server user) + +2. **File Permissions:** + - Ensure www-data user has write access to .git directory + - Ensure www-data user can execute git commands + - Proper SSH key permissions (600 for private, 644 for public) + +3. **Repository Access:** + - Repository should be private + - Deploy key should have limited access + - Monitor deploy key usage + +## Troubleshooting + +### Issue 1: Auto-sync Not Working + +**Symptoms:** Changes made via Admin UI not committed to git + +**Diagnosis:** +```bash +# Check plugin is enabled +ssh user@production-server.com +cd /var/www/grav +php bin/plugin:list | grep git-sync + +# Check plugin configuration +cat user/plugins/git-sync/git-sync.yaml + +# Check git log (should show recent commits) +git log --oneline -5 +``` + +**Solutions:** + +1. **Plugin not enabled:** + ```bash + php bin/plugin:enable git-sync + ``` + +2. **Wrong repository URL:** + - Check `repository:` in git-sync.yaml + - Ensure SSH key can access repository + +3. **SSH key not working:** + ```bash + # Test SSH connection + su - www-data + ssh -i ~/.ssh/grav_sync -T git@your-git-server.com + ``` + +4. **File permissions:** + ```bash + # Fix permissions + chown -R www-data:www-data /var/www/grav/.git + chmod 700 /var/www/grav/.git + ``` + +### Issue 2: Changes Not Pushing to Remote + +**Symptoms:** Commits made locally but not visible in remote repository + +**Diagnosis:** +```bash +# Check git status +git status + +# Check remote branches +git branch -r + +# Check recent commits (remote) +git log origin/main --oneline -3 +``` + +**Solutions:** + +1. **Network issues:** + - Check network connectivity + - Check firewall rules + - Verify Git server is accessible + +2. **Authentication issues:** + - Verify SSH key is added to repository + - Test SSH connection + - Check deploy key permissions + +3. **Remote not configured:** + ```bash + git remote -v + # Should show: origin git@server:repo.git (fetch/push) + ``` + +### Issue 3: Merge Conflicts + +**Symptoms:** Admin UI shows conflict notification, auto-sync paused + +**Solutions:** + +1. **Resolve via Admin UI:** + - Navigate to `/admin/plugins/git-sync` + - Click on conflicted file + - Edit and resolve conflict + - Click "Resolve Conflict" + +2. **Resolve via SSH:** + - SSH into server + - Resolve conflict in file + - `git add` and `git commit` + - `git push` + - Notify Git Sync + +3. **Prevent conflicts:** + - Communicate with other users + - Edit different files when possible + - Use git status before editing + +### Issue 4: Files Not Being Committed + +**Symptoms:** Some files edited in Admin UI not being committed + +**Diagnosis:** +```bash +# Check file patterns +cat user/plugins/git-sync/git-sync.yaml | grep -A 10 "files:" +``` + +**Solutions:** + +1. **File not in include pattern:** + - Add file to `files.include` + - Or use wildcard: `user/pages/**/*` + +2. **File excluded:** + - Remove from `files.exclude` + - Or modify exclude pattern + +3. **File ignored by git:** + - Check `.gitignore` + - Remove file from `.gitignore` if needed + +## Monitoring + +### Check Sync Status + +**Via Admin UI:** +- Navigate to: `/admin/plugins/git-sync` +- View: Last sync time, last commit, last push/pull +- View: Any errors or conflicts + +**Via SSH:** +```bash +# Check git status +cd /var/www/grav +git status + +# Check recent commits +git log --oneline -10 + +# Check remote sync status +git log origin/main --oneline -3 + +# Check if auto-sync is running +ps aux | grep grav-sync +``` + +### Email Notifications + +Configure notifications for important events: + +```yaml +notification: + enabled: true + email: + to: 'admin@startinglineproductions.com' + subject: 'Git Sync Notification' + on_commit: true + on_push: true + on_pull: true + on_conflict: true + on_error: true +``` + +## Advanced Configuration + +### Multiple Branches + +Use different branches for different purposes: + +```yaml +# Production +branch: 'production' + +# Staging +branch: 'staging' + +# Development +branch: 'dev' +``` + +### Custom Commit Messages + +Templates for different types of changes: + +```yaml +sync: + commit_message: 'Update from Grav Admin UI' + +# Or use dynamic message: + commit_message_template: 'Update {file} from Admin UI by {user}' +``` + +### Selective Sync + +Only sync specific files or directories: + +```yaml +files: + include: + - 'user/pages/05.areas/**/*' # Only sync area pages + - 'user/config/site.yaml' # Only sync site config + exclude: + - 'user/pages/04.equipment/**/*' # Don't sync equipment pages +``` + +## Comparison: Git Sync vs Manual Sync + +| Feature | Git Sync Plugin | Manual Sync | +|---------|----------------|-------------| +| Automatic commits | ✅ Yes | ❌ No | +| Automatic push | ✅ Yes | ❌ No | +| Automatic pull | ✅ Yes | ❌ No | +| Conflict detection | ✅ Yes | ⚠️ Manual | +| Email notifications | ✅ Yes | ❌ No | +| Setup complexity | ⚠️ Medium | ✅ Simple | +| User intervention | ⚠️ Sometimes | ✅ Always | +| Reliable sync | ✅ High | ⚠️ Depends on user | + +## Summary + +**Key Points:** +- Git Sync plugin automates two-way synchronization +- Eliminates need for manual sync processes +- Automatically commits Admin UI changes +- Automatically pushes to git repository +- Automatically pulls remote changes +- Handles conflicts gracefully +- Requires SSH key configuration +- Different configs for dev and production + +**Configuration Files:** +- Production: `/var/www/grav/user/plugins/git-sync/git-sync.yaml` +- Development: `config/www/user/plugins/git-sync/git-sync.yaml` + +**Workflow with Git Sync:** +1. Non-technical user edits via Admin UI +2. Git Sync automatically commits and pushes +3. Technical user edits locally and pushes +4. Git Sync automatically pulls changes +5. Both users see each other's changes automatically + +--- + +**For more details:** +- Plugin Repository: https://github.com/trilbymedia/grav-plugin-git-sync +- Official Documentation: https://github.com/trilbymedia/grav-plugin-git-sync/blob/master/README.md +- Workflow Guide: See WORKFLOW.md