docs: add CHANGELOG, ct-inventory, rewrite README as TOC
This commit is contained in:
@@ -1,85 +1,69 @@
|
||||
# nuclide.systems — Infrastructure Docs
|
||||
# nuclide.systems docs
|
||||
|
||||
Central documentation for the `nuc` Proxmox homelab and all hosted services.
|
||||
**Source of truth:** `/docs/` on the Proxmox host (`192.168.1.20`).
|
||||
This directory is the entry point — docs generated anywhere else should land here.
|
||||
Single source of truth for the homelab. Git-tracked since 2026-05-20.
|
||||
|
||||
---
|
||||
## Read this first
|
||||
- **[`/CLAUDE.md`](../CLAUDE.md)** (host root) — operator doctrine for any AI agent SSHing in. Skim before touching anything.
|
||||
- **[`CHANGELOG.md`](CHANGELOG.md)** — what changed and when.
|
||||
- **[`ct-inventory.md`](ct-inventory.md)** — canonical roster of LXCs / VM, IPs, role, sizing.
|
||||
|
||||
## Infrastructure
|
||||
## Layout
|
||||
|
||||
| File | Contents |
|
||||
|------|----------|
|
||||
| [proxmox-optimizations.md](proxmox-optimizations.md) | Full audit, sizing decisions, action log, pending tasks |
|
||||
```
|
||||
/docs/
|
||||
├── README.md ← you are here
|
||||
├── CHANGELOG.md ← dated bullets of every infra change
|
||||
├── ct-inventory.md ← LXC/VM roster (single source of truth)
|
||||
│
|
||||
├── infra/ ← host-level + cross-cutting state
|
||||
│ └── proxmox-state.md ← the 900-line master state doc (sizing, ZFS, NFS, DNS)
|
||||
│
|
||||
├── services/ ← per-service operational docs (current truth)
|
||||
│ ├── homelab-architecture.md topology + design rationale
|
||||
│ ├── dev-environment.md Coder + Gitea on CT 111
|
||||
│ ├── mcp-gateway.md MCP gateway on CT 104
|
||||
│ ├── comfyui.md
|
||||
│ ├── zoraxy.md reverse proxy
|
||||
│ ├── adguard-dns.md DNS + rewrites
|
||||
│ ├── cloud-gpu.md GPU passthrough + future external GPU
|
||||
│ └── pocket-id.md [planned] OIDC IdP + client registry
|
||||
│
|
||||
├── stacks/ ← CT 104 docker stacks notes
|
||||
│ ├── PORTMAP.md canonical service → port → public hostname registry
|
||||
│ ├── CLAUDE.md agent breadcrumbs (CT 104 specific)
|
||||
│ ├── storage.md [being rewritten] storage class per service
|
||||
│ ├── volumes.md [being rewritten] volume bindings per stack
|
||||
│ ├── docker-networks.md
|
||||
│ └── todo.md
|
||||
│
|
||||
├── history/ ← frozen / archived
|
||||
│ ├── traefik-migration.md ABANDONED 2026-05-16 (Zoraxy chosen)
|
||||
│ ├── traefik-migration-docker-labels.md ABANDONED 2026-05-16
|
||||
│ ├── mcp-gateway-requirements.md SUPERSEDED by services/mcp-gateway.md
|
||||
│ ├── scrubbing-list-2026-05-17.md snapshot of cleanup pass
|
||||
│ └── case-study.md narrative writeup
|
||||
│
|
||||
└── ideas/
|
||||
└── stack-ideas.md
|
||||
```
|
||||
|
||||
---
|
||||
## Operating principles
|
||||
See [`/CLAUDE.md`](../CLAUDE.md) for the full doctrine. Highlights:
|
||||
1. Keep services running; surface synergies and gaps.
|
||||
2. Enforce consistency: Pocket-ID OIDC, Zoraxy + ACME, `<svc>.nuclide.systems`, secrets in `.env`.
|
||||
3. Plan rollback at medium+ risk (ZFS snapshots, fresh experimental CTs).
|
||||
4. Every service should be AI-accessible (MCP / Coder workspace CLI / documented API).
|
||||
5. Test end-to-end before declaring done.
|
||||
6. Generate slash commands for recurring maintenance.
|
||||
|
||||
## Docker Stacks (CT 104 / 192.168.1.40)
|
||||
## Quick links
|
||||
- Pocket-ID admin: `https://id.nuclide.systems`
|
||||
- Gitea: `https://git.nuclide.systems`
|
||||
- Coder: `https://dev.nuclide.systems`
|
||||
- Nextcloud: `https://nc.nuclide.systems`
|
||||
- MCP gateway: `https://mcp.nuclide.systems`
|
||||
- Zoraxy admin: CT 108 (operator-only; **always confirm before any change** — see `[[feedback_zoraxy_confirm]]`)
|
||||
- Proxmox PVE: `https://192.168.1.20:8006`
|
||||
|
||||
### Service docs (`stacks/docs/`)
|
||||
|
||||
| File | Contents |
|
||||
|------|----------|
|
||||
| [homelab-architecture.md](stacks/docs/homelab-architecture.md) | Overall architecture overview |
|
||||
| [mcp-gateway.md](stacks/docs/mcp-gateway.md) | MCP gateway design and endpoints |
|
||||
| [mcp-gateway-requirements.md](stacks/docs/mcp-gateway-requirements.md) | MCP gateway requirements |
|
||||
| [zoraxy-setup.md](stacks/docs/zoraxy-setup.md) | Zoraxy reverse proxy setup notes |
|
||||
| [AdGuard-DNS-writes.md](stacks/docs/AdGuard-DNS-writes.md) | AdGuard DNS rewrite rules |
|
||||
| [comfyui-mcp.md](stacks/docs/comfyui-mcp.md) | ComfyUI MCP integration |
|
||||
| [dev-environment.md](stacks/docs/dev-environment.md) | CT 111 Coder + Gitea dev platform |
|
||||
| [traefik-migration.md](stacks/docs/traefik-migration.md) | Traefik → Zoraxy migration notes |
|
||||
| [traefik-migration-docker-labels.md](stacks/docs/traefik-migration-docker-labels.md) | Label mapping reference |
|
||||
| [cloud-gpu-extension.md](stacks/docs/cloud-gpu-extension.md) | Cloud GPU burst setup |
|
||||
| [scrubbing-list.md](stacks/docs/scrubbing-list.md) | Services to clean up / decommission |
|
||||
| [stack-ideas.md](stacks/docs/stack-ideas.md) | Backlog of stack ideas |
|
||||
| [case-study.md](stacks/docs/case-study.md) | Case study writeup |
|
||||
|
||||
### Operational (`stacks/`)
|
||||
|
||||
| File | Contents |
|
||||
|------|----------|
|
||||
| [PORTMAP.md](stacks/PORTMAP.md) | Port assignments for all services |
|
||||
| [storage.md](stacks/storage.md) | Volume and storage layout |
|
||||
| [volumes.md](stacks/volumes.md) | Docker volume inventory |
|
||||
| [docker-networks.md](stacks/docker-networks.md) | Docker network topology |
|
||||
| [todo.md](stacks/todo.md) | Outstanding stack tasks |
|
||||
| [CLAUDE.md](stacks/CLAUDE.md) | Agent breadcrumbs (migrated stacks, dormant services) |
|
||||
|
||||
---
|
||||
|
||||
## Nexa Project (`stacks/nexa/`)
|
||||
|
||||
| File | Contents |
|
||||
|------|----------|
|
||||
| [README.md](stacks/nexa/README.md) | Project overview |
|
||||
| [docs/01-vision-and-scope.md](stacks/nexa/docs/01-vision-and-scope.md) | Vision and scope |
|
||||
| [docs/02-roadmap.md](stacks/nexa/docs/02-roadmap.md) | Roadmap |
|
||||
| [docs/03-architecture.md](stacks/nexa/docs/03-architecture.md) | Architecture |
|
||||
| [docs/04-integration-matrix.md](stacks/nexa/docs/04-integration-matrix.md) | Integration matrix |
|
||||
| [docs/05-command-system.md](stacks/nexa/docs/05-command-system.md) | Command system |
|
||||
| [docs/06-classification-logic.md](stacks/nexa/docs/06-classification-logic.md) | Classification logic |
|
||||
| [docs/07-workflow-spec.md](stacks/nexa/docs/07-workflow-spec.md) | Workflow spec |
|
||||
| [docs/08-graphrag-architecture.md](stacks/nexa/docs/08-graphrag-architecture.md) | GraphRAG architecture |
|
||||
| [docs/09-deployment.md](stacks/nexa/docs/09-deployment.md) | Deployment |
|
||||
| [docs/10-operations.md](stacks/nexa/docs/10-operations.md) | Operations |
|
||||
| [docs/11-open-questions.md](stacks/nexa/docs/11-open-questions.md) | Open questions |
|
||||
| [docs/12-optimization-opportunities.md](stacks/nexa/docs/12-optimization-opportunities.md) | Optimization opportunities |
|
||||
| [docs/13-information-wishlist.md](stacks/nexa/docs/13-information-wishlist.md) | Information wishlist |
|
||||
|
||||
---
|
||||
|
||||
## AI Agents (`stacks/ai/`)
|
||||
|
||||
| File | Contents |
|
||||
|------|----------|
|
||||
| [home-info.md](stacks/ai/home-info.md) | Home context for agents |
|
||||
| [morning-briefing-agent.md](stacks/ai/morning-briefing-agent.md) | Morning briefing agent config |
|
||||
| [PROMPTING-2026.md](stacks/ai/PROMPTING-2026.md) | Prompting guide 2026 |
|
||||
|
||||
---
|
||||
|
||||
## Contributing
|
||||
|
||||
- Drop new docs in the appropriate subdirectory
|
||||
- Update this README when adding a new section
|
||||
- When CT 109 (management LXC) is built, the docs platform will serve this directory
|
||||
## Repo
|
||||
After git-init on 2026-05-20, mirrored to Gitea at `fkrebs/docs` (pending).
|
||||
|
||||
Reference in New Issue
Block a user