fkrebs/docs
1
0
Fork 0
Code Issues 14 Pull Requests Actions Packages Projects Releases Wiki Activity

docs: MCP gateway git/gitlab/paper-search; CT 109 plan; new backrest/db/arcane docs

Browse Source 
- mcp-gateway.md: 26 servers (added git, gitlab, paper-search catalog bridge);
  document --pass-environment requirement for env var passthrough in DinD bridges
- ct-inventory.md + homelab-architecture.md: CT 109 IP conflict, CT 113 live
- proxmox-state.md §16: Loki, sshwifty, Alloy, IP conflict note, sidecar table
  expanded to CT 103/111/113; build order updated
- infra/portmap.md: CT 113 db section; QNAP TS-251D (Klipper/Mainsail)
- services/backrest.md: full backup strategy doc (new)
- services/databases.md: CT 113 postgres/WAL-G/pgAdmin doc (new)
- services/arcane.md: Docker management IDE doc (new)
- CHANGELOG.md: 2026-05-22 entry

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
Florian Krebs
2026-05-22 09:35:07 +02:00
parent 0def5c0be9
commit 0d83f83bc0
9 changed files with 693 additions and 116 deletions
Download Patch File Download Diff File Expand all files Collapse all files
infra/portmap.md
+26 -2
View File
@@ -83,7 +83,7 @@ All arr-stack services run behind `vpn_gluetun` container network.
| [18005](http://192.168.1.40:18005) | Docling MCP | `docling-mcp` | — | SAIA Docling PDF→Markdown; reachable via gateway |
| [18007](http://192.168.1.40:18007) | Kroki MCP | `kroki-mcp` | — | Diagram rendering; reachable via gateway |
| [18009](http://192.168.1.40:18009) | Speaches | `speaches` | — | TTS/STT; LAN only |
| ~~18010~~ | ~~Shepard MCP~~ | ~~`shepard-mcp`~~ | — | **DECOMMISSIONED 2026-05-21** — Shepard will provide a native MCP server |
| ~~18010~~ | ~~Shepard MCP~~ | ~~`shepard-mcp`~~ | — | **DECOMMISSIONED 2026-05-21** — replaced by native `https://shepard.nuclide.systems/v2/mcp` (streamable HTTP; gateway entry: `shepard`, auth via `${SHEPARD_API_KEY}`) |
| [18011](http://192.168.1.40:18011) | Upload-artifact MCP | `upload-artifact-mcp` | — | S3 chat-artifacts upload; reachable via gateway |
| — | SearXNG | `searxng` | — | Internal, `shared_backend`, used by LobeHub |
@@ -136,7 +136,18 @@ _Traccar moved to 15000–15001 (Documents range). 19000–19001 now free._
| Port | Service | Container | Public URL | Notes |
|---|---|---|---|---|
| 20010 (127.0.0.1 only) | pgAdmin | `pgadmin` | — | localhost only |
| 20010 (127.0.0.1 only) | pgAdmin | `pgadmin` | — | shared-db pgAdmin, localhost only (CT 104) |
---
## LXC 113 — db (`192.168.1.6`)
CT 113 is the dedicated postgres LXC. No public proxy routes — LAN access only.
| Port | Service | Container | Notes |
|---|---|---|---|
| 5432 | Postgres 17 | `postgres` | LAN: `192.168.1.6:5432` — accepts app connections from all CTs |
| 5050 | pgAdmin 4 | `pgadmin` | LAN only: `http://192.168.1.6:5050` — no Zoraxy route |
---
@@ -157,6 +168,19 @@ CT 111 hosts the self-hosted dev platform. Same Pocket-ID SSO as the rest.
---
## QNAP TS-251D (`192.168.1.189`)
Celeron J4025, 2-core. Hosts Klipper natively (not Docker).
| Port | Service | Notes |
|---|---|---|
| 80 | Mainsail | 3D printer web UI |
| 7125 | Moonraker | Klipper API |
Config backed up daily to `git.nuclide.systems/fkrebs/klipper-config` via cron at 03:00 → covered offsite by Backrest `services/gitea` path.
---
## External Services (Not on NUC Docker)
Zoraxy routes to these external backends:
infra/proxmox-state.md
+30 -18
View File
@@ -712,30 +712,41 @@ Recovery latency improved from 5 min → 1 min; logging structured in `journalct
## 16. CT 109 "observe" — planned observability + ops LXC
Single LXC holding everything monitoring/ops-shaped. Sizing target: **4 cores / 6 GiB RAM / 30 GiB rootfs**, unprivileged, nesting=1, IP `192.168.1.6` (next free in the infra range after CT 110).
Single LXC holding everything monitoring/ops-shaped. Sizing target: **4 cores / 8 GiB RAM / 50 GiB rootfs**, unprivileged, nesting=1. RAM bumped from 6 → 8 GiB to accommodate Loki. Disk bumped from 30 → 50 GiB for Loki log retention (30d) alongside Prometheus TSDB.
⚠️ **IP conflict:** inventory originally assigned `192.168.1.6` but CT 113 (db) is already live at `.6`. CT 109 needs the next free infra IP — likely `.7` or `.8` (verify against UniFi DHCP table before provisioning).
**Access model (initial):** LAN-only. No Zoraxy routes until Tinyauth is deployed. Services reachable directly by IP.
### Stack to deploy on CT 109
| Service | Purpose |
|---|---|
| Arcane Manager | central docker management UI; edge agents on CT 101 + CT 104 + CT 110 (mTLS, agent-dialed-out) |
| Dozzle UI | aggregated container logs; Dozzle agents on CT 101 + CT 104 + CT 110 |
| Prometheus | metrics TSDB, 30 d retention |
| Grafana | dashboards over Prometheus |
| Prometheus | metrics TSDB, 30d retention |
| Loki | log aggregation backend — receives from Alloy agents on all hosts |
| Grafana | dashboards over Prometheus + Loki (unified metrics + log search) |
| Alertmanager + alertmanager-gotify-bridge | alert routing → Gotify |
| **Homarr** (selected over Homepage) | unified dashboard, native OIDC with Pocket-ID, native Prometheus widget + Grafana iframe support |
| Arcane Manager | central docker management UI; edge agents on CT 101 + CT 104 + CT 110 (mTLS, agent-dialed-out) |
| Dozzle UI | live log tail (quick debugging); agents on CT 101 + CT 104 + CT 110. Complements Loki — Dozzle for live, Loki for historical/search |
| **Homarr** | unified dashboard, native Pocket-ID OIDC, Prometheus widget + Grafana iframe support |
| Diun | docker image update notifier → Gotify |
| Tinyauth | forward-auth gate for non-OIDC apps (Backrest, raw Dozzle, raw Prometheus, raw Grafana). Speaks OIDC client to Pocket-ID, returns Basic-Auth/Remote-User header to upstream |
| docker-socket-proxy | local + remote (CT 101/104/110) — hardened read-only docker.sock for Homarr discovery |
| Tinyauth | forward-auth gate for non-OIDC apps (Backrest, raw Dozzle, raw Prometheus, raw Grafana/Loki). OIDC client to Pocket-ID |
| docker-socket-proxy | local + remote (CT 101/104/110) — hardened read-only docker.sock for Homarr/Arcane discovery |
| **sshwifty** | web SSH client, multi-tab — multiple concurrent shells to different hosts (PVE, CT 104, CT 103, CT 111, etc.). LAN-only, port 8182. SSH key auth per host, no password prompt. Zoraxy + Tinyauth gate deferred. |
### Sidecars deployed on each Docker host
### Sidecars deployed on each host
Two agents per host — **node-exporter** (metrics) and **Alloy** (logs). Kept separate: node-exporter metric names are assumed by every Prometheus dashboard/alert; Alloy emitting compatible metrics adds validation risk for no gain.
| Host | Sidecars |
|---|---|
| Host (PVE) | node-exporter, smartctl-exporter, pve-exporter (host metrics into Prometheus) |
| CT 101 | node-exporter, cAdvisor, Dozzle agent, Arcane edge agent, docker-socket-proxy |
| CT 104 | node-exporter, cAdvisor, Dozzle agent, Arcane edge agent, docker-socket-proxy |
| CT 110 | node-exporter, Dozzle agent, Arcane edge agent (test target — small/clean) |
| PVE host | node-exporter, smartctl-exporter, pve-exporter, **Alloy** (journald → Loki: pve-manager, pveproxy, pvedaemon, LXC/VM lifecycle) |
| CT 101 | node-exporter, cAdvisor, Dozzle agent, Arcane edge agent, docker-socket-proxy, **Alloy** (Docker logs + journald → Loki) |
| CT 103 | node-exporter, **Alloy** (backrest.service journal + `/var/log/rclone-*.log` → Loki) |
| CT 104 | node-exporter, cAdvisor, Dozzle agent, Arcane edge agent, docker-socket-proxy, intel_gpu_exporter, **Alloy** (Docker logs + journald → Loki) |
| CT 110 | node-exporter, Dozzle agent, Arcane edge agent, **Alloy** (journald → Loki) |
| CT 111 | node-exporter, intel_gpu_exporter, **Alloy** (journald + Coder/Gitea logs → Loki) |
| CT 113 | node-exporter, postgres_exporter, **Alloy** (journald + postgres logs → Loki) |
### Services that stay where they are (NOT on CT 109)
@@ -774,11 +785,12 @@ Build-order slot: after Arcane + socket-proxy land in §16's checklist, before T
4. Issue agent tokens, deploy Edge agents on CT 101/104/110
5. Deploy Dozzle Manager + agents
6. Deploy Diun
7. Deploy Tinyauth (configure Pocket-ID client first)
8. Deploy Homarr
9. Front the lot via Zoraxy: `arcane.`, `dozzle.`, `grafana.`, `prom.`, `home.` `.nuclide.systems`
10. Verify each through the Tinyauth gate where applicable
11. Add Diun watchlist + Alertmanager routing → Gotify
7. Deploy sshwifty (configure host list + SSH keys for PVE, CT 103, CT 104, CT 111; LAN-only port 8182)
8. Deploy Tinyauth (configure Pocket-ID client first)
9. Deploy Homarr
10. Front the lot via Zoraxy: `arcane.`, `dozzle.`, `grafana.`, `prom.`, `home.`, `shell.` `.nuclide.systems`
11. Verify each through the Tinyauth gate where applicable
12. Add Diun watchlist + Alertmanager routing → Gotify
---