AVAX — Deployment, Verzování a Instalace¶

1. Dvě prostředí: Dev a Production¶

Přehled¶

Atribut	Dev	Production
Server	`avaxdev` (192.168.1.55)	`vm-api` (10.0.1.2)
API URL	`http://192.168.1.55:8000`	`https://api.avaxis.cz`
Launcher exe	`avax-dev.exe`	`avax-launcher.exe`
Určení	Avaxis vývojáři	Všichni klienti
S3 bucket	`claudeai` (dev)	produkční bucket
Aktualizace	manuální (vývojář)	přes Deploy tlačítko v admin UI

Doporučená architektura — jediný prod exe, testování na dev serveru¶

Proč ne "testovací firmy v produkci": Testovací firmy v prod by sdílely backend s ostrými klienty. Chyba v dev kódu by mohla ovlivnit produkční data. Oddělená dev instance je bezpečnější a standardní praxe.

Jak funguje:

Vývojář → buildy dva exe ze stejného kódu:
  avax-dev.exe       (API_BASE = http://192.168.1.55:8000)
  avax-launcher.exe  (API_BASE = https://api.avaxis.cz)

Testování:
  Vývojář testuje na avax-dev.exe → dev server
  Když spokojen → klikne Deploy v admin UI launcheru

Deploy:
  Dev server spustí deployment skript:
    git pull na vm-api, vm-worker, vm-ai atd.
    restart uvicorn / gunicorn
    verze se zapíše do databáze s timestampem

Clients:
  avax-launcher.exe při startu zkontroluje S3 → stáhne nový exe pokud je novější
  Launcher update je automatický (bootstrapper)

Kdy se builduje prod exe? Prod exe lze buildovat kdykoliv ze stejného commitu — API_BASE je jediný rozdíl (compile-time konstanta v config.py). Typický workflow:

Vývojář pracuje, testuje s avax-dev.exe
Po otestování: python build.py --env prod → vygeneruje avax-launcher.exe + nahraje na S3
V admin UI klikne Deploy backend → prod servery stáhnou nový kód
Klienti dostanou nový launcher při příštím startu

2. Installer¶

2a. Standard Windows Installer (.exe)¶

Vytvořen pomocí Inno Setup (volný, vyzrálý, česká lokalizace).

Co dělá: 1. Uvítací obrazovka s logem AVAX + verze 2. Výběr adresáře (default: C:\Program Files\AVAX Launcher\) 3. Výběr variant: ☑ Vytvořit ikonu na ploše / ☑ Spustit při přihlášení 4. Kopíruje soubory: - avax-launcher.exe (PyInstaller bundle — Python uvnitř, žádná závislost) - avax-updater.exe (bootstrapper — malý, stahuje hlavní exe) - libopus.dll (pro budoucí hlasové hovory) 5. Registruje v Přidat nebo odebrat programy 6. Vytvoří zkratku na ploše a v nabídce Start 7. Volitelně spustí launcher po instalaci

Proč Python neinstalovat zvlášť: PyInstaller balí Python runtime uvnitř exe — klient nepotřebuje Python vůbec.

2b. Portable verze (.zip)¶

Pro uživatele kteří nechtějí instalátor:

avax-portable-x.x.x.zip
├── avax-launcher.exe
├── avax-updater.exe
├── libopus.dll
└── README.txt

Spustí se přímo, nastavení se ukládají do %APPDATA%\AVAX\.

2c. Dev installer (pro vývojáře)¶

Inno Setup skript s přepínačem --dev: - Nainstaluje avax-dev.exe místo produkčního - API_BASE na 192.168.1.55:8000 - Zobrazuje "DEV" badge v titulku okna

3. Jak se aktualizuje Launcher¶

3a. Bootstrapper (`avax-updater.exe`)¶

Malý exe (~1 MB), napsaný samostatně nebo jako jednoduchý Python skript. Spouští se jako první.

Start → avax-updater.exe
  1. GET https://api.avaxis.cz/launcher/latest
       → { "version": "0.4.1", "url": "s3://...", "sha256": "..." }
  2. Porovná s lokální verzí (version.txt vedle exe)
  3a. Stejná verze → spustí avax-launcher.exe a skončí
  3b. Novější verze:
       → stáhne nový exe do temp
       → ověří SHA-256
       → přejmenuje starý na avax-launcher.bak
       → přesune nový
       → spustí avax-launcher.exe a skončí

3b. Backend endpoint pro launcher verzi¶

GET /launcher/latest
→ { "version": "0.4.1", "url": "...", "sha256": "...", "changelog": "..." }

GET /launcher/history
→ [ { "version": "0.4.1", "released_at": "2026-05-05", "notes": "..." }, ... ]

3c. S3 struktura pro launcher¶

s3://avaxis-dist/
├── launcher/
│   ├── latest/
│   │   ├── avax-launcher.exe
│   │   └── version.json
│   └── history/
│       ├── 0.3.9/avax-launcher.exe
│       └── 0.4.0/avax-launcher.exe
├── installer/
│   ├── avax-setup-latest.exe
│   └── avax-portable-latest.zip

3d. Rollback¶

Pokud nová verze selhává, bootstrapper detekuje pád → obnoví avax-launcher.bak. V admin UI bude tlačítko "Vrátit na předchozí verzi".

4. Jak se aktualizují aplikace v katalogu¶

Viz docs/spec/app-catalog.md — shrnutí:

manifest.json (v S3 per aplikace):
{
  "app_id": "fakturace-pro",
  "version": "3.2.1",
  "channel": "stable",          # alpha | beta | stable
  "files": [
    { "path": "main.exe", "sha256": "...", "size": 1234567 },
    ...
  ],
  "min_launcher": "0.3.0"       # min verze launcheru pro tuto appku
}

Workflow update aplikace:

Vydavatel nahraje nové soubory do S3
  → manifest.json aktualizován (channel: alpha)
  → Avaxis schválí → beta
  → Po testování u vybraných firem → stable
  → Launcher klientů při příštím startu detekuje novou verzi → stáhne diff

Kanály per firma:
  Testovací firmy (Avaxis interní): alpha + beta
  Early adopters: beta
  Všichni ostatní: stable

5. Admin UI — záložka Verze¶

Přístupná jen pro system_role = super_admin v záložce Admin → Verze.

5a. Přehled prostředí¶

┌─────────────────────────────────────────────────────────────────┐
│  PROSTŘEDÍ                                                       │
├──────────────────┬──────────────────┬───────────────────────────┤
│                  │   DEV SERVER      │   PRODUCTION              │
├──────────────────┼──────────────────┼───────────────────────────┤
│ Backend verze    │ 0.4.1-dev        │ 0.4.0                     │
│ Git commit       │ bb076d1          │ 5a08332                   │
│ Nasazeno         │ dnes 14:32       │ 2026-05-03 09:15          │
│ Status           │ ● online         │ ● online                  │
│ Launcher na S3   │ 0.3.9-dev        │ 0.3.8                     │
└──────────────────┴──────────────────┴───────────────────────────┘

  [ Nasadit backend 0.4.1 do produkce ]   [ Nasadit launcher 0.3.9 do produkce ]

5b. Tlačítko Deploy¶

Po kliknutí:

┌────────────────────────────────────────────────┐
│  ⚠  Nasazení do produkce                       │
│                                                │
│  Máte vše důkladně otestováno?                 │
│  Chystáte se nasadit verzi 0.4.1               │
│  do produkčního prostředí.                     │
│                                                │
│  Tato akce ovlivní všechny klienty.            │
│                                                │
│          [ Zrušit ]  [ Nasadit ]               │
└────────────────────────────────────────────────┘

Po potvrzení: 1. API volá deploy endpoint na dev serveru 2. Dev server SSH/API volá prod servery → git pull && systemctl restart avax-api 3. Po restartu se ověří health check 4. Zapíše se záznam do deployment_log

5c. Historie nasazení¶

┌─────────────────────────────────────────────────────────────────────────┐
│  HISTORIE NASAZENÍ                                                       │
├────────────────────┬──────────┬──────────────┬──────────────────────────┤
│ Datum              │ Verze    │ Kdo          │ Typ                       │
├────────────────────┼──────────┼──────────────┼──────────────────────────┤
│ 2026-05-05 14:35   │ 0.4.1    │ plavecky@... │ Backend → Production      │
│ 2026-05-05 14:34   │ 0.3.9    │ plavecky@... │ Launcher → Production     │
│ 2026-05-03 09:15   │ 0.4.0    │ plavecky@... │ Backend → Production      │
└────────────────────┴──────────┴──────────────┴──────────────────────────┘

5d. Správa verzí aplikací v katalogu¶

Záložka Admin → Verze → Aplikace:

┌─────────────────────────────────────────────────────────────────────────┐
│  APLIKACE V KATALOGU                                          [ + Přidat ]│
├───────────────────┬──────────┬──────────┬──────────┬────────────────────┤
│ Aplikace          │ Alpha    │ Beta     │ Stable   │ Akce               │
├───────────────────┼──────────┼──────────┼──────────┼────────────────────┤
│ Fakturace Pro     │ 3.3.0-a  │ 3.2.1    │ 3.1.5    │ [Beta→Stable] [▲] │
│ Sklad & Výdejky   │ —        │ 2.0.0    │ 1.9.3    │ [Beta→Stable]      │
│ Mzdy a HR         │ —        │ —        │ 4.0.1    │ [Nahrát verzi]     │
└───────────────────┴──────────┴──────────┴──────────┴────────────────────┘

Propagace: Alpha → Beta → Stable, každý krok vyžaduje potvrzení.

6. DB tabulky¶

-- Záznamy o nasazení
CREATE TABLE deployment_log (
    id          UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    env         VARCHAR(20) NOT NULL,     -- 'production'
    type        VARCHAR(30) NOT NULL,     -- 'backend' | 'launcher' | 'app'
    version     VARCHAR(50) NOT NULL,
    git_commit  VARCHAR(40),
    deployed_by UUID REFERENCES users(id),
    deployed_at TIMESTAMPTZ DEFAULT now(),
    notes       TEXT
);

-- Aktuální verze prostředí (1 řádek per env+type)
CREATE TABLE deployment_current (
    env         VARCHAR(20) NOT NULL,
    type        VARCHAR(30) NOT NULL,
    version     VARCHAR(50) NOT NULL,
    git_commit  VARCHAR(40),
    deployed_at TIMESTAMPTZ,
    PRIMARY KEY (env, type)
);

-- Verze launcheru na S3
CREATE TABLE launcher_releases (
    version     VARCHAR(50) PRIMARY KEY,
    channel     VARCHAR(20) DEFAULT 'stable',  -- dev | stable
    s3_url      TEXT NOT NULL,
    sha256      VARCHAR(64) NOT NULL,
    changelog   TEXT,
    released_at TIMESTAMPTZ DEFAULT now(),
    released_by UUID REFERENCES users(id)
);

7. Backend endpoints (deployment API)¶

GET  /admin/versions                    — přehled verzí (dev + prod)
POST /admin/deploy/backend              — nasadit backend do prod
POST /admin/deploy/launcher             — nasadit launcher do prod
GET  /admin/deploy/history              — log nasazení
POST /admin/deploy/rollback             — vrátit předchozí verzi

GET  /admin/apps/{app_id}/versions      — verze aplikace (alpha/beta/stable)
POST /admin/apps/{app_id}/promote       — posunout verzi na vyšší kanál
POST /admin/apps/{app_id}/upload        — nahrát novou verzi aplikace

GET  /launcher/latest                   — pro bootstrapper (veřejné)
GET  /launcher/history                  — changelog

8. Build skript¶

build.py --env [dev|prod] [--upload]

  --env dev   → API_BASE = http://192.168.1.55:8000, exe = avax-dev.exe
  --env prod  → API_BASE = https://api.avaxis.cz,   exe = avax-launcher.exe
  --upload    → nahraje exe na S3 + aktualizuje version.json

Inno Setup:
  build.py --env prod --installer    → vygeneruje avax-setup-x.x.x.exe
  build.py --env prod --portable     → vygeneruje avax-portable-x.x.x.zip

9. Priorita implementace¶

Fáze	Součást	Odhad
D1	`build.py` — dev/prod switch, upload na S3	1 den
D2	Bootstrapper (`avax-updater.exe`)	2 dny
D3	Backend: `deployment_log`, `/admin/versions`, `/admin/deploy/*`	2 dny
D4	Launcher: Admin → Verze záložka (přehled + deploy tlačítko)	2 dny
D5	Inno Setup installer	1 den
D6	Správa verzí katalogových aplikací (propagace kanálů)	3 dny

Celkem: ~11 dní