157 lines
5.3 KiB
Markdown
157 lines
5.3 KiB
Markdown
╔══════════════════════════════════════════════════════════════════╗
|
|
║ 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.4 -->
|
|
|
|
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.4 -->
|
|
|
|
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)
|