Engineering Docs

Centralized internal engineering documentation for minhdqdev-org and the homelab infrastructure, powered by MkDocs Material.

📖 Live site (internal): https://engineering-docs.internal.minhdq.dev

---

What's Inside

Section	Content
Getting Started	How to work with this docs repo
Architecture	Org-level architecture overview and per-system designs (e.g. DSTA C4 model, diagrams, API contracts)
Homelab	Proxmox host, VMs, LXC containers, services, observability, tenants, incidents, operations, and proposals
Runbooks	Operational runbooks and incident response
ADRs	Architecture Decision Records

The Homelab section was migrated from the Docusaurus site that previously lived in minhdqdev-org/homelab under docs/.

---

Local Development

Prerequisites: Python 3.11+

pip install mkdocs-material mkdocs-minify-plugin

# Hot-reload dev server at http://localhost:8000
mkdocs serve

# Strict build (fails on broken links / nav) — run before opening a PR
mkdocs build --strict

---

Project Layout

engineering-docs/
├── docs/
│   ├── index.md                 # Home
│   ├── getting-started.md
│   ├── architecture/            # Org architecture + per-system (dsta/…)
│   ├── homelab/                 # Homelab infrastructure docs
│   │   ├── intro.md             #   topology overview
│   │   ├── ws/ vm/ ct/          #   Proxmox hosts / VMs / LXC containers
│   │   ├── srv/                 #   services (+ srv/observability/)
│   │   ├── tenants/ automation/ incidents/
│   │   └── ideas/               #   proposals & plans
│   ├── runbooks/
│   └── adrs/                    # Architecture Decision Records
├── mkdocs.yml                   # Site config + nav
├── requirements.txt
└── Dockerfile                   # Builds the static site, served via nginx

---

Deployment

On push to main, CI (.github/workflows/ci.yml) builds the Dockerfile and pushes the image to Harbor (harbor.internal.minhdq.dev/minhdqdev/engineering-docs), which is then deployed in the homelab Kubernetes cluster.

---

Contributing

1. Add or edit Markdown under docs/.
2. Register new pages in the nav section of mkdocs.yml.
3. Run mkdocs build --strict to catch broken links before opening a PR against main.