services:
  # Main Nutify application and NUT monitoring service.
  nut:
    # Select the tag matching the host CPU. This default is for AMD64/x86_64.
    image: dartsteven/nutify:latest-amd64
    # Fixed name makes logs and container commands easier to use.
    container_name: Nutify

    # Start from no Linux capabilities, then restore only those needed by the
    # entrypoint for file ownership, user switching, and process supervision.
    cap_drop:
      - ALL
    cap_add:
      - CHOWN        # Set ownership on persistent bind-mounted files.
      - DAC_OVERRIDE # Prepare files whose existing permissions are restrictive.
      - FOWNER       # Adjust modes on files prepared during startup.
      - KILL         # Supervise child NUT and web processes.
      - SETGID       # Drop services to the configured runtime group.
      - SETUID       # Drop services to the configured runtime user.
    security_opt:
      # Prevent processes from gaining additional privileges after startup.
      - no-new-privileges:true

    # USB HID discovery and driver access. This exposes only the USB bus, not
    # privileged mode or the complete host /dev tree. Major 189 is Linux USB.
    device_cgroup_rules:
      - "c 189:* rwm"

    # Persistent host directories. They survive image updates and recreation.
    volumes:
      - ./Nutify/logs:/app/nutify/logs         # Application and NUT logs.
      - ./Nutify/instance:/app/nutify/instance # Database and runtime state.
      - ./Nutify/ssl:/app/ssl                  # Optional TLS certificate/key.
      - ./Nutify/etc/nut:/etc/nut              # Generated NUT configuration.
      - /dev/bus/usb:/dev/bus/usb:rw           # USB devices for nut-scanner/NUT.
      - /run/udev:/run/udev:ro                 # Read-only USB identity metadata.

    # Base runtime settings. OIDC can be configured later in
    # System -> Authentication, without changing this file.
    environment:
      # Required secret for sessions and encrypted provider credentials.
      # Generate it once with: openssl rand -hex 32
      SECRET_KEY: ${SECRET_KEY:?Set SECRET_KEY in .env; generate it with openssl rand -hex 32}
      NUTIFY_WEB_USER: nut      # Unprivileged user running the web application.
      NUT_SERVICE_USER: nut     # Unprivileged user running NUT commands.
      UDEV: "1"                 # Enable USB/udev-aware device discovery.
      SKIP_PERMCHECK: "true"    # Never chmod/chown host USB device nodes.
      # Optional numeric host USB group when it cannot be detected at startup.
      NUTIFY_USB_GID: ${NUTIFY_USB_GID:-}
      LOG: "true"               # Enable application logging.
      LOG_LEVEL: INFO            # DEBUG, INFO, WARNING, ERROR, or CRITICAL.
      LOG_WERKZEUG: "true"      # Enable HTTP access logs.
      ENABLE_LOG_STARTUP: Y      # Log startup diagnostics without secret values.
      SSL_ENABLED: "false"      # Set true only after mounting valid TLS files.
      # Optional comma-separated exact reverse-proxy origins; wildcards fail.
      SOCKETIO_ALLOWED_ORIGINS: ${SOCKETIO_ALLOWED_ORIGINS:-}

    # Explicit external resolvers used by provider APIs and remote NUT hosts.
    dns:
      - 1.1.1.1 # Cloudflare DNS.
      - 8.8.8.8 # Google Public DNS fallback.
    dns_opt:
      - timeout:2 # Seconds allowed for each DNS attempt.
      - attempts:2 # Number of attempts before the query fails.

    # Host-to-container ports. Quote mappings to avoid YAML number parsing.
    ports:
      - "3493:3493" # NUT upsd endpoint for authorized network clients.
      - "5050:5050" # Nutify HTTP application and setup wizard.
      - "443:443"   # Nutify HTTPS endpoint when SSL_ENABLED=true.

    # Restart after crashes and host reboots until explicitly stopped.
    restart: always