Naming & Architecture

Document the fleet

As your fleet grows past a handful of machines, documentation stops being optional. Even for a personal setup, future-you (and any future Pippa) needs to know what's where, what does what, and which IP belongs to which machine. A simple text file or Notion page is enough.

Naming conventions that survive

Match SSH alias to hostname. If ssh office works, the machine's hostname should be office too. Sanity wins over cleverness.
Short and lowercase. One or two syllables. You'll type these thousands of times.
Function over hardware year. office outlives the specific Mac Studio behind it. mac-studio-2024 doesn't.
Keep portables distinguishable. macbook, pro2024, pro2023, air — easy to tell apart at a glance.

Code

Architecture doc — markdown·markdown

# Home Network Architecture

```
┌─────────────────────────────────────────────────────┐
│        Home Network (192.168.1.0/24)                 │
│                                                       │
│  ┌─────────── 10GbE Switch ────────────────┐        │
│  │                                           │        │
│  │  office(.10)  server(.11)              │        │
│  │  music(.12)   worker(.13)              │        │
│  │  mini(.30)    NAS(.40)                 │        │
│  │                                           │        │
│  └────────────────┬──────────────────────────┘        │
│                   │ 1GbE                              │
│              ┌────┴────┐                              │
│              │ Router  │── Internet                  │
│              └────┬────┘                              │
│                   │ Wi-Fi                             │
│       macbook(.20)  pro2024(.21) pro2023(.22)     │
│                                                       │
│  ── Tailscale (100.64.x.y) overlay ──                │
│     Reach any machine from anywhere                   │
└───────────────────────────────────────────────────────┘
```

## IP table

| Machine  | LAN IP    | Tailscale  | Role                |
|----------|-----------|------------|---------------------|
| office   | .10       | 100.64.0.1 | Primary workstation |
| server   | .11       | 100.64.0.2 | Build server / CI   |
| music    | .12       | 100.64.0.3 | Music production    |
| worker   | .13       | 100.64.0.4 | Background work     |
| nas      | .40       | 100.64.0.10| Storage / backups   |
| macbook  | .20       | 100.64.0.20| Daily portable      |
| ...      | ...       | ...        | ...                 |

Document the fleet

Naming conventions that survive

Code

Exercise

Progress

Comments 0