Ferrule dry-run-5fd0b27

README.md

@@ -1,3 +1,71 @@
-# ferrule-deploy
+# Ferrule
 
-Ferrule deployment files: the compose files and setup guide Portainer reads. No source.
+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.