traveler/Netgrimoire
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Compare commits

base: traveler:e3ee94cbf66b89e127c8b70f05376bd7b39156de
Branches Tags
traveler:main
..
compare: traveler:b4a5e5135622c5b8b8f8a71acb2d80a1306b01c2
Branches Tags
traveler:main

No commits in common. "e3ee94cbf66b89e127c8b70f05376bd7b39156de" and "b4a5e5135622c5b8b8f8a71acb2d80a1306b01c2" have entirely different histories.
e3ee94cbf6 ... b4a5e51356

2 changed files with 0 additions and 398 deletions
Download patch file Download diff file Expand all files Collapse all files

276
Documentation_Standards.md
View file

@ -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/<category>/`
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.

122
Service_Document_Template.md
View file

@ -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/<category>/<diagram>.png)
```
---
## Notes
Anything that does not fit elsewhere.