sjat/MakerFLOSS_Troubleshooting
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
MakerFLOSS_Troubleshooting/CLAUDE.md
sjat 9ff12700ae Initial troubleshooting workspace: access, network map, runbooks 
Scaffold for troubleshooting MakerFLOSS hosts at the makerspace.
Reference + thin runbooks model — authoritative data stays in the
source repos (AnsibleBaobabV4, MakerFLOSS_Mikrotik, MakerFLOSS).

- access.md: reach paths for mamba-on-LAN and fisi-tunneling-in
  (netbird on-demand, VPS bastion, ProxyJump via kuku->mamba),
  with the isolation rule.
- network-map.md: subnet pointers + open question on makerspace
  addressing (10.2.30/172.17.3/10.0.0).
- runbooks/switch-crs310.md: CRS310 connectivity + lockout recovery.
- incidents/: dated log scaffold.
- CLAUDE.md: operating rules for this repo.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-06-09 13:24:26 +02:00

2.1 KiB
Raw Blame History

CLAUDE.md — MakerFLOSS_Troubleshooting

Operating guide for working in this repo. This is a troubleshooting workspace for MakerFLOSS hosts at the Orange Makerspace.

What this repo is

Reference + thin runbooks. It does not hold authoritative IPs/topology/secrets — those live in the source repos. Keep it that way; link, don't copy.

Source repos (authoritative — most fixes land here)

  • ~/Projects/AnsibleBaobabV4 — canonical infra-as-code: makerfloss VPS, makerfloss1, mf04, wg1 WireGuard plane, Netbird control plane, all containers. Git remote = baobab Forgejo. Has Ansible vault (prod).
  • ~/Projects/MakerFLOSS_Mikrotik — the CRS310 switch. Ansible vault (makerfloss). Strict lockout-safety rules — read its CLAUDE.md before touching the device.
  • ~/Projects/MakerFLOSS — docs/slides site (docs.makerfloss.eu).

Rules (decided 2026-06-09)

  1. Fixes go to the relevant source repo's main. Apply directly there, then run. For live switch/infra, follow that repo's idempotency + lockout-safety rules (run device plays twice; enable VLAN-filtering last; detached self-reverting jobs for mgmt changes).
  2. Access path for Claude (on fisi): Netbird, on-demand only. Bring the overlay up for the task, netbird down immediately after. Prefer the VPS-bastion path when it suffices (no tunnel on fisi at all). Isolation is a hard requirement — nothing from the makerspace should be able to reach fisi/the homelab. See access.md §C.
  3. Reference, don't duplicate. When you need a fact, link to the source-repo file. If you cache a value here, note it can drift.
  4. Log real work in incidents/ — symptom, root cause, the source-repo commit, verification.
  5. Never commit secrets. Vault keys live under ~/.ansible/vault-keys/.

Start-of-session checklist

  1. access.md — pick a reach path for where you are.
  2. network-map.md — confirm host/subnet (note the open question about makerspace addressing).
  3. runbooks/ — find or write the runbook.
  4. Verify with evidence before claiming a fix works.