docs: add full homelab documentation structure

2026-05-05 14:43:09 -05:00
parent ee8a412a69
commit 370998b8d5
20 changed files with 1405 additions and 24 deletions
--- a/docs/reference/HOMELAB_AI_CONTEXT.md
+++ b/docs/reference/HOMELAB_AI_CONTEXT.md
@@ -0,0 +1,56 @@
+# Homelab AI Context Document
+
+This document gives an AI assistant full context of this homelab for infrastructure questions, deployments, debugging, and planning.
+
+See the individual docs in this repo for detailed information:
+
+- [Architecture Overview](../architecture/ARCHITECTURE_OVERVIEW.md)
+- [Networking Model](../architecture/NETWORKING_MODEL.md)
+- [Hardware Inventory](../architecture/HARDWARE_INVENTORY.md)
+- [Services Directory](../architecture/SERVICES_DIRECTORY.md)
+- [Stack Standards](../operations/STACK_STANDARDS.md)
+- [Deployment Checklist](../operations/DEPLOYMENT_CHECKLIST.md)
+- [Storage Notes](../operations/DOCKERSTACK_STORAGE_NOTES.md)
+- [Backup Policy](../operations/BACKUP_POLICY.md)
+- [Secrets Management](../operations/SECRETS_MANAGEMENT.md)
+- [Troubleshooting](../troubleshooting/TROUBLESHOOTING.md)
+- [Known Quirks](../troubleshooting/KNOWN_QUIRKS.md)
+- [Serenity](../servers/SERENITY.md)
+- [PlausibleDeniability](../servers/PLAUSIBLEDENABILITY.md)
+- [N.O.M.A.D.](../servers/NOMAD.md)
+- [Meshtastic Stack](MESHTASTIC.md)
+- [Expansion Plan](../planning/HOMELAB_EXPANSION_PLAN.md)
+- [TODO](../planning/TODO.md)
+
+## Quick Reference
+
+### Communication Preferences
+- One command block at a time
+- Prefer scripted/automated solutions over interactive multi-step processes
+- Uses `fresh` editor (not nano) on Linux
+- Manages remote servers via SSH from Windows 11
+- Prefers MariaDB over PostgreSQL for standalone services
+
+### Three Servers
+| Server | Role | OS | IP |
+|--------|------|----|----|
+| Serenity | NAS / Media ingestion | Unraid 7.2.4 | 10.5.1.5 |
+| PlausibleDeniability | Primary Docker host | TrueNAS Scale 25.10.2.1 | LAN DHCP |
+| N.O.M.A.D. | Offline knowledge + game servers | Ubuntu 25.10 | 10.5.1.16 |
+
+### Deployment Pattern (PD)
+```bash
+cd /mnt/docker-ssd/docker/compose/<stack>
+docker compose --env-file .env config   # validate first
+docker compose --env-file .env up -d    # deploy
+docker logs <container> --tail 20       # verify
+```
+
+### Network names
+- Shared DB network: `ix-databases_shared-databases`
+- Reverse proxy network: `pangolin`
+
+### Storage decision
+- Write-heavy / DB / SQLite / GPU → `/mnt/docker-ssd/docker/appdata/<service>`
+- General config / non-fussy → `/mnt/tank/docker/appdata/<service>`
+- Media only → `/mnt/unraid/data/media/`
--- a/docs/reference/MESHTASTIC.md
+++ b/docs/reference/MESHTASTIC.md
@@ -0,0 +1,70 @@
+# Meshtastic Stack
+
+## Overview
+Self-hosted Meshtastic monitoring and management stack running on PlausibleDeniability.
+
+## Stack Location
+`/mnt/docker-ssd/docker/compose/meshtastic/`
+
+## Containers
+
+| Container | Image | Port | Purpose |
+|-----------|-------|------|---------|
+| meshmonitor | ghcr.io/yeraze/meshmonitor:4.2.0 | 8081→3001 | Main UI + backend |
+| meshmonitor (virtual node) | — | 4404 | TCP virtual node server |
+| meshmonitor-tileserver | maptiler/tileserver-gl-light | 8082→8080 | Offline map tiles |
+| meshmonitor-mqtt-proxy | ghcr.io/ln4cy/mqtt-proxy:master | — | MQTT→TCP bridge |
+| meshmonitor-upgrader | docker:latest | — | Auto-upgrade watchdog |
+
+## Architecture
+```
+Meshtastic Node (10.5.1.172)
+        ↓ MQTT
+meshmonitor-mqtt-proxy
+        ↓ TCP (port 4404)
+meshmonitor virtual node server
+        ↓
+meshmonitor backend
+        ↓
+PostgreSQL (shared-postgres, db: meshmonitor)
+```
+
+## Node Connection
+- Node IP: `10.5.1.172`
+- Connection type: MQTT via mqtt-proxy (not direct TCP)
+- mqtt-proxy connects to meshmonitor's virtual node server on port 4404
+
+## Storage
+- Appdata: `/mnt/tank/docker/appdata/meshmonitor/data` → `/data`
+- Scripts: `./scripts` → `/data/scripts` (must be pre-created on host)
+- Tiles: `./tiles` (gitignored — large .mbtiles files)
+
+## Auto-Upgrade
+`AUTO_UPGRADE_ENABLED=true` — meshmonitor checks for new images and triggers self-upgrade.
+
+**Important:** The upgrader mounts the compose directory as `/compose` inside the container. All relative bind mount paths (e.g. `./scripts`) resolve to `/compose/scripts` on the host when the upgrader re-runs compose. Since TrueNAS root filesystem is read-only, these directories must be pre-created:
+
+```bash
+mkdir -p /mnt/docker-ssd/docker/compose/meshtastic/scripts
+```
+
+## Networks
+- `default` (internal stack network)
+- `ix-databases_shared-databases` (meshmonitor only)
+- `pangolin` (meshmonitor + tileserver)
+
+## Public URL
+`https://meshmonitor.paccoco.com`
+
+## Known Warnings
+- Node `!dd972536` has a low-entropy public key — this is a device configuration issue, not a meshmonitor bug
+- Frequent connect/disconnect cycles in logs are normal when the MQTT proxy reconnects
+
+## Tiles
+Map tiles stored in `./tiles/`. Currently includes `zurich_switzerland.mbtiles` (34MB).
+Tiles directory is gitignored. To add new tiles, download `.mbtiles` files and place in the `tiles/` directory.
+
+## TODO
+- [ ] Document all running meshtastic-map container config
+- [ ] Document meshtastic-map-mosquitto and meshtastic-mqtt containers
+- [ ] Add healthcheck to meshmonitor container