From d85b984c71ed18ad6188d35e268878126e5cf913 Mon Sep 17 00:00:00 2001 From: Administrator Date: Tue, 3 Feb 2026 02:55:08 +0000 Subject: [PATCH 1/2] docs: create Documentation_Standards --- Documentation_Standards.md | 276 +++++++++++++++++++++++++++++++++++++ 1 file changed, 276 insertions(+) create mode 100644 Documentation_Standards.md diff --git a/Documentation_Standards.md b/Documentation_Standards.md new file mode 100644 index 0000000..e1f96cb --- /dev/null +++ b/Documentation_Standards.md @@ -0,0 +1,276 @@ +--- +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 From e3ee94cbf66b89e127c8b70f05376bd7b39156de Mon Sep 17 00:00:00 2001 From: Administrator Date: Tue, 3 Feb 2026 02:57:19 +0000 Subject: [PATCH 2/2] docs: create Service_Document_Template --- Service_Document_Template.md | 122 +++++++++++++++++++++++++++++++++++ 1 file changed, 122 insertions(+) create mode 100644 Service_Document_Template.md diff --git a/Service_Document_Template.md b/Service_Document_Template.md new file mode 100644 index 0000000..ce60e38 --- /dev/null +++ b/Service_Document_Template.md @@ -0,0 +1,122 @@ +--- +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