80 lines
No EOL
3.1 KiB
Text
80 lines
No EOL
3.1 KiB
Text
KiteStacks Forgejo Automation – Watcher Script Documentation
|
||
Overview
|
||
|
||
The kitestacks-watcher.sh script is a systemd-compatible file watcher for the KiteStacks Homelab. Its main responsibilities:
|
||
|
||
Watch configured directories for file changes.
|
||
Sync changes to the correct apps/ or clusters/ folder in the repo.
|
||
Automatically bump version in README.md.
|
||
Update versioned documentation and CHANGELOG.md.
|
||
Commit and push changes to either test or main repository.
|
||
Throttle updates to prevent frequent commits when changes are rapid.
|
||
Key Features Added in This Setup
|
||
1. 20-Minute Conditional Throttling
|
||
The script now tracks the last successful push.
|
||
Commits/pushes only happen once every 20 minutes.
|
||
If changes occur multiple times within 20 minutes, they are batched into a single update.
|
||
Logs indicate skipped pushes during throttle:
|
||
[autosync] 2026-06-06 12:50:10 INFO Throttling active, skipping commit/push for 1190s
|
||
2. Initial Setup Steps
|
||
Navigate to the scripts folder:
|
||
cd ~/kitestacks-homelab-autosync-test/scripts
|
||
Make the watcher script executable:
|
||
chmod +x kitestacks-watcher.sh
|
||
Run manually to test:
|
||
./kitestacks-watcher.sh
|
||
Observe logs for startup confirmation.
|
||
Make a small change in a watched directory (e.g., apps/forgejo/README.md) to trigger the watcher.
|
||
Run in background (detach from terminal):
|
||
mkdir -p ~/logs
|
||
nohup ./kitestacks-watcher.sh > ~/logs/kitestacks-watcher.log 2>&1 &
|
||
Verify process is running:
|
||
ps aux | grep kitestacks-watcher
|
||
tail -f ~/logs/kitestacks-watcher.log
|
||
3. Optional: systemd Service
|
||
|
||
Create /etc/systemd/system/kitestacks-watcher.service:
|
||
|
||
[Unit]
|
||
Description=KiteStacks AutoSync Watcher
|
||
After=network.target
|
||
|
||
[Service]
|
||
Type=simple
|
||
User=kenpat
|
||
WorkingDirectory=/home/kenpat/kitestacks-homelab-autosync-test/scripts
|
||
ExecStart=/home/kenpat/kitestacks-homelab-autosync-test/scripts/kitestacks-watcher.sh
|
||
Restart=always
|
||
RestartSec=10
|
||
|
||
[Install]
|
||
WantedBy=multi-user.target
|
||
|
||
Enable and start:
|
||
|
||
sudo systemctl daemon-reload
|
||
sudo systemctl enable kitestacks-watcher.service
|
||
sudo systemctl start kitestacks-watcher.service
|
||
sudo systemctl status kitestacks-watcher.service
|
||
|
||
View logs:
|
||
|
||
journalctl -u kitestacks-watcher.service -f
|
||
4. Script Behavior Summary
|
||
Watches directories listed in $WATCH_DIRS.
|
||
Debounce period defined in $DEBOUNCE_SECONDS (default 15s) to batch rapid changes.
|
||
Maps filesystem paths to repo folders (apps/ for Docker apps, clusters/assassin/ for cluster configs).
|
||
Updates README.md version tags and generates versioned docs in docs/.
|
||
Maintains a CHANGELOG.md with automated entries.
|
||
Pushes updates to either test or main repo based on $STATE_FILE.
|
||
Throttle ensures that frequent changes do not flood the repository with commits.
|
||
5. Verification
|
||
Make a change to a file in the watched directories.
|
||
Confirm logs show sync, doc creation, and commit/push.
|
||
Multiple changes within 20 minutes are batched.
|
||
Watch for throttling messages confirming 20-minute delay between pushes.
|
||
6. Notes / Recommendations
|
||
Keep $WATCH_DIRS and $EXCLUDE_PATTERNS properly configured in settings.conf.
|
||
Use logs (~/logs/kitestacks-watcher.log) for debugging.
|
||
Manual testing is recommended after any config changes.
|
||
systemd integration ensures the watcher starts automatically on reboot. |