docs

docs/COMMUNITY_GUIDES.md

@@ -0,0 +1,16 @@
+# Community Guides
+
+Use the official installation guides at first and use community content as supplementary material. Open an issue if you'd like to add your link to the list 🙏 
+
+- ▶ [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/)
+- ▶ [How to Setup Pi.Alert on Your Synology NAS - Digital Aloha](https://www.youtube.com/watch?v=M4YhpuRFaUg) 
+- 📄 [防蹭网神器，网络安全助手 | 极空间部署网络扫描和通知系统『NetAlertX』](https://blog.csdn.net/qq_63499861/article/details/141105273)
+- 📄 [시놀/헤놀에서 네트워크 스캐너 Pi.Alert Docker로 설치 및 사용하기](https://blog.dalso.org/article/%EC%8B%9C%EB%86%80-%ED%97%A4%EB%86%80%EC%97%90%EC%84%9C-%EB%84%A4%ED%8A%B8%EC%9B%8C%ED%81%AC-%EC%8A%A4%EC%BA%90%EB%84%88-pi-alert-docker%EB%A1%9C-%EC%84%A4%EC%B9%98-%EB%B0%8F-%EC%82%AC%EC%9A%A9) (July 2023)
+- 📄 [网络入侵探测器Pi.Alert (Chinese)](https://codeantenna.com/a/VgUvIAjZ7J) (May 2023)
+- ▶ [Pi.Alert auf Synology & Docker by - Jürgen Barth](https://www.youtube.com/watch?v=-ouvA2UNu-A) (March 2023)
+- ▶ [Top Docker Container for Home Server Security - VirtualizationHowto](https://www.youtube.com/watch?v=tY-w-enLF6Q) (March 2023)
+- ▶ [Pi.Alert or WatchYourLAN can alert you to unknown devices appearing on your WiFi or LAN network - Danie van der Merwe](https://www.youtube.com/watch?v=v6an9QG2xF0) (November 2022)
+
+> Ordered by last update time. 

docs/DOCKER_COMPOSE.md

@@ -0,0 +1,128 @@
+# `docker-compose.yaml` Examples
+
+### Example 1
+
+```yaml
+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:
+      - local_path/config:/app/config
+      - local_path/db:/app/db      
+      # (optional) useful for debugging if you have issues setting up the container
+      - local_path/logs:/app/log
+      # (API: OPTION 1) use for performance
+      - type: tmpfs
+        target: /app/api
+      # (API: OPTION 2) use when debugging issues 
+      # -  local_path/api:/app/api
+    environment:
+      - TZ=Europe/Berlin      
+      - PORT=20211
+```
+
+To run the container execute: `sudo docker-compose up -d`
+
+### Example 2
+
+Example by [SeimuS](https://github.com/SeimusS).
+
+```yaml
+  netalertx:
+    container_name: NetAlertX
+    hostname: NetAlertX
+    privileged: true
+    # use the below line if you want to test the latest dev image
+    # image: "jokobsk/netalertx-dev:latest" 
+    image: jokobsk/netalertx:latest
+    environment:
+      - TZ=Europe/Bratislava
+    restart: always
+    volumes:
+      - ./netalertx/db:/app/db
+      - ./netalertx/config:/app/config
+    network_mode: host
+```
+
+To run the container execute: `sudo docker-compose up -d`
+
+### Example 3
+
+`docker-compose.yml` 
+
+```yaml
+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:
+      - ${APP_DATA_LOCATION}/netalertx/config:/app/config
+      - ${APP_DATA_LOCATION}/netalertx/db/:/app/db/      
+      # (optional) useful for debugging if you have issues setting up the container
+      - ${LOGS_LOCATION}:/app/log
+      # (API: OPTION 1) use for performance
+      - type: tmpfs
+        target: /app/api
+      # (API: OPTION 2) use when debugging issues 
+      # -  local/path/api:/app/api
+    environment:
+      - TZ=${TZ}      
+      - PORT=${PORT}
+```
+
+`.env` file
+
+```yaml
+#GLOBAL PATH VARIABLES
+
+APP_DATA_LOCATION=/path/to/docker_appdata
+APP_CONFIG_LOCATION=/path/to/docker_config
+LOGS_LOCATION=/path/to/docker_logs
+
+#ENVIRONMENT VARIABLES
+
+TZ=Europe/Paris
+PORT=20211
+
+#DEVELOPMENT VARIABLES
+
+DEV_LOCATION=/path/to/local/source/code
+```
+
+To run the container execute: `sudo docker-compose --env-file /path/to/.env up`
+
+### Example 4
+
+Courtesy of [pbek](https://github.com/pbek). The volume `netalertx_db` is used by the db directory. The two config files are mounted directly from a local folder to their places in the config folder. You can backup the `docker-compose.yaml` folder and the docker volumes folder.
+
+```yaml
+  netalertx:
+    # use the below line if you want to test the latest dev image
+    # image: "jokobsk/netalertx-dev:latest" 
+    image: jokobsk/netalertx
+    ports:
+      - "80:20211/tcp"
+    environment:
+      - TZ=Europe/Vienna
+    networks:
+      local:
+        ipv4_address: 192.168.1.2
+    restart: unless-stopped
+    volumes:
+      - netalertx_db:/app/db
+      - ./netalertx/:/app/config/      
+      # (API: OPTION 1) use for performance
+      - type: tmpfs
+        target: /app/api
+      # (API: OPTION 2) use when debugging issues 
+      # -  local/path/api:/app/api
+```

docs/PIHOLE_GUIDE.md

@@ -0,0 +1,45 @@
+# Integration with PiHole
+
+NetAlertX comes with 2 plugins suitable for integarting with your existing PiHole instace. One plugin is using a direct SQLite DB connection, the other leverages the DHCP.leases file generated by PiHole. You can combine both approaches and also supplement it with other [plugins](/front/plugins/README.md). 
+
+## Approach 1: `DHCPLSS` Plugin - Import devices from the PiHole DHCP leases file
+
+![DHCPLSS sample settings](/docs/img/PIHOLE_GUIDE/DHCPLSS_pihole_settings.png)
+
+### Settings
+
+| Setting | Description | Recommended value |
+| :------------- | :------------- | :-------------|
+| `DHCPLSS_RUN` | When the plugin should run.  | `schedule` |
+| `DHCPLSS_RUN_SCHD` | If you run multiple device scanner plugins, align the schedules of all plugins to the same value.  | `*/5 * * * *` |
+| `DHCPLSS_paths_to_check` | You need to map the value in this setting in the `docker-compose.yml` file. The in-container path must contain `pihole` so it's parsed correctly. | `['/etc/pihole/dhcp.leases']` |
+
+Check the [DHCPLSS plugin readme](https://github.com/jokob-sk/NetAlertX/tree/main/front/plugins/dhcp_leases#overview) for details
+
+### docker-compose changes
+
+| Path | Description |
+| :------------- | :------------- |
+| `:/etc/pihole/dhcp.leases` |  PiHole's `dhcp.leases` file. Required if you want to use PiHole `dhcp.leases` file. This has to be matched with a corresponding `DHCPLSS_paths_to_check` setting entry (the path in the container must contain `pihole`) |
+
+
+## Approach 2: `PIHOLE` Plugin - Import devices directly from the PiHole database
+
+![DHCPLSS sample settings](/docs/img/PIHOLE_GUIDE/PIHOLE_settings.png)
+
+| Setting | Description | Recommended value |
+| :------------- | :------------- | :-------------| 
+| `PIHOLE_RUN` | When the plugin should run.  | `schedule` |
+| `PIHOLE_RUN_SCHD` | If you run multiple device scanner plugins, align the schedules of all plugins to the same value.  | `*/5 * * * *` |
+| `PIHOLE_DB_PATH` | You need to map the value in this setting in the `docker-compose.yml` file. | `/etc/pihole/pihole-FTL.db` |
+
+Check the [PiHole plugin readme](https://github.com/jokob-sk/NetAlertX/tree/main/front/plugins/pihole_scan) for details
+
+### docker-compose changes
+
+| Path | Description |
+| :------------- | :------------- |
+| `:/etc/pihole/pihole-FTL.db` |  PiHole's `pihole-FTL.db` database file.  |
+
+
+Check out other [plugins](/front/plugins/README.md) that can help you discover more about your network or check how to scan [Remote networks](/docs/REMOTE_NETWORKS.md).