9ff12700ae
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>
48 lines
2.4 KiB
Markdown
48 lines
2.4 KiB
Markdown
# MakerFLOSS Troubleshooting
|
|
|
|
A working repo for troubleshooting and fixing hosts at the **Orange Makerspace**
|
|
that are part of the MakerFLOSS project.
|
|
|
|
This repo is **reference + thin runbooks**: it does *not* duplicate authoritative
|
|
data (IPs, topology, secrets). Those live in the source repos below. Here we keep
|
|
access procedures, runbooks, and an incident log, with pointers back to source.
|
|
|
|
## Source repos (authoritative)
|
|
|
|
| Repo | Path | What it owns |
|
|
|------|------|--------------|
|
|
| **AnsibleBaobabV4** | `~/Projects/AnsibleBaobabV4` | **Canonical infra-as-code.** The makerfloss VPS, `makerfloss1`, `mf04`, the makerfloss WireGuard plane (`wg1`), the Netbird control plane, and all containerised services. This is where most fixes land. |
|
|
| **MakerFLOSS_Mikrotik** | `~/Projects/MakerFLOSS_Mikrotik` | The **CRS310 switch** (`crs310-maker`) — Ansible-managed RouterOS config. The "new switch" at the makerspace. |
|
|
| **MakerFLOSS** | `~/Projects/MakerFLOSS` | Documentation site (`docs.makerfloss.eu`) and slides. Docs-only; the human-readable hardware/service catalog. |
|
|
|
|
> Note: `AnsibleBaobabV4` is a separate (homelab) project that also happens to
|
|
> manage the MakerFLOSS infrastructure — early MakerFLOSS work started there and
|
|
> stayed. Its git remote is the **baobab** Forgejo, not the MakerFLOSS one.
|
|
|
|
## Where fixes go
|
|
|
|
Fixes land in the **relevant source repo's `main`** branch (per decision
|
|
2026-06-09). Switch/live-infra changes still follow that repo's own
|
|
lockout-safety and idempotency rules (e.g. run device-touching plays twice;
|
|
enable VLAN-filtering last). This repo only holds runbooks and the incident log.
|
|
|
|
## Layout
|
|
|
|
```
|
|
.
|
|
├── access.md # HOW to reach makerspace hosts (read this first)
|
|
├── network-map.md # thin network overview + pointers + open questions
|
|
├── runbooks/ # task-focused troubleshooting guides
|
|
│ ├── README.md
|
|
│ └── switch-crs310.md
|
|
└── incidents/ # dated log of issues worked + outcomes
|
|
└── README.md
|
|
```
|
|
|
|
## Quick start for a troubleshooting session
|
|
|
|
1. Read [`access.md`](access.md) — pick a reach path for where you are
|
|
(makerspace with mamba, or tunneling in from `fisi`).
|
|
2. Check [`network-map.md`](network-map.md) for the host/subnet you're after.
|
|
3. Find or create a runbook in [`runbooks/`](runbooks/).
|
|
4. Apply fixes in the source repo; log what happened in [`incidents/`](incidents/).
|