wdc-catalog-api

wdc-catalog-api je služba ve FastAPI, ze které NKS WebDev Console zjišťuje, které verze PHP, Apache, MySQL a dalších programů může stáhnout a odkud, a do které si ukládá zálohu nastavení. Aplikace, která si sama stahuje PHP pro Windows x64 i pro macOS na Apple Silicon, potřebuje pro každou verzi a platformu platnou adresu. Kdyby je měla zapsané v sobě, musela by vyjít nová verze aplikace pokaždé, když vyjde nové PHP nebo výrobce přesune soubory. Démon si proto při startu stáhne katalog z téhle služby a drží ho v paměti.

Na odkazy výrobců se spolehnout nedá

Stahovat přímo od výrobců jde jen zčásti. ApacheLounge na build, který už stáhl ze serveru, odpoví kódem 200 a stránkou v HTML, dev.mysql.com klientům, kteří nejsou prohlížeč, vrací 403. V říjnu 2026 kvůli tomu selhala čistá instalace: soubor Apache pro Windows byl ve skutečnosti chybová stránka o 2 451 bajtech uložená jako ZIP. Katalog od té doby nabízí Apache a MySQL jen ze zrcadla v repozitáři webdev-console-binaries a u všech programů vyřadí soubor, o kterém ví, že má méně než 100 kB. Na stabilním kanálu nenabídne alfa, beta ani RC verzi a verze řadí podle čísel, ne jako text, takže 2.9.1 už nestojí nad 2.11.7.

Programy, pluginy a záloha nastavení

Katalog programů

Endpoint /api/v1/catalog vrací pro 11 programů (Apache, Nginx, Caddy, PHP, MySQL, MariaDB, PostgreSQL, Redis, Mailpit, mkcert a cloudflared) seznam verzí a ke každé odkazy pro Windows, Linux a macOS podle architektury a případně kontrolní součet SHA-256. Nové verze nikdo neopisuje ručně: generátory čtou vydání na GitHubu, výpis windows.php.net, stránku nginx.org a archive.mariadb.org a každou adresu před vložením ověří požadavkem HEAD. Veřejná instance na wdc.nks-hub.cz měla 6. listopadu 2026 v katalogu 322 verzí, od jediné u Apache po 63 u Redisu.

Katalog pluginů

Druhý endpoint, /api/v1/plugins/catalog, skládá nabídku z vydání repozitáře webdev-console-plugins. Ke každému ZIPu přidá SHA-256: vezme ho z pole digest v API GitHubu, a když chybí, soubor stáhne a spočítá sám. Odpověď GitHubu drží 60 sekund v paměti a poslední úspěšnou ukládá na disk. Když GitHub neodpoví nebo vyčerpá limit, služba vydá uloženou kopii s příznakem "stale": true. Když žádnou nemá, vrátí 503 s hlavičkou Retry-After místo prázdného katalogu. Bez tokenu dovolí GitHub 60 požadavků za hodinu, s tokenem bez jakýchkoli oprávnění 5 000.

Záloha nastavení

Démon nahraje nastavení webů a služeb pod identifikátorem zařízení a po reinstalaci si ho stáhne zpět. Zápis vyžaduje přihlášení a zařízení spojené s cizím účtem služba odmítne. Před každým přepsáním uloží předchozí stav jako snímek. Snímky jde v administraci procházet, porovnat se současným stavem jako JSON Patch podle RFC 6902, obnovit nebo vyvézt do ZIPu. Šifruje je AES-256-GCM obálkovým schématem: klíč účtu vzniká z hlavního klíče serveru přes HKDF-SHA256 a data šifruje samostatný datový klíč. Účet si může zapnout režim, kde se klíč odvozuje z hesla uživatele přes Argon2id (4 průchody, 64 MiB paměti) a server obsah bez toho hesla nepřečte.

Administrace a přístupy

Webová administrace obsluhuje katalog, uživatele, zařízení, snímky, audit s exportem do CSV, pozvánky, zálohy a pravidla pro mazání starých dat. Účty mají šest rolí od readonly po owner: podpora smí číst a resetovat hesla, operátor upravuje katalog, vlastník je na instanci jeden a nejde ho sesadit. Po pěti chybných pokusech se účet zamkne, přihlášení je omezené na pět pokusů za minutu a registrace z aplikace na tři za hodinu. Administrátorům jde vynutit dvoufázové ověření TOTP.

Provoz

Výchozí databáze je SQLite, PostgreSQL se zapne proměnnou DATABASE_URL a CI ho ověřuje zvláštním workflow. Schéma spravuje Alembic. Docker obraz se vydává do GHCR. Pro monitoring jsou tu /healthz, /readyz a /metrics pro Prometheus, logy jdou jako JSON s identifikátorem požadavku. Popis API je v OpenAPI 3.1 a má 45 cest. V produkčním režimu služba nenastartuje, dokud nemá tajné klíče pro tokeny aplikace a pro relace administrace.

Ověřeno spuštěním

Snímek nahoře je čerstvě spuštěná instance 0.50.0 na Windows s Pythonem 3.12, SQLite a ve vývojovém režimu. Katalog programů má jen data dodávaná s repozitářem, 28 verzí 11 programů, u PostgreSQL zatím žádnou. Katalog pluginů si služba načetla živě z GitHubu a vrátila všech 16 pluginů s kontrolními součty. Testy prošly týž den: 694 úspěšných a 13 přeskočených, které potřebují živou síť.

Stav projektu

Služba vznikla v dubnu 2026. Na GitHubu má 58 vydání, od v0.2.0 ze 17. dubna po v0.49.2 z 18. dubna 2026. Další práce od té doby jde rovnou do hlavní větve, je to 104 commitů a poslední je z 28. října 2026; kód i veřejná instance hlásí verzi 0.50.0. Apache je v katalogu jen ve verzi 2.4.66, protože se nabízí výhradně ze zrcadla a to zatím jinou nemá.

Jak začít

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
NKS_WDC_CATALOG_DEV=1 uvicorn app.main:app --host 127.0.0.1 --port 8765

Na Windows totéž udělá run.cmd, s Dockerem docker compose up -d. Vývojový režim založí účet admin s heslem admin a pracuje s dočasnými klíči, takže šifrované snímky po restartu nepřečte. Démon WebDev Console se na vlastní instanci přesměruje proměnnou NKS_WDC_CATALOG_URL. Potřeba je Python 3.11 nebo novější.

Zdrojový kód

Kód v Pythonu je na GitHubu v repozitáři nks-hub/wdc-catalog-api pod licencí MIT.