diff --git a/Documentation_Standards.md b/Documentation_Standards.md deleted file mode 100644 index e1f96cb..0000000 --- a/Documentation_Standards.md +++ /dev/null @@ -1,276 +0,0 @@ ---- -title: Netgrimoire Documentation -description: How to create and use Netgrimoire Docs -published: true -date: 2026-02-03T02:54:56.444Z -tags: -editor: markdown -dateCreated: 2026-02-03T02:54:56.444Z ---- - -# Homelab Documentation Structure & Diagram Standards - -This document describes the **official documentation structure** for the homelab Wiki.js instance, including: -- Folder and page layout -- Naming conventions -- How Git fits into the workflow -- How to use draw.io (diagrams.net) for diagrams -- How to ensure documentation is accessible when the lab is down - -This page is intended to be a **reference and enforcement guide**. - ---- - -## Core Principles - -1. **Wiki.js is the editor, Git is the source of truth** -2. **All documentation must be readable without Wiki.js** -3. **Diagrams must be viewable without draw.io** -4. **Folder structure must be predictable and consistent** -5. **Emergency documentation must not depend on the lab being up** - ---- - -## Repository Overview - -All documentation lives in a single Git repository. - -Wiki.js writes Markdown files into this repository automatically. -The repository can be cloned to a laptop or other device for **offline access**. - -Example: -```bash -git clone ssh://git@forgejo.example.com/homelab/docs.git -``` - ---- - -## Top-Level Folder Structure -``` -homelab-docs/ -├── README.md -├── emergency/ -├── infrastructure/ -├── storage/ -├── services/ -├── runbooks/ -├── diagrams/ -└── assets/ -``` - -### Folder Purpose - -| Folder | Purpose | -|--------|---------| -| README.md | Entry point when the lab is down | -| emergency/ | Recovery procedures and break-glass docs | -| infrastructure/ | Core systems (identity, backups, networking) | -| storage/ | Storage platforms and layouts | -| services/ | Application-specific documentation | -| runbooks/ | Step-by-step operational procedures | -| diagrams/ | All draw.io diagrams and exports | -| assets/ | Images or files used by documentation | - ---- - -## Storage Documentation Structure -``` -storage/ -└── core/ - ├── zfs.md - ├── local-drives.md - ├── nas.md - └── btrfs.md -``` - -**Guidelines:** -- Each storage technology gets its own page -- Pages describe architecture, layout, and operational notes -- Backup and snapshot policies belong elsewhere - ---- - -## Infrastructure Documentation Structure -``` -infrastructure/ -└── backups/ - ├── zfs-snapshots.md - └── application-backups.md -``` - -**Guidelines:** -- Infrastructure describes cross-cutting systems -- Anything used by multiple hosts or services belongs here -- Backup strategies are infrastructure, not storage - ---- - -## Services Documentation Structure -``` -services/ -└── mailcow.md -``` - -**Guidelines:** -- One page per service -- Page should include: - - Purpose - - Architecture - - Volumes - - Backup considerations - - Recovery notes - ---- - -## Emergency Documentation -``` -emergency/ -├── bring-up-order.md -├── swarm-recovery.md -├── zfs-import.md -├── network-restore.md -└── identity-break-glass.md -``` - -**Rules:** - -Emergency docs must be: -- Text-first -- Copy/paste friendly -- Free of dependencies - -These pages should be readable directly from Git. - ---- - -## Naming Conventions (Mandatory) - -**Folders:** -- Lowercase -- No spaces -- Example: `infrastructure/backups` - -**Page filenames:** -- Lowercase -- Hyphen-separated -- Example: `zfs-snapshots.md` - -**Page titles:** -- Human readable -- Proper case -- Example: `# ZFS Snapshots` - ---- - -## draw.io (diagrams.net) Usage - -draw.io is used **only to create diagrams**, never as the sole storage location. - -### Diagram Storage Layout -``` -diagrams/ -├── network/ -│ ├── core.drawio -│ ├── core.png -│ └── core.svg -├── docker/ -│ ├── swarm-architecture.drawio -│ └── swarm-architecture.png -└── storage/ - ├── zfs-layout.drawio - └── zfs-layout.png -``` - -### File Types - -| File | Purpose | -|------|---------| -| .drawio | Editable source | -| .png | Offline viewing | -| .svg | Zoomable / high quality (optional) | - -**Every diagram MUST have a PNG export.** - ---- - -## Adding a Diagram (Required Workflow) - -1. Create or edit the diagram in draw.io -2. Save the `.drawio` file into `diagrams//` -3. Export a `.png` (and optional `.svg`) -4. Commit all files to Git - -If a diagram cannot be viewed without draw.io running, it is **not complete**. - ---- - -## Embedding Diagrams in Wiki.js Pages - -Always embed PNG or SVG, never live editors. - -Example: -```markdown -![Core Network Diagram](../../diagrams/network/core.png) - -_Source file: core.drawio_ -``` - -This ensures: -- Fast rendering -- Offline viewing -- No service dependency - ---- - -## Git Workflow Expectations - -**Authoring:** -- All pages are created and edited in Wiki.js -- Wiki.js commits changes automatically - -**Offline Access:** -- Documentation is read directly from the Git clone -- Markdown and images must be sufficient without Wiki.js - -**What Not To Do:** -- Do not create wiki pages directly in Git -- Do not rename paths outside Wiki.js -- Do not store diagrams only inside draw.io - ---- - -## Lab-Down Access Model - -When the lab is unavailable: - -1. Open the local Git clone -2. Read `README.md` -3. Navigate to `emergency/` -4. View diagrams via `.png` files -5. Execute recovery steps - -**No services are required.** - ---- - -## README.md (Recommended Content) - -The root `README.md` should contain: -- Purpose of the documentation -- Where to start during an outage -- Link list to emergency procedures -- High-level architecture notes - ---- - -## Final Notes - -This structure is designed to: -- Scale cleanly -- Survive outages -- Remain readable for years -- Support automation and GitOps workflows - -**If documentation cannot be read when the lab is down, it is incomplete.** - -This structure makes that impossible. \ No newline at end of file diff --git a/Service_Document_Template.md b/Service_Document_Template.md deleted file mode 100644 index ce60e38..0000000 --- a/Service_Document_Template.md +++ /dev/null @@ -1,122 +0,0 @@ ---- -title: Service Documentation Template -description: Describe the service -published: true -date: 2026-02-03T02:57:07.462Z -tags: -editor: markdown -dateCreated: 2026-02-03T02:57:07.462Z ---- - -# Service Documentation Template - -Use this template for **every new service** documented under `services/`. - -Copy this file, rename it, and fill in all sections. - ---- - -# Service Name - -## Overview - -Brief description of what this service does and why it exists. - ---- - -## Architecture - -Describe how the service is deployed. - -Include: -- Host(s) -- Containers -- External dependencies -- Network exposure - ---- - -## Volumes & Data - -List all persistent data locations. -``` -/path/on/host → purpose -``` - -Include: -- What data is stored -- Whether it is critical -- Where backups occur - ---- - -## Configuration - -Document: -- Environment variables (non-secret) -- Configuration files -- Important defaults - -**Secrets must not be stored here.** Reference where they live instead. - ---- - -## Authentication & Access - -Describe: -- Authentication method -- Local access -- Break-glass access (if applicable) - ---- - -## Backups - -Explain: -- What is backed up -- How often -- Using what tool -- Where backups are stored - -Link to infrastructure backup docs if applicable. - ---- - -## Restore Procedure - -Step-by-step recovery instructions. -```bash -# example commands -``` - -This section must be usable when the service is broken. - ---- - -## Monitoring & Health - -Describe: -- How service health is checked -- Logs of interest -- Alerting (if any) - ---- - -## Common Failures - -List known failure modes and fixes. - ---- - -## Diagrams - -Embed architecture diagrams here. -```markdown -![Service Architecture](../diagrams//.png) -``` - ---- - -## Notes - -Anything that does not fit elsewhere. \ No newline at end of file