https://github.com/brege/monitorat
A federated offline-friendly dashboard and documentation system for homelabs and Linux servers
https://github.com/brege/monitorat
chartjs dashboard federation flask gunicorn javascript linux markdown-it python
Last synced: 4 months ago
JSON representation
A federated offline-friendly dashboard and documentation system for homelabs and Linux servers
- Host: GitHub
- URL: https://github.com/brege/monitorat
- Owner: brege
- License: gpl-3.0
- Created: 2025-11-11T06:07:22.000Z (8 months ago)
- Default Branch: main
- Last Pushed: 2026-02-15T00:35:14.000Z (5 months ago)
- Last Synced: 2026-02-15T04:26:33.222Z (5 months ago)
- Topics: chartjs, dashboard, federation, flask, gunicorn, javascript, linux, markdown-it, python
- Language: JavaScript
- Homepage: https://pypi.org/project/monitorat
- Size: 6.13 MB
- Stars: 1
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: docs/contributing.md
- License: LICENSE
- Roadmap: docs/roadmap.md
Awesome Lists containing this project
README
#
[ [demo](https://monitorat.brege.org) ]
**Monitorat** is a federated dashboard and documentation system.
Its philosophy is to make system monitoring and documentation continuous, much like the way tables and figures are integrated within journal articles or [Wikipedia](https://wikipedia.org/).
Available widgets:
- [metrics](#system-metrics)
- [network](#network)
- [reminders](#reminders)
- [services](#services)
- [speedtest](#speedtest)
- [wiki](#wiki)
Widgets have a general, self-contained structure where both API and UI are straightforward to create.
```
~/.config/monitorat/widgets/
└── my-widget
├── api.py
├── default.yaml
├── index.html
└── app.js
```
Documentation is editable in-browser and handled by proliferating Wiki widgets across your dashboard. Each document fragment added is a new widget instance. All documents you add to your wiki will be rendered in GitHub-flavored Markdown via [markdown-it](https://github.com/markdown-it/markdown-it).
## Gallery
[**The Demo**](https://monitorat.brege.org) is a fully interactive version of the application and provides complete resource parity between widget layouts and their YAML config snippets. In that sense, *the demo is the documentation*.
## Features
- Beautiful documentation for your Homelab and media servers.
- Completely headless and works offline.
- Responsive design for mobile and desktop, with light and dark modes.
- Track [how hot your CPU gets](https://monitorat.brege.org/#metrics-widget) over the course of the day.
- Be alerted [when under extremely high load](#alerts).
- Keep a record of [internet speedtests](https://monitorat.brege.org/#speedtest-widget) even when AFK.
- List [all your reverse-proxied services](https://monitorat.brege.org/#services-widget) with offline-friendly bookmarks.
- Even runs on Raspberry Pi 2/3 w/ Pi-Hole, Unraid, and other homelab systems.
- Has [**federation**](https://monitorat.brege.org/federation): you can monitor services, metrics data, and documentation across many machines from a central command.
---
## Installation
### PyPI
Try the demo in 3 seconds:
```bash
uv tool install monitorat && monitorat demo
```
Then open http://localhost:6100.
See: **[Package Install](./docs/install/package.md)** for installing from PyPI with pip or uv.
### Docker
See: **[Docker Install](./docs/install/docker.md)** for installation in a container.
### Source
See: **[Source Install](./docs/install/source.md)** for git-based installations or deployments to `/opt`.
---
## The Dashboard
Open `http://localhost:6161`, or your specified port, or configure through a reverse proxy.
### Configuration
These are the basic monitorat settings for your system, assuming you want to keep all icons and data close to your config file (usually `~/.config/monitorat/`):
```yaml
site:
name: "@my-nas"
title: "Dashboard @my-nas"
editing: true
paths:
data: data/
img: img/ # or /home/user/.config/monitorat/img/
widgets: { ... }
# privacy: { ... }
# alerts: { ... }
# notifications: { ... }
```
## Widgets
**Monitorat** has an extensible widget system. You can add any number of widgets to your dashboard multiple times over, re-order them, and enable/disable any you don't need.
### Configuration
You can add more widgets of other origin in `~/.config/monitorat/widgets/`.
```yaml
widgets:
enabled: # dashboard positions: from top to bottom
- my-server-notes # type: wiki
- services
- metrics
- # reminders # '#' disables this widget
- network
- speedtest
- my-widget # in ~/.config/monitorat/widgets/
```
Each widget can be configured in its own YAML block. To configure a widget in its own file:
```yaml
includes:
- "/home/user/.config/monitorat/widgets/my-widget.yaml"
```
or do this for every widget through config snippets:
```yaml
includes:
- snippets/services.yaml
- snippets/metrics.yaml
- # ... wikis, user widgets, etc
```
##### Making your own
Widgets are also quite easy to build with AI. Widget built with Codex in 12 minutes:
> [Agentic Archetype: Building Widgets with AI](docs/contributing.md#agentic-archetype)
## Available Widgets
### **Services**
- monitor systemd services, timers, and Docker containers in real time
- can be used as *homelab bookmarks* in compact cards layout
- simultaneously provides both your URL (or WAN IP) and local address (or LAN IP) for use offline
- **monitorat is completely encapsulated and works offline even when internet is down**
### **Wiki**
- uses [markdown-it](https://github.com/markdown-it/markdown-it) and GitHub-flavored markdown
- can columnate multiple documents/Markdown fragments
- editor can be used to spruce up system docs in the browser
- supports [Mermaid](https://mermaid-js.github.io/mermaid/#/) diagrams
- inline LaTeX math via [KaTeX](https://katex.org/)
- supports [GitHub admonitions](https://github.com/antfu/markdown-it-github-alerts)
### **System Metrics**
- provides an overview of system performance over time in `metrics.csv`
- measures CPU, memory, disk and network usage, temperature, etc.
- get notified when system metrics exceed configured thresholds:
Configuring Alerts
```yaml
alerts:
cooldown_minutes: 60 # Short cooldown for testing
rules:
high_load:
threshold: 2.5 # load average (e.g., the '1.23' in 1.23 0.45 0.06)
priority: 0 # normal priority
message: High CPU load detected
high_temp:
threshold: 82.5 # celsius
priority: 1 # high priority
message: High temperature warning
low_disk:
threshold: 95 # percent
priority: 0 # normal priority
message: Low disk space warning
```
### **Speedtest**
- keep a record of your internet performance over time
- currently does not perform automated runs
### **Network**
The network widget is best used on machines with continuous uptime. Two options:
- (a) using a `ddclient`-style log, or
- (b) use the built-in chirper
### **Reminders**
- facilitated by [Apprise URLs](https://github.com/caronc/apprise) (see [below](#notifications)).
- ping yourself for system chores, key changes, etc.
### Summary of Widget Features
Widget
Chart
Filters
Snapshot
Recording
Editing
Federation Merge
Notify
S. Metrics
Y
-
Y(tiles)
Y
Y(tiles)
chart
Y(alert)
Network
Y(pips)
Y(outages)
Y(tiles)
Y
N
interleave
Y(alert)
Speedtest
Y
-
-
N
-
chart
N
Services
-
Y
Y(cards)
N
Y
interleave
N
Reminders
-
Y
-
-
Y
interleave
Y
Wiki
Y
-
-
-
Y
continuous
-
> [!NOTE] Key
> Y = supported | N = planned / potential feature | \- = not applicable
## General Features
### Editing
- built-in Markdown editor and previewer
- configure new reminders and services directly through the web interface
- Web UI configuration seamlessly updates the YAML config file or downstream snippets
### Notifications
The notifications system uses [Apprise](https://github.com/caronc/apprise) to notify through practically any service via apprise URLs.
```yaml
notifications:
apprise_urls:
- "pover://abscdefghijklmnopqrstuvwxyz1234@4321zyxwvutsrqponmlkjihgfedcba"
- "mailto://1234 5678 9a1b 0c1d@sent.com?user=main@fastmail.com&to=alias@sent.com"
- # more apprise urls if needed...
```
### Federation
Yes, you can even federate multiple instances of monitorat:
- compare and plot metrics data across multiple machines
- see service statuses for your entire homelab/network from a central node
- especially useful for filtering and sorting events network-wide
> [!NOTE]
> To simultaneously use federation of remotes AND local monitoring, you must setup a client monitorat instance and a separate monitorat server to federate locals and remotes in the same pane.
### Privacy
The privacy mask helps share your setup online without exposing personal information.
```yaml
privacy:
replacements:
my-site.org: example.com
replace-me: with-this
...
mask_ips: true
```
Running `monitorat config` will print the runtime config with these masks applied as well.
---
## Development
- [**contributing**](./docs/contributing.md)
- [**changelog**](./docs/changelog.md)
- [**roadmap**](./docs/roadmap.md)
## License
[GPLv3](https://www.gnu.org/licenses/gpl-3.0.en.html)