Enhance setup documentation for sec-mcp stack with detailed preflight checks, Proxmox LXC configuration, and first test flow guidance

2026-07-01 12:50:00 -04:00 · 2026-02-28 18:30:04 -05:00
parent a958c31ecf
commit 82e9cd59d7
2 changed files with 160 additions and 13 deletions
@@ -5,16 +5,113 @@ This stack exposes MCP servers through `mcpo` as OpenAPI endpoints.
 - `mcpo` URL from host: `http://localhost:8000`
 - `mcpo` URL from inside Docker network (Open WebUI): `http://mcpo:8000`

-## 1) Start the stack
+## Preflight checklist (run before first launch)

-```powershell
+Run these in the target runtime environment (inside your LXC if using Proxmox):
+
+```bash
+ls -l /dev/kfd
+ls -l /dev/dri
+docker info
+docker compose config
 docker compose up -d --build
 ```

-For AMD GPU Ollama (Linux ROCm hosts):
+Expected outcomes:
+
+- `/dev/kfd` and `/dev/dri` exist
+- Docker daemon is healthy (`docker info` succeeds)
+- Compose config parses cleanly (`docker compose config` succeeds)
+- Stack starts without immediate container exits
+
+### Quick failure mapping
+
+| Failing check | Typical cause | Fast fix |
+|---|---|---|
+| `ls -l /dev/kfd` | GPU device not exposed to runtime | Verify host GPU/ROCm setup and LXC passthrough mounts |
+| `ls -l /dev/dri` | DRM device not exposed | Re-check `/etc/pve/lxc/<CTID>.conf` bind for `/dev/dri` |
+| `docker info` | Docker daemon not running / no permission | Start Docker service and verify LXC nesting/keyctl config |
+| `docker compose config` | YAML/env interpolation error | Validate `.env` values and recent edits to `docker-compose.yml` |
+| `docker compose up -d --build` | Service build/start failure | Check logs with `docker compose logs -f <service>` and fix first failing service |
+
+## 0) Proxmox LXC (ROCm) setup
+
+Use this section only when running the stack inside a Proxmox LXC container.
+
+### A. Verify GPU devices on Proxmox host
+
+On the Proxmox node:
+
+```bash
+ls -l /dev/kfd
+ls -l /dev/dri
+```
+
+If these do not exist on the host, fix AMD/ROCm host setup first.
+
+### B. Configure LXC for Docker + GPU passthrough
+
+Edit `/etc/pve/lxc/<CTID>.conf` on the Proxmox host and add:
+
+```ini
+features: nesting=1,keyctl=1
+lxc.apparmor.profile: unconfined
+lxc.cgroup2.devices.allow: c 226:* rwm
+lxc.cgroup2.devices.allow: c 235:* rwm
+lxc.mount.entry: /dev/dri dev/dri none bind,optional,create=dir
+lxc.mount.entry: /dev/kfd dev/kfd none bind,optional,create=file
+```
+
+Then restart the container:
+
+```bash
+pct restart <CTID>
+```
+
+### C. Validate inside the LXC container
+
+Inside the container:
+
+```bash
+ls -l /dev/kfd
+ls -l /dev/dri
+docker info
+```
+
+If `docker info` fails, complete Docker installation/config in the LXC first.
+
+### D. Continue with this guide
+
+After device and Docker validation succeed, continue with step 1 below.
+
+### E. Known caveats (LXC + Docker + ROCm)
+
+- **Unprivileged LXC may block device access**  
+  Symptom: `/dev/kfd` exists but Ollama fails to initialize ROCm.  
+  Quick fix: test with a privileged container profile or ensure device cgroup + mount entries are applied exactly.
+
+- **`docker info` fails inside LXC**  
+  Symptom: Docker daemon unreachable or permission denied.  
+  Quick fix: ensure Docker is installed/running inside the CT and `nesting=1,keyctl=1` is set in LXC config.
+
+- **`/dev/dri` or `/dev/kfd` missing after restart**  
+  Symptom: devices present on host but not in CT.  
+  Quick fix: re-check `/etc/pve/lxc/<CTID>.conf`, then `pct restart <CTID>`.
+
+- **Open WebUI can’t reach mcpo by service name**  
+  Symptom: OpenAPI import errors when using `http://mcpo:8000/...`.  
+  Quick fix: ensure Open WebUI and mcpo are in the same compose project/network; otherwise use host URL.
+
+- **ROCm performance or init instability**  
+  Symptom: model load failures or very slow startup.  
+  Quick fix: verify host ROCm compatibility first, then test Ollama alone before bringing full stack up.
+
+## 1) Start the stack
+
+This deployment assumes a ROCm-capable Linux host for Ollama (`/dev/kfd` and `/dev/dri`).

 ```powershell
-docker compose -f docker-compose.yml -f docker-compose.ollama-amd.yml up -d --build
+docker compose up -d --build
 ```

 ## 2) Open Open WebUI
@@ -75,6 +172,40 @@ From host browser:

 If these are reachable, Open WebUI can import them.

+## 6) First successful test flow (3 prompts)
+
+Run these in Open WebUI after your OpenAPI servers are connected.
+
+1. **CVE lookup path (`nvd-cve-mcp-server`)**
+
+Prompt:
+
+```text
+Use the nvd-cve-mcp-server tools to search CVEs for "OpenSSL" and return the top 3 with CVE ID, severity, and published date.
+```
+
+2. **Web conversion path (`markdownify-mcp`)**
+
+Prompt:
+
+```text
+Use markdownify-mcp to convert https://example.com to markdown and summarize it in 5 bullet points.
+```
+
+3. **Security scan tool path (`mcp-zap-server`)**
+
+Prompt:
+
+```text
+Use mcp-zap-server tools to list available scan-related tools and explain which one to run first for a baseline web assessment.
+```
+
+Expected result:
+
+- Tool calls execute without auth/network errors.
+- You get structured output from at least 2 different MCP backends.
+- Open WebUI can repeatedly call the same server without reconnecting/importing again.
+
 ## Troubleshooting

 - OpenAPI URL fails in Open WebUI container:
@@ -85,3 +216,15 @@ If these are reachable, Open WebUI can import them.
  - Verify `.env` values for `MCP_ZAP_API_KEY` and `ZAP_API_KEY`.
 - Markdown file retrieval blocked:
  - Verify `MD_SHARE_DIR` in `.env` and ensure files are in that directory.
+
+### Runtime failure mapping
+
+| Symptom | Likely cause | Fast fix |
+|---|---|---|
+| Open WebUI fails to import OpenAPI URL | Wrong base URL for deployment context | Use `http://mcpo:8000/...` when Open WebUI is in Docker, `http://localhost:8000/...` when outside |
+| OpenAPI import succeeds but tools fail at call time | Missing/incorrect mcpo auth header | Add `Authorization: Bearer <MCPO_API_KEY>` (or `X-API-Key`) in OpenAPI server settings |
+| `mcp-zap-server` tools return auth errors | `MCP_ZAP_API_KEY`/`ZAP_API_KEY` mismatch | Recheck `.env`, restart stack, confirm rendered config in mcpo logs |
+| No tools visible for one server route | Upstream MCP server failed to start | `docker compose logs -f <service>` and fix startup error first |
+| Open WebUI works but no local models in chat | Ollama reachable but model not pulled | Run `docker compose exec ollama ollama pull llama3.2` |
+| Ollama requests fail or time out | ROCm/device/runtime issue | Verify `/dev/kfd` and `/dev/dri`, then test Ollama container health and logs |
+| Markdownify `get-markdown-file` rejects paths | File outside allowed share directory | Place file under `MD_SHARE_DIR` path and retry |
@@ -2,6 +2,8 @@

 Security-focused MCP stack routed through `mcpo`, with Open WebUI + Ollama included.

+This stack is **ROCm-only** for Ollama.
+
 ## Included MCP servers

 - `triv3/mcp-kali-server`
@@ -13,13 +15,22 @@ Security-focused MCP stack routed through `mcpo`, with Open WebUI + Ollama inclu

 ## Files

- `docker-compose.yml` - AMD ROCm override for Ollama
+- `docker-compose.yml` - Main stack (Ollama runs with ROCm)
 - `mcpo-config.template.json` - Templated `mcpo` multi-server config
 - `.env.example` - Environment variable template
 - `OPENWEBUI_MCP_SETUP.md` - Step-by-step MCP setup inside Open WebUI

 ## Quick start

+Prerequisites for Ollama on ROCm hosts:
+
+- Linux host with ROCm-compatible AMD GPU
+- Device access available for `/dev/kfd` and `/dev/dri`
+
+Running in Proxmox LXC?
+
+- Follow the dedicated LXC section in `OPENWEBUI_MCP_SETUP.md` before launching (includes known caveats and quick fixes).
+
 1. Create env file:

 ```powershell
@@ -38,14 +49,6 @@ docker compose up -d --build
 - MCPO docs: `http://localhost:8000/docs`
 - Ollama API: `http://localhost:11434`

-## AMD GPU (Ollama ROCm)
-
-Use this only on Linux hosts with `/dev/kfd` and `/dev/dri` available:
-
-```powershell
-docker compose -f docker-compose.yml -f docker-compose.ollama-amd.yml up -d --build
-```
-
 ## MCPO routes

 Each MCP server is exposed by `mcpo` under its own path:
@@ -69,6 +72,7 @@ This includes:
 - Correct internal Docker URL usage (`http://mcpo:8000/...`)
 - Auth header guidance for `MCPO_API_KEY`
 - Validation and troubleshooting steps
+- A first-success test flow (section 6) to quickly verify MCP tool calls end-to-end

 ## Notes