feat: initial Blocky widget for Homepage dashboard

Parses Blocky's /metrics (Prometheus text) endpoint to show:
- Blocking status (Enabled/Disabled)
- Blocked domains count (denylist entries)
- Total queries served
- Cache hit rate %

No REST stats endpoint exists in Blocky, so the proxy handler
fetches and parses the Prometheus text format directly.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
Alkim Ake Gozen 2026-05-21 11:59:09 +09:00
commit cc34c22aa5
7 changed files with 227 additions and 0 deletions

70
INSTALL.md Normal file
View file

@ -0,0 +1,70 @@
# Installation
These files integrate as a standard service widget into the [Homepage](https://gethomepage.dev) dashboard source.
Homepage has no plugin system — you need to patch the source and rebuild.
## 1. Copy widget files
```bash
cp -r src/widgets/blocky /path/to/homepage/src/widgets/
```
## 2. Register the widget
**`src/widgets/widgets.js`** — add import and export:
```js
import blocky from "./blocky/widget";
// ... existing imports ...
export default {
blocky,
// ... existing widgets ...
};
```
**`src/widgets/components.js`** — add dynamic import:
```js
const components = {
blocky: dynamic(() => import("./blocky/component")),
// ... existing components ...
};
```
## 3. Add translations
In `public/locales/en/common.json`, merge the contents of `translations/en.json`
into the top-level object. Repeat for any other locale files you use.
## 4. Homepage config
```yaml
# services.yaml
- Infrastructure:
- Pi DNS:
href: http://10.0.50.5:4000
description: DNS ad-blocker
icon: blocky.png
widget:
type: blocky
url: http://10.0.50.5:4000
```
## What the widget shows
| Field | Source metric |
|---|---|
| Status | `blocky_blocking_enabled` (Enabled / Disabled) |
| Blocked Domains | `blocky_denylist_cache_entries{group="ads"}` |
| Total Queries | `blocky_cache_hits_total` + `blocky_cache_misses_total` |
| Cache Hit Rate | hits / (hits + misses) × 100 |
Data is pulled from Blocky's Prometheus `/metrics` endpoint — the only source
that exposes query counts. The REST `/api/blocking/status` endpoint only returns
the blocking toggle state.
## Upstream
There is an open feature request at
https://github.com/gethomepage/homepage/discussions/2732 (currently 8 upvotes —
Homepage requires 20 before considering a PR). Once it crosses that threshold,
this widget can be submitted as a PR to the official repo.