ferrule-deploy/README.md

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: 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 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: 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 for the terms.