ProxMenux/oci/catalog/curated/netalertx.json

{
  "schema_version": "0.5.0",
  "kind": "proxmenux.oci-template",
  "id": "image-netalertx",
  "status": "generated-unvalidated",
  "catalog_ui": {
    "title": {
      "en_US": "NetAlertX"
    },
    "tagline": {
      "en_US": "Discover and monitor devices on your local network."
    },
    "description": {
      "en_US": "NetAlertX discovers devices on your local network and tracks its device inventory in a self-hosted web interface."
    },
    "category": "monitoring",
    "category_label": "Monitoring & Analytics",
    "author": "NetAlertX",
    "developer": "NetAlertX",
    "icon": "https://cdn.jsdelivr.net/gh/selfhst/icons@main/webp/netalertx.webp",
    "thumbnail": null,
    "screenshots": [],
    "architectures": [
      "amd64",
      "arm64"
    ],
    "launch": {
      "scheme": "http",
      "port": 20211,
      "path": "/"
    },
    "website": "https://netalertx.com/",
    "documentation": "https://docs.netalertx.com/DOCKER_INSTALLATION/",
    "repository": "https://github.com/netalertx/NetAlertX",
    "tips": [
      "The web interface listens on port 20211. GraphQL listens on port 20212.",
      "The upstream Docker Compose baseline requests a read-only root filesystem, drops all capabilities before adding a small allow-list, and uses a temporary filesystem for /tmp. This native OCI-on-LXC profile does not reproduce those Docker Engine controls: ProxMenux validates requested cap_add values against the LXC user namespace and maps only the supported network sysctls. Docker capability bounding and read-only-rootfs behavior are not enforced.",
      "Compose network_mode: host maps to this application LXC network namespace, never the Proxmox host. Layer 2 discovery may still depend on the selected bridge and network; the installation smoke test only confirms startup and the web interface.",
      "The initial Devices page reported no devices yet and advises checking SCAN_SUBNETS. Configure scanning for the local subnet as needed; this smoke test did not verify discovery.",
      "This profile does not configure a login. The web interface opened directly to the Devices page during the smoke test."
    ],
    "mini_changelog": [],
    "display_version": null,
    "updated_at": null
  },
  "source": {
    "provider": "NetAlertX",
    "repository": "https://github.com/netalertx/NetAlertX",
    "revision": "6f3cb9bd43855596da3e8c6185490abd5784f1dd",
    "image_repository_url": "https://github.com/netalertx/NetAlertX/pkgs/container/netalertx",
    "readme_pushed_at": "",
    "compose_sha256": "1e5265637e13cc4c61901a685e4fe9cd015f8e1c52ad419de2392f2791795135",
    "generated_at": "2026-10-27T20:39:28+00:00",
    "readme_raw_url": "https://raw.githubusercontent.com/netalertx/NetAlertX/6f3cb9bd43855596da3e8c6185490abd5784f1dd/docs/DOCKER_COMPOSE.md"
  },
  "container_contract": {
    "service_name": "netalertx",
    "container_name": "netalertx",
    "image": {
      "reference": "ghcr.io/netalertx/netalertx:latest",
      "registry": "ghcr.io",
      "repository": "ghcr.io/netalertx/netalertx",
      "tag": "latest",
      "digest": null,
      "pull_policy": "resolve-selected-tag-to-architecture-digest-at-install"
    },
    "environment": [
      {
        "name": "LISTEN_ADDR",
        "example": "0.0.0.0",
        "required": true,
        "sensitive": false,
        "source": "docker-compose"
      },
      {
        "name": "PORT",
        "example": "20211",
        "required": true,
        "sensitive": false,
        "source": "docker-compose"
      },
      {
        "name": "GRAPHQL_PORT",
        "example": "20212",
        "required": true,
        "sensitive": false,
        "source": "docker-compose"
      }
    ],
    "volumes": [
      {
        "id": "volume-0",
        "container_path": "/data",
        "compose_source_example": "netalertx-data",
        "read_only": false,
        "required": true,
        "installation_choice": [
          "managed-volume",
          "host-bind"
        ],
        "default": "managed-volume",
        "managed_volume": {
          "backup": true,
          "default_size_gb": 8
        }
      }
    ],
    "ports": [],
    "related_services": [],
    "restart": "unless-stopped",
    "stop_grace_period": null,
    "original_compose": "services:\n  netalertx:\n  #use an environmental variable to set host networking mode if needed\n    container_name: netalertx                       # The name when you docker contiainer ls\n    image: ghcr.io/netalertx/netalertx:latest\n    network_mode: ${NETALERTX_NETWORK_MODE:-host}   # Use host networking for ARP scanning and other services\n\n    read_only: true                                 # Make the container filesystem read-only\n    cap_drop:                                       # Drop all capabilities for enhanced security\n      - ALL\n    cap_add:                                        # Add only the necessary capabilities\n      - NET_ADMIN                                   # Required for ARP scanning\n      - NET_RAW                                     # Required for raw socket operations\n      - NET_BIND_SERVICE                            # Required to bind to privileged ports (nbtscan)\n      - CHOWN                                       # Required for root-entrypoint to chown /data + /tmp before dropping privileges\n      - SETUID                                      # Required for root-entrypoint to switch to non-root user\n      - SETGID                                      # Required for root-entrypoint to switch to non-root group\n    # --- ARP FLUX MITIGATION ---\n    # Note: When using `network_mode: host`, these sysctls require the\n    # NET_ADMIN capability to be applied to the host namespace.\n    # \n    # If your environment restricts capabilities, or you prefer to configure\n    # them on the Host OS, REMOVE the sysctls block below and apply via:\n    # sudo sysctl -w net.ipv4.conf.all.arp_ignore=1 net.ipv4.conf.all.arp_announce=2\n    # ---------------------------\n    sysctls:                                        # ARP flux mitigation (reduces duplicate/ambiguous ARP behavior on host networking)\n      net.ipv4.conf.all.arp_ignore: 1\n      net.ipv4.conf.all.arp_announce: 2\n\n    volumes:\n      - type: volume                                # Persistent Docker-managed named volume for config + database\n        source: netalertx_data\n        target: /data                               # `/data/config` and `/data/db` live inside this mount\n        read_only: false\n\n    # Example custom local folder called /home/user/netalertx_data\n    # - type: bind\n    #   source: /home/user/netalertx_data\n    #   target: /data\n    #   read_only: false\n    # ... or use the alternative format\n    # - /home/user/netalertx_data:/data:rw\n\n      - type: bind                                  # Bind mount for timezone consistency\n        source: /etc/localtime\n        target: /etc/localtime\n        read_only: true\n\n      # Mount your DHCP server file into NetAlertX for a plugin to access\n      # - path/on/host/to/dhcp.file:/resources/dhcp.file\n\n    # tmpfs mount consolidates writable state for a read-only container and improves performance\n    # uid/gid default to the service user (NETALERTX_UID/GID, default 20211)\n    # mode=1700 grants rwx------ permissions to the runtime user only\n    tmpfs:\n      # Comment out to retain logs between container restarts - this has a server performance impact.\n      - \"/tmp:uid=${NETALERTX_UID:-20211},gid=${NETALERTX_GID:-20211},mode=1700,rw,noexec,nosuid,nodev,async,noatime,nodiratime\"\n\n      # Retain logs - comment out tmpfs /tmp if you want to retain logs between container restarts\n      # Please note if you remove the /tmp mount, you must create and maintain sub-folder mounts.\n      # - /path/on/host/log:/tmp/log\n      # - \"/tmp/api:uid=${NETALERTX_UID:-20211},gid=${NETALERTX_GID:-20211},mode=1700,rw,noexec,nosuid,nodev,async,noatime,nodiratime\"\n      # - \"/tmp/nginx:uid=${NETALERTX_UID:-20211},gid=${NETALERTX_GID:-20211},mode=1700,rw,noexec,nosuid,nodev,async,noatime,nodiratime\"\n      # - \"/tmp/run:uid=${NETALERTX_UID:-20211},gid=${NETALERTX_GID:-20211},mode=1700,rw,noexec,nosuid,nodev,async,noatime,nodiratime\"\n\n    environment:\n      LISTEN_ADDR: ${LISTEN_ADDR:-0.0.0.0}                   # Listen
  },
  "compose_stack": {
    "project_name": "netalertx",
    "deployment_model": "one-native-oci-lxc-per-compose-service",
    "user_experience": "single-application-install",
    "main_service": "netalertx",
    "service_count": 1,
    "services": [
      {
        "name": "netalertx",
        "image": "ghcr.io/netalertx/netalertx:latest",
        "is_main": true,
        "role": "frontend",
        "vmid_offset": 0,
        "depends_on": [],
        "frontend_network": true,
        "private_network": false,
        "compose": {
          "image": "ghcr.io/netalertx/netalertx:latest",
          "container_name": "netalertx",
          "network_mode": "host",
          "cap_add": [
            "NET_ADMIN",
            "NET_RAW",
            "NET_BIND_SERVICE",
            "CHOWN",
            "SETUID",
            "SETGID"
          ],
          "sysctls": {
            "net.ipv4.conf.all.arp_ignore": "1",
            "net.ipv4.conf.all.arp_announce": "2"
          },
          "restart": "unless-stopped",
          "environment": {
            "LISTEN_ADDR": "0.0.0.0",
            "PORT": "20211",
            "GRAPHQL_PORT": "20212"
          },
          "volumes": [
            "netalertx-data:/data"
          ],
          "mem_limit": "2048m"
        }
      }
    ],
    "top_level": {
      "name": "netalertx",
      "volumes": {
        "netalertx-data": {}
      }
    },
    "networking": {
      "frontend": "selected-proxmox-bridge",
      "private_required": false,
      "private_creation": "automatic-create-if-missing",
      "private_address_allocation": "automatic-static-address-per-service",
      "service_discovery": "private-addresses-with-compose-service-host-aliases",
      "dependency_external_access": "disabled-unless-service-publishes-ports",
      "prompt_user_for_private_network": false
    },
    "storage": [
      {
        "id": "netalertx-volume-0",
        "service": "netalertx",
        "container_path": "/data",
        "mode": "managed-volume",
        "user_selectable": false,
        "backup": true,
        "shared_with_other_lxc": false,
        "source_path": null,
        "source_path_prompt": null
      }
    ],
    "orchestration": {
      "reserve_vmids_atomically": 1,
      "start_order": [
        "netalertx"
      ],
      "stop_order": [
        "netalertx"
      ],
      "dependency_readiness": "compose-healthcheck-then-port-or-process-fallback",
      "rollback_on_failure": "remove-new-rootfs-preserve-created-persistent-volumes"
    },
    "installer_inputs": {
      "prompted": [
        "stack_name",
        "base_vmid",
        "rootfs_storage",
        "persistent_data_destinations",
        "frontend_bridge",
        "frontend_ipv4_mode"
      ],
      "automatic": [
        "dependent_vmids",
        "private_bridge",
        "private_subnet",
        "private_service_addresses",
        "compose_service_aliases",
        "generated_secrets",
        "dependency_start_and_stop_order"
      ],
      "generated_secrets": []
    }
  },
  "first_run": {
    "endpoints": [
      {
        "label": "Web UI",
        "scheme": "http",
        "port": 20211,
        "path": "/",
        "source": "compose-metadata"
      }
    ],
    "credentials": []
  },
  "proxmox": {
    "runtime": "native-oci-lxc",
    "technology_status": "proxmox-technology-preview",
    "defaults": {
      "unprivileged": true,
      "ostype": "auto-from-image",
      "cores": 2,
      "memory_mb": 1024,
      "swap_mb": 512,
      "rootfs_size_gb": 8,
      "rootfs_storage": "local-lvm",
      "volume_storage": "local-lvm",
      "template_storage": "local",
      "bridge": "vmbr0",
      "ipv4": "dhcp",
      "firewall": true,
      "host_managed_network": true,
      "onboot": false,
      "features": [
        "nesting=1"
      ],
      "shutdown_timeout_seconds": 30
    },
    "image_metadata_policy": {
      "entrypoint": "import-from-oci-image",
      "cmd": "import-from-oci-image",
      "environment": "import-image-env-then-apply-compose-overrides",
      "user": "import-from-oci-image",
      "working_dir": "import-from-oci-image",
      "stop_signal": "import-from-oci-image"
    },
    "installer_profile": {
      "resources": {
        "memory_default_mb": 2048
      },
      "network": {
        "compose_mode": "host"
      },
      "security": {
        "required_capabilities": [
          "NET_ADMIN",
          "NET_RAW",
          "NET_BIND_SERVICE",
          "CHOWN",
          "SETUID",
          "SETGID"
        ],
        "sysctls": [
          {
            "name": "net.ipv4.conf.all.arp_ignore",
            "value": "1"
          },
          {
            "name": "net.ipv4.conf.all.arp_announce",
            "value": "2"
          }
        ]
      }
    },
    "adaptations": [
      {
        "id": "netalertx-native-network",
        "upstream_behavior": "The official Compose profile uses host networking for layer 2 discovery and adds NET_ADMIN, NET_RAW and NET_BIND_SERVICE capabilities.",
        "native_lxc_behavior": "ProxMenux validates the declared cap_add names against the LXC user namespace and maps the documented network sysctls into the LXC configuration.",
        "reason": "A dedicated LXC already has its own address and network namespace, so Docker network plumbing is not needed.",
        "behavioral_impact": "Host mode refers to the NetAlertX LXC, not the Proxmox host. Compose cap_add values are validated but are not applied as an OCI capability bounding set; actual discovery may depend on the selected bridge and network.",
        "validation": "startup-and-web-smoke-tested-2026-10-27"
      },
      {
        "id": "netalertx-docker-hardening",
        "upstream_behavior": "The official Docker baseline sets read_only, cap_drop: ALL and a tmpfs for /tmp before adding its documented capability allow-list.",
        "native_lxc_behavior": "ProxMenux validates declared cap_add names against the LXC user namespace and maps supported sysctls, but does not translate read_only, cap_drop or tmpfs into equivalent native OCI-on-LXC controls.",
        "reason": "The OCI-on-LXC engine maps a supported subset of Compose to Proxmox resources; Docker Engine confinement options cannot be asserted as equivalent without a native mapping.",
        "behavioral_impact": "This profile does not reproduce Docker capability bounding, dropped-capability or read-only-rootfs behavior. The startup and web UI smoke test did not validate network scanning or scanner permissions.",
        "validation": "reviewed-from-upstream-compose"
      },
      {
        "id": "netalertx-persistent-data",
        "upstream_behavior": "The official Compose profile stores configuration and the device database in /data.",
        "native_lxc_behavior": "ProxMenux stores /data in a selectable managed volume or host bind directory.",
        "reason": "The app database and configuration need to survive OCI image replacement.",
        "behavioral_impact": "Persistent /data is included in Proxmox backups when a managed volume is selected.",
        "validation": "not-tested-in-installation-smoke"
      }
    ]
  },
  "compatibility": {
    "automatic_install_candidate": true,
    "validated": false,
    "supported_compose_keys": [
      "cap_add",
      "command",
      "container_name",
      "cpu_shares",
      "deploy",
      "devices",
      "entrypoint",
      "environment",
      "extra_hosts",
      "group_add",
      "healthcheck",
      "hostname",
      "image",
      "init",
      "ipc",
      "labels",
      "logging",
      "mac_address",
      "mem_limit",
      "network_mode",
      "networks",
      "ports",
      "privileged",
      "restart",
      "runtime",
      "security_opt",
      "shm_size",
      "stdin_open",
      "stop_grace_period",
      "sysctls",
      "tty",
      "ulimits",
      "user",
      "volumes",
      "working_dir"
    ],
    "untranslated_blockers": [],
    "policy": "Single-image definitions are installable when every declared Compose option has a native Proxmox translation. Multi-image and unsupported runtime features remain blocked until their orchestrator or mapping is available."
  },
  "validation": {
    "schema": "passed-at-generation",
    "clean_install": "pending",
    "service_health": "pending",
    "restart_persistence": "pending",
    "backup_restore": "pending",
    "update_preserves_data": "pending"
  },
  "lifecycle": {
    "update_strategy": "resolve-latest-image-then-apply-reviewed-native-lxc-update",
    "registry_state": {
      "resolved_architecture": null,
      "resolved_digest": null,
      "image_version_label": null,
      "image_created": null
    },
    "change_detection": "compare-compose-sha256-and-resolved-latest-image-digest",
    "automatic_unattended_updates": false
  }
}