docs: refresh repo README and add component guides
This commit is contained in:
parent
e8d06c2374
commit
a12e713d1f
3 changed files with 152 additions and 64 deletions
40
docs/setup-wizard/README.md
Normal file
40
docs/setup-wizard/README.md
Normal file
|
|
@ -0,0 +1,40 @@
|
|||
# Setup Wizard
|
||||
|
||||
Interactive bootstrap for Debian-based VM templates. The wizard is safe to re-run and is designed for Proxmox clones that need the same base hardening, tooling, and share mounts before they enter service.
|
||||
|
||||
## Files
|
||||
- `bootstrap.sh` – convenience wrapper you drop on the template. It escalates to root, pulls the latest wizard, and executes it.
|
||||
- `setup.sh` – primary script. Uses `whiptail` menus to configure the VM.
|
||||
|
||||
## Requirements
|
||||
- Debian 12/13 guest with network access to `git.jordanwages.com`.
|
||||
- Either `curl` or `wget`. The wizard auto-installs `whiptail` if it is missing.
|
||||
- Ability to escalate to root (`sudo`, root shell, or root password).
|
||||
|
||||
## Running The Wizard
|
||||
1. Place `bootstrap.sh` on the template (or use the `curl | bash` one-liner in the main README).
|
||||
2. Execute `sudo ./bootstrap.sh` (or simply `./bootstrap.sh` as root).
|
||||
3. Follow the `whiptail` prompts. You can cancel at any step; no changes are committed until each section completes.
|
||||
|
||||
You can re-run `setup.sh` at any time to reapply updates, rotate keys, or adjust NAS mounts. The managed sections overwrite prior state so the machine always matches the latest answers.
|
||||
|
||||
## What The Wizard Configures
|
||||
- **Core packages**: installs `sudo`, `curl`, `gnupg`, `lsb-release`, `nfs-common`, and any optional tools you choose (`htop`, `jq`, `git`, etc.).
|
||||
- **System updates**: full `apt-get dist-upgrade` with a progress gauge.
|
||||
- **Sudo access**: toggles passwordless sudo for any non-system users on the box.
|
||||
- **Hostname**: updates `/etc/hosts` and `hostnamectl`
|
||||
- **SSH keys**: overwrites `authorized_keys` for `root` and the primary user (`jordanwages` by default) after deduplicating entries.
|
||||
- **Shell quality-of-life**: installs bat/ncdu aliases and replaces `neofetch` with `fastfetch` for login banners.
|
||||
- **NFS mounts**: manages a comment-delimited block in `/etc/fstab` for the NAS hosts you select and attempts to mount them immediately.
|
||||
- **Logging**: tee'd transcript stored at `/var/log/freshbox.log` on each run.
|
||||
|
||||
## Customization
|
||||
- **Default SSH key**: edit `DEFAULT_SSH_KEY` near the top of `setup.sh` to your preferred public key.
|
||||
- **Optional packages**: expand the `TOOLS=(...)` array; everything listed appears as a checkbox in the “Extra Utilities” menu.
|
||||
- **NAS hosts**: change the `NFS_HOSTS=(...)` array to match your environment. Each value becomes a selectable share under `/media/<host>`.
|
||||
- **Primary user**: adjust `USER_NAME` if your golden image uses a different account than `jordanwages`.
|
||||
|
||||
## Troubleshooting
|
||||
- Wizard aborts with missing `whiptail`: rerun the script; it self-installs `whiptail` before launching menus.
|
||||
- NFS mounts fail: the wizard leaves a ⚠️ note in the final dialog. Check `/var/log/freshbox.log` for the mount error and re-run once networking or permissions are fixed.
|
||||
- Need to inspect actions: review `/var/log/freshbox.log`, which captures command output from the session.
|
||||
90
docs/uptime-kuma/README.md
Normal file
90
docs/uptime-kuma/README.md
Normal file
|
|
@ -0,0 +1,90 @@
|
|||
# Uptime Kuma Push Client
|
||||
|
||||
`kuma-push.sh` sends heartbeat updates to your Uptime Kuma instance by iterating through a JSON inventory of checks. It is built for guests that cannot be polled directly but can reach the Kuma push endpoint.
|
||||
|
||||
## Files
|
||||
- `kuma-push.sh` – performs the checks and submits results via HTTP GET.
|
||||
- `kuma-checks.json` – declarative list of checks the script will execute.
|
||||
|
||||
## Requirements
|
||||
- `bash`, `jq`, `wget`, and access to `https://status.jordanwages.com` (adjust `BASE` in the script if your Kuma lives elsewhere).
|
||||
- Optional: `systemd`, `cron`, or another scheduler to run the script every minute.
|
||||
|
||||
## Configuration (`kuma-checks.json`)
|
||||
Each object in the array represents one Kuma monitor and should contain:
|
||||
|
||||
| Field | Required | Description |
|
||||
|-------|----------|-------------|
|
||||
| `name` | ✔ | Human-friendly label shown inside Kuma. Sent back in the push message. |
|
||||
| `type` | ✔ | One of `native`, `http`, `service`, `docker`, `mount`, or `disk`. |
|
||||
| `push` | ✔ | Kuma push token for the monitor. |
|
||||
| `target` | ◐ | Interpreted per check type (URL, systemd service name, container name, mount path, or disk device). Not used for `native`. |
|
||||
| `threshold` | ◐ | Only used for `disk` checks. Marks the percentage usage at which the disk turns unhealthy. |
|
||||
|
||||
Example:
|
||||
```json
|
||||
{
|
||||
"name": "web_frontend",
|
||||
"type": "http",
|
||||
"target": "http://localhost:8080/health",
|
||||
"push": "xxxxxxxxxxxxxxxx"
|
||||
}
|
||||
```
|
||||
|
||||
## Check Types
|
||||
- **native**: Always reports `up`. Useful for “is the agent alive” checks.
|
||||
- **http**: Issues a `wget` to the target URL and reports `up` when the request succeeds. Ping time is the response time in ms.
|
||||
- **service**: Calls `systemctl is-active` on the target unit.
|
||||
- **docker**: Uses `docker inspect` to confirm the container is running.
|
||||
- **mount**: Uses `mountpoint -q` to verify the target path is mounted.
|
||||
- **disk**: Finds the mount that corresponds to the device (e.g. `vda5` or `/dev/sda1`) and reports `down` when usage meets/exceeds `threshold`.
|
||||
|
||||
## Scheduling
|
||||
A one-minute cadence keeps Kuma happy without overwhelming it. Two common options:
|
||||
|
||||
### systemd timer
|
||||
Create `/etc/systemd/system/kuma-push.service`:
|
||||
```ini
|
||||
[Unit]
|
||||
Description=Send Uptime Kuma push heartbeats
|
||||
|
||||
[Service]
|
||||
Type=oneshot
|
||||
ExecStart=/usr/local/bin/kuma-push.sh
|
||||
```
|
||||
|
||||
Create `/etc/systemd/system/kuma-push.timer`:
|
||||
```ini
|
||||
[Unit]
|
||||
Description=Run Uptime Kuma push heartbeats every minute
|
||||
|
||||
[Timer]
|
||||
OnBootSec=1min
|
||||
OnUnitActiveSec=1min
|
||||
AccuracySec=5s
|
||||
|
||||
[Install]
|
||||
WantedBy=timers.target
|
||||
```
|
||||
|
||||
Enable both:
|
||||
```bash
|
||||
sudo systemctl daemon-reload
|
||||
sudo systemctl enable --now kuma-push.timer
|
||||
```
|
||||
|
||||
### cron
|
||||
Copy the script into `/usr/local/bin` and drop the following into `crontab -e`:
|
||||
```
|
||||
* * * * * /usr/local/bin/kuma-push.sh >/dev/null 2>&1
|
||||
```
|
||||
|
||||
## Customization Tips
|
||||
- Update the `BASE` variable inside `kuma-push.sh` if your Kuma origin or token path changes.
|
||||
- When `curl` is available you can swap `wget` for `curl` calls; the current implementation favours `wget` so the template can stay minimal.
|
||||
- Add jitter with the `sleep $(( RANDOM % 5 ))` line if you scale to dozens of VMs—feel free to widen the range.
|
||||
|
||||
## Troubleshooting
|
||||
- **Missing dependencies**: install `jq` and `wget` (`apt install jq wget`). The script exits if either is missing.
|
||||
- **No pushes arriving**: confirm the machine reaches the Kuma endpoint manually with `wget`. Kuma will mark the monitor down automatically when pushes stop.
|
||||
- **Disk check always down**: ensure the `target` resolves to a mounted device (`lsblk -f` and `findmnt` help confirm the correct name).
|
||||
Loading…
Add table
Add a link
Reference in a new issue