Skip to content

NetAlertX Docker Compose Deployment Guide

NetAlertX is a lightweight network monitoring application that automatically discovers devices on your network and alerts you when they appear, disappear or change.

It is an excellent addition to any homelab because it provides a live inventory of everything connected to your network, from servers and desktops to phones, tablets, printers and IoT devices.

This guide shows how to deploy NetAlertX using Docker Compose.

Official project:

What You'll Need

Before starting, make sure you have:

  • A Linux server with Docker and Docker Compose installed
  • A working Docker environment
  • A local network that NetAlertX can scan
  • Basic knowledge of Docker Compose

Create the Project Folder

I keep all Docker applications under /opt/docker.

Create a folder for NetAlertX:

mkdir -p /opt/docker/netalertx
cd /opt/docker/netalertx

Basic Docker Compose Example

Create a file called docker-compose.yml.

services:
  netalertx:
    image: jokobsk/netalertx:latest
    container_name: netalertx

    network_mode: host

    restart: unless-stopped

    volumes:
      - ./data:/data

Start the container:

docker compose up -d

Access the Web Interface

Once the container has started, open:

http://YOUR_SERVER_IP

When using network_mode: host, NetAlertX uses its default web port directly on the host.

First-Time Configuration

After logging in you can:

  • Scan your local network
  • Name your devices
  • Mark permanent devices
  • Ignore devices you don't care about
  • Configure notifications
  • Schedule automatic scans

Over time NetAlertX builds an accurate inventory of everything on your network.

Why Host Networking?

Unlike many Docker applications, NetAlertX needs direct access to your local network in order to discover devices.

Using:

network_mode: host

allows it to:

  • detect new devices
  • identify MAC addresses
  • monitor IP address changes
  • perform network discovery without Docker network restrictions

For this reason, host networking is the recommended deployment method.

Advanced Example (Reference Only)

The following is my production Docker Compose configuration. Passwords and sensitive information have been removed.

services:
  netalertx:
    image: jokobsk/netalertx:latest
    container_name: netalertx
    stop_grace_period: 30s

    network_mode: host

    privileged: true

    environment:
      - TZ=America/Santo_Domingo

    volumes:
      - /opt/docker/netalertx/data:/data
      - /opt/docker/netalertx/tmp:/tmp

    restart: unless-stopped

Notes on My Configuration

My deployment includes a few additional options:

  • privileged: true allows NetAlertX to access lower-level networking features used by some discovery methods.
  • The timezone is set to match my location.
  • Configuration and database files are stored under /opt/docker/netalertx.
  • Host networking provides direct visibility of every device on my LAN.

Typical Uses

I use NetAlertX to:

  • Discover new devices joining my network
  • Keep an inventory of all servers and virtual machines
  • Monitor IoT devices
  • Detect unexpected devices
  • Identify devices that have gone offline
  • Help troubleshoot DHCP and networking issues

It's surprising how often you discover forgotten devices that are still connected to your network.

Notifications

NetAlertX supports a variety of notification methods, including:

  • Email
  • ntfy
  • MQTT
  • Webhooks
  • Telegram
  • Discord
  • Slack
  • Pushover

I recommend configuring notifications so you're alerted when new or unknown devices appear on your network.

Updating NetAlertX

To update to the latest version:

docker compose pull
docker compose up -d

Troubleshooting

No devices detected

Check that:

  • Host networking is enabled.
  • The server is connected to the correct network.
  • Your firewall isn't blocking network discovery.

Web interface won't load

Verify that:

  • The container is running:
docker ps
  • Host networking isn't conflicting with another application already using the same port.

Device names are incorrect

Initially NetAlertX only knows MAC addresses and hostnames.

As you identify devices you can rename them within the interface, making future alerts much easier to understand.

Related Guides

Final Thoughts

NetAlertX is one of those applications that quietly runs in the background until the day you really need it. Whether you're tracking down an unfamiliar device, troubleshooting network issues or simply keeping an inventory of your homelab, it provides a clear view of what's happening on your network.

For anyone running more than a handful of devices, it's a valuable addition to a self-hosted homelab.