# Ferrule

Ferrule is a monitoring dashboard for UniFi networks, hypervisors and
storage. It shows what the vendors' own screens mostly don't: fan speeds,
per-port error counters, SFP optics, PoE draw, temperatures, NVR disk
health, WAN failover and cable modem health. It also keeps its own record
of outages, so the record survives the controller.

This repository is how you deploy it: a Docker Compose stack for Portainer,
and the full guide. Ferrule runs from a published image, so nothing is
built on your host.

## What you need

- A Docker host with **Portainer**, with outbound internet access to pull
  the images.
- At least one thing to watch:
  - a UniFi console (gateway, and a UNVR for Protect);
  - or Proxmox VE, Proxmox Backup Server, vCenter/ESXi;
  - or a Synology, QNAP or TrueNAS.
- **A licence key**, if you're a beta tester; you'll get it from us. Without
  one, Ferrule starts a 30-day trial of the paid features. When the trial
  ends, it keeps monitoring, with the paid features paused.

## Five steps

1. **Create read-only credentials** on what you'll watch: a UniFi API key
   and a local view-only admin, or an API token for Proxmox. The exact
   clicks are in [PORTAINER.md](PORTAINER.md): Step 1 for UniFi, and
   "Hypervisors and storage" for the rest.
2. **Portainer → Stacks → Add stack.**
   - Name: `ferrule`.
   - Build method: **Repository**.
   - Repository URL: `https://git.uglyhousesneedlove.com/steve/ferrule-deploy`
   - Repository reference: `refs/heads/main`
   - Compose path: `docker-compose.yml`
   - Authentication: **off**. This repository is public.
3. **Environment variables.**
   - Paste the contents of [`stack.env.example`](stack.env.example) and fill
     in your hosts and credentials.
   - Keep `FERRULE_VERSION` as it is. It's the current release.
   - Set `UNIFI_ENABLED=false` if you have no UniFi console.
4. **Deploy the stack**, then open `http://<docker host>:8090`.
5. **Settings → License:** paste your key and press **Apply**. The status
   shows "Not confirmed online yet" until Ferrule next checks in, within a
   day. After that it shows "Confirmed online".

Once it's running, use **Settings → Stack environment** to add
hypervisors, storage, notifications and sign-in. It generates each
variable for you to paste into Portainer.

## Updating

When a new release comes out, set `FERRULE_VERSION` to it in the stack's
environment variables, and press **Update the stack**. Nothing changes
until you do.

## Help and feedback

Everything is covered in [PORTAINER.md](PORTAINER.md): every variable,
each source's setup, and Troubleshooting. For anything else,
contact whoever sent you your key.

Your licence key is checked once a day against a signed list at
`https://license.ferrulehq.dev/revoked`. That's a plain download: nothing
about you, your network or your install is sent.

---

Ferrule is an independent project, not affiliated with Ubiquiti or the
other vendors it names. See [LICENSE](LICENSE) for the terms.