bnhf/apcupsd repository overview

services:
  apcupsd:
    image: bnhf/apcupsd:latest
    container_name: apcupsd
    hostname: ${HOSTNAME} # Set a unique hostname per instance -- used in apcupsd-cgi and email notifications.
    devices:
      - ${APC_USB:-/dev/null} # Set APC_USB to your device path on masters (e.g. /dev/usb/hiddev0). Defaults to /dev/null on slaves.
    ports:
      - 3551:3551
    environment:
      - UPSNAME=${UPSNAME} # Sets a name for the UPS (1 to 8 chars), that will be used by System Tray notifications, apcupsd-cgi and Grafana dashboards.
      - TZ=${TZ}
    volumes:
      - /var/run/dbus/system_bus_socket:/var/run/dbus/system_bus_socket # Required to support host shutdown from the container.
      - ${HOST_DIR:-/data}/apcupsd:/etc/apcupsd # /etc/apcupsd can be bound to a directory or a docker volume.
    restart: unless-stopped

services:
  apcupsd: # This docker-compose typically requires no editing. Use the Environment variables section of Portainer to set your values.
    # 2026.06.01
    # GitHub home for this project: https://github.com/bnhf/apcupsd-admin-plus.
    # Docker container home for this project with setup instructions: https://hub.docker.com/r/bnhf/apcupsd.
    image: bnhf/apcupsd:${TAG:-latest} # Add the tag like latest or test to the environment variables below.
    container_name: apcupsd
    hostname: ${HOSTNAME} # Set a unique hostname per instance -- used in apcupsd-cgi and email notifications.
    dns_search: ${DOMAIN:-localdomain} # LAN domain for hostname resolution (e.g. local, localdomain). Optionally append a Tailnet domain space-separated.
    devices:
      - ${APC_USB:-/dev/null} # USB device for the connected UPS. Set APC_USB to your device path on masters (e.g. /dev/usb/hiddev0). Defaults to /dev/null on slaves.
    ports:
      - ${HOST_PORT:-3551}:3551 # Use the standard apcupsd port number of 3551, or optionally change it if it's in use on your Docker host. Default=3551.
    environment:
      - APCUPSD_COMPOSE=2026.06.01 # Do not change this value.
      # ── Identity ────────────────────────────────────────────────────────────
      - UPSNAME=${UPSNAME} # Sets a name for the UPS (1 to 8 chars), that will be used by System Tray notifications, apcupsd-cgi and Grafana dashboards.
      - TZ=${TZ} # Timezone, e.g. America/Denver.
      # ── UPS connectivity ────────────────────────────────────────────────────
      # On slaves set UPSCABLE=ether, UPSTYPE=net, DEVICE=masterhost:3551. No need to modify the devices section.
      - UPSCABLE=${UPSCABLE:-usb} # Cable type: usb, ether, etc. (default=usb).
      - UPSTYPE=${UPSTYPE:-usb} # UPS type: usb, net, etc. (default=usb).
      - DEVICE=${DEVICE} # Leave blank for USB masters. On slaves set to masterhost:3551.
      # ── Shutdown thresholds ─────────────────────────────────────────────────
      - POLLTIME=${POLLTIME:-60} # Interval (in seconds) at which apcupsd polls the UPS for status (default=60).
      - ONBATTERYDELAY=${ONBATTERYDELAY:-6} # Sets the time in seconds from when a power failure is detected until an onbattery event is initiated (default=6).
      - BATTERYLEVEL=${BATTERYLEVEL:-5} # Sets the daemon to send the poweroff signal when the UPS reports a battery level of x% or less (default=5).
      - MINUTES=${MINUTES:-5} # Sets the daemon to send the poweroff signal when the UPS has x minutes or less remaining power (default=5).
      - TIMEOUT=${TIMEOUT:-0} # Sets the daemon to send the poweroff signal when the UPS has been ON battery power for x seconds (default=0).
      - KILLDELAY=${KILLDELAY:-0} # If non-zero, sets the daemon to attempt to turn the UPS off x seconds after sending a shutdown request (default=0).
      # ── Maintenance ──────────────────────────────────────────────────────────
      - BATTDATE=${BATTDATE} # Date of last battery replacement in mm/dd/yy format, e.g. 06/01/26.
      - SELFTEST=${SELFTEST:-336} # UPS self-test interval in hours, e.g. 336 (2 weeks) (default=336).
      - EVENTSFILEMAX=${EVENTSFILEMAX:-10} # Sets the maximum size of the events file in kilobytes. 1024 is recommended. (default=10).
      - UPDATE_SCRIPTS=${UPDATE_SCRIPTS:-true} # Set to true if you'd like all the apcupsd scripts and .conf file to be overwritten with the latest versions (default=true).
      # ── Multi-UPS monitoring ────────────────────────────────────────────────
      - APCUPSD_HOSTS=${APCUPSD_HOSTS} # If this is the MASTER, then enter the APCUPSD_HOSTS list here, including this system (space separated).
      - APCUPSD_NAMES=${APCUPSD_NAMES} # Match the order of this list one-to-one to APCUPSD_HOSTS list, including this system (space separated).
      # ── Email notifications via Gmail SMTP ──────────────────────────────────
      - SMTP_GMAIL=${SMTP_GMAIL} # Gmail account (with 2FA enabled) to use for SMTP.
      - GMAIL_APP_PASSWD=${GMAIL_APP_PASSWD} # App password for apcupsd from Gmail account being used for SMTP.
      - NOTIFICATION_EMAIL=${NOTIFICATION_EMAIL} # The Email account to receive on/off battery messages and other notifications.
      - POWER_RESTORED_EMAIL=${POWER_RESTORED_EMAIL} # Set to true if you'd like an Email notification when power is restored after UPS shutdown.
      # ── Wake-on-LAN via WoLweb ──────────────────────────────────────────────
      - WOLWEB_HOSTNAMES=${WOLWEB_HOSTNAMES} # Space-separated list of hostnames to send WoL Magic Packets to on startup.
      - WOLWEB_PATH_BASE=${WOLWEB_PATH_BASE} # Everything after http:// and before the /hostname required to wake a system with WoLweb e.g. raspberrypi6:8089/wolweb/wake.
      - WOLWEB_DELAY=${WOLWEB_DELAY:-0} # Seconds to delay before sending WoL Magic Packets to WOLWEB_HOSTNAMES (default=0).
      # ── Proxmox shutdown via API ─────────────────────────────────────────────
      - PVE_SHUTDOWN_HOSTS=${PVE_SHUTDOWN_HOSTS} # Ordered list of pve hostnames (or IPs) to be used for API shutdown. Used with matching lists of PVE_SHUTDOWN_NODES and PVE_SHUTDOWN_TOKENS.
      - PVE_SHUTDOWN_NODES=${PVE_SHUTDOWN_NODES} # Ordered list of pve nodes. Used with matching lists of PVE_SHUTDOWN_HOSTS and PVE_SHUTDOWN_TOKENS.
      - PVE_SHUTDOWN_TOKENS=${PVE_SHUTDOWN_TOKENS} # Ordered list of pve API tokens with secrets in the form <username>@<realm>!<tokenid>=<secret>.
    healthcheck:
      test: ["CMD-SHELL", "apcaccess | grep -E 'ONLINE' >> /dev/null"] # Command to check health.
      interval: ${HC_INTERVAL:-30s} # Interval between health checks. Default=30s.
      timeout: ${HC_TIMEOUT:-5s} # Timeout for each health check. Default=5s.
      retries: ${HC_RETRIES:-3} # How many times to retry. Default=3.
      start_period: ${HC_START_PERIOD:-15s} # Estimated time to boot. Default=15s.
    volumes:
      - /var/run/dbus/system_bus_socket:/var/run/dbus/system_bus_socket # Required to support host shutdown from the container.
      - ${HOST_DIR:-/data}/apcupsd:/etc/apcupsd # /etc/apcupsd can be bound to a directory or a docker volume.
    restart: unless-stopped

# If you prefer to use Docker Volumes instead of directory bindings, uncomment below as required.
# volumes: # Use this section for volume bindings only
#   config: # The name of the stack will be appended to the beginning of this volume name, if the volume doesn't already exist
#     external: true # Use this directive if you created the docker volume in advance

TAG=latest
HOSTNAME=myhost_ups
DOMAIN=localdomain
APC_USB=/dev/usb/hiddev0
HOST_PORT=3551
HOST_DIR=/data
UPSNAME=MyUPS
TZ=America/Denver
UPSCABLE=usb
UPSTYPE=usb
DEVICE=
POLLTIME=60
ONBATTERYDELAY=6
BATTERYLEVEL=5
MINUTES=5
TIMEOUT=0
KILLDELAY=0
BATTDATE=01/01/25
SELFTEST=336
EVENTSFILEMAX=1024
UPDATE_SCRIPTS=true
APCUPSD_HOSTS=192.168.1.10 192.168.1.11
APCUPSD_NAMES=Closet Office
[email protected]
GMAIL_APP_PASSWD=xxxx xxxx xxxx xxxx
[email protected]
POWER_RESTORED_EMAIL=true
WOLWEB_HOSTNAMES=server1 server2
WOLWEB_PATH_BASE=raspberrypi6:8089/wolweb/wake
WOLWEB_DELAY=30
PVE_SHUTDOWN_HOSTS=pve1 pve2
PVE_SHUTDOWN_NODES=pve1 pve2
PVE_SHUTDOWN_TOKENS=shutdown@pve!token1=secret1 shutdown@pve!token2=secret2

docker exec apcupsd /etc/apcupsd/testshutdown

2026-06-01 10:00:01 -0600  testshutdown: Starting dry-run connectivity checks
2026-06-01 10:00:01 -0600  testshutdown: Testing Proxmox API for node pve1 via 192.168.1.10
2026-06-01 10:00:02 -0600  testshutdown: OK - pve1 reachable at 192.168.1.10, PVE version 8.2.1, token valid
2026-06-01 10:00:02 -0600  testshutdown: Testing dbus connectivity
2026-06-01 10:00:02 -0600  testshutdown: OK - dbus login1 is responding
2026-06-01 10:00:02 -0600  testshutdown: All checks passed

services:
  apcupsd-cgi: # This docker-compose typically requires no editing. Use the Environment variables section of Portainer to set your values.
    # 2026.06.01
    image: bnhf/apcupsd-cgi:${TAG:-latest}
    container_name: apcupsd-cgi
    dns_search: ${DNS_SEARCH:-localdomain} # Set to your LAN's domain name (often local or localdomain). Default=localdomain.
    ports:
      - ${HOST_PORT:-3552}:80 # Port to access the apcupsd-cgi web interface. Default=3552.
    environment:
      - UPSHOSTS=${UPSHOSTS} # Ordered list of hostnames or IP addresses of UPS connected computers (space separated, no quotes).
      - UPSNAMES=${UPSNAMES} # Matching ordered list of location names to display on status page (space separated, no quotes).
      - TZ=${TZ} # Timezone to use for status page -- UTC is the default.
    volumes:
      - ${HOST_DIR:-/data}/apcupsd-cgi:/etc/apcupsd
    restart: unless-stopped

UPSHOSTS (List of hostnames or IP addresses for computers with connected APC UPSs. Space separated without quotes.)
UPSNAMES (List of names you'd like used in the WebUI. Order must match UPSHOSTS. Space separated without quotes.)
TZ (Timezone for apcupsd-cgi to use when displaying information about individual UPS units)

services:
  wolweb: # This docker-compose typically requires no editing. Use the Environment variables section of Portainer to set your values.
    # 2026.06.01
    image: bnhf/wolweb:${TAG:-latest}
    container_name: wolweb
    environment:
      - WOLWEBPORT=${WOLWEBPORT:-8089} # The port you'd like WoLweb to use. Default=8089.
      - WOLWEBVDIR=${WOLWEBVDIR:-/wolweb} # The virtual directory for WoLweb to use. Default=/wolweb.
      - WOLWEBBCASTIP=${WOLWEBBCASTIP} # The broadcast IP for your subnet including the port (192.168.0.255:9 or 192.168.1.255:9 are typical).
    volumes:
      - ${HOST_DIR:-/data}/wolweb:/wolweb/data # Bind a directory to /wolweb/data for data persistence.
    network_mode: host # host is the only network mode that supports WoL Magic Packets.
    restart: unless-stopped

PVE_SHUTDOWN_HOSTS=192.168.1.10
PVE_SHUTDOWN_NODES=pve1 pve2 pve3
PVE_SHUTDOWN_TOKENS=shutdown@pve!mytoken=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

PVE_SHUTDOWN_HOSTS=192.168.1.10 192.168.1.11
PVE_SHUTDOWN_NODES=pve1 pve2
PVE_SHUTDOWN_TOKENS=shutdown@pve!token1=secret1 shutdown@pve!token2=secret2