# 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.