Skip to content
Register

What do you use for documenting your network that you'll actually maintain?

Networking by SamAlvi 24 replies 2.5K views
SamAlvi

Member OP

Self-Host Everything

#1

I've been running BookStack in docker compose behind traefik for three years now, with authelia for auth and a nightly restic backup (https://restic.net) to my minio instance. It's glorious. Zero subscription fees, full control, reverse proxy handles the tls.

But I'll be honest: I haven't updated the actual content in six months. The infrastructure is maintained beautifully. The documentation is a graveyard. So my question to all of you is: what do you use for documenting your network that you'll actually maintain? Not what looks good in a demo, not what you wish you used. What actually gets updated when you change a vlan or add a peer?

My current list of abandoned tools:
- bookstack (self-hosted, abandoned)
- netbox (self-hosted, too complex for my scale, abandoned)
- obsidian (local only, never synced properly)
- a single google doc (don't ask)

my cloud. my rules. my 3AM alerts.
YuriDavid

Member

#2

---
- abandoned tools
- all of them
- eventually
---
- sustainable approaches
- none
- proven by observation
---
- NOTE: the only documentation that survives is the config itself
- WARNING: comments in config rot faster than external docs
---
- my actual practice
- grep -r across /etc
- git log for the story
- blame for the who
---
- the question itself implies
- a desire for cleanliness
- cleanliness is not achievable
- accept entropy

indentation is not optional
JO

Member

#3

Authelia + traefik is solid. I run the same stack.

SH

Member

#4

I've cycled through so many of these. Currently on NetBox but I know I'm one busy week away from it becoming another tombstone. The only thing that's stuck is a plaintext file in my homelab git repo called NETWORK_LIES.md where I write what I *thought* was true when I made a change. It's ugly, it's wrong half the time, but I actually open it because there's no mental load to editing it.

Paulo3

Member

#5

Same problem here. I tried BookStack, Wiki.js, Outline, even Notion for a while. The friction of opening another tab and formatting something kills it. What I've landed on is just using my Unifi controller's notes field for VLANs and a shared Google Sheet for IP allocations. It's not pretty but it's two clicks away from where I already am.

PacketpunkUma

Member

#6

This is why I just annotate my docker-compose files with comments and call it architecture docs. If the container dies, I'm already in the file. If I'm not in the file, I'm not documenting anyway.

SamAlvi

Member OP

Self-Host Everything

#7
YuriDavid said:
The only documentation that survives is the config itself

I want to argue with this but I can't. My traefik dynamic config https://traefik.io has seventeen routers and I can tell you which three I actually remember. The rest are archaeology.

my cloud. my rules. my 3AM alerts.
ray_takeba

Member

Ex-Sysadmin

#8

Forty years and the only documentation system I've seen survive a job change is a paper notebook. Not even kidding. The young ones laugh until their cloud account gets locked on their last day. I have three decades of network changes in spiral bounds.

jane_ffm

Member

#9

At my last job we ran Confluence and it was a disaster of stale pages. Now I just use Hetzner's own documentation for their stuff, my own terse markdown for the rest, and I stopped pretending I was building a knowledge base. I'm building breadcrumbs for future me.

Single mode till I die 💀
YuriDavid

Member

3 #10
shell36 said:
NETWORK_LIES.md

This is the most honest filename I have ever seen. I am stealing this. My current equivalent is called temp_notes.txt and it is 34000 lines.

indentation is not optional

Post a reply

You need an account to reply. Log in or register to join the conversation.

Post reply Preview Save draft