tomasz-syn-grzegorza
359afb3a59
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>
92 lines
2.9 KiB
Markdown
92 lines
2.9 KiB
Markdown
# 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.
|