Initial import: bare-metal stacks, Server UI, GPU fan, tutorials.

Infrastructure configs for GMKtec K11 (Docker, vLLM, LocalAI, ComfyUI, control-plane, gpu-fan agent, Server UI with CLI/file explorer/GPU fan curve). Co-authored-by: Cursor <cursoragent@cursor.com>
2026-07-05 12:02:04 +00:00
commit 359afb3a59
153 changed files with 18169 additions and 0 deletions
@@ -0,0 +1,91 @@
+# Konwencje projektu
+
+Zasady spójne dla wszystkich stacków w `ubuntu-bare-metal`.
+
+## Stack Docker
+
+Każdy stack w `stacks/<nazwa>/`:
+
+```
+stacks/<nazwa>/
+├── README.md
+├── docker-compose.yml
+├── .env.example          # szablon bez sekretów
+├── .env                  # lokalny, w .gitignore
+├── .gitignore
+└── scripts/
+    ├── start.sh          # walidacja + pull + up
+    └── pull.sh           # opcjonalnie — tylko obraz
+```
+
+- **Profile compose:** `profiles: [<nazwa>]` — start jawny: `docker compose --profile <nazwa> up -d`
+- **GPU:** `gpus: all` + `CUDA_VISIBLE_DEVICES=0` (tylko RTX 3090 Ti)
+- **Dane:** bind mounty pod `${DATA_ROOT}/apps/<nazwa>/`, nie named volumes (backup na `/data`)
+- **Restart:** `restart: unless-stopped` na produkcji
+
+## Zmienne środowiskowe
+
+| Zmienna | Typowy zakres |
+|---------|----------------|
+| `DATA_ROOT` | `/data` |
+| `CUDA_VISIBLE_DEVICES` | `0` |
+| `HF_TOKEN` | vLLM — tylko gated models |
+| `LOCALAI_API_KEY` | LocalAI — legacy API auth |
+| `LOCALAI_PORT` | domyślnie 8080 (użytkownik może zmienić, np. 8070) |
+| `COMFYUI_PORT` | domyślnie 8188 |
+| `VLLM_PORT` | domyślnie 8000 |
+
+W **Server UI** porty edytowalnych stacków są zapisywane w `stacks/<nazwa>/.env`. Metadane (`port_env`, `port_default`, `port_editable`) w `stacks/server-ui/stacks.yaml`.
+
+Sekrety **tylko** w `.env` na serwerze. W `.env.example` — puste lub komentarz.
+
+### Control plane (gpu-fan + Server UI)
+
+Jeden plik credentials — **nie** osobne `/opt/server-ui/.env` i `/opt/gpu-fan/.env`:
+
+| Środowisko | Plik |
+|------------|------|
+| Produkcja | `/opt/control-plane/.env` |
+| Dev | `stacks/control-plane/.env` |
+
+Wspólny `API_KEY` dla panelu i proxy gpu-fan. Szczegóły: [`CONTROL-PLANE-ENV.md`](CONTROL-PLANE-ENV.md).
+
+## Tutorial (`manual-tutorial/`)
+
+- Numeracja: `00`, `01`, … `03b`, `04`, `05`, …
+- Język: polski; komendy i nazwy pakietów po angielsku
+- Każdy rozdział: cel, wymagania, komendy, weryfikacja, troubleshooting
+- Użytkownik potwierdza ukończenie („krok X gotowy”) przed kolejnym rozdziałem
+
+## Modele LLM
+
+- **Brak auto-download** przy `docker compose pull`
+- Katalog centralny vLLM: `stacks/vllm/models.catalog.yaml`
+- GGUF → LocalAI lub llama.cpp; AWQ/HF → vLLM
+- Kilka modeli na dysku, **jeden aktywny w VRAM**
+
+## Git i bezpieczeństwo
+
+- Nie commituj: `.env`, `upstream/`, kluczy API, tokenów HF
+- `coding-agent/` — bez wartości sekretów
+- Commity tylko na wyraźną prośbę użytkownika
+- Nie `git push --force` na main/master
+
+## Ścieżki bezwzględne na serwerze
+
+Domyślny root repo:
+
+```
+/home/tomasz-syn-grzegorza/cursor/ubuntu-bare-metal
+```
+
+W tutorialach używaj tej pełnej ścieżki w przykładach `cd`.
+
+## GMKtec K11 — numeracja NVMe
+
+| Urządzenie | Rozmiar | Rola |
+|------------|---------|------|
+| `nvme1n1` | ~128 GB | System `/` |
+| `nvme0n1` | ~1 TB | Dane `/data` |
+
+Zawsze weryfikuj po `SIZE` i `MOUNTPOINT`, nie po numerze urządzenia.