Knowledge Base

When I write a solution for myself, such as my gallery or my transparent web proxy, I write a master document that describes how I built it, why I built it, and how to use it. Why I built it usually starts the document, and explains what I needed it for: What problem it solves. Sometimes my solutions are proof-of-concept or demonstrations only. But still, I like to remind my future self of what it's for. How I built it ("Architecture") is the section that explains the initial steps, such as packages installed, users added, selinux contexts or policies built (and not necessarily the methodology for building an selinux policy, at this point, due to the repetition), pip packages versus system packages, and so on. Anything that I needed to do only once for the solution (per host, if a multi-node solution). The how to use it section is titled "Operations." I describe how to do tasks, such as set up a new entry or new instance, or modify a commonly-updated setting. This section tends to grow over time as I update the solution. On rare occasions I need to update the architecture section of the document because I had to make a one-time change for the solution. The how-to section can duplicate some information from the Architecture section, if I expect some of those first-time steps are what are repeated for the proposed future steps. When I publish a solution, I try to move all my configs to a separate conf file, so that I can include a app.conf.example file or similar, and exclude app.conf from source control. I even have a small sed script that helps scrub my private data:

$ sed -r -f /mnt/public/work/gitlab/scrub.sed < app.conf > app.conf.example

The contents of the script are mostly just substitutions.

s/privateservername([0-9]*)/serve\1/g;
s/username73/exampleuser5/g;

I always include a References section, so that I can review my sources in the future. I do return to them, because I am seeking to expand my solution or fix a part that breaks (i.e., used to work but doesn't now).