[FriarTech]

From the author on r/selfhosted: Ever set up a bunch of services, then completely forget how your network is configured a month later? I got tired of boring documentation - cause I didn't do it, and I built Network Chronicles - a "game" that turns exploring your infrastructure into solving the mystery of a missing sysadmin. The rest of this I summarized with the bot from my game:

The game hooks into your shell and turns normal Linux commands into game actions:

    Run ip route → "You've discovered the network gateway! +25 XP"

    Check log files → Find cryptic messages from the missing admin

    Run nmap on your network → Unlock a new area in the mystery

As you explore, the game builds documentation of your setup while advancing the story. Everything is represented with retro terminal UI - no graphics, just ASCII art and styled text.

What it looks like in practice:

    You get mysterious messages from "The Architect" (the missing admin)

    Your shell prompt shows your level and current quest

    Running normal commands sometimes triggers discoveries

    An in-game journal records everything you learn

    Challenge scripts create puzzles that teach Linux skills

The core idea: What if documenting your homelab felt like playing Hacknet or Uplink instead of writing a technical manual?

The real magic: It actually integrates with your REAL infrastructure. If you have services on specific ports, the game will incorporate them into the story and challenges.

This is a personal project I've been working on - not publicly available yet, mostly due to hardware constraints on running multiple models simultaneously; but I'd love to know: Would something like this motivate you to better understand and document your setup? What features would make it valuable to you?

EDIT/UPDATE: How do I stress that this is way way under-developed and in development and not advisable for you to install just yet? I guess the best way is to provide a link. https://github.com/Fimeg/NetworkChronicles

This is CONCEPT. Its what I always wanted my tech to do. It's hardly feature complete - at best alpha 0.0.4 To gain a FULL understanding of what this might be - see the premise file: https://github.com/Fimeg/NetworkChronicles/blob/main/premise...

[sudodudeo]

This is such an awesome concept and I love it. Is there a non-game version of this somewhere that maps out your networking and service config?

[RestartKernel]

For anyone wanting to avoid this mystery, putting the game aside, I highly recommend NixOS. It has its quirks, but the declarative configuration basically forces you to document each system, circumventing many of the issues satirised (?) with this game.

It still gets complicated if you have many interconnected devices to manage of course, but at least it limits the obscurity of the most complex devices in your network.

I'm open to alternatives though, if anyone has some to share.

[bayindirh]

I like the idea behind the Nix and NixOS, however, it works for personal systems and small servers, not the production servers you have at work, and I tend to document those as well.

I have found a couple of ways of doing documentation.

1. I document myself, with my style: I have a big Obsidian vault with work related documents, it's loosely based on Diataxis [0] method. I live document the part I'm working on once, and when I need to repeat the deed, I can update any changed parts, if any.

2. SaltStack. People doesn't prefer it much when it comes to Ansible, but pillars and recipes allows automation tons of stuff in a self documenting format. Plus, if you wish SaltStack has drift control and anchoring (like the default CFEngine behavior).

3. Terraform. Not incorporated by me, but a project uses it, and we use it in turn. What's nice about it is scaling. They have a variables file, and change the number of the server type you want to scale, and apply. It's scaled automatically. Infrastructure as code at best.

You want to installs with specific versions and packages? You can use xCAT for RedHat and Debian systems (which will be replaced by Lenovo Conflence soonish). You can re-provision a system to the exact state you want with three commands and, within 15 minutes, your system will be ready. Since it uses the repositories local to xCAT, no version drifting occurs.

I personally install Debian stable, enable security updates, and periodically make sure that things are working. Not taking much time (10 minutes per month?).

[0]: https://diataxis.fr/

[a_t48]

I used SaltStack to manage robot OSes in the past, at the urging of my boss. It was super powerful, but it felt a little too powerful, and a little too magical.

[bayindirh]

When you dive deep into the documentation, how every action is mapped to specific OS is detailed nicely.

For example, package management actions map to specialized packages per OS, and for that specific package, documentation gives how the specific package calls the binaries or use the libraries. After a certain point you start to build call trees and see everything in your mind before pressing enter.