Docker Compose Guide

Docker Compose Guide

This page documents the Docker Compose profile currently used for Nutify in this repository. It is written for beginners who want a stable and reproducible deployment.

1) What This Compose Profile Gives You

With this profile you get:

• containerized Nutify runtime
• USB device visibility for local UPS detection
• persistent data folders for logs, DB state, SSL, and NUT config
• mandatory login flow

2) Recommended Compose (Reference Profile)

Use this exact configuration:

services:
  nut:
    # Container image
    image: dartsteven/nutify:amd64-latest        # Nutify image version
    container_name: Nutify                       # Static container name for easy reference

    # Privileges required for 
    # direct UPS and USB device access
    privileged: true                             # Broad hardware access for NUT and USB integration
    cap_add:
      - SYS_ADMIN                                # Extended system administration capabilities
      - SYS_RAWIO                                # Raw hardware I/O access
      - MKNOD                                    # Create special device files if needed

    # USB device mapping
    devices:
      - /dev/bus/usb:/dev/bus/usb:rwm            # Map host USB bus into the container
    device_cgroup_rules:
      - 'c 189:* rwm'                            # Allow all USB character devices

    # Persistent storage and host integration
    volumes:
      - ./Nutify/logs:/app/nutify/logs           # Application logs
      - ./Nutify/instance:/app/nutify/instance   # Persistent app data and runtime files
      - ./Nutify/ssl:/app/ssl                    # SSL certificates and private keys
      - ./Nutify/etc/nut:/etc/nut                # NUT configuration directory
      - /dev:/dev:rw                             # Full device tree access for hardware detection
      - /run/udev:/run/udev:ro                   # Udev event access for hotplug monitoring

    # Runtime environment
    environment:
      - SECRET_KEY=test1234567890                # Secret key used for sessions and encrypted values
      - UDEV=1                                   # Enable udev-aware USB detection mode
      - LOG=true                                 # Enable general application logging: true/false, default is false
      - LOG_LEVEL=INFO                           # Accepted values currently are DEBUG, INFO, WARNING, ERROR, CRITICAL
      - LOG_WERKZEUG=true                        # Enable Werkzeug HTTP/server logs: true or false, default is false
      - ENABLE_LOG_STARTUP=Y                     # Valid values are Y or N, default is N, any other value is treated as N
      - SSL_ENABLED=false                        # true or false, default is false
     
     # DNS resolvers
    dns:
      - 1.1.1.1                                  # Cloudflare DNS
      - 8.8.8.8                                  # Google DNS
    dns_opt:
      - timeout:2                                # DNS timeout per query
      - attempts:2                               # Retry count before failure

    # Exposed ports
    ports:
      - 3493:3493                                # NUT daemon communication port
      - 5050:5050                                # Nutify application port
      - 443:443                                  # HTTPS secure web access

    restart: always                              # Keep the service running across failures/reboots
    user: root                                   # Root required for full device and NUT access

3) Where This Compose Exists in the Repo

Same profile is stored in:

• github/docker-compose.yaml

4) Prerequisites

Before running:

• Docker Engine and Docker Compose plugin installed
• host machine can expose /dev/bus/usb if using local UPS
• write permission for ./Nutify/* folders
• free ports: 3493, 5050, 443

5) Field-by-Field Explanation

Image and Identity

• image: pinned tested build tag
• container_name: stable name for logs and operations

Hardware Access

• privileged: true
• cap_add: SYS_ADMIN, SYS_RAWIO, MKNOD
• USB and cgroup device rules

Why:

• many NUT driver flows need low-level hardware access

Persistence Volumes

• ./Nutify/logs -> runtime logs
• ./Nutify/instance -> database and app state
• ./Nutify/ssl -> certificates
• ./Nutify/etc/nut -> generated/managed NUT configs

Host mounts:

• /dev:/dev:rw
• /run/udev:/run/udev:ro

These improve hotplug and hardware visibility.

Environment Variables

• SECRET_KEY: required for secure runtime behavior
• UDEV=1: enables udev-aware behavior in container runtime

DNS and Ports

• DNS: 1.1.1.1, 8.8.8.8
• 3493: NUT service
• 5050: Nutify web UI
• 443: HTTPS endpoint

Restart and User

• restart: always: service resilience across host/container restarts
• user: root: required by this hardware-oriented profile

6) Quick Start Commands

From directory containing docker-compose.yaml:

docker compose up -d

Check status:

docker compose ps

Watch logs:

docker compose logs -f

Stop stack:

docker compose down

7) First-Run Validation Checklist

After first up -d:

1. open http://<host>:5050
2. complete wizard (if setup mode is active)
3. verify login works
4. verify topbar shows expected target
5. open System -> Advanced -> NUT Manager and verify inventory

8) Safe Update Procedure

1. backup:
   • ./Nutify/instance
   • ./Nutify/etc/nut
   • ./Nutify/logs
2. update only image tag
3. run:

docker compose pull
docker compose up -d

4. validate login, targets, and dashboards

9) Safe Rollback Procedure

If new tag is unstable:

1. restore previous known-good image tag
2. run:

docker compose up -d

3. validate target inventory and UI behavior

10) Troubleshooting Quick Notes

UI not reachable:

• check docker compose ps
• check port conflicts on 5050 and 443

No local UPS detected:

• verify USB mounts and privileges
• verify host sees UPS under /dev/bus/usb

11) Common Mistakes

• changing SECRET_KEY unexpectedly between restarts
• removing hardware mounts and losing UPS visibility
• using image tag for wrong architecture
• editing two compose files in parallel and starting wrong one

12) Security Notes for Beginners

• keep SECRET_KEY private
• avoid committing secrets in public repositories
• use strong admin credentials in wizard step 1
• restrict network exposure if instance is LAN-only