A practical, copy-and-paste guide to running NetAlertX on a Linux server with Docker: install Docker, start the official container, open the web interface and keep it secure and updated.
config and db subfolders, run the official ghcr.io/netalertx/netalertx:latest image with host networking and the NET_RAW, NET_ADMIN and NET_BIND_SERVICE capabilities, then open http://SERVER-IP:20211 in your browser.Know What is on Your Network, From Any Linux Server
NetAlertX discovers devices on your LAN, tracks when they connect or disconnect and alerts you to anything unknown. Docker makes the installation quick and keeps it separate from the rest of your system.
Any Docker-Capable Linux
Works on Ubuntu, Debian, Fedora, Raspberry Pi OS and similar systems.
About 15 Minutes
Install Docker, run one command and open the dashboard.
Data Stays Local
Scan data is stored on your server unless you add cloud notifications.
Requirements
NetAlertX scans the network that its host is connected to, so install it on a Linux machine that sits on the LAN you want to monitor, such as a small server, a mini PC, a VM or a Raspberry Pi.
- A Linux server with Docker Engine support (Ubuntu, Debian, Fedora, RHEL-based or Raspberry Pi OS)
- A user with sudo access and internet connectivity
- Port 20211 free on the host, or another port of your choice
- A modern browser, since the project supports Chrome and Firefox
If you are still learning Linux administration, our Linux tutorials cover server basics, and our networking guides explain IP addressing and VLANs.
Step 1: Install Docker on Linux
Install Docker Engine
The recommended method is to add Docker’s official package repository, as described in Docker’s installation documentation. For a quick lab or test server, Docker also provides a convenience script:
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.shDocker says this script is meant for development and test environments. Use the repository method on production servers.
Start Docker and enable it at boot
sudo systemctl enable --now dockerVerify the installation
sudo docker --version
sudo docker run hello-worldYou should see a version number and a short “Hello from Docker” message.
Step 2: Create the Data Folders
Prepare persistent storage
The official notes say the data directory should contain a config and a db folder. Create them:
sudo mkdir -p /opt/netalertx/data/config /opt/netalertx/data/dbEverything NetAlertX saves, including its settings and device database, will live in /opt/netalertx/data, so it survives container updates.
Step 3: Run the NetAlertX Container
Start the official image
Run this command, which follows the quick start in the NetAlertX repository:
sudo 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/data:/data \
-v /etc/localtime:/etc/localtime:ro \
--tmpfs /tmp:uid=20211,gid=20211,mode=1700 \
-e PORT=20211 \
-e APP_CONF_OVERRIDE='{"GRAPHQL_PORT":"20214"}' \
ghcr.io/netalertx/netalertx:latestWhat the options mean
| Option | Purpose |
|---|---|
--network=host | Lets the container see your LAN so scans can discover devices |
--restart unless-stopped | Starts NetAlertX again after a reboot or crash |
--cap-add=... | Grants the network permissions needed for low-level scans such as ARP |
-v /opt/netalertx/data:/data | Stores config and database on the host |
-v /etc/localtime... | Keeps the container clock in sync with the host (read-only) |
--tmpfs /tmp... | Temporary in-memory folder owned by user 20211 |
-e PORT=20211 | Sets the web interface port |
APP_CONF_OVERRIDE | Overrides an app setting, here the GraphQL port |
Check that it is running
sudo docker ps
sudo docker logs -f netalertxThe container should be listed as “Up”. Press Ctrl+C to leave the log view.
Step 4: Open the Firewall Port
If a firewall is active, allow the web port, and limit it to your local network instead of the whole internet. On Ubuntu with UFW, using your own subnet:
sudo ufw allow from 192.168.1.0/24 to any port 20211 proto tcpReplace 192.168.1.0/24 with your LAN range. Other distributions use firewalld or nftables, so apply the equivalent rule there.
Step 5: Open the Web Interface
Find the server IP
hostname -IBrowse to NetAlertX
From another computer on the network, open:
http://SERVER-IP:20211The device list fills in as the first scans complete, which can take a few minutes.
First-time configuration
- Enable the discovery method that fits your network. See the NetAlertX discovery methods overview.
- Choose how often scans run.
- Add a notification service such as Telegram, ntfy or Pushover.
- Name your known devices so unknown ones stand out.
Manage, Update and Back Up NetAlertX
Start, stop and restart
sudo docker stop netalertx
sudo docker start netalertx
sudo docker restart netalertxUpdate to the latest image
sudo docker pull ghcr.io/netalertx/netalertx:latest
sudo docker stop netalertx
sudo docker rm netalertxThen run the same docker run command from Step 3 again. Your data folder is kept. Read the release notes first.
Back up your data
Copy the config and db folders regularly:
sudo tar -czf netalertx-backup-$(date +%F).tar.gz -C /opt/netalertx dataKeep the archive on another disk or machine. For wider planning, see our backup and disaster recovery guides. If you would rather manage everything from one file, switch to the Docker Compose method.
Security Best Practices
NetAlertX holds a list of every device on your network, so treat the dashboard as an admin tool.
- Do not expose port 20211 directly to the internet
- Put the interface behind a reverse proxy that requires authentication
- Restrict access with a firewall, as in Step 4
- Keep the image updated for security fixes
- Only scan networks that you own or are authorized to monitor
Troubleshooting
The page does not load
Check sudo docker ps, confirm the firewall rule and use the correct IP and port.
No devices are found
Make sure --network=host and the three capabilities are in your run command, and that a scan method is enabled.
Permission denied for docker
Run the command with sudo, or add your user to the docker group and log in again. Group members have powerful access, so do this only on trusted systems.
Permission errors on the data folder
The container uses user ID 20211 for its temporary folder. If logs show permission problems, check the ownership notes in the official Docker guide.
Port already in use
Change the PORT value, remove the container and run it again.
Devices on other VLANs are missing
ARP scanning sees only the local segment. Use the project’s remote-network options or Sync Nodes.
Still stuck? Read the logs with sudo docker logs netalertx and search the project’s GitHub issues.
Frequently Asked Questions
Which Linux distributions can run NetAlertX?
Any distribution that can run Docker Engine, including Ubuntu, Debian, Fedora, RHEL-based systems and Raspberry Pi OS.
Which port does NetAlertX use?
In this setup the web interface listens on port 20211, set with the PORT environment variable.
Why does the container use host networking?
NetAlertX needs to see your local network to discover devices, and the project’s quick start uses host networking for that.
Will I lose my data when I update the container?
No, as long as the data folder stays mounted. Back up the config and db folders before major upgrades.
Should I use docker run or Docker Compose?
Both work. Docker run is quick for a first test, while Compose keeps your settings in one file and is easier to maintain.
Is NetAlertX free?
Yes. It is open source under the GPL-3.0 license.
Conclusion
You now have NetAlertX running in Docker on Linux, with its data stored safely on the host. From here, enable a scan method, add notifications and lock down the dashboard so you hear about unknown devices quickly. Keep the image updated and back up the data folder to stay safe.
config and db folders → Run the container → Allow port 20211 from the LAN → Open the web UI → Enable scanning and alerts → Secure and back up.Keep Learning with VMoreCloud
Find more step-by-step tutorials on networking, Linux, Windows Server, Azure and virtualization.
Sources & Further Reading
- NetAlertX on GitHub (quick start and features)
- NetAlertX Docker installation guide
- NetAlertX documentation
- Docker Engine installation documentation
Technical note: options and image behaviour can change between NetAlertX releases. These commands follow the project’s official quick start, so confirm them against the current documentation and test on a non-critical host before you rely on them.