Skip to main content

wiki auto sync

Wiki Auto-Sync System

Date: 2026-01-24 Status: ✅ Active Purpose: Automatically sync wiki changes every 5 minutes across all devices

Overview

The Wiki Auto-Sync system enables seamless multi-device development by automatically syncing wiki changes every 5 minutes. Edit from ANY device (Mac M3, M4, phone, iPad, code-server) and changes propagate automatically.

Key Features

  • ✅ Auto-sync every 5 minutes - No manual commits needed
  • ✅ Multi-device support - Work from anywhere
  • ✅ Deletion protection - Blocks commits if >30% files deleted
  • ✅ Automatic backups - 24 incremental backups (2 hours retention)
  • ✅ Conflict resolution - Auto-rebase with safety rollback
  • ✅ Comprehensive logging - Track all sync operations

How It Works

┌─────────────────┐
│  Any Device:    │
│  Mac M3/M4      │
│  Phone/iPad     │  1. Edit wiki files
│  code-server    │     on NAS
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  NAS Cron Job   │  2. Every 5 min:
│  (Every 5 min)  │     - Backup
└────────┬────────┘     - Safety checks
         │              - Commit changes
         ▼              - Rebase/push
┌─────────────────┐
│  GitLab Remote  │  3. Synced to
│  (Origin)       │     GitLab
└─────────────────┘

Result: All devices see latest changes within 5 minutes, no manual git commands needed.

Installation

On NAS (blueflynas)

# SSH to NAS
ssh bluefly@blueflynas.tailcf98b3.ts.net

# Run installer
/volume1/AgentPlatform/scripts/install-wiki-sync-cron.sh

This will:

  1. Verify scripts exist
  2. Install cron job (runs every 5 minutes)
  3. Run initial test sync
  4. Show status

Verify Installation

# Check cron job
crontab -l | grep wiki-auto-sync

# View status
/volume1/AgentPlatform/scripts/wiki-sync-status.sh

Usage

From Any Device

  1. Edit wiki files on NAS:

    # From Mac M3/M4
cd /Volumes/AgentPlatform/wikis/blueflyio/technical-docs.wiki
vim some-page.md

# From code-server (browser)
# Edit files in /workspace/wikis/technical-docs.wiki/

# From phone/iPad (via code-server)
# Browse to code-server URL, edit files

  2. Save changes - That's it! No git commands needed.

  3. Wait up to 5 minutes - Auto-sync will:

    • Create backup
    • Check for dangerous deletions
    • Commit your changes
    • Push to GitLab

  4. Changes appear on all devices within 5 minutes

Manual Sync (Optional)

If you want immediate sync:

# SSH to NAS
ssh bluefly@blueflynas

# Run sync manually
/volume1/AgentPlatform/scripts/wiki-auto-sync.sh

Safety Features

Deletion Protection

Problem: Accidentally delete 50% of wiki files, auto-sync commits the deletion.

Solution: Script aborts if >30% of files would be deleted:

# Configuration in wiki-auto-sync.sh
MAX_DELETION_PERCENT=30  # Abort if >30% deleted
MIN_FILES_THRESHOLD=5    # Min files before checking percentage

What Happens:

  1. Script detects 31% of files deleted
  2. 🚨 ABORTS commit operation
  3. Creates emergency backup
  4. Resets working tree to HEAD
  5. Logs error for review

Manual Recovery:

# Review what was deleted
cd /volume1/AgentPlatform/wikis/blueflyio/technical-docs.wiki
git status

# Restore from emergency backup if needed
ls /volume1/AgentPlatform/backups/wikis/technical-docs.wiki/

Automatic Backups

Every sync creates a backup before any operations:

# Backup location
/volume1/AgentPlatform/backups/wikis/[wiki-name]/[timestamp]/

# Example
/volume1/AgentPlatform/backups/wikis/technical-docs.wiki/20260124-032100/

Retention: 24 backups (last 2 hours at 5-min intervals)

Restore from Backup:

# List backups
ls -lt /volume1/AgentPlatform/backups/wikis/technical-docs.wiki/

# Copy from backup
rsync -a /volume1/AgentPlatform/backups/wikis/technical-docs.wiki/20260124-032100/ \
         /volume1/AgentPlatform/wikis/blueflyio/technical-docs.wiki/

Conflict Resolution

Auto-Rebase: If local and remote diverged:

  1. Create safety backup
  2. Attempt git pull --rebase origin main
  3. If successful: Push changes
  4. If failed: Abort rebase, keep local changes, log error

Manual Resolution (if auto-rebase fails):

ssh bluefly@blueflynas
cd /volume1/AgentPlatform/wikis/blueflyio/technical-docs.wiki

# Review conflict
git status

# Resolve manually
# ... edit conflicted files ...
git add .
git rebase --continue
git push origin main

Monitoring

Status Dashboard

# Interactive dashboard
ssh bluefly@blueflynas
/volume1/AgentPlatform/scripts/wiki-sync-status.sh

Shows:

  • ✅ Cron job status
  • 📝 Recent sync activity
  • 📚 Wiki repository status
  • 💾 Backup statistics
  • 📋 Log file locations

View Live Logs

# Today's log
tail -f /volume1/AgentPlatform/logs/wiki-sync/sync-$(date +%Y%m%d).log

# Show errors only
grep ERROR /volume1/AgentPlatform/logs/wiki-sync/sync-$(date +%Y%m%d).log

Check Sync Status

# Quick status check
ssh bluefly@blueflynas '/volume1/AgentPlatform/scripts/wiki-sync-status.sh' | head -30

File Locations

/volume1/AgentPlatform/
├── scripts/
│   ├── wiki-auto-sync.sh              # Main sync script
│   ├── wiki-sync-status.sh            # Status dashboard
│   └── install-wiki-sync-cron.sh      # Installer
├── wikis/blueflyio/                   # Wiki repositories
│   ├── technical-docs.wiki/           # Technical docs
│   └── api_normalization.wiki/        # API normalization
├── backups/wikis/                     # Automatic backups
│   ├── technical-docs.wiki/
│   │   ├── 20260124-032100/           # Timestamp-based backups
│   │   ├── 20260124-032600/
│   │   └── ...                        # (24 backups retained)
│   └── api_normalization.wiki/
└── logs/wiki-sync/                    # Sync logs
    ├── sync-20260124.log              # Today's log
    ├── sync-20260123.log
    └── ...                            # (7 days retained)

Cron Configuration

# Wiki Auto-Sync - Run every 5 minutes
*/5 * * * * /volume1/AgentPlatform/scripts/wiki-auto-sync.sh

Schedule: Every 5 minutes (12 times per hour, 288 times per day)

Edit Cron:

ssh bluefly@blueflynas
crontab -e

Troubleshooting

Cron Job Not Running

# Check if installed
crontab -l | grep wiki-auto-sync

# If not found, install
/volume1/AgentPlatform/scripts/install-wiki-sync-cron.sh

# Check cron service (Synology)
sudo synoservice --status crond

Sync Errors

# View today's errors
grep ERROR /volume1/AgentPlatform/logs/wiki-sync/sync-$(date +%Y%m%d).log

# Common issues:
# 1. Git authentication - check SSH keys
# 2. Merge conflicts - resolve manually
# 3. Network issues - check GitLab connectivity

Deletion Warning

If sync aborts due to deletion protection:

# 1. Review what was deleted
cd /volume1/AgentPlatform/wikis/blueflyio/technical-docs.wiki
git status

# 2. If deletion was intentional, commit manually
git add -A
git commit -m "chore: intentional deletion of obsolete files"
git push origin main

# 3. If deletion was accidental, reset
git reset --hard HEAD

# 4. Restore from backup if needed
rsync -a /volume1/AgentPlatform/backups/wikis/technical-docs.wiki/[latest]/ ./

View Backup

# List all backups for a wiki
ls -lt /volume1/AgentPlatform/backups/wikis/technical-docs.wiki/

# View backup contents
ls -la /volume1/AgentPlatform/backups/wikis/technical-docs.wiki/20260124-032100/

Uninstall

# SSH to NAS
ssh bluefly@blueflynas

# Remove cron job
crontab -e
# Delete the line: */5 * * * * /volume1/AgentPlatform/scripts/wiki-auto-sync.sh

# Or remove all cron jobs
crontab -r

# Optional: Remove backups
# rm -rf /volume1/AgentPlatform/backups/wikis/

# Optional: Remove logs
# rm -rf /volume1/AgentPlatform/logs/wiki-sync/

Multi-Device Workflow Example

Scenario: You're developing across Mac M4 (home), Mac M3 (office), and iPad (travel).

Morning (Mac M4)

# Work on Mac M4
cd /Volumes/AgentPlatform/wikis/blueflyio/technical-docs.wiki
vim infrastructure/new-feature.md
# Save and close

# Auto-sync commits within 5 minutes
# ✅ Changes pushed to GitLab

Afternoon (Office Mac M3)

# Arrive at office, check wiki on Mac M3
cd /Volumes/AgentPlatform/wikis/blueflyio/technical-docs.wiki
git pull  # Or wait for auto-sync

# ✅ See morning's changes automatically
# Continue editing
vim infrastructure/new-feature.md
# Save

# Auto-sync commits within 5 minutes

Evening (iPad via code-server)

# Browse to code-server on iPad
https://code.blueflyagents.com

# Open wiki
/workspace/wikis/technical-docs.wiki/

# ✅ See all changes from Mac M4 and M3
# Edit files in browser
# Changes auto-sync within 5 minutes

Result: Seamless development across all devices, no manual git operations needed.

Configuration

Adjust Sync Frequency

Edit crontab:

ssh bluefly@blueflynas
crontab -e

# Every 5 minutes (default)
*/5 * * * * /volume1/AgentPlatform/scripts/wiki-auto-sync.sh

# Every 10 minutes
*/10 * * * * /volume1/AgentPlatform/scripts/wiki-auto-sync.sh

# Every 1 minute (aggressive)
* * * * * /volume1/AgentPlatform/scripts/wiki-auto-sync.sh

Adjust Safety Thresholds

Edit /volume1/AgentPlatform/scripts/wiki-auto-sync.sh:

# Default values
MAX_DELETION_PERCENT=30  # Abort if >30% files deleted
MIN_FILES_THRESHOLD=5    # Min files before checking percentage

# More conservative (abort at 10% deletion)
MAX_DELETION_PERCENT=10

# Less conservative (abort at 50% deletion)
MAX_DELETION_PERCENT=50

Change Backup Retention

Edit /volume1/AgentPlatform/scripts/wiki-auto-sync.sh:

# Default: Keep 24 backups (2 hours at 5-min intervals)
find "$BACKUP_DIR/$wiki_name" -maxdepth 1 -type d -name "20*" | sort -r | tail -n +25 | xargs -r rm -rf

# Keep 48 backups (4 hours)
... | tail -n +49 | ...

# Keep 12 backups (1 hour)
... | tail -n +13 | ...

Performance

Resource Usage

  • CPU: Minimal (~1% during sync)
  • Memory: ~50MB per sync operation
  • Disk I/O: Moderate (backup creation + git operations)
  • Network: Depends on change size (typically <1MB per sync)

Scalability

Tested with:

  • ✅ 2 wikis (current setup)
  • ✅ Up to 1000 files per wiki
  • ✅ 5-minute sync interval

For more wikis or faster sync, adjust cron frequency or optimize script.

Security

SSH Key Authentication

Sync uses SSH keys for GitLab authentication:

# Verify SSH key on NAS
ssh bluefly@blueflynas
cat ~/.ssh/id_rsa.pub

# Test GitLab connection
ssh -T git@gitlab.com

File Permissions

# Scripts (executable)
-rwx------ wiki-auto-sync.sh
-rwx------ wiki-sync-status.sh
-rwx------ install-wiki-sync-cron.sh

# Logs (read/write)
drwx------ /volume1/AgentPlatform/logs/wiki-sync/

# Backups (read/write)
drwx------ /volume1/AgentPlatform/backups/wikis/

Benefits

For Development

  • ✅ No manual git commands - Focus on writing, not committing
  • ✅ Work from anywhere - Any device with NAS access
  • ✅ Automatic backups - Never lose work
  • ✅ Conflict-free - Auto-rebase handles divergence

For Collaboration

  • ✅ Always synced - Team sees changes within 5 minutes
  • ✅ Audit trail - All changes logged
  • ✅ Safety checks - Prevents accidental data loss

For DevOps

  • ✅ Automated - Set and forget
  • ✅ Monitored - Status dashboard + logs
  • ✅ Recoverable - Backups + git history

Comparison: Manual vs Auto-Sync

AspectManual GitAuto-Sync
Commit frequencyWhen you rememberEvery 5 min
Device switchingPull/push manuallyAutomatic
Conflict resolutionManualAuto-rebase
BackupManualAutomatic (24x)
Deletion protectionNoneBuilt-in
Multi-deviceComplexSeamless
Mental overheadHighNone

Future Enhancements

Potential improvements:

  • Web dashboard (view status from browser)
  • Slack/Discord notifications on errors
  • Webhook support (trigger on push)
  • Selective sync (exclude certain files)
  • Remote backup (S3, Backblaze)
  • Metrics collection (Prometheus/Grafana)

Contact

Last Updated: 2026-01-24 Status: ✅ Active and Stable Next Review: 2026-02-24