NetAlertX is a self-hosted network visibility tool that helps administrators discover devices on their local networks, maintain an inventory of connected assets, and identify changes in network activity. In this practical guide, learn what NetAlertX does, how to deploy it with Docker, configure network scanning, and troubleshoot common discovery problems.
See What Is Connected to Your Network
Use NetAlertX to build a clearer picture of network-connected devices and support day-to-day network administration from a self-hosted web interface.
What Is NetAlertX?
NetAlertX is an open-source network visibility and asset discovery project. It is designed to help users identify devices on their networks, organize discovered assets, and monitor changes over time. It is useful for home labs, small networks, and IT administrators who want a dedicated view of connected devices.
The project is particularly relevant when you need more visibility than a basic router client list provides. Depending on your configuration and available scanning methods, NetAlertX can collect device information, help maintain an inventory, and support notifications or workflows around discovered assets.
Users searching for “jokobsk NetAlertX” may encounter older guides, repository references, and community discussions. Because project instructions and Docker configuration can change, the current repository and documentation should be your source of truth.
Key NetAlertX Features
Device Discovery
Discover visible network assets through supported scanning plugins and configured network ranges.
Asset Inventory
Maintain a centralized view of discovered devices and organize the information used by your network team.
Change Awareness
Review device discovery changes and use configured alerts to help identify unexpected network activity.
Configurable Scanners
Configure supported scanning plugins, subnets, and discovery settings for your environment.
Integrations
Explore documented integrations, notification options, and workflows that suit your monitoring setup.
Self-Hosted Deployment
Run NetAlertX in your own environment using its supported container-based deployment approach.
Available features and their behavior depend on the NetAlertX version, enabled plugins, permissions, and network topology. Consult the official documentation before designing a production monitoring workflow.
How to Install NetAlertX with Docker
Docker is the recommended deployment route in the NetAlertX installation documentation. A Linux host with access to the target network is generally the most appropriate starting point for Layer 2 discovery.
Prerequisites
- A supported Linux host or server for Docker.
- Docker Engine and Docker Compose installed and working.
- Permission to configure container networking and capabilities.
- A known network subnet and the correct network interface.
- Persistent storage for NetAlertX configuration and database data.
Prepare the host
Install Docker using the instructions for your Linux distribution. Verify that the Docker service is running and that you can execute Docker commands with the appropriate privileges.
Open the official installation instructions
Review the maintained repository and Docker installation guide before deploying. The recommended Compose configuration can change between project releases.
Deploy with the maintained Compose configuration
Use the current official Compose file rather than copying an older third-party configuration. The repository documents launching the project from source with Docker Compose.
This sequence builds and starts the project from the cloned repository. Follow the current repository instructions for environment variables, permissions, and persistent storage.
Check container status
After deployment, inspect the container and logs. Use the container name configured in your Compose file if it differs from the example below.
If the container uses a different name, substitute that name in the logs command. Check for permission, port, or network configuration errors before proceeding.
Open the web interface
The standard documented web interface port is 20211 unless changed in your configuration. Open the interface using the Linux host’s reachable IP address.
Replace YOUR_LINUX_HOST_IP with the actual address
of your host. If the interface does not load, check container
status, port settings, listening addresses, and host firewall
rules. Do not expose the interface directly to the public internet.
Configure NetAlertX for Network Discovery
Starting the container is only the first part of a working installation. Configure the correct subnet, interface, discovery plugins, and persistent storage for your environment.
1. Identify the network subnet
On a Linux host, use the following command to review local interface addresses and identify the network connected to the segment you want to monitor.
For example, a small lab might use 192.168.1.0/24.
This is only an example: configure the actual subnet and interface
used by your network. A subnet entry by itself does not guarantee
that all devices will be discoverable.
2. Configure scanning settings
Open the NetAlertX settings interface and review the scanner
configuration. For the default ARP scanning workflow, the official
documentation requires at least one valid subnet and interface
in the SCAN_SUBNETS setting.
Follow the current configuration syntax in the official guide. Use only interfaces and networks that you own or are authorized to administer.
3. Allow the initial discovery scan to finish
The official Docker installation guide notes that initial discovery can take several minutes and advises waiting approximately 5–10 minutes. Actual scan duration depends on the network, plugins, and configuration.
4. Review the discovered devices
Inspect the device inventory and validate a sample of discovered addresses against your router, DHCP server, switches, and known endpoints. Where appropriate, add useful labels or categories so the inventory is easier to maintain.
5. Configure alerts and integrations
Review the supported notification channels and workflow options documented by the project. Test alerts using an authorized, controlled change in your lab before relying on them operationally.
NetAlertX Docker Compose and Persistent Storage
Persistent storage matters because configuration and database files should survive container recreation. The current Compose documentation provides a baseline configuration and explains named volumes and bind mounts.
| Setting | Purpose | What to check |
|---|---|---|
| Host networking | Provides network visibility required by documented Layer 2 scanning methods. | Linux host, correct interface, and appropriate privileges. |
| Port 20211 | Default web interface port in the documented setup. | Configured port, listening address, and firewall rules. |
| Persistent volume | Stores configuration and database data. | Volume mounts, ownership, write access, and backups. |
| Container capabilities | Supports required scanning and service operations. | Use the maintained configuration and avoid unnecessary privileges. |
| Environment settings | Controls selected runtime options. | Use the variables documented for your installed release. |
Avoid mixing an older Compose file with a newer container image without checking the migration documentation. The NetAlertX project explicitly warns that Compose configuration has changed.
Official reference: NetAlertX Docker Compose documentation .
Troubleshooting Common NetAlertX Problems
NetAlertX does not discover devices
Verify that the configured subnet is correct, the scanning interface exists, and the container has the permissions and networking mode required by the selected scanner. ARP-based discovery is generally limited to the relevant Layer 2 segment; devices on routed networks may need a different documented discovery approach.
The web interface is unavailable
Check docker ps and the container logs. Confirm the
configured port and listening address, then review the Linux
host firewall and any network filtering between your computer
and the server.
The container reports permission errors
Inspect the ownership and permissions of the mounted data directories. The current project documents a service user with UID/GID 20211 by default. If you customize the runtime user, ensure the data and temporary mounts use compatible ownership and permissions.
Some devices are missing from the inventory
Check whether the device is on a different VLAN or subnet, whether the host can reach the relevant network segment, and whether the selected discovery plugin can observe that device. Client isolation, VLAN boundaries, sleeping endpoints, and scanning intervals can affect results.
An upgrade causes unexpected behavior
Review the version-specific migration instructions before upgrading or recreating the container. Back up the database and configuration first, and avoid deleting persistent volumes unless you intentionally want to remove their contents.
Security Best Practices
Network discovery tools operate close to your infrastructure. Treat the NetAlertX server and its web interface as administrative components, especially when monitoring business or production networks.
- Restrict access: Allow access to the web interface only from trusted management networks or through an appropriately secured remote-access method.
- Use least privilege: Retain only the capabilities required for your chosen scanners and deployment.
- Protect persistent data: Back up the configuration and database and protect backup copies.
- Update carefully: Review release notes and migration instructions before replacing the container image or Compose configuration.
- Validate alerts: A discovered device or change should be investigated in context; it does not automatically prove malicious activity.
- Respect network authorization: Scan only networks you own or have explicit permission to monitor.
Final Thoughts
NetAlertX is worth evaluating if you want a self-hosted way to discover devices and maintain better visibility into a home lab, office network, or authorized IT environment. Docker provides the documented installation route, while correct subnet selection, scanning configuration, persistent storage, and network permissions determine how useful the deployment will be.
If you arrived here through the search term “jokobsk NetAlertX,” use the current official NetAlertX repository and documentation for installation and upgrade guidance. This helps avoid relying on outdated commands or configurations from older tutorials.
References and Official Resources
-
NetAlertX — Official GitHub Repository
Project overview, supported features, installation entry points, and current source.
-
NetAlertX — Official Documentation
Configuration, installation, notifications, scanning, and troubleshooting guidance.
-
NetAlertX — Docker Compose
Baseline Compose configuration, networking requirements, and persistent storage.
-
NetAlertX — Docker Installation Guide
Container setup, scanner configuration, and common installation issues.
-
NetAlertX — Installation Options
Supported installation approaches and links to platform-specific instructions.
Editorial and accuracy note: This guide is based on the project’s publicly available documentation. The deployment has not been represented as independently tested by the author. Commands, supported platforms, and configuration options may change between releases. Verify current instructions before using them in production. NetAlertX is an independent open-source project; VMoreCloud is not affiliated with or endorsed by its maintainers.