Deploy NetAlertX on a Linux server using a single docker-compose.yml file. This guide covers the folders, the Compose file, first start, updates and common fixes.
Run NetAlertX the Clean Way: One Compose File, Persistent Data
Docker Compose keeps your NetAlertX settings in a single file you can read, back up and reuse. Start, stop and update the whole stack with one command.
One-Command Deploy
Start the container with docker compose up -d.
Persistent Data
Config and database live on the host, so upgrades keep your settings.
Easy Updates
Pull the new image and recreate the container in two commands.
Introduction
NetAlertX scans your network, keeps an inventory of connected devices and alerts you when something new appears. The project’s quick start uses a long docker run command. That works, but a Docker Compose file is easier to maintain: every option is written down in one place, you can store it in version control and you can recreate the container exactly the same way after an update.
This guide turns the official quick-start command into a Compose file and walks through the full installation. If you want to understand what the tool can detect first, see our NetAlertX features and network monitoring guide.
docker run quick start. Compare it with the project’s Docker installation guide before you deploy, and read the migration guide if you upgrade an older install.Requirements
- A Linux host on the network you want to scan, such as a mini PC, a VM or a Raspberry Pi
- Docker Engine with the Compose plugin (see Docker’s installation guide)
- Administrator (sudo) access on the host
- Port 20211 free on the host, or another port you choose
- A modern browser: the project supports Chrome and Firefox
New to Linux administration? Browse our Linux tutorials for server basics, and our networking guides for IP addressing and VLAN background.
| docker run option | Compose equivalent |
|---|---|
--network=host | network_mode: host |
--restart unless-stopped | restart: unless-stopped |
--cap-add=NET_RAW (and others) | cap_add: list |
-v /local_data_dir:/data | volumes: entry |
--tmpfs /tmp:... | tmpfs: entry |
-e PORT=20211 | environment: entry |
Step 1: Check Docker and Compose
Confirm both tools are installed
Run these commands on the host:
docker --version
docker compose versionBoth should print a version number. If docker compose is not found, install the Compose plugin from Docker’s documentation.
Step 2: Create the Project and Data Folders
Make a folder for the stack
The official notes say the data directory should contain a config and a db folder. Create them next to your Compose file:
mkdir -p ~/netalertx/data/config ~/netalertx/data/db
cd ~/netalertxEverything NetAlertX saves, including its settings and device database, will live in ~/netalertx/data, so it survives container updates.
Step 3: Create the docker-compose.yml File
Write the Compose file
Create the file:
nano docker-compose.ymlPaste this content:
services:
netalertx:
container_name: netalertx
image: ghcr.io/netalertx/netalertx:latest
network_mode: host
restart: unless-stopped
cap_add:
- NET_RAW
- NET_ADMIN
- NET_BIND_SERVICE
volumes:
- ./data:/data
- /etc/localtime:/etc/localtime:ro
tmpfs:
- /tmp:uid=20211,gid=20211,mode=1700
environment:
PORT: "20211"
APP_CONF_OVERRIDE: '{"GRAPHQL_PORT":"20214"}'Save and close the file (Ctrl+O, Enter, then Ctrl+X in nano).
What each setting does
| Setting | Purpose |
|---|---|
image | The official NetAlertX image from the GitHub Container Registry |
network_mode: host | Lets the container see your LAN so scans can discover devices |
restart: unless-stopped | Starts NetAlertX again after a reboot or a crash |
cap_add | Grants the network permissions needed for low-level scans such as ARP |
./data:/data | Stores config and database on the host |
/etc/localtime | Keeps the container time the same as the host (read-only) |
tmpfs | A temporary in-memory /tmp owned by user 20211 |
PORT | The port of the web interface |
APP_CONF_OVERRIDE | Overrides an app setting, here the GraphQL port |
Want a different web port? Change the PORT value, and make sure nothing else on the host uses it.
Step 4: Validate and Start NetAlertX
Check the file for mistakes
docker compose configThis prints the final configuration, or an error that points to the problem line. YAML is sensitive to spaces, so indent with spaces, not tabs.
Start the container
docker compose up -dDocker downloads the image and starts NetAlertX in the background.
Verify that it is running
docker compose ps
docker logs -f netalertxThe status should show the container as running. Press Ctrl+C to leave the log view.
Step 5: Open the Web Interface
Browse to NetAlertX
From another computer on the same network, open:
http://SERVER-IP:20211Replace SERVER-IP with the host’s IP address. The device list fills in as the first scans complete, which can take a few minutes.
Step 6: First-Time Configuration
- Open Settings and enable the discovery method that matches your network. See the list of methods in our NetAlertX discovery methods overview.
- Set how often scans run.
- Add a notification service such as Telegram, ntfy or Pushover so new-device alerts reach you.
- Name your known devices and mark them, so unknown ones stand out.
- Secure the interface before you rely on it (see the security section below).
Step 7: Update, Stop and Back Up
Update to the latest image
cd ~/netalertx
docker compose pull
docker compose up -dRead the release notes first, especially after a major version change.
Stop or remove the container
docker compose stop
docker compose downdown removes the container but keeps your data folder.
Back up your data
The project stores its data in the config and db folders, so copy them regularly:
tar -czf netalertx-backup-$(date +%F).tar.gz -C ~/netalertx dataStore the archive on another disk or machine. For broader backup planning, see our backup and disaster recovery guides.
Security Best Practices
NetAlertX holds a list of every device on your network, so treat its dashboard as an admin tool.
- Do not expose port 20211 directly to the internet
- Put the interface behind a reverse proxy that requires authentication
- Limit access with a host or network firewall
- 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 that the container is running with docker compose ps, that the host firewall allows the port, and that you used the right IP and port.
No devices are found
Make sure network_mode: host and the network capabilities are present, and that a scan method is enabled in Settings.
Permission errors on the data folder
The container uses user ID 20211 for its temporary folder. If logs show permission problems, check the ownership requirements in the official Docker guide and adjust the data folder accordingly.
Devices on other VLANs are missing
ARP scanning sees only the local segment. Use the project’s remote-network options or Sync Nodes for other subnets.
Port already in use
Change the PORT value in the Compose file and run docker compose up -d again.
YAML errors
Run docker compose config. Use spaces for indentation and keep the JSON value in quotes.
Still stuck? Check the container logs with docker logs netalertx and search the project’s GitHub issues.
Frequently Asked Questions
Why use Docker Compose instead of docker run?
A Compose file records all your options in one readable file. It is easier to back up, share, change and reuse than a long command.
Which port does NetAlertX use?
In this setup the web interface listens on port 20211, set with the PORT variable.
Why does NetAlertX need host networking?
It must see your local network to discover devices, and the project’s quick start uses host networking for that reason.
Will I lose my data when I update?
No, as long as the ./data folder stays mounted. Back it up before major upgrades.
Can I install it without Docker?
Yes. The project documents a bare-metal installation, a Home Assistant add-on and an Unraid app.
Is NetAlertX free?
Yes, it is open source under the GPL-3.0 license.
Conclusion
With one docker-compose.yml, you now have NetAlertX running as a repeatable, easily updated service. Your configuration and device database sit in a single data folder, and you can restart, update or move the stack with a few commands. The next step is to enable a scan method, add notifications and secure the dashboard so you are alerted to unknown devices quickly.
data/config and data/db → Write docker-compose.yml → docker compose up -d → Open port 20211 → 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. This Compose file was adapted from the project’s official docker run quick start, so confirm it against the current documentation and test on a non-critical host before you rely on it.