╔══════════════════════════════════════════════════════════════════╗
║       KiteStacks Homelab — Auto-Sync Setup Guide                ║
╚══════════════════════════════════════════════════════════════════╝

WHAT THIS DOES
──────────────
Watches your Docker app directories for any file changes.
On each change it automatically:

  1. Copies the changed file into the correct repo folder
       ~/docker/homepage/  →  apps/homepage/
       ~/docker/<app>/     →  apps/<app>/
       /etc/kitestacks/    →  clusters/assassin/

  2. Bumps the version in README.md
       <!-- version: 1.3.7 -->

  3. Creates a new versioned doc file
       docs/KiteStacks-Homelab-Documentation-v1.3.3.md

  4. Appends an entry to CHANGELOG.md

  5. Commits with your existing style:
       "Automated update: 2026-06-06 03:36:00"

  6. Pushes to Forgejo at gitforge.kitestacks.com

It pushes to a TEST repo first so you can verify before
flipping to kenpat/kitestacks-homelab.


FILES
─────
  setup.sh              ← Run first (as root)
  promote.sh            ← Run to switch test → main repo
  status.sh             ← Health check
  config/
    settings.conf.example
    settings.conf       ← Your config (fill this in first)
  scripts/
    kitestacks-watcher.sh ← The daemon (started by systemd)


STEP-BY-STEP
════════════

1. GET A FORGEJO TOKEN
   gitforge.kitestacks.com → User Settings → Applications
   → Generate New Token → name it "autosync"
   → Scopes: ✓ repository (read + write)
   Copy it — you only see it once.

2. CONFIGURE
   cp config/settings.conf.example config/settings.conf
   nano config/settings.conf

   Required changes:
     FORGEJO_TOKEN="your-token-here"
     WATCH_DIRS="/home/kenpat/docker /etc/kitestacks"
                 ↑ adjust to match where your app files live

3. RUN SETUP
   sudo bash setup.sh

   This will:
   • Install git, inotify-tools, curl, jq
   • Create kitestacks-homelab-autosync-test on Forgejo
   • Clone it to /opt/kitestacks-autosync/
   • Bootstrap README.md and docs/ at v1.3.0
   • Install and start the systemd service

4. VERIFY
   bash status.sh
   journalctl -u kitestacks-autosync -f

   Trigger a test change:
     touch /home/kenpat/docker/homepage/test-autosync.txt

   Check gitforge.kitestacks.com/kenpat/kitestacks-homelab-autosync-test
   You should see:
     • A new commit: "Automated update: 2026-06-06 ..."
     • apps/homepage/test-autosync.txt  added
     • README.md version bumped: 1.3.0 → 1.3.1
     • docs/KiteStacks-Homelab-Documentation-v1.3.1.md  created
     • CHANGELOG.md entry added

   Clean up the test file:
     rm /home/kenpat/docker/homepage/test-autosync.txt

5. PROMOTE TO MAIN REPO
   sudo bash promote.sh

   Type "promote" to confirm. From this point on, all changes
   go to kenpat/kitestacks-homelab.


HOW THE README.md VERSIONING WORKS
════════════════════════════════════
The script tracks versions using an HTML comment tag that is
invisible when the README renders:

  # KiteStacks Homelab

  <!-- version: 1.3.7 -->

  Private GitOps repository for the KiteStacks homelab.
  ...

This tag is injected automatically on first run (it won't
change how your README looks in the browser).

The docs/ reference line is also kept current:
  docs/KiteStacks-Homelab-Documentation-v1.3.4.md


DIRECTORY MAPPING
═════════════════
When a file changes, it's placed in the repo like this:

  Server path                          Repo path
  ─────────────────────────────────    ─────────────────────────────────
  ~/docker/homepage/config/…           apps/homepage/config/…
  ~/docker/kavita-docker-automation/…  apps/kavita-docker-automation/…
  /etc/kitestacks/…                    clusters/assassin/…


MANAGING THE SERVICE
════════════════════
  bash status.sh                              # health check
  journalctl -u kitestacks-autosync -f        # live logs
  sudo systemctl restart kitestacks-autosync  # restart
  sudo systemctl stop    kitestacks-autosync  # stop


DEBOUNCE
════════
Default: 15 seconds after the last change before committing.
This means if you save 10 files in 5 seconds, you get ONE commit
not 10. Adjust DEBOUNCE_SECONDS in settings.conf.


TROUBLESHOOTING
═══════════════
Push fails with auth error
  → Check FORGEJO_TOKEN is correct in settings.conf
  → Re-run: sudo bash setup.sh

"Config not found" on start
  → sudo bash setup.sh  (it will copy the example for you)

Service crashes
  → journalctl -u kitestacks-autosync -n 50
  → Check WATCH_DIRS path(s) exist

Files not appearing in apps/ subfolder
  → Check WATCH_DIRS in settings.conf matches your actual
    Docker compose directory (e.g. /home/kenpat/docker)
