Net-Doc

For the past 8 months I’ve been working on a documentation system for us to store everything we might need on our network. Especially given that “network” in a secondary school means everything from the Hyper-V cluster down to the access control units for the motorised gates at the front of school.

Documentation is a really important part of the network. I had little to none when I started at my current school and even with my best efforts I found that when our new engineer started I just didn’t have the documentation needed to get them up to speed without me to answer lots of questions. So it came time to make a proper system and spend the time writing everything down.

I first started this project thinking I’d find it required more time than I could give it, but I’m almost surprised to say that today I released version 1.0.0, which represents the first stable release! There is still work to do and plenty of issues placed against the version 1.1 milestone but right now it’s working for us and getting better with every commit.

We had tried a few systems before I decided to try building my own. Originally we used a shared OneNote notebook, which has the same flaw to me as a wiki, a lot of copying the same content around so we can make all the “VLAN” documentation look the same. Some of the systems I looked at seemed to either tie you into their structure, or where a wiki in a different skin.

What is Net-Doc?

So what is Net-Doc? Net-Doc is a documentation system that allows you to build out the structure of your documentation your way. It gives very little out of the gate which allows 2 instances to vastly different. We for example have our “main” network documentation in one container and then another one which is the Duke of Edinbrugh kit list.

Data is split into Assets, which are a collection of Fields. An Entry is an instance of an Asset which stores Values for the Fields. Some of the SQL queries are monsters, finding values only for entries that you have permission to read causes an interesting build up of conditions.

There is then a “simple” markdown document store, which can feed into a process list.

Finally there is a Password system that stores passwords and user account details using reversible encryption. The keys for which are set in environment variables.

All of these display their relationships and revisions, for example from our core switch entry.

It has a link to the Backups VLAN, as it is mentioned in the notes field for that VLAN. The link to the Server Room network cab comes from a relation on the cabinet that lists all the switches in the cab. We then have a link to the password for the switch.

There is then the revision history for the entry. From here we can go back to any point in the past for the entry.

Our asset list has become quite big:

We’ve found it invaluable being able to build the assets as we need. We’ve even found that we’ve been replacing some fields with whole assets, getting ready to add sub-assets as a future feature.

How is Net-Doc?

Net-Doc is built using Remix and Prisma which have both been amazing to work with. The database backend is an SQLite database which really suits this use-case.

There is quite a few packages included in Net-Doc that can all be found in the package.json.

What Next?

We aren’t done with Net-Doc, not by a long way. But today’s release gets us a stable base to build from, and ultimately if we stopped development today it would function no problem for anyone taking over the network.

All the enchancement ideas are listed on the GitHub issue tracker, so you can keep track of how was are going.

Links

• GitHub
• Docs