haylan/LLM-Server
1
0 Fork 0
Code Issues 4 Pull Requests Actions Packages Projects Releases Wiki Activity

Docs cleanup: restructure, move code comments into docs, remove image generation #65

Merged
haylan merged 5 commits from docs/cleanup-and-restructure into main 2026-09-24 20:01:31 +00:00
Conversation 0 Commits 5 Files Changed 23
+406 -1119
haylan commented 2026-09-24 19:53:03 +00:00
Owner
Copy link
Copy source

Executes the plan from the wayfinder map #55 (checklist: #64).

What changes

  • Removed from the stack: ComfyUI + Qwen-Image (comfyui, downloader-comfyui, scripts/switch-model.sh), Open WebUI, Lazytainer, neo4j, with their volumes, env keys and update.sh steps (#58, #63).
  • qdrant is bound to loopback only (no auth). The dashboard port stays LAN-published, and the docs now say so correctly (#63).
  • Docs restructured (#60): README reduced to intro + quickstart + index. New architecture.md, gateway.md (replaces proxy-key-onboarding.md) and operations.md. network-access.md rewritten, coding-CLI docs fixed. docs/research/README.md marks each research doc current or superseded, and proxy-request-priority.md moved there.
  • Glossary CONTEXT.md (#59). Every doc opens with a Source of truth line, names keys, and doesn't restate values.
  • Code comments → docs (#61): compose, .env.example and update.sh keep one-line pointers, inline warnings for data loss / security / breakage, and "auto-filled — leave blank" markers.
  • Agent guide docs/agents/writing-docs.md + new-term procedure in domain.md, reached via a pointer in CLAUDE.md (#62).

Audit findings fixed along the way (#56): the stale OMNIROUTE_PORT:-4000 endpoint everywhere, the dashboard wrongly described as unpublished, Lazytainer described as working, and the contradictory account of the classifier's VRAM fix.

Checks run

  • every # see docs/…#… pointer and every markdown link resolves to an existing file/heading (script)
  • every non-research doc has its source-of-truth line and a README index row (server-planing.md is left unchanged by decision)
  • no non-research doc restates a compose / .env.example value
  • docker compose config -q passes; bash -n scripts/update.sh

Deploy (run on the server after merge — not done by this PR)

  1. ./scripts/update.sh. Its --remove-orphans removes the comfyui, open-webui, lazytainer and neo4j containers. Expect a conflict prompt only if server .env values differ from the defaults.
  2. docker volume rm llm-server_comfyui-data llm-server_open-webui-data llm-server_neo4j-data (check the prefix with docker volume ls).
  3. OmniRoute dashboard: revoke the openwebui-chat API key and delete the comfyui provider connection, if they exist.
  4. Reverse proxy: remove knowledge.proxy-ai.home and any comfy.home / :8008 route.
  5. Optional: delete stale COMFYUI_*, OPENWEBUI_OMNIROUTE_KEY, NEO4J_PASSWORD, LAZYTAINER_* lines from the server .env, and docker image rm the unused images.
  6. Verify: docker compose ps shows only llama-server, qwen-classifier, omniroute, qdrant; qdrant is unreachable on 6333 from another LAN host; a coding CLI still gets a response through the gateway.

🤖 Generated with Claude Code

Executes the plan from the wayfinder map #55 (checklist: #64). ## What changes - **Removed from the stack:** ComfyUI + Qwen-Image (`comfyui`, `downloader-comfyui`, `scripts/switch-model.sh`), Open WebUI, Lazytainer, neo4j, with their volumes, env keys and `update.sh` steps (#58, #63). - **qdrant** is bound to loopback only (no auth). The dashboard port stays LAN-published, and the docs now say so correctly (#63). - **Docs restructured** (#60): README reduced to intro + quickstart + index. New `architecture.md`, `gateway.md` (replaces `proxy-key-onboarding.md`) and `operations.md`. `network-access.md` rewritten, coding-CLI docs fixed. `docs/research/README.md` marks each research doc current or superseded, and `proxy-request-priority.md` moved there. - **Glossary** `CONTEXT.md` (#59). Every doc opens with a *Source of truth* line, names keys, and doesn't restate values. - **Code comments → docs** (#61): compose, `.env.example` and `update.sh` keep one-line pointers, inline warnings for data loss / security / breakage, and "auto-filled — leave blank" markers. - **Agent guide** `docs/agents/writing-docs.md` + new-term procedure in `domain.md`, reached via a pointer in `CLAUDE.md` (#62). Audit findings fixed along the way (#56): the stale `OMNIROUTE_PORT:-4000` endpoint everywhere, the dashboard wrongly described as unpublished, Lazytainer described as working, and the contradictory account of the classifier's VRAM fix. ## Checks run - [x] every `# see docs/…#…` pointer and every markdown link resolves to an existing file/heading (script) - [x] every non-research doc has its source-of-truth line and a README index row (`server-planing.md` is left unchanged by decision) - [x] no non-research doc restates a compose / `.env.example` value - [x] `docker compose config -q` passes; `bash -n scripts/update.sh` ## Deploy (run on the server after merge — not done by this PR) 1. `./scripts/update.sh`. Its `--remove-orphans` removes the comfyui, open-webui, lazytainer and neo4j containers. Expect a conflict prompt only if server `.env` values differ from the defaults. 2. `docker volume rm llm-server_comfyui-data llm-server_open-webui-data llm-server_neo4j-data` (check the prefix with `docker volume ls`). 3. OmniRoute dashboard: revoke the `openwebui-chat` API key and delete the `comfyui` provider connection, if they exist. 4. Reverse proxy: remove `knowledge.proxy-ai.home` and any `comfy.home` / :8008 route. 5. Optional: delete stale `COMFYUI_*`, `OPENWEBUI_OMNIROUTE_KEY`, `NEO4J_PASSWORD`, `LAZYTAINER_*` lines from the server `.env`, and `docker image rm` the unused images. 6. Verify: `docker compose ps` shows only llama-server, qwen-classifier, omniroute, qdrant; qdrant is unreachable on 6333 from another LAN host; a coding CLI still gets a response through the gateway. 🤖 Generated with [Claude Code](https://claude.com/claude-code)
haylan added 5 commits 2026-09-24 19:53:03 +00:00
chore: remove image generation, Open WebUI, Lazytainer and neo4j fd55ce6669 
Drops the comfyui, downloader-comfyui, open-webui, lazytainer and neo4j
services with their volumes, env keys and update.sh steps, plus
scripts/switch-model.sh and the two image-generation research docs.

Refs #55 (removal inventory #58, intent vs. source #63)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
fix(qdrant): bind port to loopback only 072eeb78c2 
qdrant has no auth; it was reachable from the whole LAN.

Refs #55 (intent vs. source #63)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
docs: restructure around source-of-truth pages a0e5e9704b 
- CONTEXT.md glossary
- README reduced to intro, quickstart and doc index
- new architecture.md, gateway.md (from proxy-key-onboarding.md),
  operations.md; network-access.md rewritten
- coding-cli-setup: stale OMNIROUTE_PORT:-4000 endpoint, terms and
  duplicated per-slot/classifier explanations fixed
- research/README.md index; proxy-request-priority.md moved there as
  superseded

Every doc names keys instead of restating values and links its source.

Refs #55 (#56, #57, #59, #60)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
chore: move code comments into docs, leave one-line pointers 05effe5c88 
Explanations from docker-compose.yml, .env.example and
scripts/update.sh now live in docs/architecture.md, gateway.md,
network-access.md and operations.md. Code keeps `# see docs/...`
pointers, one-line warnings (storage key, SSRF guard, WAL grace period,
git pull ordering) and "auto-filled — leave blank" markers.

Refs #55 (comment destination map #61)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
docs(agents): add writing-docs guide and new-term procedure e27f5c03b6 
docs/agents/writing-docs.md holds the doc/comment rules and done-check,
reached via a pointer in CLAUDE.md (AGENTS.md and QWEN.md import it).
docs/agents/domain.md gains the procedure for new or conflicting terms.

Refs #55 (agent guide #62)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
haylan merged commit ea07daa3cc into main 2026-09-24 20:01:30 +00:00
haylan deleted branch docs/cleanup-and-restructure 2026-09-24 20:01:32 +00:00
Sign in to join this conversation.
Reviewers
No Reviewers
Labels
Clear labels
wayfinder:grilling
Wayfinder grilling ticket
 wayfinder:map
Wayfinder map issue
 wayfinder:prototype
Wayfinder prototype ticket
 wayfinder:research
Wayfinder research ticket
 wayfinder:task
Wayfinder task ticket
No labels
Milestone
No items
No Milestone
Projects
Clear projects
No projects
Assignees
Clear assignees
haylan (Arthur Erlich)
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: haylan/LLM-Server#65