{ "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 for connections on all interfaces\n PORT: ${PORT:-20211} # Application port\n GRAPHQL_PORT: ${GRAPHQL_PORT:-20212} # GraphQL API port (passed into APP_CONF_OVERRIDE at runtime)\n # NETALERTX_DEBUG: ${NETALERTX_DEBUG:-0} # 0=kill all services and restart if any dies. 1 keeps running dead services.\n # PUID: 20211 # Runtime PUID override, set to 0 to run as root\n # PGID: 20211 # Runtime PGID override\n\n # Resource limits to prevent resource exhaustion\n mem_limit: 2048m # Maximum memory usage\n mem_reservation: 1024m # Soft memory limit\n cpu_shares: 512 # Relative CPU weight for CPU contention scenarios\n pids_limit: 512 # Limit the number of processes/threads to prevent fork bombs\n logging:\n options:\n max-size: \"10m\" # Rotate log files after they reach 10MB\n max-file: \"3\" # Keep a maximum of 3 log files\n\n # Always restart the container unless explicitly stopped\n restart: unless-stopped\n\nvolumes: # Persistent volume for configuration and database storage\n netalertx_data:\n" }, "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 } }