wiki/Catalogue-Self-Hosted/apps/app-peanut.md

---
title: PeaNUT
created: 2026-06-07
updated: 2026-06-07
type: app
tags: [catalogue, networking, ups, monitoring, nut, apc, eaton, python, dashboard]
confidence: high
contested: false
sources: [https://selfh.st/apps/?tag=networking, https://github.com/Brandawg93/PeaNUT]
---

# 🔋 PeaNUT

> **Dashboard web et client NUT** léger pour surveiller vos onduleurs (UPS) compatibles : charge batterie, autonomie restante, consommation, alertes. Le compagnon visuel idéal d'un serveur [[app-nut]] ou d'un NAS qui expose le protocole network UPS tools.

| Métadonnée | Valeur |
| :--- | :--- |
| **Site web** | [github.com/Brandawg93/PeaNUT](https://github.com/Brandawg93/PeaNUT) |
| **GitHub** | [Brandawg93/PeaNUT](https://github.com/Brandawg93/PeaNUT) |
| **License** | MIT |
| **Langage** | Python (FastAPI) + TypeScript (frontend) |
| **Étoiles** | 410 ⭐ |
| **Dernière MAJ** | 2026-05-30 |
| **Catégorie** | [[cat-networking\|Networking]] |

## Description

PeaNUT est une **web UI moderne pour NUT (Network UPS Tools)**, le démon de référence sous Linux pour piloter un onduleur (UPS) via USB ou réseau. Plutôt que de subir la console `upsc` en CLI ou l'interface vieillissante d'[[app-nut]], PeaNUT expose un **dashboard temps réel** (charge, tension, fréquence, température, autonomie estimée) avec **historique**, **alertes** (push, email, webhook), et **commandes** (test batterie, arrêt graceful des machines).

Le projet supporte nativement les onduleurs des marques les plus courantes : **APC, CyberPower, Eaton, Tripp Lite, MGE, Best Power**. Il suffit d'un onduleur USB branché à un serveur (ou d'un onduleur réseau avec carte SNMP/ethernet) et d'un démon NUT (nut-server) qui l'expose via le port 3493. PeaNUT se connecte, scrape les variables MIB, et les affiche.

Cas d'usage typique : un onduleur APC Back-UPS 1500VA protège un NAS Synology et un petit serveur. Sur le NAS tourne `nut-server`, sur le serveur tourne PeaNUT (Docker). Le dashboard PeaNUT montre l'autonomie (12 min), la charge (32%), la consommation (180W). Quand une coupure dépasse 5 minutes, PeaNUT déclenche un webhook Home Assistant qui initie l'arrêt propre des VMs avant que la batterie ne meure.

## Installation

### Docker Compose (recommandé)

```yaml
# docker-compose.yml
services:
  peanut:
    image: brandawg93/peanut:latest
    container_name: peanut
    restart: unless-stopped
    ports:
      - "8480:8080"
    environment:
      - NUT_HOST=192.168.1.50        # IP du serveur NUT
      - NUT_PORT=3493
      - NUT_USER=monuser
      - NUT_PASS=***      - TZ=Europe/Paris
      - INFLUX_HOST=influxdb.local  # optionnel : export métriques
      - INFLUX_TOKEN=***    volumes:
      - peanut-config:/config
    depends_on:
      - nut-server

  # Exemple : NUT server intégré (si onduleur USB sur la même machine)
  nut-server:
    image: instantlinux/nut-upsd:latest
    container_name: nut-server
    restart: unless-stopped
    devices:
      - /dev/bus/usb:/dev/bus/usb     # onduleur USB passé au container
    ports:
      - "3493:3493"
    environment:
      - SHUTDOWNCMD=shutdown -h now
    volumes:
      - nut-config:/etc/nut
    privileged: true

volumes:
  peanut-config:
  nut-config:
```

> ⚠️ Le serveur NUT (`nut-server`) doit tourner ailleurs (Synology, OpenWRT, machine avec onduleur USB) ; PeaNUT n'est qu'un **client** / dashboard.

### Installation manuelle (Docker simple)

```bash
docker run -d \
  --name peanut \
  -p 8480:8080 \
  -e NUT_HOST=192.168.1.50 \
  -e NUT_PORT=3493 \
  -e NUT_USER=monuser \
  -e NUT_PASS=***\
  -v peanut-config:/config \
  --restart unless-stopped \
  brandawg93/peanut:latest
```

## Configuration

Sur le serveur NUT, configurer l'utilisateur et l'onduleur :

```conf
# /etc/nut/ups.conf
[apc-ups]
  driver = usbhid-ups
  port = auto
  desc = "APC Back-UPS 1500"

# /etc/nut/upsd.conf
LISTEN 0.0.0.0 3493

# /etc/nut/upsd.users
[monuser]
  password = ***  actions = SET
  instcmds = ALL

# /etc/nut/upsmon.conf
MONITOR apc-ups@localhost 1 monuser *** master
SHUTDOWNCMD "/sbin/shutdown -h now"
```

Côté PeaNUT (UI web sur `http://localhost:8480`), ajouter le serveur NUT et les seuils d'alerte.

API JSON exposée (utile pour scripts) :

```bash
curl http://peanut.local:8480/api/v1/devices | jq
# Charge, status, charge en %, runtime restant, etc.
```

## Alternatives

### Open Source

- [[app-nut]] — NUT lui-même, en CLI / upsc
- **apcupsd** — APC-spécifique, plus ancien
- **Network UPS Tools Web UI (inactive)** — projets communautaires de GUI
- **Grafana + InfluxDB + NUT exporter** — DIY dashboard
- **Synology / QNAP built-in** — limité à leur écosystème
- **Home Assistant NUT integration** — basique, sans historique
- **OpenWRT NUT package** — sur le routeur, ultra-léger

### Propriétaire (ce que PeaNUT remplace)

- **PowerChute Business Edition (APC/Schneider)** — 50-300€ selon l'onduleur
- **Eaton Intelligent Power Manager** — payant
- **CyberPower PowerPanel** — Windows/macOS, pas Linux
- **ManageEngine OpManager UPS module** — enterprise
- **PRTG UPS sensor** — payant, Paessler
- **Tripp Lite PowerAlert** — UI basique, vieillissante

## Sécurité

- **LAN-only par défaut** : PeaNUT expose l'état de l'onduleur. Mettre derrière un reverse-proxy avec auth (Authentik, Authelia) ou VPN ([[app-wireguard]]).
- **Mots de passe NUT** : l'utilisateur NUT a des droits `SET` ; un attaquant peut déclencher un shutdown. Restreindre via `actions` dans `upsd.users`.
- **HTTPS** : activer TLS via Traefik/Caddy ; les credentials transitent en clair sinon.
- **2FA sur l'UI** : PeaNUT supporte l'auth intégrée, l'activer.
- **Alertes webhook** : chiffrer si le canal n'est pas déjà sécurisé (Ntfy, Discord OK).
- **Surveillance du daemon NUT** : si `upsd` meurt, PeaNUT ne reçoit plus rien. Superviser via [[app-watchtower]] ou [[app-prometheus]].
- **Updates** : suivre les releases, vulnérabilités potentielles dans FastAPI.
- **Pas d'auto-shutdown sauvage** : configurer des seuils d'autonomie (ex : shutdown si < 5 min) pour éviter d'éteindre un serveur qui pourrait tenir.

## Ressources

- [GitHub](https://github.com/Brandawg93/PeaNUT)
- [Documentation NUT](https://networkupstools.org)
- [Liste des drivers NUT supportés](https://networkupstools.org/stable-hcl.html)
- [Discord communautaire](https://discord.gg/peanut)
- [Wiki PeaNUT](https://github.com/Brandawg93/PeaNUT/wiki)

## Pages Liées

- [[cat-networking|Networking]] — Catégorie parente
- [[cat-monitoring|Monitoring]] — Catégorie cousine
- [[app-nut|NUT (Network UPS Tools)]] — Serveur source
- [[app-home-assistant|Home Assistant]] — Intégration et automatisation shutdown
- [[app-prometheus|Prometheus]] — Métriques long-terme
- [[app-grafana|Grafana]] — Visualisation historique
- [[recettes-docker-compose|Recettes Docker Compose]]
- [[protection-onduleurs-homelab|Protection onduleurs homelab]] — Stratégie globale