Home Assistant Addons: Docker & NUT Integration

Hey there, fellow Home Assistant enthusiasts! If you're like me and rocking the pure Docker version of Home Assistant (not HA OS or Supervised), you've probably run into a bit of a roadblock when it comes to those super handy add-ons. It's a bit of a bummer that we can't just click and install them directly, right? But don't despair! Over the years, I've found that many add-ons can be successfully run in their own Docker containers and then integrated into Home Assistant. It's a fantastic workaround that keeps our setups lean and customizable. Today, we're diving deep into the world of running the NUT (Network UPS Tools) add-on outside of the typical Home Assistant add-on manager, specifically for those of us managing our Home Assistant instance via Docker or Docker Compose. We'll explore how to get this essential power monitoring tool up and running, ensuring your home automation stays online even when the power goes out.

The Challenge of Docker-Based Home Assistant and Add-ons

Running Home Assistant in a pure Docker environment offers a lot of flexibility and control. You're not tied to a specific operating system, and you can manage your Home Assistant instance alongside other Dockerized applications with ease. However, this flexibility comes with a trade-off: the built-in add-on store, which is a cornerstone of the HA OS and Supervised installations, isn't directly available. This means that if you want to use functionalities provided by official or community add-ons, you need to find alternative ways to deploy them. For many, the go-to solution is to containerize these add-ons themselves. This approach involves creating or finding existing Docker images for the desired add-on, configuring them appropriately, and then ensuring they can communicate with your main Home Assistant instance. It requires a bit more technical know-how, involving Dockerfiles, docker-compose.yml files, and understanding network configurations, but the payoff is a truly customized and robust setup. The NUT add-on is a perfect example of a tool that many would want to run alongside their Home Assistant setup, especially for those who have invested in Uninterruptible Power Supplies (UPS) to protect their critical home network equipment. Ensuring Home Assistant itself is aware of the power status and can potentially trigger automations based on UPS events is a crucial aspect of a resilient smart home. Without direct add-on support, we need to get creative, and containerizing NUT is a prime candidate for this.

Why NUT is Crucial for Your Smart Home

Let's talk about why the Network UPS Tools (NUT) is such a big deal, especially when you've got a whole smart home ecosystem humming along. Think about all the devices you have: your router, your Wi-Fi access points, your NAS, your smart home hub (which is Home Assistant, of course!), maybe even some security cameras. A sudden power outage, even a brief flicker, can cause all of these to shut down abruptly. This isn't just an inconvenience; it can lead to data corruption on your NAS, your network going down, and your automations grinding to a halt at the most critical moments. A UPS acts as a buffer, providing a temporary power source from its battery. But simply having a UPS isn't enough; you need to communicate with it. This is where NUT shines. It's a powerful, open-source suite of tools that allows you to monitor your UPS status – things like battery charge level, input voltage, load percentage, and whether it's running on battery power. More importantly, NUT can alert you to power issues and, crucially, can gracefully shut down your connected devices before the UPS battery completely drains. For Home Assistant users, integrating NUT means your smart home can become aware of power problems. Imagine automations that trigger when the power goes out: maybe it sends you a notification, shuts down non-essential devices to conserve battery, or even initiates a safe shutdown of your Home Assistant server itself if the outage is prolonged. This level of control and awareness is invaluable for maintaining the reliability and resilience of your smart home, turning a potential disaster into a managed event. Without this integration, your Home Assistant instance is flying blind during a power outage, completely unaware of the precarious situation.

Setting Up NUT as a Standalone Docker Container

So, how do we get NUT running as its own Docker container when you're not using the Home Assistant add-on system? It's definitely achievable! The first step is to find a reliable Docker image for NUT. Many community members have created and maintain such images, often available on Docker Hub. When selecting an image, look for one that is actively maintained, has good reviews, and clearly states its compatibility with common UPS hardware. Once you've chosen an image, you'll need to configure it. This typically involves setting up environment variables within your Docker run command or docker-compose.yml file. Key configuration parameters usually include specifying your UPS hardware (e.g., USBUPS for USB-connected UPSs or SNMPUPS for network-connected ones), the device path for USB connections (like /dev/bus/usb/...), and credentials if your UPS requires them. You'll also need to define how NUT will communicate its status. This often involves setting up a NUT server component within the container and potentially a client component that can interact with it. A common setup is to run NUT in server mode, providing an HTTP or CGI interface, or more commonly, an upsd (UPS daemon) that Home Assistant can query. The docker-compose.yml file is your best friend here. It allows you to define the NUT service, its image, necessary environment variables, volume mounts (for persistent configuration or logs), and network settings. Crucially, you'll want to ensure the NUT container can communicate with your Home Assistant instance. This might involve running both containers on the same Docker network or exposing specific ports from the NUT container so Home Assistant can access its status information. For instance, if your NUT container exposes the upsd service on port 3493, your Home Assistant configuration will need to point to that port.

Example Docker Compose Configuration for NUT

Let's get a bit more concrete with a docker-compose.yml snippet. This is a simplified example, and you'll need to adapt it based on your specific UPS hardware and Docker environment. The goal is to define a service for NUT that can run independently.

version: "3.8"

services:
  nut-server:
    image: yours/nut-server-image:latest  # Replace with a real NUT image
    container_name: nut-server
    restart: unless-stopped
    environment:
      # Example variables - CONSULT YOUR IMAGE DOCUMENTATION!
      - UPS_MODEL=your_ups_model
      - UPS_PORT=/dev/hidraw0  # Or your specific UPS device path
      - UPS_DRIVER=usbhid  # Or your UPS driver (e.g., apcups, snmp-ups)
      - NUT_MONITOR_USER=monitor
      - NUT_MONITOR_PASS=your_monitor_password
      - NUT_ADMIN_USER=admin
      - NUT_ADMIN_PASS=your_admin_password
    devices:
      - "/dev/bus/usb:/dev/bus/usb" # Granting access to USB devices
    networks:
      - ha_network

networks:
  ha_network:
    external: true # Assuming you have a pre-existing Docker network for Home Assistant

Important Notes for this configuration:

• image: You'll need to find a suitable NUT Docker image. Search Docker Hub for nut-server or similar. Popular choices might include images built by the community.
• devices: This is critical for USB-connected UPS devices. It maps your host's USB devices into the container. You might need to adjust /dev/bus/usb or specific device nodes based on your system.
• Environment Variables: The variables like UPS_MODEL, UPS_PORT, UPS_DRIVER, and user/password details are examples. You absolutely MUST consult the documentation for the specific NUT Docker image you choose. Each image will have its own set of required and optional environment variables for configuration.
• networks: This assumes you have a Docker network named ha_network that your Home Assistant container is also connected to. This is vital for communication between Home Assistant and the NUT container. If you don't have one, you'll need to define it or connect them via the host network if necessary (though a dedicated network is cleaner).
• Permissions: Ensure the user running Docker on your host has the necessary permissions to access the UPS device files.

This docker-compose.yml file defines a service named nut-server. It specifies the Docker image to use, restarts the container automatically, sets up environment variables for configuration, maps USB devices into the container, and connects it to your Home Assistant's Docker network. Once this is set up, you can run docker-compose up -d in the directory containing this file to start your NUT container.

Integrating NUT with Home Assistant (Docker Install)

Now that you have your NUT container humming along, the next step is to integrate it with your Home Assistant instance. Since you're running Home Assistant in Docker, you won't be using the built-in Add-on integration. Instead, you'll be configuring the NUT integration directly within Home Assistant's configuration.yaml file or through the UI if you're using newer versions of Home Assistant that support it. The key is to point Home Assistant to your running NUT server. You'll need to specify the host (which will be the service name or IP address of your NUT container on the Docker network, e.g., nut-server if they are on the same network), the port (3493 is the default for upsd), and the username and password you configured within your NUT container setup (e.g., the monitor user credentials). For example, in your configuration.yaml (or within the Integrations UI under the NUT integration), you'd add something like this:

# Example configuration.yaml entry
nut:
  host: nut-server  # Or the IP address of the nut-server container
  port: 3493
  username: monitor
  password: your_monitor_password
  # Optional: Specify UPS name if you have multiple
  # ups_name: myups

After saving your configuration.yaml file, you'll need to restart your Home Assistant Docker container for the changes to take effect. Once Home Assistant restarts, navigate to the Integrations page. You should see the NUT integration listed, and it should display the status of your UPS. You'll now have entities available in Home Assistant that represent your UPS, such as battery level, power status, and more. These entities can be used to create dashboards, trigger automations (e.g., sending notifications when on battery, initiating a graceful shutdown of Home Assistant if the power is out for too long), and generally enhance the resilience of your smart home setup. The beauty of this Docker-to-Docker integration is that it keeps your NUT monitoring completely separate from your Home Assistant core, providing a more robust and modular system. This decoupled approach means that if something were to happen with your NUT container, it wouldn't directly affect your Home Assistant instance, and vice-versa. Remember to check the Home Assistant documentation for the most up-to-date configuration options for the NUT integration, as Home Assistant continuously evolves.

Troubleshooting Common Issues

Even with the best-laid plans, you might run into a few hiccups when setting up NUT in Docker and integrating it with Home Assistant. One of the most common issues is connectivity problems. Ensure that both your Home Assistant container and your NUT container are on the same Docker network. If they are, you should be able to use the service name of the NUT container (e.g., nut-server) as the host address in your Home Assistant configuration. If you're using host networking or separate networks, you'll need to use the IP address of the NUT container and ensure that the necessary ports (defaulting to 3493 for upsd) are accessible. Another frequent problem relates to device access, particularly for USB UPS devices. Double-check that you've correctly mapped the USB devices from your host into the NUT container using the devices section in your docker-compose.yml file. Sometimes, specific USB device nodes need to be exposed rather than the entire /dev/bus/usb directory. Consult the documentation for your specific NUT Docker image and your host operating system for the correct device path. Permissions are also a key area to check; the user running the Docker container needs read/write access to the UPS device files. If you see errors related to