How to Deploy a Local Network Monitoring System with Docker in 10 Minutes

How to Deploy a Local Network Monitoring System with Docker in 10 Minutes

How Many Devices Are Actually on Your Network?

Over the years working as a backend developer, I've come to a realization: Network management isn't just an ops team's job—it's a trap every technologist eventually walks into.

Home NAS devices, Raspberry Pis, a friend's phone temporarily connecting to WiFi, IoT gadgets quietly coming online... Your router's admin panel is always a mess. In enterprise environments, it's even worse: shadow IT devices connecting, IP address drift, unauthorized services coming online. By the time you notice, something has often already gone wrong.

I previously tried mobile apps like Fing—scan once, check once—but they can't continuously monitor. Tools like Zabbix or Nagios are too heavy; just tuning plugins takes a full day. That's when I discovered NetAlertX—a network visibility platform you can get running with a single Docker command. It continuously discovers devices, monitors status changes, and even sends automated notifications.

In this guide, I'll walk you through deploying NetAlertX from scratch, configuring active scanning, and integrating Telegram alerts on your local network. Follow along, and you'll have a 24/7 pair of eyes watching your network.

Prerequisites

Why is host network mode mandatory? Because NetAlertX uses tools like arp-scan and nmap under the hood, which need direct access to the physical NIC to send and receive Layer 2 Ethernet frames. If you use bridge networking, ARP requests get NAT'd away and nothing gets discovered. I hit this pitfall on my first deployment.

Step 1: Launch the Container

NetAlertX officially provides a one-liner Docker command. We'll use it directly, but I'll break down every parameter for you.

mkdir -p /opt/netalertx/{config,db}

docker run -d \
  --name netalertx \
  --network=host \
  --restart unless-stopped \
  --cap-add=NET_RAW \
  --cap-add=NET_ADMIN \
  --cap-add=NET_BIND_SERVICE \
  -v /opt/netalertx/config:/data/config \
  -v /opt/netalertx/db:/data/db \
  -v /etc/localtime:/etc/localtime:ro \
  -e PORT=20211 \
  -e APP_CONF_OVERRIDE='{"GRAPHQL_PORT":"20214"}' \
  ghcr.io/netalertx/netalertx:latest

Parameter breakdown:

• --network=host: Container shares the host's network stack, mandatory for ARP scanning
• --cap-add=NET_RAW and the other two caps: Grant the container packet injection and low-port binding permissions
• -v mounting /data/config and /data/db: Data persistence, so container upgrades don't lose your data
• -v /etc/localtime: Aligns container timezone with host, preventing log timestamp confusion
• PORT=20211: Web UI port, modifiable as needed

Wait about 30 seconds, then visit http://<host-ip>:20211 in your browser to see the NetAlertX dashboard.

Step 2: Configure ARP Scanning to Make Devices "Pop Up" Automatically

Once inside the system, the first thing to do is tell it: How should it discover devices?

NetAlertX supports over a dozen scanning plugins: arp-scan, Pi-hole DHCP, UNIFI controller, SNMP router integration, and more. For home networks, the most straightforward and effective option is arp-scan. Its principle is simple: send an ARP request to every IP in your subnet, and live devices will respond.

Configuration steps:

1. In the left navigation, click Settings → Plugins
2. Find Scan > ARP-SCAN and enable it
3. Set the scan interval to the default 15 minutes (too high a frequency can cause broadcast storms)
4. In Network range, enter your subnet, e.g., 192.168.1.0/24
5. Save and wait for one scan cycle, then refresh the Devices page

You'll see a device table, deduplicated by MAC address, with fields for first discovery time, last online time, and vendor information. If you connect a phone to WiFi now, it will appear in the next scan cycle. This kind of continuous monitoring is something no mobile app can replicate.

Step 3: Hands-On — Integrating Telegram Alerts

Seeing a device list isn't enough. The truly valuable scenario is: Get notified the moment a new device connects.

NetAlertX uses the Apprise framework internally, supporting 80+ notification channels. Here I'll demonstrate Telegram because it's the most convenient.

3.1 Create a Telegram Bot

1. Search for @BotFather in Telegram, send /newbot
2. Follow the prompts to name your bot and retrieve the API Token (format like 123456:ABC-DEF...)
3. Search for @userinfobot, send any message, and get your own Chat ID

3.2 Configure the Notification Channel

Back to NetAlertX's Settings page:

1. Navigate to Notification → Notification channels
2. Add an Apprise channel
3. Enter URL: tgram://<BotToken>/<ChatID>
4. Save

3.3 Bind Alert Events

Having a channel isn't enough; you must tell the system when to send notifications:

1. In the left navigation, go to Settings → Notification rules
2. Create a new rule with the trigger condition New device detected
3. Select the Telegram channel you just created
4. Save

Next time a friend connects to your home WiFi or an IoT device quietly comes online, your phone will instantly receive a Telegram message: device name, MAC, IP, discovery time—all clear at a glance.

FAQ

1. Scanning devices across subnets / VLANs fails

ARP is a Layer 2 protocol and naturally cannot cross subnets. If you have multiple VLANs, you need to deploy a NetAlertX collection node in each subnet and use the Sync Nodes feature to aggregate results back to a central node. For home users, a single /24 subnet is usually sufficient.

2. Notifications are too frequent and spamming my phone

Add a throttling rule in Notification rules, e.g., allow only one notification per hour for the same event. This is strongly recommended for production environments; otherwise, frequent IP up/down events will blow up your phone's notifications.

3. Will container upgrades lose data?

No. As long as you properly mounted /data/config and /data/db, simply stop the old container, pull the new image, and docker run again—your data remains intact. It's recommended to create a tar backup of these directories before upgrading.

4. Incomplete scans on WiFi networks

Some routers enable MAC address randomization (iOS/Android's "Private WiFi Address" feature), causing the same device to show different MAC addresses each time. You can disable this feature on the router side, or alternatively use DHCP lease imports to supplement discovery.

Summary

After following this guide, you've accomplished something genuinely valuable: You deployed a continuously running network asset monitoring platform with a single Docker command, complete with automatic discovery and real-time alert automation. No cloud service registration required, all data keeps local, and the system is highly extensible.

There's plenty more you can explore later: integrate with Home Assistant for smart home automation, export metrics via Prometheus to build Grafana dashboards, or configure Webhooks to trigger n8n workflow automations. I'll cover these in future articles.

If you're interested in NetAlertX, find it on GitHub at netalertx/NetAlertX (currently 7k+ stars), with documentation at docs.netalertx.com. Drop a comment if you run into any deployment issues.