Portainer Templates logo

Portainer Templates

NetAlertX NetAlertX

Stack

Network

WIFI / LAN intruder detector. Scans for devices connected to your network and alerts you if new and unknown devices are found.

Image details

Pulls: 4.4M
Architecture: amd64, arm64, arm/v7, arm/v6, arm64/v8
Image size: 104 MB
Latest: 26.8
User: jokobsk
Created: Apr 07, 2024
Updated: 11 days ago
Status: active

Configuration

Type
Compose
Platform
linux
Image
jokobsk/netalertx:latest
Volumes
/app/config : /portainer/Files/AppData/Config/netalertx/config/app/db : /portainer/Files/AppData/Config/netalertx/db
Env vars
TZ=Europe/AthensPORT=20211
Restart
unless-stopped
Source
Repo

Template by xneo1·Source

Standalone Install

Select an install method, to see config/commands for deploying NetAlertX

Installation method

Install on Portainer

Import all app templates into your Portainer instance, for easy 1-click deploys

  1. Ensure both Docker and Portainer are installed, and up-to-date
  2. Log into your Portainer web UI
  3. Under Settings → App Templates, paste the below URL
  4. Head to Home → App Templates, and the list of apps will show up
  5. Select NetAlertX, fill in any config options, and hit Deploy

Template Import URL

https://raw.githubusercontent.com/Lissy93/portainer-templates/main/templates.json
Show Me demo
Original stackfile

The compose file this template deploys, straight from its repo:

services:
  netalertx:
    container_name: netalertx
    # use the below line if you want to test the latest dev image
    # image: "jokobsk/netalertx-dev:latest" 
    image: "jokobsk/netalertx:latest"      
    network_mode: "host"        
    restart: unless-stopped
    volumes:
      - /portainer/Files/AppData/Config/netalertx/config:/app/config 
      - /portainer/Files/AppData/Config/netalertx/db:/app/db  
    environment:
      - TZ=Europe/Athens      
      - PORT=20211

Or deploy it directly from the source:

git clone https://github.com/xneo1/portainer_templates
cd portainer_templates
docker compose -f Template/Stack/netalertx.yml up -d

More install options in our documentation.

Docker Size Docker Pulls GitHub Release Discord Home Assistant

NetAlertX - Network Visibility & Asset Intelligence Framework

---

|| Docker guide || Releases || Docs || Plugins || Website


Head to https://netalertx.com/ for more gifs and screenshots 📷.
!NOTE There is also an experimental 🧪 bare-metal install method available.

📕 Basic Usage

!WARNING You will have to run the container on the host network and specify SCAN_SUBNETS unless you use other plugin scanners. The initial scan can take a few minutes, so please wait 5-10 minutes for the initial discovery to finish.

docker run -d --rm --network=host \
  -v /local_data_dir:/data \
  -v /etc/localtime:/etc/localtime \
  --tmpfs /tmp:uid=${NETALERTX_UID:-20211},gid=${NETALERTX_GID:-20211},mode=1700 \
  -e PORT=20211 \
  -e APP_CONF_OVERRIDE={"GRAPHQL_PORT":"20214"} \
  ghcr.io/netalertx/netalertx:latest

Runtime UID/GID: The image defaults to a service user netalertx (UID/GID 20211). A separate readonly lock owner also uses UID/GID 20211 for 004/005 immutability. You can override the runtime UID/GID at build (ARG) or run (--user / compose user:) but must align writable mounts (/data, /tmp*) and tmpfs uid/gid to that choice.

See alternative docked-compose examples.

Default ports

DefaultDescriptionHow to override
20211Port of the web interface-e PORT=20222
20212Port of the backend API server-e APPCONFOVERRIDE={"GRAPHQLPORT":"20214"} or via the GRAPHQLPORT Setting

Docker environment variables

VariableDescriptionExample/Default Value
PUIDRuntime UID override, set to 0 to run as root.20211
PGIDRuntime GID override20211
PORTPort of the web interface20211
LISTENADDRSet the specific IP Address for the listener address for the nginx webserver (web interface). This could be useful when using multiple subnets to hide the web interface from all untrusted networks.0.0.0.0
LOADEDPLUGINSDefault plugins to load. Plugins cannot be loaded with APPCONFOVERRIDE, you need to use this variable instead and then specify the plugins settings with APPCONFOVERRIDE."PIHOLE","ASUSWRT"
APPCONFOVERRIDEJSON override for settings (except LOADEDPLUGINS).{"SCANSUBNETS":"'192.168.1.0/24 --interface=eth1'","GRAPHQLPORT":"20212"}
ALWAYSFRESHINSTALL⚠ If true will delete the content of the /db & /config folders. For testing purposes. Can be coupled with watchtower to have an always freshly installed netalertx/netalertx-dev image.true

You can override the default GraphQL port setting GRAPHQL_PORT (set to 20212) by using the APP_CONF_OVERRIDE env variable. LOADED_PLUGINS and settings in APP_CONF_OVERRIDE can be specified via the UI as well.

Docker paths

!NOTE See also Backup strategies.

RequiredPathDescription
✅:/dataFolder which needs to contain a /db and /config sub-folders.
✅/etc/localtime:/etc/localtime:roEnsuring the timezone is the same as on the server.
:/tmp/logLogs folder useful for debugging if you have issues setting up the container
:/tmp/apiThe API endpoint containing static (but regularly updated) json and other files. Path configurable via NETALERTXAPI environment variable.
:/app/front/plugins/<plugin>/ignorepluginMap a file ignoreplugin to ignore a plugin. Plugins can be soft-disabled via settings. More in the Plugin docs.
:/etc/resolv.confUse a custom resolv.conf file for better name resolution.

Folder structure

Use separate db and config directories, do not nest them:
data
├── config
└── db

Permissions

If you are facing permissions issues run the following commands on your server. This will change the owner and assure sufficient access to the database and config files that are stored in the /local_data_dir/db and /local_data_dir/config folders (replace local_data_dir with the location where your /db and /config folders are located).
# Use the runtime UID/GID you intend to run with (default 20211:20211)
sudo chown -R ${NETALERTX_UID:-20211}:${NETALERTX_GID:-20211} /local_data_dir
sudo chmod -R a+rwx /local_data_dir

Initial setup

  • If unavailable, the app generates a default app.conf and app.db file on the first run.
  • The preferred way is to manage the configuration via the Settings section in the UI, if UI is inaccessible you can modify app.conf in the /data/config/ folder directly

Setting up scanners

You have to specify which network(s) should be scanned. This is done by entering subnets that are accessible from the host. If you use the default ARPSCAN plugin, you have to specify at least one valid subnet and interface in the SCAN_SUBNETS setting. See the documentation on How to set up multiple SUBNETS, VLANs and what are limitations for troubleshooting and more advanced scenarios.
If you are running PiHole you can synchronize devices directly. Check the PiHole configuration guide for details.
!NOTE You can bulk-import devices via the CSV import method.

Community guides

You can read or watch several community configuration guides in Chinese, Korean, German, or French.
Please note these might be outdated. Rely on official documentation first.

Common issues

💙 Support me

| GitHub | Buy Me A Coffee | | --- | --- |
  • Bitcoin: 1N8tupjeCK12qRVU2XrV17WvKK7LCawyZM
  • Ethereum: 0x6e2749Cb42F4411bc98501406BdcD82244e3f9C7

📧 Email me at [email protected] if you want to get in touch or if I should add other sponsorship platforms.

Check the logs first

Nine times out of ten the logs tell you exactly what went wrong.

  • In Portainer, go to Containers, click the container, then Logs. Or run docker logs <container>
  • Exit codes help too: 137 means killed, usually out of memory. 126 or 127 means the command inside the image is broken.

Permission denied on volumes

If the logs show "permission denied", the app can't write to its data folder on the host.

  • Fix the ownership: sudo chown -R 1000:1000 /portainer/Files/AppData/Config/netalertx/config (and the same for the other mapped folders)

Image won't pull

Test the pull directly on the host: docker pull jokobsk/netalertx:latest

  • "manifest unknown" means the tag no longer exists. This template uses latest, so try pinning a specific version instead.
  • "toomanyrequests" is the Docker Hub rate limit. Log in with docker login to raise it.
  • "no space left on device" means a full disk. Reclaim space with docker system prune

"exec format error"

This means the image was built for a different CPU architecture than your server.

  • This image supports: amd64, arm64, arm/v7, arm/v6, arm64/v8
  • Check yours with uname -m: x86_64 is amd64, aarch64 is arm64. Raspberry Pi and other ARM boards are the usual culprits.

Container keeps restarting

The unless-stopped restart policy relaunches the app after every crash, so the real error can scroll past.

  • Check the logs right after a restart, the last few lines before it died are the useful ones.
  • Get the exit code with docker inspect <container> --format '{{.State.ExitCode}}'
  • Still stuck? Redeploy once with the restart policy set to no so the failure stays visible.

Stack won't deploy

Compose stacks fail fast on small mistakes, and Portainer shows the reason just above the editor.

  • YAML only accepts spaces for indentation, a single tab breaks the whole file.

Raise an issue

Found something which isn't working as it should? Here's how to report it.

A Compose stack

NetAlertX is a Compose stack, a set of containers defined in one file and brought up together by Portainer, then started and stopped as a single app.

The app image

An image is the app packed up ready to go, everything NetAlertX needs bundled into one download. This template pulls jokobsk/netalertx:latest, which Docker fetches once (about 104 MB) and then starts your own copy from.

Where the image comes from

Docker pulls its images from registries, public libraries of ready-built apps. NetAlertX's comes from Docker Hub, published by jokobsk.

Version tags

The bit after the colon in the image name is the version tag. Here it's latest, which always points at the newest build, so a redeploy can bump you to a newer release without you asking. Newest right now is 26.8. Pin a specific tag if you would rather stay on one version.

Which machines it runs on

Every image is built for particular CPU types. This one ships for amd64, arm64, arm/v7, arm/v6, arm64/v8, so it runs on both regular x86 servers and ARM boards like a Raspberry Pi.

Volumes

A volume is where NetAlertX keeps its files so they survive an update or a restart. Without one, anything it saves would sit inside the container and vanish the moment it's recreated. This template mounts:

  • /app/config from /portainer/Files/AppData/Config/netalertx/config on the host
  • /app/db from /portainer/Files/AppData/Config/netalertx/db on the host

Environment variables

Environment variables are the settings you hand over when you deploy, things like a password or a timezone. NetAlertX takes 2 of them, all with defaults you can leave alone or tweak:

  • TZ, defaults to Europe/Athens
  • PORT, defaults to 20211

Restart policy

The restart policy here is unless-stopped, so Docker restarts NetAlertX after a crash or reboot, but leaves it off when you stop it on purpose. You can change this on the deploy screen. The choices are no (never restart), on-failure (only after a crash), unless-stopped (restart unless you stop it), and always (bring it back no matter what).

Networking

Nothing custom is set, so NetAlertX sits on Docker's default bridge network: its own private space that reaches the outside world only through the ports it publishes.

Container name

Once it's deployed, Portainer names the container netalertx. That's what you'll spot in the containers list and use in commands like docker logs netalertx.

Platform

The platform is linux, the kind of system the container is built to run on. Docker and Portainer handle this on a normal Linux server.

Portainer app templates

Zooming out, this whole page comes from a Portainer app template: a short recipe telling Portainer how to set NetAlertX up. Add the template list to Portainer once, then deploying NetAlertX is a click rather than a wall of config.