NUT Server Docker Container

Containerized Network UPS Tools server on Debian, for monitoring USB UPS devices over the network (port 3493). Multi-arch: linux/amd64, linux/arm64, linux/arm/v7. Tested on Raspberry Pi 4.

Status: community-maintained, no active testing. Functional and stable for the author's setup (Raspberry Pi 4 + APC USB UPS). Issues and PRs welcome.

Quick Start

services:
  nut-server:
    image: nardo86/nut-server:latest
    container_name: nut-server
    ports:
      - "3493:3493"
    # Bind /dev/bus/usb as a volume (not `devices:`) so the UPS stays visible
    # after a USB re-enumeration — see "USB access" below
    volumes:
      - "/dev/bus/usb:/dev/bus/usb"
    device_cgroup_rules:
      - "c 189:* rwm"
    environment:
      NAME: home-ups
      DESC: Home APC Back-UPS ES 700
      POLLFREQ: 5
      TZ: Europe/Rome
    restart: unless-stopped

Or as a one-shot docker run:

docker run -d --name nut-server -p 3493:3493 \
  -v /dev/bus/usb:/dev/bus/usb \
  --device-cgroup-rule='c 189:* rwm' \
  --restart unless-stopped \
  nardo86/nut-server:latest

Configuration

Variable	Description	Default
NAME	UPS identifier	ups
DRIVER	NUT driver	usbhid-ups
PORT	Device port	auto
POLLFREQ	Polling interval (s)	5
DESC	UPS description	UPS
USERSSTRING	NUT users block (see below)	# (none)
TZ	Timezone	Etc/UTC

Find your UPS

lsusb
# Bus 001 Device 005: ID 051d:0002 American Power Conversion UPS

USB access

When a UPS drops off the bus and reconnects (flaky cable, self-reset), the kernel re-enumerates it under a new device node (.../001/005 → .../001/006). Mappings made with --device/devices: are snapshotted at container creation, so after a re-enumeration the container keeps talking to the dead node and the driver reports stale data until you recreate it.

Binding the whole /dev/bus/usb tree as a volume plus a device cgroup rule (c 189:* rwm — major 189 is USB) keeps newly enumerated nodes visible inside the container, as shown in the Quick Start. Pinning a single node with --device=/dev/bus/usb/001/005 still works if your UPS never re-enumerates, but is fragile.

Synology / remote monitoring users

USERSSTRING='[monuser]
  password = secret
  upsmon slave'

Compatible drivers: see the NUT Hardware Compatibility List. Common alternatives to usbhid-ups: blazer_usb, nutdrv_qx.

Troubleshooting

• Device not found: check lsusb on the host, verify the USB mapping, ensure the container has access (no --user overrides, USB cgroup allowed).
• Data for UPS [...] is stale - check driver: the UPS re-enumerated on the USB bus and the container lost it — see "USB access" above for the re-enumeration-proof mapping. The built-in healthcheck marks the container unhealthy in this state; Docker does not restart unhealthy containers by itself, so pair it with something that does (e.g. autoheal with an autoheal=true label on this container).
• Connection refused on 3493: verify port mapping and host firewall.
• Driver errors in logs: wrong driver for your model — try blazer_usb or nutdrv_qx.

Notes

• NUT version tracks whatever Debian stable ships (currently bookworm), not the upstream latest.
• Built with help from Claude (Anthropic). Review the configuration before production use. No warranty.
• Image: https://hub.docker.com/r/nardo86/nut-server

Support

⭐ Star • 🐛 Issue • 🔧 PR • ☕ https://paypal.me/ErosNardi