Merge branch 'main' of https://github.com/jokob-sk/NetAlertX

Updating base image to Alpine 3.22

.github/FUNDING.yml

@@ -1,2 +1,3 @@
 github: jokob-sk
 patreon: 84385063
+buy_me_a_coffee: jokobsk

.github/tweet.md

@@ -1,2 +1,2 @@
-🎉 New release: **v25.5.24 - MQTT, UI improvements, multiple notification emails** is live! 🚀
-Check it out here: https://github.com/jokob-sk/NetAlertX/releases/tag/v25.5.24
+🎉 New release: **v25.6.7 - Legacy upgrade removal and Fully Qualified Domain Names 🆎** is live! 🚀
+Check it out here: https://github.com/jokob-sk/NetAlertX/releases/tag/v25.6.7

Dockerfile

@@ -1,4 +1,4 @@
-FROM alpine:3.21 AS builder
+FROM alpine:3.22 AS builder
 
 ARG INSTALL_DIR=/app
 
@@ -22,7 +22,7 @@ RUN pip install openwrt-luci-rpc asusrouter asyncio aiohttp graphene flask tplin
 RUN cat ${INSTALL_DIR}/install/freebox_certificate.pem >> /opt/venv/lib/python3.12/site-packages/aiofreepybox/freebox_certificates.pem
 
 # second stage
-FROM alpine:3.21 AS runner
+FROM alpine:3.22 AS runner
 
 ARG INSTALL_DIR=/app
 

docker-compose.yml

@@ -66,7 +66,8 @@ services:
       - ${DEV_LOCATION}/front/appEvents.php:/app/front/appEvents.php      
       - ${DEV_LOCATION}/front/appEventsCore.php:/app/front/appEventsCore.php      
       - ${DEV_LOCATION}/front/multiEditCore.php:/app/front/multiEditCore.php      
-      - ${DEV_LOCATION}/front/plugins:/app/front/plugins      
+      - ${DEV_LOCATION}/front/plugins:/app/front/plugins    
+      
       # DELETE END anyone trying to use this file: comment out / delete ABOVE lines, they are only for development purposes
       # ---------------------------------------------------------------------------
     environment:      

docs/API.md

@@ -49,6 +49,8 @@ query GetDevices($options: PageQueryOptionsInput) {
 }
 ```
 
+See also: [Debugging GraphQL issues](./DEBUG_GRAPHQL.md)
+
 ### `curl` Command
 
 You can use the following `curl` command to execute the query. 

docs/COMMUNITY_GUIDES.md

@@ -2,6 +2,7 @@
 
 Use the official installation guides at first and use community content as supplementary material. Open an issue or PR if you'd like to add your link to the list 🙏 (Ordered by last update time)
 
+- ▶ [Discover & Monitor Your Network with This Self-Hosted Open Source Tool - Lawrence Systems](https://www.youtube.com/watch?v=R3b5cxLZMpo) (June 2025)
 - ▶ [Home Lab Network Monitoring - Scotti-BYTE Enterprise Consulting Services](https://www.youtube.com/watch?v=0DryhzrQSJA) (July 2024)
 - 📄 [How to Install NetAlertX on Your Synology NAS - Marius hosting](https://mariushosting.com/how-to-install-pi-alert-on-your-synology-nas/) (Updated frequently)
 - 📄 [Using the PiAlert Network Security Scanner on a Raspberry Pi - PiMyLifeUp](https://pimylifeup.com/raspberry-pi-pialert/)

docs/DEBUG_GRAPHQL.md

@@ -0,0 +1,64 @@
+# Debugging GraphQL server issues
+
+The GraphQL server is an API middle layer, running on it's own port specified by `GRAPHQL_PORT`, to retrieve and show the data in the UI. It can also be used to retrieve data for custom third party integarions. Check the [API documentation](./API.md) for details. 
+
+The most common issue is that the GraphQL server doesn't start properly, usually due to a **port conflict**. If you are running multiple NetAlertX instances, make sure to use **unique ports** by changing the `GRAPHQL_PORT` setting. The default is `20212`.
+
+## How to update the `GRAPHQL_PORT` in case of issues
+
+As a first troubleshooting step try changing the default `GRAPHQL_PORT` setting. Please remember NetAlertX is running on the host so any application uising the same port will cause issues.  
+
+### Updating the setting via the Settings UI
+
+Ideally use the Settings UI to update the setting under General -> Core -> GraphQL port:
+
+![GrapQL settings](./img/DEBUG_GRAPHQL/graphql_settings_port_token.png)
+
+You might need to temporarily stop other applications or NetAlertX instances causing conflicts to update the setting. The `API_TOKEN` is used to authenticate any API calls, including GraphQL requests. 
+
+### Updating the `app.conf` file
+
+If the UI is not accessible, you can directly edit the `app.conf` file in your `/config` folder:
+
+![Editing app.conf](./img/DEBUG_GRAPHQL/app_conf_graphql_port.png)
+
+### Using a docker variable
+
+All application settings can also be initialized via the `APP_CONF_OVERRIDE` docker env variable. 
+
+```yaml
+...
+ environment:
+      - TZ=Europe/Berlin      
+      - PORT=20213
+      - APP_CONF_OVERRIDE={"GRAPHQL_PORT":"20214"}
+...
+```
+
+## How to check the GraphQL server is running?
+
+There are several ways to check if the GraphQL server is running.
+
+### Init Check
+
+You can navigate to Maintenance -> Init Check to see if `isGraphQLServerRunning` is ticked:
+
+![Init Check](./img/DEBUG_GRAPHQL/Init_check.png)
+
+### Checking the Logs
+
+You can navigate to Maintenance -> Logs and search for `graphql` to see if it started correctly and serving requests:
+
+![GraphQL Logs](./img/DEBUG_GRAPHQL/graphql_running_logs.png)
+
+### Inspecting the Browser console
+
+In your browser open the dev console (usually F12) and navigate to the Network tab where you can filter GraphQL requests (e.g., reload the Devices page).
+
+![Browser Network Tab](./img/DEBUG_GRAPHQL/network_graphql.png)
+
+You can then inspect any of the POST requests by opening them in a new tab.
+
+![Browser GraphQL Json](./img/DEBUG_GRAPHQL/dev_console_graphql_json.png)
+
+

docs/PERFORMANCE.md

@@ -85,8 +85,8 @@ services:
       # (Optional) Useful for debugging setup issues
       - local/path/logs:/app/log
       # (API: OPTION 1) Store temporary files in memory (recommended for performance)
-      - type: tmpfs              # ◀ 
-        target: /app/api         # ◀ 
+      - type: tmpfs              # ◀ 🔺
+        target: /app/api         # ◀ 🔺
       # (API: OPTION 2) Store API data on disk (useful for debugging)
       # - local/path/api:/app/api
     environment:

front/plugins/avahi_scan/avahi_scan.py

@@ -58,9 +58,9 @@ def main():
 
     # Retrieve devices
     if get_setting_value("REFRESH_FQDN"): 
-        devices = device_handler.getUnknown()
-    else:
         devices = device_handler.getAll()
+    else:        
+        devices = device_handler.getUnknown()
 
     mylog('verbose', [f'[{pluginName}] Devices count: {len(devices)}'])   
     

front/plugins/dig_scan/digscan.py

@@ -56,9 +56,9 @@ def main():
 
     # Retrieve devices
     if get_setting_value("REFRESH_FQDN"): 
-        devices = device_handler.getUnknown()
-    else:
         devices = device_handler.getAll()
+    else:        
+        devices = device_handler.getUnknown()
 
     mylog('verbose', [f'[{pluginName}] Devices count: {len(devices)}'])   
     

front/plugins/nbtscan_scan/nbtscan.py

@@ -58,9 +58,9 @@ def main():
 
     # Retrieve devices
     if get_setting_value("REFRESH_FQDN"): 
-        devices = device_handler.getUnknown()
-    else:
         devices = device_handler.getAll()
+    else:        
+        devices = device_handler.getUnknown()
 
     mylog('verbose', [f'[{pluginName}] Devices count: {len(devices)}'])   
     

front/plugins/nslookup_scan/nslookup.py

@@ -60,9 +60,9 @@ def main():
 
     # Retrieve devices
     if get_setting_value("REFRESH_FQDN"): 
-        devices = device_handler.getUnknown()
-    else:
         devices = device_handler.getAll()
+    else:        
+        devices = device_handler.getUnknown()
 
     mylog('verbose', [f'[{pluginName}] Devices count: {len(devices)}'])   
     

front/plugins/unifi_import/script.py

@@ -52,7 +52,7 @@ def main():
 
     
     # init global variables
-    global UNIFI_USERNAME, UNIFI_PASSWORD, UNIFI_HOST, UNIFI_SITES, PORT, VERIFYSSL, VERSION, FULL_IMPORT
+    global UNIFI_USERNAME, UNIFI_PASSWORD, UNIFI_HOST, UNIFI_SITES, PORT, VERIFYSSL, VERSION, FULL_IMPORT, API_KEY
 
     # parse output
     plugin_objects = Plugin_Objects(RESULT_FILE)    
@@ -65,6 +65,10 @@ def main():
     VERIFYSSL       = get_setting_value("UNFIMP_verifyssl")
     VERSION         = get_setting_value("UNFIMP_version")
     FULL_IMPORT     = get_setting_value("UNFIMP_fullimport")
+    API_KEY         = get_setting_value("UNFIMP_api_key")
+
+    if API_KEY == '':
+        API_KEY = None
 
     plugin_objects = get_entries(plugin_objects)
 
@@ -96,7 +100,28 @@ def get_entries(plugin_objects: Plugin_Objects) -> Plugin_Objects:
     
         mylog('verbose', [f'[{pluginName}] site: {site}'])
 
-        c = Controller(UNIFI_HOST, UNIFI_USERNAME, UNIFI_PASSWORD, port=PORT, version=VERSION, ssl_verify=VERIFYSSL, site_id=site)
+
+        # def __init__(  
+        #         self,
+        #         host,
+        #         username=None,
+        #         password=None,
+        #         port=8443,
+        #         version="v5",
+        #         site_id="default",
+        #         ssl_verify=True,
+        #         api_key=None
+        # ):
+
+        c = Controller(
+            UNIFI_HOST, 
+            UNIFI_USERNAME, 
+            UNIFI_PASSWORD, 
+            port=PORT, 
+            version=VERSION, 
+            ssl_verify=VERIFYSSL, 
+            site_id=site,
+            api_key=API_KEY)
         
         online_macs = set()
         processed_macs = []

front/plugins/vendor_update/script.py

@@ -19,7 +19,7 @@ from plugin_helper import Plugin_Object, Plugin_Objects, decodeBase64, handleEmp
 from logger import mylog, Logger, append_line_to_file
 from helper import timeNowTZ, get_setting_value 
 from const import logPath, applicationPath, fullDbPath
-from device import query_MAC_vendor
+from scan.device_handling import query_MAC_vendor
 import conf
 from pytz import timezone
 

mkdocs.yml

@@ -61,6 +61,7 @@ nav:
   - Troubleshooting:
       - Inspecting Logs: LOGGING.md
       - Debugging Tips: DEBUG_TIPS.md
+      - Debugging GraphQL: DEBUG_GRAPHQL.md
       - Debugging Invalid JSON: DEBUG_INVALID_JSON.md
       - Debugging Plugins: DEBUG_PLUGINS.md
       - Debugging Web UI Port: WEB_UI_PORT_DEBUG.md