Your Name
3536f267c7
- rename bin/pos-usb-server -> pos-share-usb-server, pos-system-nfs-{client,server} -> pos-share-nfs-{client,server}
- update # POS: headers, usage strings, INTERACTIVE_CMDS, usage() EXAMPLES, notify-scope comment
- docs: new DOC/howto/share.md (USB+NFS consolidated), drop usb.md + system.md NFS sections,
POS.md ### share section, HOWTO/README/AGENT_Context/README/DEV/AGENTS updates
- make gen && make check green
89 lines
4.6 KiB
Markdown
89 lines
4.6 KiB
Markdown
# `pos` HOW-TO Guides
|
|
|
|
Hands-on, copy-paste guides for every `pos` category. These are the **tutorial**
|
|
layer: flags, examples, configuration, recipes, and troubleshooting. For the
|
|
authoritative one-line reference (every command + flag), see
|
|
[DOC/POS.md](POS.md).
|
|
|
|
## Quick start — pick your category
|
|
|
|
| Category | What you can do | Guide |
|
|
|----------|-----------------|-------|
|
|
| `pos ai` | Chat with Google Gemini from CLI or Telegram | [ai](howto/ai.md) |
|
|
| `pos network` | IP info, hotspot, scan, port check | [network](howto/network.md) |
|
|
| `pos docker` | Compose services, container dashboards, disposable VMs | [docker](howto/docker.md) |
|
|
| `pos media` | Download audio/video via yt-dlp | [media](howto/media.md) |
|
|
| `pos system` | Backups, firewall, health dashboard | [system](howto/system.md) |
|
|
| `pos system event-trigger` | Threshold-rule monitors that alert on crossing | [event-trigger](howto/event-trigger.md) |
|
|
| `pos ssh` | Load keys into the agent | [ssh](howto/ssh.md) |
|
|
| `pos share` | Share USB devices & filesystems over the network (USB, NFS) | [share](howto/share.md) |
|
|
| `pos communication` | Send Telegram/Matrix messages & alerts, /command listeners | [communication](howto/communication.md) |
|
|
| `pos entertainment` | Scheduled auto-messages from public APIs | [entertainment](howto/entertainment.md) |
|
|
|
|
Every tool is `bin/pos-<category>-<command>`; run `pos <category> --help` to
|
|
list a category, and any tool's `--help`/`--help`-style usage for full flags.
|
|
|
|
## Cross-cutting concepts (read once)
|
|
|
|
These apply to several categories at once.
|
|
|
|
### Config files — `~/.config/linux_post_install/`
|
|
|
|
Runtime tool config lives here as `<tool>.env` files (`chmod 600`). Precedence
|
|
is always **flags > environment > config file**. `postinstall.sh` installs the
|
|
templates (without overwriting an existing file):
|
|
|
|
| File | Used by | Keys |
|
|
|------|---------|------|
|
|
| `telegram.env` | `pos communication telegram sender` / `listener`, everything that alerts | `TELEGRAM_BOT_TOKEN`, `TELEGRAM_CHAT_ID` |
|
|
| `matrix.env` | `pos communication matrix sender` / `listener` | `MATRIX_HOMESERVER`, `MATRIX_ACCESS_TOKEN`, `MATRIX_USER_ID`, `MATRIX_ROOM_ID` |
|
|
| `notify.env` | `lib/notify.sh` (all alerting) | `NOTIFY_PLATFORM` (e.g. `telegram,matrix`) |
|
|
| `system.env` | `pos system health`, `pos system backup` | `BACKUP_SERVICE_ROOTS`, `HEALTH_BACKUP_MAX_AGE_DAYS` |
|
|
| `compose.env` | `pos docker compose` | `TS_AUTHKEY`, `TZ`, `DNS_SERVER`, `SERVICES_BASE` |
|
|
| `entertainment.env` | `pos entertainment *` | plugin keys (`WEATHER_LAT`…), `ENABLED` |
|
|
| `ai.env` | `pos ai gemini` | `AI_GEMINI_API_KEY`, `AI_GEMINI_MODEL` |
|
|
|
|
```bash
|
|
pos config telegram # set TELEGRAM_BOT_TOKEN / TELEGRAM_CHAT_ID
|
|
pos config matrix # set MATRIX_HOMESERVER / MATRIX_ROOM_ID, then:
|
|
pos communication matrix sender login --user @you:example.org # fetch an access token
|
|
pos entertainment config set WEATHER_LAT=36.51 WEATHER_LON=40.75
|
|
```
|
|
|
|
### The notify system — `lib/notify.sh`
|
|
|
|
Any tool that "announces" something calls `notify_send`, which delivers to every
|
|
platform in `NOTIFY_PLATFORM` (default `telegram`). It is **silent-fail**: if no
|
|
platform is configured it warns and never breaks the calling tool.
|
|
|
|
```bash
|
|
# ~/.config/linux_post_install/notify.env
|
|
NOTIFY_PLATFORM=telegram # comma-separated to send to all
|
|
```
|
|
|
|
Ship with `telegram` and `matrix` — add both to `NOTIFY_PLATFORM` to fan out
|
|
alerts (Matrix needs `pos config matrix` + a `login`-fetched token first).
|
|
Adding another platform = create `bin/pos-communication-<p>` implementing
|
|
`send <value> [--markdown]` and list it. See
|
|
[DOC/DEV.md → Alerting](DEV.md) for the contract.
|
|
|
|
### Scheduling
|
|
|
|
- **Daily health digest** (`pos system health --send` at 08:00) — `systemd/pos-health.{service,timer}`,
|
|
enabled by postinstall once `telegram.env` exists. See [system](howto/system.md).
|
|
- **Entertainment auto-triggers** — per-plugin `pos entertainment enable <plugin> <interval>`,
|
|
uses systemd user timers (or cron fallback). See [entertainment](howto/entertainment.md).
|
|
|
|
### Gotcha: run from anywhere
|
|
|
|
`install.sh` copies `bin/pos*` + `lib/*` to `/usr/local/bin`, so `pos` works
|
|
after the repo is deleted. After pulling new changes, re-run `./install.sh` (or
|
|
just copy the changed `bin/`/`lib/` files) to refresh the installed copies.
|
|
|
|
## How the guides relate to `DOC/POS.md`
|
|
|
|
- **`DOC/POS.md`** = reference. One table row per command, full flag lists,
|
|
compose/ScaleTail config strategy. Use it when you need the exact flag.
|
|
- **This guide set** = how-to. Examples, recipes, config walk-throughs, and
|
|
troubleshooting, linking back to POS.md rather than duplicating it.
|