Operations

Everything runs through just:

brew install just                  # macOS
just                               # list all recipes
just --list --list-submodules      # recipes inside every module

Modules live in just/*.just and are included from the root justfile:

Module	Purpose
just ansible ...	Deploy, health-check, restart, cert renewal
just credentials ...	Tunnel credential export
just docs ...	Docs generation, device labels
just mqtt ...	MQTT CA + client certificate lifecycle
just sync ...	Push config/certs to a device
just tf ...	Terraform init/plan/apply/validate

Root-level recipes cover the workflow, validation and device helpers: just provision, just setup-device (alias setup-device-lite), just validate, just validate-ansible, just ssh <device>, just logs <device> <service>, just status <device>, just nodered-env <device>, just clean, plus the aliases just deploy, just deploy-all, just deploy-nodered and just reinstall-nodered.

Fleet health

just ansible health          # all environments
just ansible health-dev
just ansible health-staging
just ansible health-prod
just ansible health-lite

Runs ansible/playbooks/healthcheck.yml, which per device checks: Node-RED service status, cloudflared service status, MQTT certificate validity/expiry, and disk space, then prints a per-device summary.

Certificate renewal

just ansible renew-certs

Renews any device's MQTT client cert when it has fewer than 30 days left (ansible/playbooks/renew-certificates.yml, threshold set by mqtt_cert_expiry_threshold_days). Safe to run on a schedule — it's a no-op for certs that aren't close to expiry.

Restarting services

just ansible restart rpi-prod-<serial>
just ansible restart-prod     # environment-wide, requires confirmation

Or directly:

ssh tagai@rpi-prod-<serial>-ssh.tagai.uk
sudo systemctl restart node-red
sudo systemctl restart cloudflared

Logs

just logs rpi-prod-<serial> node-red
# or directly:
ssh tagai@rpi-prod-<serial>-ssh.tagai.uk
sudo journalctl -u node-red -n 100 -f
sudo journalctl -u cloudflared -n 100 -f

Adding / removing a device

Add: edit config/devices.yml, then follow runbooks/provisioning.md.

Remove: delete the entry from config/devices.yml, then:

cd terraform && terraform apply

This tears down that device's tunnel and DNS records. The device itself isn't touched remotely — decommission it physically/on-network separately.

Deploying a Node-RED flow update

just deploy-nodered                    # all devices
just deploy-nodered --limit rpi-prod-<serial>
just deploy-nodered --version v1.0.0

See reference/nodered-git-deployment.md for rollback and CI/CD trigger details.

Troubleshooting

See the troubleshooting section of runbooks/provisioning.md for provisioning-time issues. For a device that's already deployed but unhealthy, start with just ansible health-<env> and just logs <device> <service> above.