Files
web-framework-resources/docs/resources.md
T

7.8 KiB

Web Framework Resources

Complete plugin packages and theme templates for Web Framework.

Default catalog: https://gitea.coreplay.eu/Dymas/web-framework-resources/raw/branch/main/catalog.json. Open Config → Add resources, search, and install a plugin or theme. Restart, then enable the plugin or select the theme. The six starter packages are also bundled in the framework for offline first startup. Queue is available only through this resource repository and requires framework 0.6.0+.

Folder layout

Every resource has its own source folder: plugins/<id>/ or themes/<id>/. Starter plugin packages include plugin.py, implementation.py, plugin.json, README, and their page/widget templates. They depend on public framework APIs and the common shell, rather than on the shared starter implementation. Theme folders contain theme.json and any accompanying files; the bundled themes are presets using the framework design system.

Every JSON manifest declares id, name, description, and version. Plugin manifests also declare dependencies, an array of required default provider IDs (or []). The catalog copies this field unchanged into each plugin entry. Themes also declare mode (dark, light, system), accent (violet, blue, green), and density (comfortable, compact). Versioned ZIP archives contain the entire resource with files at the archive root. Catalog entries record type, metadata, relative archive path and SHA-256.

Persistence and updates

Framework Compose mounts host folders ./plugins and ./themes outside the container, with one subfolder per resource. Image rebuilds and restarts preserve existing files. Missing defaults are copied locally from the image; no resource ZIPs are downloaded at startup.

The app checks catalogs in the background on startup and through Check for updates on the configuration pages. Checks only compare metadata: they never replace code or download archives. Local versions use PEP 440 comparison; source provenance protects against same-ID packages from another publisher. Operators can disable startup checks with [resources].check_updates_on_startup = false.

To update, stop the workspace, back up the resource folder, verify a newer archive against its catalog SHA-256, extract it into that folder, then restart. Keep the mounted resource folders and control-data volume. Saved plugin content and configuration remain in the control store.

Publish resources

Store newly developed plugins and themes here with all required helpers, templates, and assets in their own subfolder. Increment the resource version, build its complete ZIP, and update catalog.json with schema version 1. Commit source, archive, and catalog together. Keep old versioned archives for existing installations. Publish catalogs and archives for unauthenticated read access; never include secrets.

The initial six starter resources can be regenerated with PYTHONPATH=. python tools/prepare_resources.py /path/to/web-framework-resources from the framework repository. The exporter refreshes bundled source directories and retains independently developed resources in the catalog. python tools/build_catalog.py builds every source resource without replacing bundled source. Only configure trusted repositories: plugin code runs with the application user's privileges after restart.

Resource browsing in framework 0.7.0+

Config → Add resources provides Sources, Themes, and Plugins subtabs. Sources offers the built-in Web Framework Resources catalog plus additional HTTP(S) catalog URLs, one per line. At least one source is required, with a maximum of 20. Source changes require plugins.manage and CSRF, persist in encrypted settings, and apply immediately to browsing, installation, and update checks. The built-in source can be deselected when using another source. Invalid source changes preserve the previous configuration; the source screen does not fetch catalogs.

Themes and Plugins remember independent browser-session searches and show responsive tiles. Installed resources are highlighted green and sorted first, then alphabetically; available resources use a plain Install button. Installation retains the selected subtab and search. The main Config → Themes page also uses green installed tiles and places the active template first. Detailed implementation reference: framework resource functions.

Installed version inventory in framework 0.8.0+

Config → About lists installed plugins and themes with their versions. It includes newly installed manifests before restart and marks them Restart to load, as well as loaded resources and their current activation/selection state. General settings rename the project and configure a domain-root, subdomain, or path-prefix URL; URL policy activates after restarting the framework. See the workspace settings reference.

Modular media resources in 0.4.0

The catalog includes Watchlist, Thumbnails, Anime Search, Anime Providers, Media Handoff, AI Subtitles and Discord Notifications. Each declares framework_version >=0.9.0 and implements a documented replaceable capability. Upgrade the framework before installing them. See setup and contracts. Provider archives include full source, upstream GPL license and attribution; local Node dependencies are excluded from archives and supplied by the image or source setup.

Framework 0.10.0+ previews dependencies in a floating window: Install adds all missing requirements, Ignore installs the selected plugin, and Cancel installs nothing. Existing dependencies are kept. The builder rejects invalid or missing dependency IDs, cycles, and changed contents under a previously published version. See media dependency mapping for the current packages and required providers.

tools.build_catalog.build(root) validates metadata and the complete local plugin graph before building archives. Required IDs must exist in this catalog and cycles fail publication. Unchanged versioned archives retain their exact bytes, changed published contents require a version bump, and previous archives remain available. Tests compare declared dependencies with runtime requirements and mandatory service defaults, and verify manifest, catalog, archive and runtime versions.

Framework-managed updates (0.11.0+)

Use Resource updates → Check for updates → Update, then Restart workspace. The framework verifies the same publisher, version and archive checksums, stages packages and missing dependencies away from running files, and applies them at startup. It keeps the previous package backup and restores it if the update cannot start. Settings, content and enabled state stored in the framework data directory persist. New required providers must be configured/enabled before an enabled consumer can start; failed dependency validation restores the old packages. Standard CLI/Docker deployments can restart the application from the web UI; external WSGI deployments need a complete process-manager restart. Universal plugin hot reload is not supported.

Framework 0.11.2+ migrates ownership of existing runtime plugin/theme contents to app UID/GID 10001 during Compose initialization, without following symlinks. This fixes backup moves for older host-owned packages. Development sources in this checkout and the application data volume are untouched. Update permission errors are reported before download.

Framework 0.12.0 adds Update all to Resource updates. It prepares all available plugin/theme updates and missing dependencies together, preserves already prepared packages, and applies them with one restart. Shared requirements are downloaded once; invalid graphs or archives leave the new batch unprepared. Individual update choices remain available.