Alkim Ake Gozen
cc34c22aa5
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>
70 lines
1.9 KiB
Markdown
70 lines
1.9 KiB
Markdown
# 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.
|