wdc-catalog-api

wdc-catalog-api is a FastAPI service from which NKS WebDev Console learns which versions of PHP, Apache, MySQL and other programs it can download and from where, and where it stores a backup of its settings. An application that downloads PHP itself for both Windows x64 and macOS on Apple Silicon needs a valid address for every version and platform. If these were hard-coded, a new application release would be needed every time a new PHP came out or a vendor moved its files. The daemon therefore downloads the catalogue from this service at start-up and keeps it in memory.

Vendor download links cannot be relied on

Downloading straight from vendors works only in part. ApacheLounge answers a build it has removed from its server with status 200 and an HTML page, and dev.mysql.com returns 403 to clients that are not a browser. In October 2026 this broke a fresh installation: the Apache file for Windows was in fact a 2,451-byte error page saved as a ZIP. Since then the catalogue offers Apache and MySQL only from the mirror in the webdev-console-binaries repository, and for every program it drops a file it knows to be smaller than 100 kB. On the stable channel it never offers an alpha, beta or RC version, and it sorts versions by number rather than as text, so 2.9.1 no longer sits above 2.11.7.

Programs, plugins and settings backup

Program catalogue

The /api/v1/catalog endpoint returns, for 11 programs (Apache, Nginx, Caddy, PHP, MySQL, MariaDB, PostgreSQL, Redis, Mailpit, mkcert and cloudflared), a list of versions with download links for Windows, Linux and macOS per architecture and, where known, a SHA-256 checksum. Nobody copies new versions in by hand: generators read GitHub releases, the windows.php.net listing, the nginx.org page and archive.mariadb.org, and check every address with a HEAD request before inserting it. On 6 November 2026 the public instance at wdc.nks-hub.cz listed 322 versions, from a single one for Apache to 63 for Redis.

Plugin catalogue

The second endpoint, /api/v1/plugins/catalog, builds its list from the releases of the webdev-console-plugins repository. It adds a SHA-256 to every ZIP, taken from the digest field of the GitHub API or, when that is missing, computed by downloading the file. The GitHub response is kept in memory for 60 seconds and the last successful one is saved to disk. When GitHub does not answer or the rate limit runs out, the service serves the saved copy marked "stale": true. When it has none, it returns 503 with a Retry-After header instead of an empty catalogue. Without a token GitHub allows 60 requests an hour; with a token that has no scopes at all, 5,000.

Settings backup

The daemon uploads the settings of its sites and services under a device identifier and downloads them again after a reinstall. Writing requires a login, and the service refuses a device linked to another account. Before every overwrite it stores the previous state as a snapshot. In the admin panel snapshots can be browsed, compared with the current state as an RFC 6902 JSON Patch, restored or exported to a ZIP. They are encrypted with AES-256-GCM in an envelope scheme: the account key is derived from the server's master key via HKDF-SHA256, and the data is encrypted with a separate data key. An account can switch on a mode in which the key is derived from the user's passphrase via Argon2id (4 passes, 64 MiB of memory), and the server cannot read the content without that passphrase.

Admin panel and access

The web admin panel covers the catalogue, users, devices, snapshots, an audit log with CSV export, invitations, backups and retention rules. Accounts have six roles from readonly to owner: support may read and reset passwords, an operator edits the catalogue, and there is one owner per instance who cannot be demoted. An account locks after five failed attempts, login is limited to five attempts a minute and registration from the application to three an hour. TOTP two-factor authentication can be enforced for administrators.

Running it

The default database is SQLite; PostgreSQL is switched on with the DATABASE_URL variable and CI checks it in a separate workflow. Alembic manages the schema. The Docker image is published to GHCR. It exposes /healthz, /readyz and /metrics for Prometheus; logs are JSON with a request identifier. The API description is OpenAPI 3.1 with 45 paths. In production mode the service will not start until it has secret keys for application tokens and admin sessions.

Verified by running it

The screenshot above shows a freshly started instance of 0.50.0 on Windows with Python 3.12, SQLite and development mode. The program catalogue holds only the data shipped with the repository, 28 versions of 11 programs and none yet for PostgreSQL. The service fetched the plugin catalogue live from GitHub and returned all 16 plugins with checksums. The test suite passed the same day: 694 passed and 13 skipped that need the live network.

Project status

The service started in April 2026. It has 58 releases on GitHub, from v0.2.0 on 17 April to v0.49.2 on 18 April 2026. Since then work has gone straight to the main branch: 104 commits, the latest on 28 October 2026, and both the code and the public instance report version 0.50.0. Apache appears in the catalogue only as version 2.4.66, because it is offered solely from the mirror and the mirror has no other yet.

Getting started

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

On Windows run.cmd does the same; with Docker it is docker compose up -d. Development mode creates an admin account with the password admin and uses temporary keys, so encrypted snapshots cannot be read after a restart. The WebDev Console daemon is pointed at your own instance with the NKS_WDC_CATALOG_URL variable. It needs Python 3.11+.

Source code

The Python code is on GitHub in the nks-hub/wdc-catalog-api repository under the MIT licence.