New Grimoire

Netgrimoire/Conventions/Doc-Standards.md

@@ -0,0 +1,276 @@
+---
+title: Netgrimoire Documentation
+description: How to create and use Netgrimoire Docs
+published: true
+date: 2026-02-20T04:16:19.329Z
+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.

Netgrimoire/Conventions/Service-Doc-Template.md

@@ -0,0 +1,122 @@
+---
+title: Service Documentation Template
+description: Describe the service
+published: true
+date: 2026-04-10T13:23:01.021Z
+tags: 
+editor: markdown
+dateCreated: 2026-02-03T02:57:07.462Z
+---
+
+# Service Documentation Template - 1
+
+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.

Netgrimoire/Conventions/Theme.md

@@ -0,0 +1,174 @@
+---
+title: Documentation Style Guide
+description: Applying a theme
+published: true
+date: 2026-02-25T21:32:16.786Z
+tags: 
+editor: markdown
+dateCreated: 2026-02-24T14:03:00.791Z
+---
+
+# Netgrimoire Theme — Wiki.js Implementation Guide
+
+## What You're Getting
+
+Two files to transform your Wiki.js library into the Netgrimoire aesthetic:
+
+| File | Purpose |
+|------|---------|
+| `netgrimoire-theme.css` | Global site theme — dark background, teal glow, Cinzel headers, animated sidebar |
+| `netgrimoire-hero-block.html` | Animated constellation hero banner for your library landing page |
+
+---
+
+## Part 1 — Apply the Global Theme CSS
+
+This is the main transformation. It reskins the entire Wiki.js UI.
+
+### Step 1: Open the Wiki.js Admin Panel
+
+Navigate to your Wiki.js instance and go to:
+
+```
+Administration (gear icon) → Theme
+```
+
+### Step 2: Locate "Custom CSS"
+
+On the Theme page, scroll down until you see the **"Custom CSS"** text area. It may be labelled "CSS Override" depending on your Wiki.js version.
+
+### Step 3: Paste the CSS
+
+Open `netgrimoire-theme.css`, select all (`Ctrl+A`), copy, and paste the entire contents into the Custom CSS field.
+
+### Step 4: Apply
+
+Click **"Apply"** or **"Save"** at the top or bottom of the Theme page. Wiki.js applies the CSS live — you do not need to restart the container.
+
+### Step 5: Verify
+
+Open your wiki in a new browser tab. You should see:
+
+- Dark `#0a0d12` background
+- Teal/cyan navigation links and headers
+- Cinzel serif font on headings
+- Glowing active sidebar item
+- Teal-bordered code blocks and tables
+
+**If styles are not applying**, do a hard refresh (`Ctrl+Shift+R`) to clear cached CSS.
+
+---
+
+## Part 2 — Add the Animated Hero Banner to Your Library Page
+
+This places a live constellation animation at the top of your document library index page.
+
+### Step 1: Open the Library Page for Editing
+
+Navigate to your document library landing page and click **Edit** (pencil icon, top right).
+
+### Step 2: Switch to Source / HTML Mode
+
+In the Wiki.js editor toolbar, look for one of the following depending on your editor:
+
+- **Markdown editor**: Click the `<>` or "Insert HTML Block" button
+- **Visual editor (WYSIWYG)**: Look for `< >` Source button, or Insert → HTML Block
+
+### Step 3: Paste the Hero HTML
+
+Open `netgrimoire-hero-block.html`, copy the full contents, and paste into the HTML block at the very top of your page, before any other content.
+
+### Step 4: Save the Page
+
+Click **Save**. The constellation animation will render automatically when the page loads.
+
+### Step 5: Customize (Optional)
+
+To change the banner title text, find this line in the HTML:
+
+```html
+>DOCUMENT LIBRARY</div>
+```
+
+Replace `DOCUMENT LIBRARY` with whatever you want (e.g., `THE GRIMOIRE`, `KNOWLEDGE VAULT`).
+
+To change the subtitle:
+
+```html
+>Netgrimoire Knowledge Vault</div>
+```
+
+---
+
+## Part 3 — Google Fonts (Internet Access Required)
+
+The theme imports three fonts automatically via Google Fonts:
+
+| Font | Used For |
+|------|---------|
+| Cinzel | Headers, nav section labels, card titles |
+| Share Tech Mono | Code blocks, inline code, footer |
+| Raleway | Body text, nav items, descriptions |
+
+These load via a `@import` at the top of the CSS and require your browser to have internet access when loading the page. Since Netgrimoire is a local server, this means:
+
+- **If your browser machine has internet**: Fonts load automatically — no action needed.
+- **If fully air-gapped**: The fonts will fall back to system serif/monospace. To self-host, download the font files and serve them from your Forgejo or a local nginx path, then replace the `@import` line with `@font-face` blocks pointing to your local URLs.
+
+---
+
+## Part 4 — Fine-Tuning
+
+### Adjusting the Teal Color
+
+All colors are defined as CSS variables at the top of the CSS file. To shift the color tone, change `--ng-teal`:
+
+```css
+:root {
+  --ng-teal: #00e5cc;   /* default — cyan-teal */
+  /* try:  #00cfff  for more blue */
+  /* try:  #39ff14  for neon green */
+  /* try:  #bf5fff  for purple arcane */
+}
+```
+
+### Making the Background Darker
+
+Adjust `--ng-bg-base` and `--ng-bg-deep`:
+
+```css
+:root {
+  --ng-bg-base: #070a0e;  /* even darker */
+  --ng-bg-deep: #030507;
+}
+```
+
+### Constellation Node Count
+
+In `netgrimoire-hero-block.html`, find:
+
+```javascript
+var NODE_COUNT = 55;
+```
+
+Increase for a denser network, decrease for a sparser, more minimal look.
+
+---
+
+## Troubleshooting
+
+| Symptom | Fix |
+|---------|-----|
+| CSS not applying | Hard refresh (`Ctrl+Shift+R`); check for syntax errors in the CSS field |
+| Fonts showing as Times New Roman | Browser lacks internet access; see Part 3 above |
+| Hero animation not rendering | Check browser console for JS errors; ensure the page saved the HTML block |
+| Sidebar colors still white | Some Wiki.js versions use different class names; inspect with browser DevTools and let Claude know which element needs targeting |
+| Dark mode toggle fighting the theme | Wiki.js's built-in dark mode toggle may conflict — set it to Dark in Administration → Theme before applying custom CSS |
+
+---
+
+## Notes
+
+- Wiki.js stores custom CSS in the database, so it survives container restarts.
+- After updating Wiki.js, re-check the Theme page — major version upgrades occasionally reset the CSS field.
+- The hero block is per-page; you can add it to any page you want the constellation effect on.