piNail/wifi-onboarding-draft/RECOVERY_AND_RUNBOOK.md

Recovery and Support Runbook

Use this when users report they cannot reach the web UI.

User-Facing Recovery

1. Power cycle device.
2. Try http://pinail.local:5000.
3. If unavailable, check router client list for pinail host and use IP.
4. If still unavailable, hold setup/reset button (5-10s) to force setup AP.
5. Rejoin piNail-Setup-XXXX and re-enter WiFi credentials.

Technician Quick Checks (SSH)

• Service status:
  • sudo systemctl status pinail2
• Logs:
  • sudo journalctl -u pinail2 -n 150 --no-pager
• WLAN status:
  • ip addr show wlan0
  • iwgetid
• Reachability:
  • ping -c 3 192.168.0.1

Common Failure Cases

• Wrong SSID/password:
  • force setup mode, re-enter credentials.
• Router changed subnet:
  • use mDNS or router client list to discover new IP.
• Stale browser cache:
  • hard refresh (Ctrl+Shift+R / Cmd+Shift+R).
• Service stuck after network transitions:
  • sudo systemctl restart pinail2.

Recommended Production Defaults

• DHCP + router reservation.
• mDNS hostname advertised (pinail.local).
• Physical setup/reset button available without opening enclosure.