Skip to content

Install

At the end of this page Ferrule will be running, and you'll have it open in your browser. Use Portainer if you like a web interface, or Docker Compose from a terminal: Ferrule works the same either way.

1. Get Ferrule

  1. In Portainer, open Stacks and click Add stack.
  2. Name: ferrule. Use lowercase letters, with no spaces.
  3. Build method: choose Repository.

  4. Fill in:

    Field Value
    Repository URL https://git.uglyhousesneedlove.com/steve/ferrule-deploy
    Repository reference refs/heads/main
    Compose path docker-compose.yml
    Authentication off (the repository is public)

  5. Leave Enable relative path volumes off.

On your Docker host:

git clone https://git.uglyhousesneedlove.com/steve/ferrule-deploy.git ferrule
cd ferrule
cp stack.env.example .env

Everything below happens in this ferrule folder.

2. Add the settings

Scroll down to Environment variables and click Advanced mode. Paste the lines below.

Open .env in a text editor. It already has every setting with an example value. Change the ones below, and leave the rest.

Replace each value with yours:

FERRULE_VERSION=0.9.0

UNIFI_HOST=https://192.168.1.1
UNIFI_API_KEY=paste-the-gateway-api-key
UNIFI_USERNAME=telemetry
UNIFI_PASSWORD=paste-the-gateway-password
  • FERRULE_VERSION is the release to run. Use the one you were told, never latest.
  • UNIFI_HOST is your gateway's address, starting https://.
  • If Protect runs on a separate UNVR, add four more lines (UniFi Protect).
  • If you have no UniFi console, set UNIFI_ENABLED=false instead of the UNIFI_ lines, and add a server or storage system (Watching without UniFi).

That's all it needs to start. You'll add everything else from inside Ferrule later, and it writes those lines for you.

3. Start it

Click Deploy the stack.

docker compose up -d

Docker downloads Ferrule and starts two containers, ferrule and ferrule-victoria-metrics. The first time takes a minute or two.

4. Open it

Go to http://<your docker host>:8090.

How to know it worked

  • Both containers are running, and ferrule turns healthy within about a minute. In Portainer, look at the stack's containers; with Compose, run docker compose ps.
  • The dashboard shows a WAN tab and a LAN tab with your devices.
  • Needs attention at the top lists anything that's wrong. On a healthy network it may be empty, or it may already have found something.

If it didn't work, see Troubleshooting. The most common causes:

What you see What to do
set FERRULE_VERSION to the release to run Add the FERRULE_VERSION line
manifest unknown FERRULE_VERSION has a typo
login rejected in the ferrule logs The UniFi account has two-factor sign-in on, or it's a cloud account rather than a local one (UniFi Network)
The page opens but shows no devices Check UNIFI_HOST, and that the Docker host can reach the gateway

The ferrule logs are under the container in Portainer, or docker compose logs ferrule with Compose.

Why two containers?

ferrule reads your equipment and serves the dashboard. ferrule-victoria-metrics stores the history behind the graphs. Both keep their data on Docker volumes, so nothing is written to the host's own folders, and redeploying never loses anything.

Changing a setting later

Every page in these docs that says "add these lines to your settings" means this:

  1. Open the ferrule stack and find Environment variables.
  2. Add or change the lines. In Advanced mode you can paste several at once.
  3. Click Pull and redeploy.
  1. Open .env in the folder where you cloned ferrule-deploy.
  2. Add or change the lines.
  3. Run docker compose up -d in that folder.

Next