108 lines
5.0 KiB
Markdown
108 lines
5.0 KiB
Markdown
# CLAUDE.md
|
|
|
|
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
|
|
|
## What this is
|
|
|
|
Ansible playbooks that deploy and configure MeshCore packet-capture monitoring
|
|
nodes running on Raspberry Pi Zero W / Zero 2 W hardware (hostnames
|
|
`dm-baldock`, `dm-ashwell`, `dm-edworth`). All work happens under `ansible/`.
|
|
|
|
## Commands
|
|
|
|
```bash
|
|
cd ansible
|
|
|
|
# Deploy a single host (recommended for first run / testing)
|
|
ansible-playbook -i inventory.yml site.yml --limit dm-edworth
|
|
|
|
# Deploy all nodes
|
|
ansible-playbook -i inventory.yml site.yml
|
|
|
|
# Dry run
|
|
ansible-playbook -i inventory.yml site.yml --limit dm-edworth --check
|
|
|
|
# If sudo needs a password
|
|
ansible-playbook -i inventory.yml site.yml --limit dm-edworth --ask-become-pass
|
|
```
|
|
|
|
`ansible.cfg` sets `inventory.yml` and `../.vault_pass` as defaults, so
|
|
`-i`/`--vault-password-file` are usually implicit. The play prompts for a
|
|
Tailscale auth key each run — leave blank if the node is already
|
|
authenticated.
|
|
|
|
Bootstrapping a brand-new node needs manual, out-of-band steps first (flashing
|
|
the SD card, `ssh-copy-id`, running `sudo tailscale up`, running the
|
|
meshcore-packet-capture installer interactively over SSH). See the full
|
|
checklist in README.md before assuming `site.yml` alone can bring up a new
|
|
host — it can't, on the first pass.
|
|
|
|
## Architecture
|
|
|
|
**Inventory**: `inventory.yml` defines group `meshcore` (all nodes), with
|
|
subgroups `zero_w` / `zero2_w` by hardware. `site.yml` applies the `meshcore`
|
|
group with `become: true` at the play level.
|
|
|
|
**Vars layering**: `group_vars/all/vars.yml` (shared defaults, e.g. SSH
|
|
pubkeys, wifi networks every node joins) → `group_vars/meshcore.yml`
|
|
(MQTT/packet-capture config, still plaintext) → `host_vars/<host>/vars.yml`
|
|
(per-host `serial_port` for the MeshCore USB device, `wifi_ssid_location`).
|
|
Secrets are split into parallel `vault.yml` files (Ansible Vault, password in
|
|
gitignored `../.vault_pass`) at both the `group_vars/all/` and per-host
|
|
levels — `*/vault.yml.example` documents the expected keys.
|
|
|
|
**Roles run in this order** (`site.yml`): `wifi` → `base` → `meshcore_cli` →
|
|
`meshcore_capture` → `scripts`.
|
|
|
|
- `wifi` — NetworkManager (`community.general.nmcli`) connections for
|
|
`dotnetwork` (home), `dotmobile` (phone hotspot fallback), and the
|
|
host-specific deployed-location network.
|
|
- `base` — authorizes SSH keys, installs base apt packages, sets MOTD,
|
|
installs Tailscale (always) and authenticates it only if an auth key was
|
|
supplied.
|
|
- `meshcore_cli` — installs `meshcore-cli` via pipx.
|
|
- `meshcore_capture` — wraps the upstream `agessaman/meshcore-packet-capture`
|
|
installer. This is the trickiest role in the repo; see below.
|
|
- `scripts` — deploys small helper scripts (`voltage.sh`, `bandwidth.sh`).
|
|
|
|
### `meshcore_capture` role — two installer generations
|
|
|
|
The upstream installer changed its layout between versions, and this repo
|
|
must support both because two nodes were bootstrapped under the old one:
|
|
|
|
- `meshcore_capture_layout: system` (default, set in
|
|
`group_vars/all/vars.yml`) — current upstream (v2.0.0+): dedicated
|
|
`meshcore-capture` system user, `/opt` + `/etc/meshcore-packet-capture`,
|
|
`config.d/*.toml`, service `meshcore-packet-capture.service`.
|
|
- `meshcore_capture_layout: legacy` — how `dm-baldock`/`dm-ashwell` were
|
|
originally set up: flat `~/.meshcore-packet-capture`, `.env.local`, service
|
|
`meshcore-capture.service`. Only kept so the role stays a safe no-op on
|
|
those two hosts; do not use it for new nodes.
|
|
|
|
Which config template, service name, and update-script flags get used all
|
|
branch on this variable — check `host_vars/<host>/vars.yml` for an override
|
|
before assuming the `system` defaults apply.
|
|
|
|
**The installer itself cannot run non-interactively on a fresh install** — it
|
|
opens `/dev/tty` directly for prompts and hangs forever over plain SSH/ansible
|
|
with no human to answer. Ansible's `creates:` guard on that task means it only
|
|
ever runs once; a human must SSH in and run it manually the first time (see
|
|
README.md step 9), after which reruns of `site.yml` just rewrite config and
|
|
restart the service. Do not attempt to script answers into it via
|
|
`script`/pty tricks — this was already tried and abandoned as too fragile.
|
|
|
|
### Other non-obvious constraints
|
|
|
|
- `ansible_become` as a *connection* variable takes precedence over a task's
|
|
own `become: false`, silently running supposedly-unprivileged tasks as
|
|
root. Because of this, `become` is set once at the play level in
|
|
`site.yml`, never in `group_vars`/`host_vars` — see the comment at the top
|
|
of `group_vars/all/vars.yml`.
|
|
- `armv6l` hosts (Pi Zero W, i.e. `dm-baldock`) have no prebuilt `cffi` wheel
|
|
and need `libffi-dev`/`pkg-config` to compile it; that apt task in the
|
|
`base` role is conditioned on `ansible_architecture`.
|
|
- Flashing SD cards with Raspberry Pi Imager 1.9.6 (the current Flathub
|
|
build) silently fails to write OS customisation on Trixie images — grab
|
|
`rpi-imager_2.0.10_amd64.deb`+ from GitHub releases instead. Full detail in
|
|
README.md ("Imager gotcha").
|