╔══════════════════════════════════════════════════════════════════╗ ║ 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// → apps// /etc/kitestacks/ → clusters/assassin/

2. Bumps the version in README.md

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

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)