Modules

Modules

🌐 English · Deutsch

The Module Manager (/extensions, admin only) lets you install and manage modules that extend MediaForge — with their own pages, settings cards, sidebar links or providers. Sidebar entries contributed by a module carry a small "M" pill (tooltip: "Module: <name>") so you can always tell built-in features from module features. The page is fully mobile-responsive.

Module Store

The store is built into the /extensions page: the catalog loads automatically in the browser, and the Refresh button bypasses the ~15 minute cache. The store URL and the trusted signing keys are compiled into the build and cannot be changed via the UI (shown read-only). Admins can, however, add extra repository URLs — one http(s) URL per line.

Store unreachable: RecursionError: maximum recursion depth exceeded

Not a network or certificate problem — a broken Python interpreter. truststore (which MediaForge uses to validate against the operating system's certificate store) captures the real ssl.SSLContext class when it is imported. If something else in that Python installation wrote a subclass into the ssl module first — typically a .pth file or a sitecustomize.py, as corporate TLS-inspection tooling installs — CPython's own verify_mode setter calls itself until the stack is full. Every TLS handshake through truststore is then affected: the store, the Dev Info feed and the mpv download.

The culprit observed in practice is the pip-system-certs package, whose pip_system_certs.pth injects pip._vendor.truststore into the ssl module at interpreter startup. pip uninstall pip-system-certs removes the cause.

Important: MediaForge's fallback only covers the store, the Dev Info feed and the mpv download. urllib3-future (which GLOBAL_SESSION and the DoH resolver run on) builds its own context on every connection and recurses the same way — that cannot be intercepted from outside. While the injection is in place, everything can still go "offline" at once, DNS included.

Since v1.3.x MediaForge detects this at startup, reports it once in the log and under Settings → Network & Access → DNS test, and falls back to the bundled certificate store. Certificate verification stays fully enabled — only which root certificates validate the chain changes.

To find the culprit:

python -c "import ssl,truststore as t;print(ssl.SSLContext is t._ssl_constants._original_SSLContext)"
dir <Python>\Lib\site-packages\*.pth

Trust tiers

The trust tier is decided by cryptographic signature verification — not by what the store index claims:

Tier	Meaning
Official	Signed with the MediaForge team key
Verified	Third-party code that was reviewed, repackaged and signed by a maintainer
Unverified	Unsigned, signed with an unknown key, or modified after signing

Additionally, an Unreviewed badge marks submissions nobody has read yet. Unverified and unreviewed modules are hidden by default and only appear when the toggle "Allow unverified and unreviewed modules" is enabled.

⚠️ A module runs inside MediaForge with full access to your data. Only enable unverified/unreviewed modules if you trust the source.

Installation and updates

• The package is first downloaded to a staging area, where the signature is verified — packages that fail verification never reach the live folder.
• New modules go live immediately, without a restart: blueprint, settings card, sidebar entries and translations are available on the next request.
• Upgrading an already-loaded module stays staged and shows a "restart required" banner; the UI offers a built-in self-restart.

Dependencies

Modules may declare their own Python requirements. The Install dependency button (admin) installs only the declared requirements from PyPI into ~/.mediaforge/module_deps/ — MediaForge's own dependencies always take import precedence. The same button works for store modules before installing them.

Sensitive settings

Modules can declare settings keys whose values are stored encrypted in the database. Settings-card fields of type secret are encrypted automatically.

Backup

Modules can register their own backup categories, which then show up in the export/import dialog — see Backup.

Theme packs

The same store also distributes theme packs — CSS-only skins for the whole UI (index entries with "type": "template", marked with a Theme badge and filterable in the catalog). They install and uninstall live, never needing a restart. See Theme Packs.

Write your own module or theme

The store is open to third parties, and the /extensions page says so: above the store settings there is a Build your own module or theme card linking straight to the material you need.

Link	Where it goes
Module examples	.examples/thirdparties/ — working example modules (own pages, tabs, menus, providers, hooks, UI components), each with its own README
Theme examples	.examples/themes/ — a complete example theme pack plus README
Developer docs	this page and the developer section of the wiki
Publish on the developer portal	mediaforge.softarchiv.com — upload a finished module or theme so it appears in the store

Shared UI building blocks

A module does not have to invent its own look. MediaForge's core CSS is loaded on every page and its class names are stable, so a module that uses them looks native for free — badges, toggles, the chb-main checkbox, segmented buttons, multi-selects, token fields, chips, pagination, KPI cards, the MFCharts chart primitives, and the shared TMDB detail modal (MFDetailModal), which gives you a poster/synopsis/metadata view for anything you can name by TMDB id.

Two stylesheets divide the vocabulary between them. forms.css holds the form controls — the chb-main checkbox, segmented buttons, multi-selects, token fields, chips, pagination — and is loaded everywhere. mf_components.css holds the layout and content blocks the July 2026 redesign is built from, and needs its own <link> on your page:

Block	What it is
.mf-search	Search field with a leading icon and a clear button
.mf-toolbar	Page toolbar with one row per job — row 1 finds, row 2 shapes the view
.mf-poster-grid / .mf-poster-card	Responsive 2:3 poster grid; status in a corner flag, attribution in a permanently visible foot
.mf-avatar	Initials disc for "who asked for this"
.mf-timeline	Continuous time rail with stops, a glowing "now" dot and named gaps ("3 days with nothing")
.mf-progress	Named stages of one item (requested → approved → downloaded)
.mf-empty	Inline "nothing matches these filters" state, as opposed to the full-page .empty-state

The Calendar and Seerr pages are built out of these, so a module that uses them does not just look native — it stays in step when those pages are restyled. Every colour comes from the theme tokens, so a user's theme pack restyles a module's page for free.

Enable the Example: UI Components module for a live, click-through gallery of all of them with copyable markup, and see the "Reusable UI components" section of .examples/thirdparties/README.md for the reference table.

What the Modulmanager tells you

Each module card carries one state — Running, Off, Skipped or Error — and the list puts problems first, because those are the ones you need. Under the name it lists what the module actually registered in MediaForge: menu entries and settings cards, but also content sources, hosters, event hooks and background workers, with the ones that reach into MediaForge's own work highlighted. For a module you did not write yourself that is a more useful answer than who signed it. An import error can be unfolded in full and copied in one click, for a bug report.

Uninstalling a module now really removes its routes from the running app instead of only blocking them, so a module can be uninstalled and installed again without a restart.

A freshly submitted entry starts out unreviewed, so it is only listed while Allow unverified and unreviewed modules is enabled. A module from a third-party repository or an unsigned submission is not second-class by design — it simply carries no signature this build trusts.