Authors Document

10 commandments for Documenting [(wip)]

1. 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.

2. 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.

3. 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.

4. NO secrets in my docs.

   We will have a hc vault, use it!

5. 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

6. Hard segmentation between the 3 environments

   core, production and testing

7. 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.

8. Guests/user accounts should be created following the principle of least privilege.

9. Core Services* should be failover protected.

10. 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

<div class="hl-registry-embed" data-id="R-<type>-<id>"></div>

--
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:

!!! 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)]

Custom Styler

Bit of a easter egg plugin, try Ctrl+C

RegI UI

This is my custom instances documentation as code (unfortunately JSON) Plugin to log:

• Bare-Metal Devices (metal)
• Network Devices (net)
• Virtual Machines (vm)
• Container Instances (ct)
• Services (ser)
• Cloud (cloud)
• IoT (iot)

Based on Inventory it will automatically generate a ID. Since I use Ben10 aliens for my naming we will use this for all but Container Instances and Services.

Logic behind this is if it has a shell it has a soul. --Probably a turtle

Read only Demo

Get A specific Instance using its ID

<div class="hl-registry-embed" data-id="R-<type>-<id>"></div>

Get A set of instances of a specific type

<div class="hl-registry-embed"
     data-type="Network"
     data-cols="avaDtar, name, make, model">
</div>

Custom columns

<div class="hl-registry-embed"
     data-cols="avatar, name, make, model">
</div>

data-cols Options

General & Identification: id type name hostName status aliases tags notes docs

Network: ipAddresses vlans macAddr dnsCnames subnets publicIP ports

Hardware & Specs: make model cpuDesc vCPUs ramGB diskGB disks

Virtualisation & Cloud: hypervisor vmId provider region instanceType accountId

Containers & Storage: image imageTag orchestrator volumes capacityTB raidLevel protocol shares

Other: parentId role firmware createdAt updatedAt actions