10 commandments for Documenting [(wip)]
-
Documentation as code.
I usually prefer having my documentation with my code. So although I have separated out my code from my /docs I will have markdown README.md files withing parent directories that will be inserted into relevant parts of this docs. This is Mainly to remind me to update these crucial bits.
-
Plan in Docs.
Call it spike if you're cooperate but Plan first then code or testing if your writing app code. Then update your docs to reflect the details.
-
Test.
The homelab should have a septate test environment for things I want to mess with, here I should be able to manually deploy containers / vms witch shouldn't affect or communicate with the prod env. Things such as Ansible playbooks and terraform should be first tested (as much as possible) here before we run in prod or core env.
-
NO secrets in my docs.
We will have a hc vault, use it!
-
Minimal Attack Surface.
Use a proxy / 0 trust service to expose to the internet anything that cant should be thrown into untrusted net eg; crafty
-
Hard segmentation between the 3 environments
core,productionandtesting -
All running VMs/Hosts should be centrally monitored.
- Use Bezel and Grafana for this.
- If ssh is enables something needs to be pinged on each attempt.
- TODO: look into finding a way to log ssh attempts.
-
Guests/user accounts should be created following the principle of least privilege.
-
Core Services* should be failover protected.
-
Fallow the 123 backing up strategy.
- 1 offsite - We will use an S3 Bucket for this
- 2 different medias
- 3 Copies (one air gapped)
Docs Patterns
Page Boilerplate
--
title: [Host Name]
summary: [e.g. Primary Proxmox Node / Offsite Backup VPS]
external_links:
- [Web GUI/Console URL]
- [Hardware Manual]
---
# [Service Name] Overview
**OS:** [e.g. Proxmox VE 8.x / Ubuntu 22.04]
**Hardware:** [e.g. Optiplex 7050 / Ryzen 5 5600G]
**CPU/RAM:** [Cores / Total Memory]
**Storage:** [ZFS Mirror / LVM / NVMe Details]
**Backup:** [Level 1, Level 2, Level 3, Level 4, Level 5]
**Host:** [VM/LXC/Node]
**IP/DNS:** [Static IP]
**Access:** [Proxy/VPN/Local]
**Purpose:** [Core Function]
## 1. Network Configuration
| Interface | IP Address | Gateway | VLAN | Role |
| :--- | :--- | :--- | :--- | :--- |
| eth0 | [Static IP] | [Gateway IP] | [ID] | Management |
| vmbr0 | [IP] | [Gateway IP] | [ID] | Bridge |
**MAC Address:** [XX:XX:XX:XX:XX:XX]
**SSH Port:** [22 / Custom]
## 1. Prerequisites
- OS/Env: [e.g. Debian/Proxmox]
- Dependencies: [e.g. Docker, Python]
- Network: [e.g. Port 80, 443]
## 2. Infrastructure Setup
### Directory Structure
```bash
# Update and install core utilities
apt update && apt install -y vim curl htop net-tools
```
--
title: [Guide for]
summary: [e.g. Setting up proxmox]
external_links:
- [service docs]
- [forms / youtube video]
---
## Summary (WIP)
### Objective
### Prerequisites
- Requirement 1
- Requirement 2
- ...
### Instructions
### Verification
### Troubleshooting
--
title: [Service Name]
summary: [What it does]
external_links:
- [Documentation]
- [Source Code]
---
# [Service Name] Overview
**Host:** [VM/LXC/Node]
**IP/DNS:** [Static IP]
**Access:** [Proxy/VPN/Local]
**Purpose:** [Core Function]
---
## 1. Prerequisites
- OS/Env: [e.g. Debian/Proxmox]
- Dependencies: [e.g. Docker, Python]
- Network: [e.g. Port 80, 443]
---
## 2. Infrastructure Setup
### Directory Structure
```bash
mkdir -p /path/to/app/data
mkdir -p /path/to/app/config
```
Extendible and Reusable note sections
Attaching raw text:
{{ read_raw (<file>) }}
Attaching csv files:
{{ read_csv (<file>) }}
Adding Banners:
Information:
Something new is coming to mkdocs-shadcn
Note:
We notice that x=2
Warning:
There is a risk doing x/0
Danger:
Don't look at node_modules please!
new:
Don't look at node_modules please!
!!! info "System Status: Work In Progress"
<br>
The [**Genesis State**](/genesis/) is currently being defined. Automation via Ansible and Terraform is in active development. Expect broken links and "under construction" signs.
---
!!! danger "System Status: Work In Progress"
<br>
The [**Genesis State**](/genesis/) is currently being defined. Automation via Ansible and Terraform is in active development. Expect broken links and "under construction" signs.
---
!!! warning "System Status: Work In Progress"
<br>
The [**Genesis State**](/genesis/) is currently being defined. Automation via Ansible and Terraform is in active development. Expect broken links and "under construction" signs.
---
Tags
[(production)][(prod)][(info)][(initialised)] [(ready)][(success)][(active)] [(test)][(warning)][(unallocated)] [(beta)][(danger)][(inactive)] [(tip)][(new)] [(question)] [(bug)] [(wip)][(neutral)]
If you want to add custome styling to tags wrap your text in the following syantax and add a class of it with lower caps, space into dashes.
[(test)]