Wiki · Getting Started · Features · Architecture & Apps · Development
 |
 |
 |
 |
|---|---|---|---|
 |
 |
DockStat is an extensible container administration and monitoring platform that aims to combine the best ideas from tools like Portainer, Grafana and Dockge into a single, modular solution. It focuses on real-world manageability, deep observability and a runtime plugin-first architecture so the platform can evolve with your stack.
⚠️ Disclaimer
DockStat is currently in Pre-Alpha. Expect breaking changes, missing features and instability. Use for testing and evaluation only unless you know it's suitable for your environment.
DockStat's goal is to be the unified UI and runtime for managing containerized infrastructures (Docker for now, with intentions to expand). It provides:
- A responsive web UI for container & stack lifecycle operations.
- A monitoring layer with table and graph views and network visualizations.
- A runtime plugin system that supports frontend components, backend services and full-stack plugins.
- Stack and template management (prebuilt Docker Compose templates, stack-level plugins).
- Multi-node monitoring via adapters that let a single DockStat instance manage multiple Docker hosts.
- Runtime-compatible plugin system:
- Frontend UI components (widgets, pages)
- Backend services (collectors, adapters)
- Full-stack plugins (both frontend and backend)
- Theming:
- CSS variable driven theming for deep customization
- Stacks & Templates:
- Prebuilt Docker Compose templates (DockStore)
- Stack-level plugin hooks (Traefik/Caddy examples)
- Automatic node provisioning (e.g. Hetzner Cloud plugin)
- Future: Kubernetes support roadmap
- Monitoring & Visualization:
- Table-based and graph-based metrics
- Network visualization with sigma.js / reagraph
- Whole-stack monitoring (containers, services, networks)
- Custom Dashboards:
- Home-Assistant style widget system extendable via plugins
- Multi-Node Monitoring:
- Adapters abstract different backends (local Docker, remote Docker API, SSH, etc.)
- Per-adapter configuration and credentials
- Extensible datastore:
- Lightweight persistence (bun:sqlite used in current prototypes) for local storage and historic metrics
- Core: React, React Router v7, Bun
- Frontend: TypeScript, TailwindCSS, GSAP, lucide-react
- Backend / Integrations: ElysiaJS, Dockerode, bun:sqlite, @dockstat/* packages (internal libs)
- Monorepo layout: apps/, packages/ (typings, db, sql-wrapper, plugins, ...)
- apps/
- dockstat — main frontend / UI app (React Router SPA)
- dockstore — community hub for templates, themes & plugins
- docs — documentation and Outline wiki sync helpers
- packages/ (internal packages / libraries used by apps)
- .github/ (assets such as logos and CI configs)
See apps/README.md for per-app details.
Requirements
- Bun (used for development and scripts)
- Node ecosystem tools (if you prefer npm/pnpm for some tasks)
- Docker (for testing container interactions)
- Optional: access to cloud provider API keys (for provisioning plugins)
Quick start (from Repo root)
- Install dependencies:
bun install- Start dockstat in development:
cd ./apps/dockstat
bun run devDockStat is designed to grow through plugins. Plugins can register UI components, provide backend services (collectors, adapters, provisioning modules), or both.
Plugin types
- Frontend plugin: Registers routes, pages or widgets in the UI. Usually provides a manifest and runtime hooks.
- Backend plugin: Runs a process/service that collects metrics, talks to external APIs or adds adapters for new node types.
- Full-stack plugin: Includes both frontend and backend parts and ships as a single distributable.
Concepts
- Manifest: A plugin manifest describes name, version, provided capabilities, and entry points.
- Lifecycle: Plugins are discovered at runtime and may be started/stopped without recompiling the host (subject to host safety).
Developer notes
- Keep plugin APIs minimal; prefer well-documented typed contracts.
DockStore is the ecosystem hub for templates, themes and plugins:
- Pre-built Docker Compose templates for common apps (AdGuard, Grafana, Home Assistant, etc.)
- Themes and UI tweaks
- Plugin marketplace / registry for community contributions
DockStat separates collection and aggregation from visualization via adapters:
- Docker client adapters (can manage multiple hosts)
- Cloud provisioning adapters (Hetzner, others planned)
- Custom adapters can be written as backend plugins to bring new node types under management
Adapters expose:
- Node discovery & registration
- Metrics collection configuration
- Connection and credential management
- Each app/package should have its own README and local dev scripts.
- Use TypeScript and JSDoc for public APIs.
- Follow repository linting and formatting rules (see root scripts and package.json).
- CI should run type checks, linters and tests on PRs.
Common scripts
- bun run dev — start development servers
- bun run build — build production bundles
- biome — linting and type checks (project specific)
Adding an app
- Create directory in apps/
- Add package.json with scripts (dev/build/lint/check-types)
- Add tsconfig.json extending root config
- Update root workspace config if needed
- Pre-Alpha: expect breaking API and UX changes.
- Limited production hardening; use only for testing.
- Some features (Kubernetes support, advanced alerting, long-term metrics storage) are planned but not yet implemented.
Short term
- Stabilize plugin runtime API
- Improve adapter management and credentials handling
- Expand DockStore templates and build a simple web marketplace
Medium term
- Advanced dashboards and widget editor
- Built-in alerting and notification center
- Optional integration with time-series DB for long-term metrics
Long term
- Kubernetes management support
- Multi-tenant and RBAC features
- Rich plugin ecosystem and marketplace
Contributions, ideas and bug reports are welcome.
- Check the Wiki for developer docs and architecture notes
- Open issues for bugs or feature requests
- Submit PRs with small, focused changes and good descriptions
- If you're adding a plugin or template, prefer adding it to apps/dockstore for discoverability
Start with the repository Wiki and the Outline docs:
- Wiki: https://outline.itsnik.de/s/9d88c471-373e-4ef2-a955-b1058eb7dc99
- apps/README.md and apps/dockstat/README.md for per-app instructions