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

2025-12-07 09:36:05 -08:00 · 2022-12-06 19:00:10 +11:00
parent 516ecdf84c a81d2deaab
commit f7fbf9488a
3 changed files with 48 additions and 66 deletions
--- a/README.md
+++ b/README.md
@@ -16,24 +16,10 @@ unknown devices. It also warns if a "always connected" devices disconnects.
 [![Docker Pulls](https://img.shields.io/docker/pulls/jokobsk/pi.alert?label=Pulls&logo=docker&color=0aa8d2&logoColor=fff)](https://hub.docker.com/r/jokobsk/pi.alert)
 [![Docker Pushed](https://img.shields.io/badge/dynamic/json?color=0aa8d2&logoColor=fff&label=Pushed&query=last_updated&url=https%3A%2F%2Fhub.docker.com%2Fv2%2Frepositories%2Fjokobsk%2Fpi.alert%2F&logo=docker&link=http://left&link=https://hub.docker.com/repository/docker/jokobsk/pi.alert)](https://hub.docker.com/r/jokobsk/pi.alert)

-🐳 [Docker hub](https://registry.hub.docker.com/r/jokobsk/pi.alert) <br/>
-📄 [Dockerfile](https://github.com/jokob-sk/Pi.Alert/blob/main/Dockerfile) <br/>
-📚 [Docker instructions](https://github.com/jokob-sk/Pi.Alert/blob/main//dockerfiles/README.md)
-
-
-Dark mode (and much more) within this fork courtesy of [leiweibau](https://github.com/leiweibau/Pi.Alert)
-
-## How it works
-The system continuously scans the network for:
-  - New devices
-  - New connections (re-connections)
-  - Disconnections
-  - "Always Connected" devices down
-  - Devices IP changes
-  - Internet IP address changes
+🐳 [Docker hub](https://registry.hub.docker.com/r/jokobsk/pi.alert) | 📄 [Dockerfile](https://github.com/jokob-sk/Pi.Alert/blob/main/Dockerfile) | 📚 [Docker instructions](https://github.com/jokob-sk/Pi.Alert/blob/main//dockerfiles/README.md)

 ## 🔍 Scan Methods
-Up to three scanning methods are used:
+The system continuously scans the network for, **New devices**, **New connections** (re-connections), **Disconnections**, **"Always Connected" devices down**, Devices **IP changes** and **Internet IP address changes**. Scanning methods are:
  - **Method 1: arp-scan**. The arp-scan system utility is used to search
        for devices on the network using arp frames.
  - **Method 2: Pi-hole**. This method is optional and complementary to
@@ -46,49 +32,44 @@ Up to three scanning methods are used:
        that were not discovered by the other methods.


-### 🧩 Integrations 
-   - [Apprise](https://hub.docker.com/r/caronc/apprise) 
-   - [Pushsafer](https://www.pushsafer.com/)
-   - [NTFY](https://ntfy.sh/)
+## 🧩 Notification Integrations 
+   - [Apprise](https://hub.docker.com/r/caronc/apprise), [Pushsafer](https://www.pushsafer.com/), [NTFY](https://ntfy.sh/)
   - Webhooks ([sample JSON](docs/webhook_json_sample.json))
-   - (❗Experimental) Home Assistant (via [MQTT](https://www.home-assistant.io/integrations/mqtt/) (processing ~5s per device, deleting not supported, use [MQTT Explorer](https://mqtt-explorer.com/) for now))  
+   - (❗Experimental) Home Assistant via [MQTT](https://www.home-assistant.io/integrations/mqtt/) 
+     - discovery ~10s per device, deleting not supported, use [MQTT Explorer](https://mqtt-explorer.com/) for now

-  | ![Report 1][report1] | ![Report 2][report2] |
-  | -------------------- | -------------------- |

-### 🔐 Security
-There is a configurable login to prevent unauthorized use. 
+## 🔐 Security

-> * Set `PIALERT_WEB_PROTECTION = True` in `pialert.conf` to enable. The default password is `123456`.
-> To change password run `/home/pi/pialert/back/pialert-cli`
+- Configurable login to prevent unauthorized use. 
+- Set `PIALERT_WEB_PROTECTION = True` in `pialert.conf` to enable. 
+- The default password is `123456`.
+- To change password run `/home/pi/pialert/back/pialert-cli`

 ## 📑 Features   
-  - Display in a visual way all the information collected by the back
-    - Sessions, Connected devices, Favorites
-    - Events, Presence, Concurrent devices
-    - Down alerts
-    - IP's
+  - Display:
+    - Sessions, Connected devices, Favorites, Events, Presence, Concurrent devices, Down alerts, IP's
    - Manual Nmap scans, Optional speedtest for Device "Internet"
    - Simple Network relationship display
  - Maintenance tasks and Settings like:
    - Status Infos (active scans, database size, backup counter)
-    - Theme Selection (blue, red, green, yellow, black, purple)
-    - Language Selection (english, german, spanish)
-    - Light/Dark-Mode Switch
+    - Theme Selection (blue, red, green, yellow, black, purple) and Light/Dark-Mode Switch
+    - Language Selection (English, German, Spanish)    
    - Pause arp-scan
-    - DB maintenance, Backup, Restore tools
-    - CSV Export / Import
+    - DB maintenance, Backup, Restore tools and CSV Export / Import
  - Help/FAQ Section 

  | ![Screen 1][screen1] | ![Screen 2][screen2] |
  | -------------------- | -------------------- |
  | ![Screen 3][screen3] | ![Screen 4][screen4] |
  | ![Screen 5][screen5] | ![Screen 6][screen6] |
+  | ![Report 1][report1] | ![Report 2][report2] |
+ 

 # 📥 Installation
 <!--- --------------------------------------------------------------------- --->

- ⚠ Please note, this [fork (jokob-sk)](https://github.com/jokob-sk/Pi.Alert) is only tested via the [docker install method](dockerfiles/README.md). Check out [leiweibau's fork](https://github.com/leiweibau/Pi.Alert/) if you want to install Pi.Alert on the server directly.
+ ⚠ This [fork (jokob-sk)](https://github.com/jokob-sk/Pi.Alert) is only tested via the [docker install method](dockerfiles/README.md). Check out [leiweibau's fork](https://github.com/leiweibau/Pi.Alert/) if you want to install Pi.Alert on the server directly.

 Instructions for [pucherot's original code can be found here](https://github.com/pucherot/Pi.Alert/)

@@ -118,7 +99,7 @@ Instructions for [pucherot's original code can be found here](https://github.com
  This code is a collaborative body of work, with special thanks to: 

   - 🏆 [pucherot/Pi.Alert](https://github.com/pucherot/Pi.Alert) is the original creator od PiAlert
-   - [leiweibau](https://github.com/leiweibau/Pi.Alert): Things
+   - [leiweibau](https://github.com/leiweibau/Pi.Alert): Dark mode (and much more)
   - [Macleykun](https://github.com/Macleykun): Help with Dockerfile clean-up
   - [Final-Hawk](https://github.com/Final-Hawk): Help with NTFY, styling and other fixes
   - [TeroRERO](https://github.com/terorero): Spanish translation
--- a/config/pialert.conf
+++ b/config/pialert.conf
@@ -7,6 +7,9 @@
 #  Puche 2021        pi.alert.application@gmail.com        GNU GPLv3
 #-------------------------------------------------------------------------------

+# GENERAL settings
+# ----------------------
+
 PIALERT_PATH            = '/home/pi/pialert'
 DB_PATH                 = PIALERT_PATH + '/db/pialert.db'
 LOG_PATH                = PIALERT_PATH + '/log'
@@ -15,9 +18,11 @@ PRINT_LOG               = False
 TIMEZONE                = 'Europe/Berlin'
 PIALERT_WEB_PROTECTION  = False
 PIALERT_WEB_PASSWORD    = '8d969eef6ecad3c29a3a629280e686cf0c3f5d5a86aff3ca12020c923adc6c92'
-# Specifies which events trigger notofications. Remove the event type(s) you don't want to get notified on (overrides device-specific settings in the UI).
-INCLUDED_SECTIONS       = ['internet', 'new_devices', 'down_devices', 'events']
-SCAN_CYCLE_MINUTES      = 5  # delay between scans
+
+INCLUDED_SECTIONS       = ['internet', 'new_devices', 'down_devices', 'events']   # Specifies which events trigger notifications. 
+                                                                                  # Remove the event type(s) you don't want to get notified on 
+                                                                                  # Overrides device-specific settings in the UI.
+SCAN_CYCLE_MINUTES      = 5            # delay between scans

 # EMAIL settings
 # ----------------------
@@ -38,13 +43,11 @@ REPORT_DASHBOARD_URL    = 'http://pi.alert/'
 # ----------------------
 REPORT_WEBHOOK          = False
 WEBHOOK_URL             = 'http://n8n.local:5555/webhook-test/aaaaaaaa-aaaa-aaaa-aaaaa-aaaaaaaaaaaa'
-# webhook payload data format for the "body > attachements > text" attribute in https://github.com/jokob-sk/Pi.Alert/blob/main/docs/webhook_json_sample.json
-#   supported values: 'json' or 'html' or 'text'
-#   e.g.: for discord use 'html'
-WEBHOOK_PAYLOAD         = 'json'  
-WEBHOOK_REQUEST_METHOD  = 'GET'  # POST, GET...
-# set event level to 0 for no message, 1 for Internet changes only, 2 for new devices and 1, 3 for down devices and 2 and 4 for events and 3. i.e. everything
-EVENT_LEVEL             = 4
+WEBHOOK_PAYLOAD         = 'json'       # webhook payload data format for the "body > attachements > text" attribute 
+                                       # in https://github.com/jokob-sk/Pi.Alert/blob/main/docs/webhook_json_sample.json 
+                                       #   supported values: 'json', 'html' or 'text'
+                                       #   e.g.: for discord use 'html'
+WEBHOOK_REQUEST_METHOD  = 'GET'        # POST, GET...

 # Apprise settings
 #-----------------------
@@ -57,9 +60,8 @@ APPRISE_URL             = 'mailto://smtp-relay.sendinblue.com:587?from=user@gmai
 REPORT_NTFY             = False
 NTFY_HOST               = 'https://ntfy.sh'
 NTFY_TOPIC              = 'replace_my_secure_topicname_91h889f28'
-# set username and password if authentication is used https://docs.ntfy.sh/config/#users-and-roles
-NTFY_USER               = ''
-NTFY_PASSWORD           = ''
+NTFY_USER               = 'user'       # set username... 
+NTFY_PASSWORD           = 'passw0rd'   # ...and password if authentication is used https://docs.ntfy.sh/config/#users-and-roles

 # PUSHSAFER (https://www.pushsafer.com/) settings
 # ----------------------
@@ -74,7 +76,7 @@ MQTT_PORT               = 1883
 MQTT_USER               = 'mqtt'
 MQTT_PASSWORD           = 'passw0rd'
 MQTT_QOS                = 0
-MQTT_DELAY_SEC          = 2  # delay in seconds, increase if not all devices are created in Home Assistant
+MQTT_DELAY_SEC          = 2            # delay in seconds, increase if not all devices are created in Home Assistant

 # DynDNS
 # ----------------------
@@ -110,6 +112,6 @@ DHCP_LEASES             = '/etc/pihole/dhcp.leases'

 SCAN_SUBNETS            = '--localnet'

-# Maintenance Tasks Cron
+# Maintenance Task Settings
 # ----------------------
 DAYS_TO_KEEP_EVENTS = 90
--- a/dockerfiles/README.md
+++ b/dockerfiles/README.md
@@ -6,9 +6,8 @@

 # 🐳 A docker image for Pi.Alert 

-🐳 [Docker hub](https://registry.hub.docker.com/r/jokobsk/pi.alert) <br/>
-📄 [Dockerfile](https://github.com/jokob-sk/Pi.Alert/blob/main/Dockerfile) <br/>
-📚 [Docker instructions](https://github.com/jokob-sk/Pi.Alert/blob/main//dockerfiles/README.md)
+
+🐳 [Docker hub](https://registry.hub.docker.com/r/jokobsk/pi.alert) | 📄 [Dockerfile](https://github.com/jokob-sk/Pi.Alert/blob/main/Dockerfile) | 📚 [Docker instructions](https://github.com/jokob-sk/Pi.Alert/blob/main//dockerfiles/README.md)

 Big thanks to <a href="https://github.com/Macleykun">@Macleykun</a> for help and tips&tricks for Dockerfile(s):

@@ -16,23 +15,23 @@ Big thanks to <a href="https://github.com/Macleykun">@Macleykun</a> for help and
  <img src="https://avatars.githubusercontent.com/u/26381427?size=50"> 
 </a>

-## ℹ Usage 
+## ℹ Basic Usage 

-pialert.conf
+### pialert.conf
 - Everytime you rebuilt the container with a new image check if new settings have been added in [pialert.conf](https://github.com/jokob-sk/Pi.Alert/blob/main/config/pialert.conf).

-Network
+### Network
 - You will have to run the container on the host network, e.g: `sudo docker run --rm --net=host jokobsk/pi.alert`

-Default Port 
+### Default Port 
 - The app is accessible on the port `:20211`.

-> Please note - the cronjob is executed every 3 and 5 minutes so wait that long for all of the scans to run.
+> Please note - the initial scan can take up-to 20min (with 50 devices and MQTT). Subsequent ones 3 and 5 minutes so wait that long for all of the scans to run.

 ## 💾 Setup and Backups

 1. (**required**) Download `pialert.conf` and `version.conf` from [here](https://github.com/jokob-sk/Pi.Alert/tree/main/config).     
-2. (**required**) In `pialert.conf` specify your network adapter (will probably be `eth0` or `eth1`) and the network filter (which **significantly** speeds up the scan process), e.g. if your DHCP server assigns IPs in the 192.168.1.0 to 192.168.1.255 range specify it the following way: 
+2. (**required**) In `pialert.conf` specify your network adapter (will probably be `eth0` or `eth1`) and the network filter (which **significantly** speeds up the scan process), e.g. if your DHCP server assigns IPs in the 192.168.1.0 to 192.168.1.255 range, specify it the following way: 
   * `SCAN_SUBNETS    = '192.168.1.0/24 --interface=eth0'`
 3. (**required**) Use your configuration by: 
   * Mapping the container folder `/home/pi/pialert/config` to a persistent folder containing `pialert.conf` and `version.conf`,     
@@ -41,13 +40,13 @@ Default Port
 5. Database backup
   * Download the [original DB from GitHub](https://github.com/jokob-sk/Pi.Alert/blob/main/db/pialert.db).
   * Map the `pialert.db` file (⚠ not folder) from above to `/home/pi/pialert/db/pialert.db` (see [Examples](https://github.com/jokob-sk/Pi.Alert/tree/main/dockerfiles#-examples) for details). 
-   * If facing issues (AJAX errors, can't write to DB, etc,) make sure permissions are set correctly, alternatively check the logs under `/home/pi/pialert/log`. 
+   * If facing issues (AJAX errors, can't write to DB, etc,) make sure permissions are set correctly, and check the logs under `/home/pi/pialert/log`. 
   * To solve permission issues you can also try to create a DB backup and then run a DB Restore via the **Maintenance > Backup/Restore** section.
-   * If the database is in read-only mode you can solve this by setting the owner and group by executing the following command on the host system: `docker exec pialert chown -R www-data:www-data /home/pi/pialert/db/pialert.db`. 
+   * You can try also setting the owner and group of the `pialert.db` by executing the following on the host system: `docker exec pialert chown -R www-data:www-data /home/pi/pialert/db/pialert.db`. 
 6. The container supports mapping to local User nad Group IDs. Specify the enviroment variables `HOST_USER_ID` and `HOST_USER_GID` if needed.
 7. You can override the port by specifying the `PORT` env variable.

-Config examples can be found below.
+Docker-compose examples can be found below.

 ## 📄 Examples