jokobsk/netalertx

By jokobsk

β€’Updated 2 days ago

πŸ”NetAlertX is monitoring your WIFI/LAN network and alerting of new devices.

Image
Monitoring & Observability
Networking
Security

1M+

Docker SizeDocker PullsGitHub ReleaseDiscordHome Assistant

NetAlertX - Network scanner & notification framework

⁠

Head to https://netalertx.com/⁠ for more gifs and screenshots πŸ“·.

Note
There is also an experimental πŸ§ͺ [bare-metal install](https://github.com/jokob-sk/NetAlertX/blob/main/docs/HW_INSTALL.md) 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](https://github.com/jokob-sk/NetAlertX/blob/main/docs/PLUGINS.md). 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_path/config:/app/config \
  -v local_path/db:/app/db \
  --mount type=tmpfs,target=/app/api \
  -e PUID=200 -e PGID=300 \
  -e TZ=Europe/Berlin \
  -e PORT=20211 \
  ghcr.io/jokob-sk/netalertx:latest

See alternative docked-compose examples⁠.

Docker environment variables
VariableDescriptionExample Value
PORTPort of the web interface20211
PUIDApplication User UID102
PGIDApplication User GID82
LISTEN_ADDRSet 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
TZTime zone to display stats correctly. Find your time zone here⁠Europe/Berlin
LOADED_PLUGINSDefault plugins⁠ to load. Plugins cannot be loaded with APP_CONF_OVERRIDE, you need to use this variable instead and then specify the plugins settings with APP_CONF_OVERRIDE.["PIHOLE","ASUSWRT"]
APP_CONF_OVERRIDEJSON override for settings (except LOADED_PLUGINS).{"SCAN_SUBNETS":"['192.168.1.0/24 --interface=eth1']","GRAPHQL_PORT":"20212"}
ALWAYS_FRESH_INSTALL⚠ 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](https://github.com/jokob-sk/NetAlertX/blob/main/docs/BACKUPS.md).
RequiredPathDescription
βœ…:/app/configFolder which will contain the app.conf & devices.csv (read about devices.csv⁠) files
βœ…:/app/dbFolder which will contain the app.db database file
:/app/logLogs folder useful for debugging if you have issues setting up the container
:/app/apiA simple API endpoint⁠ containing static (but regularly updated) json and other files.
:/app/front/plugins/<plugin>/ignore_pluginMap a file ignore_plugin 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⁠.

Use separate db and config directories, do not nest them.

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 /app/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](https://github.com/jokob-sk/NetAlertX/blob/main/docs/DEVICES_BULK_EDITING.md).

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

GitHubBuy Me A CoffeePatreon
  • Bitcoin: 1N8tupjeCK12qRVU2XrV17WvKK7LCawyZM
  • Ethereum: 0x6e2749Cb42F4411bc98501406BdcD82244e3f9C7

πŸ“§ Email me at [netalertx@gmail.com](mailto:netalertx@gmail.com⁠?subject=NetAlertX Donations) if you want to get in touch or if I should add other sponsorship platforms.

Docker Pull Command

docker pull jokobsk/netalertx