Keep the Lights On with PeaNUT

Monitor UPS power status with PeaNUT on a Raspberry Pi, protecting servers and cold-chain equipment from outages while training volunteers in critical infrastructure care.

Power outages destroy data. A server that loses power without warning can corrupt databases, break file systems, and leave a nonprofit's infrastructure unusable for days. For organizations in rural areas, older buildings, or regions with unstable grids, an uninterruptible power supply (UPS) is not a luxury—it is infrastructure insurance. PeaNUT, a lightweight web dashboard for the Network UPS Tools (NUT) protocol, runs on a Raspberry Pi and gives your team real-time visibility into battery health, load levels, and estimated runtime.

Cost versus Consequences

A consumer-grade UPS costs $80–150. A Raspberry Pi to monitor it costs $75. Combined, they are cheaper than a single hour of downtime recovering a corrupted database—or a spoiled pallet of refrigerated medications.

Without monitoring, a UPS is a black box. Batteries degrade silently. A unit that once provided thirty minutes of runtime may offer only three after two years. PeaNUT exposes that decay before it becomes a crisis, giving volunteers time to replace batteries or shift workloads to redundant systems.

What You Need

Raspberry Pi 2 or newer (ARMv7 or ARM64)
One or more UPS units with NUT compatibility (APC, CyberPower, and Eaton are widely supported)
USB cable from each UPS to the Pi
Docker installed on the Pi (recommended) or willingness to compile from source

Installing the NUT Server

Before PeaNUT can display anything, the Pi needs to talk to the UPS. Install NUT:

sudo apt update
sudo apt install nut

Identify your UPS:

lsusb | grep -i "cyber\|apc\|eaton"

Edit /etc/nut/nut.conf and set the mode:

MODE=standalone

Edit /etc/nut/ups.conf to add your device. For a common CyberPower model:

[cyberpower]
  driver = usbhid-ups
  port = auto
  desc = "Main Server UPS"

Start the driver and server:

sudo systemctl restart nut-driver-enumerator
sudo systemctl restart nut-server

Verify communication:

upsc cyberpower@localhost

You should see voltage, load percentage, battery charge, and estimated runtime.

Installing PeaNUT

PeaNUT is distributed as a Docker container. Create a compose file:

services:
  peanut:
    image: brandawg93/peanut
    container_name: peanut
    ports:
      - "8080:8080"
    environment:
      - NUT_HOST=localhost
      - NUT_PORT=3493
    restart: unless-stopped

Start it:

docker compose up -d

Access the dashboard at http://YOUR_PI_IP:8080. You will see battery charge bars, load percentages, and runtime estimates for every connected UPS.

Dashboards That Matter

PeaNUT's interface is clean enough for non-technical staff. Pin the dashboard to a wall-mounted tablet or an old monitor connected to the Pi. At a glance, anyone can answer:

Is the battery healthy?
How much load are we drawing?
If the power goes out right now, how long do we have?

For multi-site organizations, PeaNUT supports multiple NUT servers. A single Pi in the main office can monitor UPS units in the satellite kitchen, the garden shed, and the server closet simultaneously.

Automated Shutdown

The ultimate protection is graceful shutdown when battery runs low. Edit /etc/nut/upssched.conf to trigger a shutdown script at a defined threshold, such as "ten minutes of runtime remaining":

AT ONBATT * START-TIMER shutdown 600
AT LOWBATT * EXECUTE shutdown

Link the timer to a script that cleanly shuts down your server, saves open databases, and powers off the Pi before the UPS dies completely. Test this quarterly—an untested shutdown script is wishful thinking.

Volunteer Maintenance Schedule

UPS batteries are consumables. Assign a volunteer to check PeaNUT monthly:

Log into the dashboard. Is every UPS showing "Online"?
Note the runtime estimate. Has it dropped significantly since last month?
Physically inspect the UPS: is the exhaust vent blocked by dust or storage boxes?
Document findings in a paper logbook next to the server

Replace batteries every two to three years, or sooner if runtime drops below your minimum safe threshold. Most consumer UPS units use standard 12V sealed lead-acid batteries available at hardware stores for $20–40.

Why This Matters for Nonprofits

Small organizations often treat power protection as an afterthought—until the first outage wipes a week of intake records or destroys a donor database. PeaNUT turns power monitoring into a visible, teachable routine. The volunteer who checks the battery dashboard today is the same person who will recognize a failing UPS before it fails, who will know how to swap a battery, and who will understand why graceful shutdown matters. That competence compounds. It protects your data, your equipment, and the trust of the people who depend on your services.