Skip to content

Modules

Jump to bottom
Dennis Braun edited this page Mar 16, 2026 · 6 revisions

Module System

Since v2026-02-28 — DOCSight is modular. Every major feature is a self-contained module that can be enabled, disabled, or replaced.

What Are Modules?

Modules are self-contained feature packages that plug into DOCSight without touching core code. Each module lives in its own directory with a manifest.json that tells DOCSight what the module provides — API endpoints, data collectors, settings panels, translations, and more.

DOCSight discovers modules automatically on startup. Drop a folder in the right place, restart, and it's live. No config files to edit, no code to change.

There are two kinds:

Built-in Modules Community Modules
Ship with DOCSight Yes — inside the Docker image No — you add them yourself
Location app/modules/ (read-only) /modules/ volume mount
Badge in Settings "Built-in" "Community"
Updates With DOCSight releases Independent, from module author

Built-in Modules

These ship with every DOCSight installation:

Module What It Does Type
Backup Scheduled backups, one-click download, restore from setup wizard Integration
BNetzA Import official German broadband measurement protocols (PDF/CSV) Integration
BQM ThinkBroadband broadband quality monitoring with calendar view Integration
Incident Journal Document ISP issues with icons, attachments, incident groups, and export Analysis
MQTT Home Assistant auto-discovery with per-channel sensors Integration
Reports Generate complaint letters and technical PDF reports Analysis
Smokeping Live latency graphs from your Smokeping instance Integration
Speedtest Speed test history from Speedtest Tracker Integration
Modulation Performance Per-protocol-group modulation health index with intraday channel drill-down (details) Analysis
Classic Default DOCSight theme (charcoal + purple) Theme
Ocean Blue-toned dark theme Theme
Tribu Warm, modern theme inspired by the Tribu design system Theme
VFKD Thresholds Signal thresholds based on the official Vodafone pNTP Interface Specification v1.06 (details) Driver
Weather Correlate signal quality with outdoor temperature via Open-Meteo Integration

Core features like the Dashboard, Signal Trends, Channel Timeline, Event Log, Correlation Analysis, and DOCSIS signal analysis are part of the core and always available — they cannot be disabled.

Theme Modules

Themes are a special module type that customize DOCSight's visual appearance. They use the same module system as other modules but declare "contributes": "theme" and include a theme.json file with design tokens.

Built-in Themes

DOCSight ships with three themes:

Theme Description
Classic The default charcoal + purple design
Ocean A blue-toned dark theme
Tribu A warm, modern theme inspired by the Tribu design system

Switch themes in Settings > Appearance. Changes apply instantly with a live preview -- no restart required.

Only one theme can be active at a time (mutual exclusion). Enabling a new theme automatically disables the previous one.

How Theme Modules Work

A theme module contains two key files:

my-theme/
├── manifest.json    # Module metadata with "contributes": "theme"
└── theme.json       # Design tokens (colors, fonts, radii, shadows)

The manifest.json for a theme looks like:

{
  "id": "community.mytheme",
  "name": "My Theme",
  "description": "A custom color scheme for DOCSight",
  "version": "1.0.0",
  "author": "your-github-username",
  "minAppVersion": "2026.3",
  "type": "theme",
  "contributes": "theme"
}

The theme.json defines CSS custom properties that override the default design tokens:

{
  "colors": {
    "bg-primary": "#1a1b2e",
    "bg-secondary": "#242640",
    "accent": "#7c5cff",
    "text-primary": "#e8e8f0",
    "text-secondary": "#a0a0b8",
    "success": "#4caf50",
    "warning": "#ff9800",
    "danger": "#f44336"
  },
  "fonts": {
    "heading": "Outfit, sans-serif",
    "body": "Inter, sans-serif",
    "mono": "JetBrains Mono, monospace"
  },
  "radii": {
    "card": "12px",
    "button": "8px"
  }
}

Creating a Custom Theme

  1. Copy any built-in theme directory as a starting point
  2. Change the id, name, and author in manifest.json
  3. Edit theme.json with your preferred colors, fonts, and radii
  4. Install as a community module

Community themes can also be shared via the Community Module Registry.

Managing Modules

Viewing Installed Modules

Go to Settings > Modules to see all installed modules with their status, version, and type.

Enabling / Disabling

Each module card has an enable/disable toggle. Changes require a container restart to take effect — a banner will remind you.

Disabling a module:

  • Removes its sidebar entry, API endpoints, and settings panel
  • Does not delete any stored data (safe to re-enable later)
  • Core features are unaffected

Module Settings

Modules that have configuration options appear under Settings > Extensions in the sidebar. Click the module name to open its settings panel.

Not all modules have settings — for example, Journal and Reports work out of the box without any configuration.

Installing Community Modules

Community modules extend DOCSight with features built by other users. They are not reviewed or maintained by the DOCSight team unless marked as verified.

From Settings (recommended)

Since v2026-03-16.3

  1. Go to Settings > Extensions
  2. Scroll down to Community Modules and click Browse
  3. Find the module you want and click Install
  4. Restart the container when prompted

Installed modules are disabled by default. After restart, enable them via the toggle in Settings > Extensions.

Available modules are fetched from the docsight-modules registry.

Manual Installation

If you prefer to install modules manually or want to use modules not in the registry:

Step 1: Add a volume mount to your docker-compose.yml:

services:
  docsight:
    image: ghcr.io/itsdnns/docsight:latest
    volumes:
      - docsight_data:/data
      - ./modules:/modules    # <-- add this line
    ports:
      - "8765:8765"

Step 2: Clone or download a community module into the modules/ directory:

mkdir -p modules
cd modules
git clone https://github.com/author/docsight-mymodule mymodule

The directory name doesn't matter -- DOCSight reads the manifest.json inside it.

Step 3: Restart DOCSight:

docker compose restart docsight

Step 4: Go to Settings > Extensions. Your new module should appear with a "Community" badge.

If something went wrong, check the container logs:

docker compose logs docsight | grep -i module

DOCSight never crashes due to a broken module. If a manifest is invalid or the module fails to load, it's logged and skipped — everything else keeps running.

Finding Community Modules

Browse the Community Module Registry for available modules. The registry lists each module with its description, author, repository link, and whether it's been verified by the DOCSight team.

Updating a Community Module

cd modules/mymodule
git pull
docker compose restart docsight

Removing a Community Module

rm -rf modules/mymodule
docker compose restart docsight

The module disappears from Settings and all its routes/settings are removed. Any data the module stored in its own SQLite tables remains in the data volume but is inert.

Building Your Own Module

Want to build a module? The Community Module Registry has everything you need:

Quick Overview

A module is a directory with at least these two files:

my-module/
├── manifest.json    # What the module is and what it provides
└── __init__.py      # Python package marker (can be empty)

The manifest.json declares everything:

{
  "id": "community.mymodule",
  "name": "My Module",
  "description": "What this module does",
  "version": "1.0.0",
  "author": "your-github-username",
  "minAppVersion": "2026.2",
  "type": "integration",
  "contributes": {
    "routes": "routes.py",
    "i18n": "i18n/"
  }
}

Module types: driver (modem support), integration (external services), analysis (data visualization), theme (UI customization)

What modules can contribute:

Contribution What It Does
routes Flask Blueprint with API endpoints and pages
collector Scheduled data collection (runs in polling loop)
publisher Data export to external services (e.g., MQTT)
settings Configuration panel in Settings > Extensions
i18n Translation files (EN/DE/FR/ES)
static CSS and JavaScript (auto-loaded if named style.css / main.js)
tab Dashboard tab
card Dashboard card widget
theme UI theme with design tokens (theme.json) — only one active at a time
thresholds Signal threshold profile (only one active at a time — see Reference Values)
driver Modem/router hardware driver (extends ModemDriver) — see Driver Modules

Driver Modules

Since v2026-03-03 — Community modules can contribute modem/router drivers, adding hardware support without modifying DOCSight core.

Driver modules declare "contributes": {"driver": "driver.py:ClassName"} in their manifest. The class must extend ModemDriver from app/drivers/base.py and implement four methods: login(), get_docsis_data(), get_device_info(), and get_connection_info().

How Driver Modules Work

A driver module contains:

my-driver/
├── manifest.json    # Module metadata with "contributes": {"driver": "..."}
├── driver.py        # ModemDriver subclass
└── __init__.py      # Python package marker (can be empty)

The manifest.json for a driver looks like:

{
  "id": "community.mymodem",
  "name": "My Modem Driver",
  "description": "DOCSIS driver for My Modem brand",
  "version": "1.0.0",
  "author": "your-github-username",
  "minAppVersion": "2026.3",
  "type": "driver",
  "contributes": {
    "driver": "driver.py:MyModemDriver"
  }
}

The driver value uses the format filename.py:ClassName. DOCSight loads the class dynamically on startup.

Priority and Override

Module-contributed drivers take priority over built-in drivers with the same key. This lets community modules override or improve existing drivers without waiting for a DOCSight release.

Security Restriction

Driver modules cannot also contribute collector or publisher. This prevents a driver module from exfiltrating credentials to external services. If a manifest declares both a driver and a collector/publisher, DOCSight rejects the module on startup and logs the reason.

Creating a Driver Module

  1. Create a Python file with a class that extends ModemDriver
  2. Implement the four required methods (see Adding Modem Support for the return format)
  3. Write a manifest.json with "type": "driver" and "contributes": {"driver": "yourfile.py:YourClass"}
  4. Install as a community module

The built-in GenericDriver (app/drivers/generic.py) is a minimal reference implementation. For a full DOCSIS driver example, study any of the built-in drivers.

Reference Implementations

Study the built-in modules for real-world examples:

Start With If You Want To Build Complexity
Reports Routes-only module (API endpoints, no config) Minimal
Journal Routes + JavaScript + i18n Medium
Weather Full module: collector + routes + settings + i18n Full
MQTT Publisher pattern (data export) Medium
VFKD Thresholds Threshold profile (data-only, no code) Minimal

Architecture

For the technically curious — here's how the module system works under the hood.

Discovery Flow

Startup
  ├── Scan app/modules/     (built-in, inside Docker image)
  ├── Scan /modules/         (community, volume mount)
  │
  ├── For each directory with manifest.json:
  │     ├── Validate manifest (required fields, ID format, type)
  │     ├── Check for duplicates (first found wins)
  │     ├── Check disabled list (from config.json)
  │     └── Create ModuleInfo
  │
  └── For each enabled module:
        ├── Register config defaults (bool/int auto-detected)
        ├── Merge i18n translations (namespaced under module ID)
        ├── Load Flask Blueprint (routes)
        ├── Mount static files at /modules/<id>/static/
        ├── Resolve template paths (settings, tab, card)
        ├── Load Collector class (instantiated later in polling loop)
        ├── Load Publisher class (instantiated later)
        └── Load Driver class (registered in DriverRegistry)

Error Isolation

Every step is wrapped in try/except. A broken module never takes down DOCSight:

  • Invalid manifest → logged, skipped, discovery continues
  • Import error in routes/collector → module marked with error, other modules unaffected
  • Runtime crash in collector → base class catches it, applies exponential backoff

The Settings > Modules page shows error states so you can diagnose issues.

ID Format

Module IDs must match ^[a-z][a-z0-9_.]+$:

  • docsight.* — reserved for built-in modules
  • community.* — recommended for community modules
  • username.* — also valid (use your GitHub username)

Config Integration

Modules declare config defaults in their manifest:

"config": {
  "mymodule_enabled": false,
  "mymodule_interval": 300
}

These are auto-registered in DOCSight's config system:

  • Boolean values → BOOL_KEYS (checkbox parsing)
  • Integer values → INT_KEYS (number parsing)
  • Saved to config.json alongside core config
  • Accessible via get_config_manager() in routes

API

The module management API (used by the Settings UI):

Method Endpoint What It Does
GET /api/modules List all modules with status
POST /api/modules/<id>/enable Enable a disabled module
POST /api/modules/<id>/disable Disable an enabled module

Both enable/disable return {"success": true, "restart_required": true} — the change only takes effect after a container restart.

Home | Quick Start | Configuration | API Reference | GitHub

Home

Getting Started

Monitoring

Documentation & Evidence

Integrations

System

Community

Reference

Development

Clone this wiki locally