# 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.