diff --git a/.github/ISSUE_TEMPLATE/setup-help.yml b/.github/ISSUE_TEMPLATE/setup-help.yml new file mode 100755 index 00000000..ecd11c93 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/setup-help.yml @@ -0,0 +1,74 @@ +name: Setup help +description: 'When submitting an issue enable LOG_LEVEL="trace" and re-search first.' +labels: ['Setup πŸ“₯'] +body: +- type: checkboxes + attributes: + label: Did I research? + description: Please confirm you checked the usual places before opening a setup support request. + options: + - label: I have searched the docs https://jokob-sk.github.io/NetAlertX/ + required: true + - label: I have searched the existing open and closed issues + required: true + - label: I confirm my SCAN_SUBNETS is configured and tested as per https://github.com/jokob-sk/NetAlertX/blob/main/docs/SUBNETS.md + required: true +- type: checkboxes + attributes: + label: The issue occurs in the following browsers. Select at least 2. + description: This step helps me understand if this is a cache or browser-specific issue. + options: + - label: "Firefox" + - label: "Chrome" + - label: "Other (unsupported) - PRs welcome" + - label: "N/A - This is an issue with the backend" +- type: textarea + attributes: + label: What I want to do + description: Describe what you want to achieve. + placeholder: | + + validations: + required: false +- type: textarea + attributes: + label: Relevant settings you changed + description: | + Paste a screenshot or setting values of the settings you changed. + validations: + required: false +- type: textarea + attributes: + label: docker-compose.yml + description: | + Paste your `docker-compose.yml` + render: python + validations: + required: false +- type: dropdown + attributes: + label: What installation are you running? + options: + - Production (netalertx) + - Dev (netalertx-dev) + - Home Assistant (addon) + validations: + required: true +- type: textarea + attributes: + label: app.log + description: | + Logs with debug enabled (https://github.com/jokob-sk/NetAlertX/blob/main/docs/DEBUG_TIPS.md) ⚠ + ***Generally speaking, all bug reports should have logs provided.*** + Tip: You can attach images or log files by clicking this area to highlight it and then dragging files in. + Additionally, any additional info? Screenshots? References? Anything that will give us more context about the issue you are encountering! + You can use `tail -100 /app/log/app.log` in the container if you have trouble getting to the log files. + validations: + required: false +- type: checkboxes + attributes: + label: Debug enabled + description: I confirm I enabled `debug` + options: + - label: I have read and followed the steps in the wiki link above and provided the required debug logs and the log section covers the time when the issue occurs. + required: true diff --git a/.github/workflows/mkdocs.yml b/.github/workflows/mkdocs.yml index 7c855abc..15620ced 100755 --- a/.github/workflows/mkdocs.yml +++ b/.github/workflows/mkdocs.yml @@ -18,7 +18,9 @@ jobs: python-version: '3.9' - name: Install MkDocs - run: pip install mkdocs mkdocs-material + run: | + pip install mkdocs mkdocs-material + pip install mkdocs-github-admonitions-plugin - name: Deploy MkDocs run: mkdocs gh-deploy --force diff --git a/README.md b/README.md index f2651762..a1693d17 100755 --- a/README.md +++ b/README.md @@ -111,21 +111,21 @@ Proudly using [Weblate](https://hosted.weblate.org/projects/pialert/). Help out -[main]: ./docs/img/devices_split.png "Main screen" -[device_details]: ./docs/img/device_details.png "Screen 1" -[events]: ./docs/img/events.png "Screen 2" -[presence]: ./docs/img/presence.png "Screen 3" -[maintenance]: ./docs/img/maintenance.png "Screen 4" -[network]: ./docs/img/network.png "Screen 5" -[settings]: ./docs/img/settings.png "Screen 6" -[showcase]: ./docs/img/showcase.gif "Screen 6" -[help_faq]: ./docs/img/help_faq.png "Screen 7" -[sync_hub]: ./docs/img/sync_hub.png "Screen 8" -[notification_center]: ./docs/img/notification_center.png "Screen 8" -[sent_reports_text]: ./docs/img/sent_reports_text.png "Screen 8" -[device_nmap]: ./docs/img/device_nmap.png "Screen 9" -[report1]: ./docs/img/report_sample.png "Report sample 1" -[main_dark]: /docs/img/1_devices_dark.jpg "Main screen dark" -[maintain_dark]: /docs/img/5_maintain.jpg "Maintain screen dark" -[follow_star]: /docs/img/Follow_Releases_and_Star.gif "Follow and Star" +[main]: ../img/devices_split.png "Main screen" +[device_details]: ../img/device_details.png "Screen 1" +[events]: ../img/events.png "Screen 2" +[presence]: ../img/presence.png "Screen 3" +[maintenance]: ../img/maintenance.png "Screen 4" +[network]: ../img/network.png "Screen 5" +[settings]: ../img/settings.png "Screen 6" +[showcase]: ../img/showcase.gif "Screen 6" +[help_faq]: ../img/help_faq.png "Screen 7" +[sync_hub]: ../img/sync_hub.png "Screen 8" +[notification_center]: ../img/notification_center.png "Screen 8" +[sent_reports_text]: ../img/sent_reports_text.png "Screen 8" +[device_nmap]: ../img/device_nmap.png "Screen 9" +[report1]: ../img/report_sample.png "Report sample 1" +[main_dark]: ./img/1_devices_dark.jpg "Main screen dark" +[maintain_dark]: ./img/5_maintain.jpg "Maintain screen dark" +[follow_star]: ./img/Follow_Releases_and_Star.gif "Follow and Star" diff --git a/docker-compose.yml b/docker-compose.yml index 75f83f5e..7da64b71 100755 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -28,6 +28,8 @@ services: - ${APP_DATA_LOCATION}/netalertx/dhcp_samples/pihole_dhcp_full.leases:/etc/pihole/dhcp.leases - ${APP_DATA_LOCATION}/netalertx/dhcp_samples/pihole_dhcp_2.leases:/etc/pihole/dhcp2.leases - ${APP_DATA_LOCATION}/pihole/etc-pihole/pihole-FTL.db:/etc/pihole/pihole-FTL.db + - ${DEV_LOCATION}/mkdocs.yml:/app/mkdocs.yml + - ${DEV_LOCATION}/docs:/app/docs - ${DEV_LOCATION}/server:/app/server - ${DEV_LOCATION}/test:/app/test - ${DEV_LOCATION}/dockerfiles:/app/dockerfiles diff --git a/dockerfiles/README.md b/dockerfiles/README.md index 0129c332..550f5f44 100755 --- a/dockerfiles/README.md +++ b/dockerfiles/README.md @@ -9,8 +9,8 @@ | [πŸ“‘ Docker guide](https://github.com/jokob-sk/NetAlertX/blob/main/dockerfiles/README.md) | [πŸš€ Releases](https://github.com/jokob-sk/NetAlertX/releases) | [πŸ“š Docs](https://github.com/jokob-sk/NetAlertX/tree/main/docs) | [πŸ”Œ Plugins](https://github.com/jokob-sk/NetAlertX/blob/main/front/plugins/README.md) | [πŸ€– Ask AI](https://gurubase.io/g/netalertx) |----------------------| ----------------------| ----------------------| ----------------------| ----------------------| - - + + Head to [https://netalertx.com/](https://netalertx.com/) for more gifs and screenshots πŸ“·. diff --git a/docs/AUTHELIA.md b/docs/AUTHELIA.md index d0d998f7..f0657716 100755 --- a/docs/AUTHELIA.md +++ b/docs/AUTHELIA.md @@ -1,6 +1,8 @@ -(DRAFT) Authelia support - +## Authelia support +> [!WARNING] +> +> This is community contributed content and work in progress. Contributions are welcome. ```yaml theme: dark diff --git a/docs/BACKUPS.md b/docs/BACKUPS.md index 253b377c..132d8dfa 100755 --- a/docs/BACKUPS.md +++ b/docs/BACKUPS.md @@ -18,7 +18,7 @@ To decide on a backup strategy, check where the data is stored: ### Core Configuration -The core application configuration is in the `app.conf` file (See [Settings System](https://github.com/jokob-sk/NetAlertX/blob/main/docs/SETTINGS_SYSTEM.md) for details), such as: +The core application configuration is in the `app.conf` file (See [Settings System](./SETTINGS_SYSTEM.md) for details), such as: - Notification settings - Scanner settings @@ -37,7 +37,7 @@ The core device data is backed up to the `devices_.csv` or `devices.c ### Historical data -Historical data is stored in the `app.db` database (See [Database overview](https://github.com/jokob-sk/NetAlertX/blob/main/docs/DATABASE.md) for details). This data includes: +Historical data is stored in the `app.db` database (See [Database overview](./DATABASE.md) for details). This data includes: - Plugin objects - Plugin historical entries @@ -50,7 +50,7 @@ The safest approach to backups is to backup all of the above, by taking regular Arguably, the most time is spent setting up the device list, so if only one file is kept I'd recommend to have a latest backup of the `devices_.csv` or `devices.csv` file, followed by the `app.conf` file. You can also download `app.conf` and `devices.csv` file in the Maintenance section: -![Backup and Restore Section in Maintenance](/docs/img/BACKUPS/Maintenance_Backup_Restore.png) +![Backup and Restore Section in Maintenance](./img/BACKUPS/Maintenance_Backup_Restore.png) ### Scenario 1: Full backup @@ -81,6 +81,6 @@ Even with a corrupted database you can recover what I would argue is 99% of the - upload the `app.conf` file into the mounted `/app/config/` folder as described in the [Setup documentation](https://github.com/jokob-sk/NetAlertX/blob/main/dockerfiles/README.md#docker-paths). - rename the `devices_.csv` to `devices.csv` and place it in the `/app/config` folder -- Restore the `devices.csv` backup via the [Maintenance section](https://github.com/jokob-sk/NetAlertX/blob/main/docs/DEVICES_BULK_EDITING.md) +- Restore the `devices.csv` backup via the [Maintenance section](./DEVICES_BULK_EDITING.md) diff --git a/docs/COMMON_ISSUES.md b/docs/COMMON_ISSUES.md new file mode 100755 index 00000000..4cc08c41 --- /dev/null +++ b/docs/COMMON_ISSUES.md @@ -0,0 +1,44 @@ +### Loading... + +Often if the application is misconfigured the `Loading...` dialog is continuously displayed. This is most likely caused by the backed failing to start. The **Maintenance -> Logs** section should give you more details on what's happenning. If there is no exception, check the Portainer log, or start the container in the foreground (without the `-d` parameter) to observe any exceptions. It's advisable to enable `trace` or `debug`. Check the [Debug tips](./DEBUG_TIPS.md) on detailed instructions. + +### Incorrect SCAN_SUBNETS + +One of the most common issues is not configuring `SCAN_SUBNETS` correctly. If this setting is misconfigured you will only see one or two devices in your devices list after a scan. Please read the [subnets docs](./SUBNETS.md) carefully to resolve this. + +### Permissions + +Make sure you [File permissions](./FILE_PERMISSIONS.md) are set correctly. + +* If facing issues (AJAX errors, can't write to DB, empty screen, etc,) make sure permissions are set correctly, and check the logs under `/app/log`. +* To solve permission issues you can try setting the owner and group of the `app.db` by executing the following on the host system: `docker exec netalertx chown -R www-data:www-data /app/db/app.db`. +* If still facing issues, try to map the app.db file (⚠ not folder) to `:/app/db/app.db` (see [docker-compose Examples](https://github.com/jokob-sk/NetAlertX/blob/main/dockerfiles/README.md#-docker-composeyml-examples) for details) + +### Container restarts / crashes + +* Check the logs for details. Often a required setting for a notification method is missing. + +### unable to resolve host + +* Check that your `SCAN_SUBNETS` variable is using the correct mask and `--interface`. See the [subnets docs for details](./SUBNETS.md). + +### Invalid JSON + +Check the [Invalid JSON errors debug help](./DEBUG_INVALID_JSON.md) docs on how to proceed. + +### sudo execution failing (e.g.: on arpscan) on a Raspberry Pi 4 + +> sudo: unexpected child termination condition: 0 + +Resolution based on [this issue](https://github.com/linuxserver/docker-papermerge/issues/4#issuecomment-1003657581) + +``` +wget ftp.us.debian.org/debian/pool/main/libs/libseccomp/libseccomp2_2.5.3-2_armhf.deb +sudo dpkg -i libseccomp2_2.5.3-2_armhf.deb +``` + +The link above will probably break in time too. Go to https://packages.debian.org/sid/armhf/libseccomp2/download to find the new version number and put that in the url. + +### Only Router and own device show up + +Make sure that the subnet and interface in `SCAN_SUBNETS` are correct. If your device/NAS has multiple ethernet ports, you probably need to change `eth0` to something else. \ No newline at end of file diff --git a/docs/CUSTOM_PROPERTIES.md b/docs/CUSTOM_PROPERTIES.md index df4110e7..755aed9f 100755 --- a/docs/CUSTOM_PROPERTIES.md +++ b/docs/CUSTOM_PROPERTIES.md @@ -1,6 +1,6 @@ # Custom Properties for Devices -![Custom Properties](/docs/img/CUSTOM_PROPERTIES/Device_Custom_Properties.png) +![Custom Properties](./img/CUSTOM_PROPERTIES/Device_Custom_Properties.png) ## Overview @@ -41,7 +41,7 @@ Custom properties are structured as a list of objects, where each property inclu ## Usage on the Device Listing Page -![Custom Properties](/docs/img/CUSTOM_PROPERTIES/Device_Custom_Properties_vid.gif) +![Custom Properties](./img/CUSTOM_PROPERTIES/Device_Custom_Properties_vid.gif) Visible properties (`CUSTPROP_show: true`) are displayed as interactive icons in the device listing. Each icon can perform one of the following actions based on the `CUSTPROP_type`: diff --git a/docs/DATABASE.md b/docs/DATABASE.md index de4beb47..bf89b00a 100755 --- a/docs/DATABASE.md +++ b/docs/DATABASE.md @@ -23,15 +23,15 @@ - [screen1]: /docs/img/DATABASE/CurrentScan.png - [screen2]: /docs/img/DATABASE/Devices.png - [screen4]: /docs/img/DATABASE/Events.png - [screen6]: /docs/img/DATABASE/Online_History.png - [screen7]: /docs/img/DATABASE/Parameters.png - [screen10]: /docs/img/DATABASE/Plugins_Events.png - [screen11]: /docs/img/DATABASE/Plugins_History.png - [screen12]: /docs/img/DATABASE/Plugins_Language_Strings.png - [screen13]: /docs/img/DATABASE/Plugins_Objects.png - [screen15]: /docs/img/DATABASE/Sessions.png - [screen16]: /docs/img/DATABASE/Settings.png + [screen1]: ./img/DATABASE/CurrentScan.png + [screen2]: ./img/DATABASE/Devices.png + [screen4]: ./img/DATABASE/Events.png + [screen6]: ./img/DATABASE/Online_History.png + [screen7]: ./img/DATABASE/Parameters.png + [screen10]: ./img/DATABASE/Plugins_Events.png + [screen11]: ./img/DATABASE/Plugins_History.png + [screen12]: ./img/DATABASE/Plugins_Language_Strings.png + [screen13]: ./img/DATABASE/Plugins_Objects.png + [screen15]: ./img/DATABASE/Sessions.png + [screen16]: ./img/DATABASE/Settings.png diff --git a/docs/DEBUG_PLUGINS.md b/docs/DEBUG_PLUGINS.md index edd317d3..a84fb49b 100755 --- a/docs/DEBUG_PLUGINS.md +++ b/docs/DEBUG_PLUGINS.md @@ -9,7 +9,7 @@ For a more in-depth overview on how plugins work check the [Plugins development ### Prerequisites - Make sure you read and followed the specific plugin setup instructions. -- Ensure you have [debug enabled (see More Logging)](https://github.com/jokob-sk/NetAlertX/blob/main/docs/DEBUG_TIPS.md#1-more-logging-) +- Ensure you have [debug enabled (see More Logging)](./DEBUG_TIPS.md#1-more-logging-) ### Potential issues @@ -75,7 +75,7 @@ In the above output notice the section logging how many events are produced by t These values, if formatted correctly, will also show up in the UI: -![Plugins table](/docs/img/DEBUG_PLUGINS/plugin_objects_pihole.png) +![Plugins table](./img/DEBUG_PLUGINS/plugin_objects_pihole.png) ### Sharing application state diff --git a/docs/DEBUG_TIPS.md b/docs/DEBUG_TIPS.md index d7eb7b95..d81a4a08 100755 --- a/docs/DEBUG_TIPS.md +++ b/docs/DEBUG_TIPS.md @@ -2,14 +2,13 @@ Please follow tips 1 - 4 to get a more detailed error. -## 1. More Logging πŸ“ƒ +## 1. More Logging When debugging an issue always set the highest log level: `LOG_LEVEL='trace'` - -## 2. Surfacing errors when container restarts πŸ” +## 2. Surfacing errors when container restarts Start the container via the **terminal** with a command similar to this one: @@ -25,7 +24,7 @@ docker run --rm --network=host \ > ⚠ Please note, don't use the `-d` parameter so you see the error when the container crashes. Use this error in your issue description. -## 3. Check the _dev image and open issues ❓ +## 3. Check the _dev image and open issues If possible, check if your issue got fixed in the `_dev` image before opening a new issue. The container is: @@ -35,7 +34,7 @@ If possible, check if your issue got fixed in the `_dev` image before opening a Please also search [open issues](https://github.com/jokob-sk/NetAlertX/issues). -## 4. Disable restart behavior πŸ›‘ +## 4. Disable restart behavior To prevent a Docker container from automatically restarting in a Docker Compose file, specify the restart policy as `no`: @@ -60,39 +59,6 @@ Sometimes specific log sections are needed to debug issues. The Devices and Curr 5. Open a new issue and post (redacted) output into the issue description (or send to the netalertx@gmail.com email if sensitive data present). 6. Please set `LOG_LEVEL` to `debug` or lower. -## πŸ“ƒCommon issues +## Common issues -### Permissions - -* If facing issues (AJAX errors, can't write to DB, empty screen, etc,) make sure permissions are set correctly, and check the logs under `/app/log`. -* To solve permission issues you can try setting the owner and group of the `app.db` by executing the following on the host system: `docker exec netalertx chown -R www-data:www-data /app/db/app.db`. -* If still facing issues, try to map the app.db file (⚠ not folder) to `:/app/db/app.db` (see [docker-compose Examples](https://github.com/jokob-sk/NetAlertX/blob/main/dockerfiles/README.md#-docker-composeyml-examples) for details) - -### Container restarts / crashes - -* Check the logs for details. Often a required setting for a notification method is missing. - -### unable to resolve host - -* Check that your `SCAN_SUBNETS` variable is using the correct mask and `--interface`. See teh [subnets docs for details](/docs/SUBNETS.md). - -### Invalid JSON - -Check the [Invalid JSON errors debug help](/docs/DEBUG_INVALID_JSON.md) docs on how to proceed. - -### sudo execution failing (e.g.: on arpscan) on a Raspberry Pi 4 - -> sudo: unexpected child termination condition: 0 - -Resolution based on [this issue](https://github.com/linuxserver/docker-papermerge/issues/4#issuecomment-1003657581) - -``` -wget ftp.us.debian.org/debian/pool/main/libs/libseccomp/libseccomp2_2.5.3-2_armhf.deb -sudo dpkg -i libseccomp2_2.5.3-2_armhf.deb -``` - -The link above will probably break in time too. Go to https://packages.debian.org/sid/armhf/libseccomp2/download to find the new version number and put that in the url. - -### Only Router and own device show up - -Make sure that the subnet and interface in `SCAN_SUBNETS` are correct. If your device/NAS has multiple ethernet ports, you probably need to change `eth0` to something else. +See [Common issues](./COMMON_ISSUES.md) for details. diff --git a/docs/DEVICES_BULK_EDITING.md b/docs/DEVICES_BULK_EDITING.md index b64c350a..78be7579 100755 --- a/docs/DEVICES_BULK_EDITING.md +++ b/docs/DEVICES_BULK_EDITING.md @@ -1,14 +1,18 @@ -# πŸ–Š Multi-editing via the UI +# Editing multiple devices at once + +NetAlertX allows you to mass-edit devices via a CSV export and import feature, or directly in the UI. + +## UI multi edit > [!NOTE] -> Make sure you have your backups saved and restorable before doing any mass edits. Check [Backup strategies](/docs/BACKUPS.md). +> Make sure you have your backups saved and restorable before doing any mass edits. Check [Backup strategies](./BACKUPS.md). You can select devices in the _Devices_ view by selecting devices to edit and then clicking the _Multi-edit_ button or via the _Maintenance_ > _Multi-Edit_ section. -![Maintenance > Multi-edit](/docs/img/DEVICES_BULK_EDITING/MULTI-EDIT.gif) +![Maintenance > Multi-edit](./img/DEVICES_BULK_EDITING/MULTI-EDIT.gif) -# πŸ“Bulk-edit devices via CSV Export/Import +## CSV bulk edit > [!NOTE] > As always, backup everything, just in case. @@ -17,17 +21,19 @@ You can select devices in the _Devices_ view by selecting devices to edit and th 2. A `devices.csv` is generated in the `/config` folder 3. Edit the `devices.csv` file however you like. -![Maintenance > CSV Export](/docs/img/DEVICES_BULK_EDITING/MAINTENANCE_CSV_EXPORT.png) +![Maintenance > CSV Export](./img/DEVICES_BULK_EDITING/MAINTENANCE_CSV_EXPORT.png) > [!NOTE] > The file containing a list of Devices including the Network relationships between Network Nodes and connected devices. You can also trigger this by acessing this URL: `/php/server/devices.php?action=ExportCSV` or via the `CSV Backup` plugin. (πŸ’‘ You can schedule this) -![Settings > CSV Backup](/docs/img/DEVICES_BULK_EDITING/CSV_BACKUP_SETTINGS.png) +![Settings > CSV Backup](./img/DEVICES_BULK_EDITING/CSV_BACKUP_SETTINGS.png) + +### File encoding format > [!NOTE] > Keep Linux line endings (suggested editors: Nano, Notepad++) -![Nodepad++ line endings](/docs/img/DEVICES_BULK_EDITING/NOTEPAD++.png) +![Nodepad++ line endings](./img/DEVICES_BULK_EDITING/NOTEPAD++.png) diff --git a/docs/DEVICE_DISPLAY_SETTINGS.md b/docs/DEVICE_DISPLAY_SETTINGS.md index 3b78ca21..81260151 100755 --- a/docs/DEVICE_DISPLAY_SETTINGS.md +++ b/docs/DEVICE_DISPLAY_SETTINGS.md @@ -3,4 +3,4 @@ This set of settings allows you to group Devices under different views. The Archived toggle allows you to exclude a Device from most listings and notifications. -![Display settings](/docs/img/DEVICE_MANAGEMENT/DeviceDetails_DisplaySettings.png) \ No newline at end of file +![Display settings](./img/DEVICE_MANAGEMENT/DeviceDetails_DisplaySettings.png) \ No newline at end of file diff --git a/docs/DEVICE_MANAGEMENT.md b/docs/DEVICE_MANAGEMENT.md index ca4a461b..18d2d50e 100755 --- a/docs/DEVICE_MANAGEMENT.md +++ b/docs/DEVICE_MANAGEMENT.md @@ -4,20 +4,20 @@ The Main Info section is where most of the device identifiable information is st > [!NOTE] > -> You can multi-edit devices by selecting them in the main Devices view, from the Mainetence section, or via the CSV Export functionality under Maintenance. More info can be found in the [Devices Bulk-editing docs](https://github.com/jokob-sk/NetAlertX/blob/main/docs/DEVICES_BULK_EDITING.md). +> You can multi-edit devices by selecting them in the main Devices view, from the Mainetence section, or via the CSV Export functionality under Maintenance. More info can be found in the [Devices Bulk-editing docs](./DEVICES_BULK_EDITING.md). - ![Main Info](/docs/img/DEVICE_MANAGEMENT/DeviceManagement_MainInfo.png) + ![Main Info](./img/DEVICE_MANAGEMENT/DeviceManagement_MainInfo.png) ## Main Info - **MAC**: MAC addres of the device. Not editable, unless creating a new dummy device. - **Last IP**: IP addres of the device. Not editable, unless creating a new dummy device. - **Name**: Friendly device name. Autodetected via various πŸ†Ž Name discovery [plugins](https://github.com/jokob-sk/NetAlertX/blob/main/front/plugins/README.md). The app attaches `(IP match)` if the name is discovered via an IP match and not MAC match which could mean the name could be incorrect as IPs might change. - - **Icon**: Partially autodetected. Select an existing or [add a custom icon](https://github.com/jokob-sk/NetAlertX/blob/main/docs/ICONS.md). You can also auto-apply the same icon on all devices of the same type. + - **Icon**: Partially autodetected. Select an existing or [add a custom icon](./ICONS.md). You can also auto-apply the same icon on all devices of the same type. - **Owner**: Device owner (The list is self-populated with existing owners and you can add custom values). - **Type**: Select a device type from the dropdown list (`Smartphone`, `Tablet`, - `Laptop`, `TV`, `router`, etc.) or add a new device type. If you want the device to act as a **Network device** (and be able to be a network node in the Network view), select a type under Network Devices or add a new Network Device type in Settings. More information can be found in the [Network Setup docs](https://github.com/jokob-sk/NetAlertX/blob/main/docs/NETWORK_TREE.md). + `Laptop`, `TV`, `router`, etc.) or add a new device type. If you want the device to act as a **Network device** (and be able to be a network node in the Network view), select a type under Network Devices or add a new Network Device type in Settings. More information can be found in the [Network Setup docs](./NETWORK_TREE.md). - **Vendor**: The manufacturing vendor. Automatically updated by NetAlertX when empty or unknown, can be edited. - **Group**: Select a group (`Always on`, `Personal`, `Friends`, etc.) or type your own Group name. @@ -32,11 +32,11 @@ The Main Info section is where most of the device identifiable information is st You can create dummy devices from the Devices listing screen. -![Create Dummy Device](/docs/img/DEVICE_MANAGEMENT/Devices_CreateDummyDevice.png) +![Create Dummy Device](./img/DEVICE_MANAGEMENT/Devices_CreateDummyDevice.png) The **MAC** field and the **Last IP** field will then become editable. -![Save Dummy Device](/docs/img/DEVICE_MANAGEMENT/DeviceEdit_SaveDummyDevice.png) +![Save Dummy Device](./img/DEVICE_MANAGEMENT/DeviceEdit_SaveDummyDevice.png) > [!NOTE] diff --git a/docs/DEV_ENV_SETUP.md b/docs/DEV_ENV_SETUP.md index ee84a232..b7689ecc 100755 --- a/docs/DEV_ENV_SETUP.md +++ b/docs/DEV_ENV_SETUP.md @@ -6,6 +6,7 @@ ### Development Guidelines **Priority Order (Highest to Lowest):** + 1. πŸ”Ό Fixing core bugs that lack workarounds. 2. πŸ”΅ Adding core functionality that unlocks other features (e.g., plugins). 3. πŸ”΅ Refactoring to enable faster development. @@ -14,12 +15,14 @@ πŸ’‘ **Design Philosophy:** Focus on core functionality and integrate with existing tools rather than reinventing the wheel. Examples: + - Using **Apprise** for notifications instead of implementing multiple separate gateways. - Implementing **regex-based validation** instead of one-off validation for each setting. πŸ“Œ **Note on UI requests:** -UI changes have lower priority due to framework limitations and mobile support constraints. -PRs are welcome, but **keep them small & focused**. + +- UI changes have lower priority due to framework limitations and mobile support constraints. +- PRs are welcome, but **keep them small & focused**. ## 1. Download the code: @@ -76,7 +79,7 @@ Most code changes can be tetsed without rebuilding the container. When working o 1. You can usually restart the backend via Maintenance > Logs > Restart server -![image](/docs/img/DEV_ENV_SETUP/Maintenance_Logs_Restart_server.png) +![image](./img/DEV_ENV_SETUP/Maintenance_Logs_Restart_server.png) 2. If above doesn't work, SSH into the container and kill & restart the main script loop @@ -88,6 +91,7 @@ Most code changes can be tetsed without rebuilding the container. When working o ## βž• Contributing & Pull Requests **Before submitting a PR, please ensure:** + βœ” Changes are **backward-compatible** with existing installs. βœ” No unnecessary changes are made. βœ” New features are **reusable**, not narrowly scoped. @@ -98,10 +102,12 @@ Most code changes can be tetsed without rebuilding the container. When working o - Fresh install (no DB/config). - Existing DB/config compatibility. - Notification testing: + - Email - Apprise (e.g., Telegram) - Webhook (e.g., Discord) - MQTT (e.g., Home Assistant) + - Settings persistence. - Updating a Device - Plugin functionality. diff --git a/docs/HOME_ASSISTANT.md b/docs/HOME_ASSISTANT.md index 2b8d28fa..72e19d5b 100755 --- a/docs/HOME_ASSISTANT.md +++ b/docs/HOME_ASSISTANT.md @@ -3,7 +3,7 @@ NetAlertX comes with MQTT support, allowing you to show all detected devices as devices in Home Assistant. It also supplies a collection of stats, such as number of online devices. > [!TIP] -> You can install NetAlertX also as a Home Assistant addon [![Home Assistant](https://img.shields.io/badge/Repo-blue?logo=home-assistant&style=for-the-badge&color=0aa8d2&logoColor=fff&label=Add)](https://my.home-assistant.io/redirect/supervisor_add_addon_repository/?repository_url=https%3A%2F%2Fgithub.com%2Falexbelgium%2Fhassio-addons) via the [alexbelgium/hassio-addons](https://github.com/alexbelgium/hassio-addons/). +> You can install NetAlertX also as a Home Assistant addon [![Home Assistant](https://img.shields.io/badge/Repo-blue?logo=home-assistant&style=for-the-badge&color=0aa8d2&logoColor=fff&label=Add)](https://my.home-assistant.io/redirect/supervisor_add_addon_repository/?repository_url=https%3A%2F%2Fgithub.com%2Falexbelgium%2Fhassio-addons) via the [alexbelgium/hassio-addons](https://github.com/alexbelgium/hassio-addons/). This is only possible if you run a supervised instance of Home Assistant. If not, you can still run NetAlertX in a separate Docker container and follow this guide to configure MQTT. ## ⚠ Note @@ -21,15 +21,17 @@ NetAlertX comes with MQTT support, allowing you to show all detected devices as 2. Configure a user name and password on your broker. 3. Note down the following details that you will need to configure NetAlertX: - - MQTT host url (usually your Home Assistant IP) - - MQTT broker port - - User - - Password + + - MQTT host url (usually your Home Assistant IP) + - MQTT broker port + - User + - Password 4. Open the _NetAlertX_ > _Settings_ > _MQTT_ settings group - - Enable MQTT - - Fill in the details from above - - Fill in remaining settings as per description + + - Enable MQTT + - Fill in the details from above + - Fill in remaining settings as per description ![Configuration Example][configuration] @@ -40,9 +42,9 @@ NetAlertX comes with MQTT support, allowing you to show all detected devices as | ![Screen 3][list] | ![Screen 4][overview] | - [configuration]: /docs/img/HOME_ASISSTANT/HomeAssistant-Configuration.png "configuration" - [sensors]: /docs/img/HOME_ASISSTANT/HomeAssistant-Device-as-Sensors.png "sensors" - [history]: /docs/img/HOME_ASISSTANT/HomeAssistant-Device-Presence-History.png "history" - [list]: /docs/img/HOME_ASISSTANT/HomeAssistant-Devices-List.png "list" - [overview]: /docs/img/HOME_ASISSTANT/HomeAssistant-Overview-Card.png "overview" + [configuration]: ./img/HOME_ASISSTANT/HomeAssistant-Configuration.png "configuration" + [sensors]: ./img/HOME_ASISSTANT/HomeAssistant-Device-as-Sensors.png "sensors" + [history]: ./img/HOME_ASISSTANT/HomeAssistant-Device-Presence-History.png "history" + [list]: ./img/HOME_ASISSTANT/HomeAssistant-Devices-List.png "list" + [overview]: ./img/HOME_ASISSTANT/HomeAssistant-Overview-Card.png "overview" diff --git a/docs/ICONS.md b/docs/ICONS.md index e8071210..3ac355bb 100755 --- a/docs/ICONS.md +++ b/docs/ICONS.md @@ -1,8 +1,8 @@ ## Icons overview -Icons are used to visually distinguish devices in the app in most of the device listing tables and the [network tree](/docs/NETWORK_TREE.md). +Icons are used to visually distinguish devices in the app in most of the device listing tables and the [network tree](./NETWORK_TREE.md). -![Raspberry Pi with a brand icon](/docs/img/ICONS/devices-icons.png) +![Raspberry Pi with a brand icon](./img/ICONS/devices-icons.png) ### Icons Support @@ -19,19 +19,19 @@ You can assign icons individually on each device in the Details tab. Copying the SVG (for example from [iconify.design](https://icon-sets.iconify.design/)): -![iconify svg](/docs/img/ICONS/iconify_design_copy_svg.png) +![iconify svg](./img/ICONS/iconify_design_copy_svg.png) Copying the HTML code from [Font Awesome](https://fontawesome.com/search?o=r&m=free). -![Font awesome](/docs/img/ICONS/font_awesome_copy_html.png) +![Font awesome](./img/ICONS/font_awesome_copy_html.png) 2. Navigate to the device you want to use the icon on and click the "+" icon: -![preview](/docs/img/ICONS/device_add_icon.png) +![preview](./img/ICONS/device_add_icon.png) 3. Paste in the copied HTML or SVG code and click "OK": -![Paste SVG](/docs/img/ICONS/paste-svg.png) +![Paste SVG](./img/ICONS/paste-svg.png) 6. "Save" the device diff --git a/docs/INITIAL_SETUP.md b/docs/INITIAL_SETUP.md index 0308e6c1..320752e3 100755 --- a/docs/INITIAL_SETUP.md +++ b/docs/INITIAL_SETUP.md @@ -12,22 +12,22 @@ - Define networks to scan by entering accessible subnets. - Default plugin: **ARPSCAN** β†’ Requires at least one valid subnet + interface in `SCAN_SUBNETS`. -- πŸ“– [Subnet & VLAN setup guide](https://github.com/jokob-sk/NetAlertX/blob/main/docs/SUBNETS.md) (for troubleshooting and advanced scenarios). +- πŸ“– [Subnet & VLAN setup guide](./SUBNETS.md) (for troubleshooting and advanced scenarios). ### πŸ”„ PiHole Sync - If using **PiHole**, devices can be synced automatically. -- πŸ“– [PiHole configuration guide](https://github.com/jokob-sk/NetAlertX/blob/main/docs/PIHOLE_GUIDE.md). +- πŸ“– [PiHole configuration guide](./PIHOLE_GUIDE.md). ### πŸ“¦ Bulk Import > [!NOTE] -> You can bulk-import devices via the [CSV import method](https://github.com/jokob-sk/NetAlertX/blob/main/docs/DEVICES_BULK_EDITING.md). +> You can bulk-import devices via the [CSV import method](./DEVICES_BULK_EDITING.md). --- ## 🌍 Community Guides - Various community-written configuration guides in **Chinese, Korean, German, French**. -- πŸ“– [Community Guides](https://github.com/jokob-sk/NetAlertX/blob/main/docs/COMMUNITY_GUIDES.md) +- πŸ“– [Community Guides](./COMMUNITY_GUIDES.md) > ⚠️ **Note:** These guides may be outdated. Always refer to the official documentation first. @@ -37,4 +37,4 @@ Before creating a new issue: - Check if a similar issue was [already resolved](https://github.com/jokob-sk/NetAlertX/issues?q=is%3Aissue+is%3Aclosed). -- Review [common debugging tips](https://github.com/jokob-sk/NetAlertX/blob/main/docs/DEBUG_TIPS.md). +- Review [common debugging tips](./DEBUG_TIPS.md). diff --git a/docs/INSTALLATION.md b/docs/INSTALLATION.md new file mode 100755 index 00000000..04143bd0 --- /dev/null +++ b/docs/INSTALLATION.md @@ -0,0 +1,18 @@ +# Installation options + +NetAlertX can be installed several ways. The best supported option is Docker, followed by a supervised the Home Assistant instance, as an Unraid app and lastly on bare metal. + +- [[Installation] Docker (recommended)](https://github.com/jokob-sk/NetAlertX/blob/main/dockerfiles/README.md) +- [[Installation] Home Assistant](https://github.com/alexbelgium/hassio-addons/tree/master/netalertx) +- [[Installation] Unraid App](https://unraid.net/community/apps) +- [[Installation] Bare metal (experimental - looking for maintainers)](https://github.com/jokob-sk/NetAlertX/blob/main/docs/HW_INSTALL.md) + +If facing issues, please spend a few minutes seraching. + +- Check [common issues](./COMMON_ISSUES.md) +- Have a look at [Community guides](./COMMUNITY_GUIDES.md) +- [Search closed or open issues or discussions](https://github.com/jokob-sk/NetAlertX/issues?q=is%3Aissue) +- Check [Discord](https://discord.gg/NczTUTWyRr) + +> [!NOTE] +> If you can't find a solution anywhere, ask in Discord if you think it's a quick question, otherwise open a new [issue](https://github.com/jokob-sk/NetAlertX/issues/new?template=setup-help.yml). Please fill in as much as possible to speed up the help process. \ No newline at end of file diff --git a/docs/MIGRATION.md b/docs/MIGRATION.md index f9fa2170..c92db242 100755 --- a/docs/MIGRATION.md +++ b/docs/MIGRATION.md @@ -6,7 +6,7 @@ ## STEPS: > [!TIP] -> In short: The application will auto-migrate the database, config, and all device information. A ticker message on top will be displayed until you update your docker mount points. It's always good to have a [backup strategy](https://github.com/jokob-sk/NetAlertX/blob/main/docs/BACKUPS.md) in place. +> In short: The application will auto-migrate the database, config, and all device information. A ticker message on top will be displayed until you update your docker mount points. It's always good to have a [backup strategy](./BACKUPS.md) in place. 1. Backup your current config and database (optional `devices.csv` to have a backup) (See bellow tip if facing issues) 2. Stop the container @@ -38,7 +38,7 @@ The application installation folder in the docker container has changed from `/h > [!NOTE] -> The application uses symlinks linking the old db and config locations to the new ones, so data loss should not occur. [Backup strategies](https://github.com/jokob-sk/NetAlertX/blob/main/docs/BACKUPS.md) are still recommended to backup your setup. +> The application uses symlinks linking the old db and config locations to the new ones, so data loss should not occur. [Backup strategies](./BACKUPS.md) are still recommended to backup your setup. # Examples diff --git a/docs/NETWORK_TREE.md b/docs/NETWORK_TREE.md index 5dbafca0..67fb5917 100755 --- a/docs/NETWORK_TREE.md +++ b/docs/NETWORK_TREE.md @@ -2,7 +2,7 @@ Make sure you have a root device with the MAC `Internet` (No other MAC addresses are currently supported as the root node) set to a network device type (e.g.: **Type**:`Router`). -> πŸ’‘ Tip: You can add dummy devices via the [Create dummy device](https://github.com/jokob-sk/NetAlertX/blob/main/docs/DEVICE_MANAGEMENT.md#dummy-devices) button in the Devices listing page. +> πŸ’‘ Tip: You can add dummy devices via the [Create dummy device](./DEVICE_MANAGEMENT.md#dummy-devices) button in the Devices listing page. > πŸ’‘ Tip: Export your configuration of the Network and Devices once in a while via the Export CSV feature under **Maintenance** -> **Backup/Restore** -> **CSV Export**. @@ -17,7 +17,7 @@ Make sure you have a root device with the MAC `Internet` (No other MAC addresses > [!NOTE] > -> [Bulk-edit devices](/docs/DEVICES_BULK_EDITING.md) by using the _CSV Export_ functionality in the _Maintenance_ section. You can use this to fix `Internet` node assignment issues. +> [Bulk-edit devices](./DEVICES_BULK_EDITING.md) by using the _CSV Export_ functionality in the _Maintenance_ section. You can use this to fix `Internet` node assignment issues. ## πŸ”Detailed example: @@ -27,7 +27,7 @@ In this example you will setup a device named `rapberrypi` as a `Switch` in our - Go to the `Devices` (1) page: -![Device details](/docs/img/NETWORK_TREE/Device_Details_Network_Type.png) +![Device details](./img/NETWORK_TREE/Device_Details_Network_Type.png) - In the (2) `Details` tab navigate to the the `Type` (3) dropdown and select the type `Switch` (4). @@ -42,7 +42,7 @@ In this example you will setup a device named `rapberrypi` as a `Switch` in our - Navigate to your `Network` (1) page: -![Network page](/docs/img/NETWORK_TREE/Network_Page.png) +![Network page](./img/NETWORK_TREE/Network_Page.png) - Notice the newly added `raspberrypi` (2) tab which now represents a network node, also showing up in the tree (3). - As we asssigned the `raspberrypi` in the previous (1) Device details page section to the `Internet` parent network node in step (6), the link is also showing up in the tree diagram (4) @@ -52,7 +52,7 @@ In this example you will setup a device named `rapberrypi` as a `Switch` in our - After clicking the `Assign` button in the previous section, the `(AppleTV)` (1) device is now connected to our `raspberrypi` (2). -![Network page with 2 levels](/docs/img/NETWORK_TREE/Network_Page_2_Levels.png) +![Network page with 2 levels](./img/NETWORK_TREE/Network_Page_2_Levels.png) - You can see the `raspberrypi` represents the Network node type `Switch` (3) - The `(AppleTV)` to `raspberrypi` connection is also displayed in the table of `Connected devices` (4). diff --git a/docs/NOTIFICATIONS.md b/docs/NOTIFICATIONS.md index 60e8d8cd..656a3ac7 100755 --- a/docs/NOTIFICATIONS.md +++ b/docs/NOTIFICATIONS.md @@ -9,11 +9,11 @@ There are 4 ways how to influence notifications: > [!NOTE] > It's recommended to use the same schedule interval for all plugins responsible for scanning devices, otherwise false positives might be reported if different devices are discovered by different plugins. Check the **Settings** > **Enabled settings** section for a warning: -> ![Schedules out-of-sync](/docs/img/NOTIFICATIONS/Schedules_out-of-sync.png) +> ![Schedules out-of-sync](./img/NOTIFICATIONS/Schedules_out-of-sync.png) ## Device settings πŸ’» -![Device notification settings](/docs/img/NOTIFICATIONS/Device-notification-settings.png) +![Device notification settings](./img/NOTIFICATIONS/Device-notification-settings.png) There are 4 settings on the device for influencing notifications. You can: @@ -23,7 +23,7 @@ There are 4 settings on the device for influencing notifications. You can: ## Plugin settings πŸ”Œ -![Plugin notification settings](/docs/img/NOTIFICATIONS/Plugin-notification-settings.png) +![Plugin notification settings](./img/NOTIFICATIONS/Plugin-notification-settings.png) On almost all plugins there are 2 core settings, `_WATCH` and `_REPORT_ON`. @@ -34,7 +34,7 @@ Click the **Read more in the docs.** Link at the top of each plugin to get more ## Global settings βš™ -![Global notification settings](/docs/img/NOTIFICATIONS/Global-notification-settings.png) +![Global notification settings](./img/NOTIFICATIONS/Global-notification-settings.png) In Notification Processing settings, you can specify blanket rules. These allow you to specify exceptions to the Plugin and Device settings and will override those. @@ -45,7 +45,7 @@ In Notification Processing settings, you can specify blanket rules. These allow ## Ignoring devices πŸ”• -![Ignoring new devices](/docs/img/NOTIFICATIONS/NEWDEV_ignores.png) +![Ignoring new devices](./img/NOTIFICATIONS/NEWDEV_ignores.png) You can completely ignore detected devices globally. This could be because your instance detects docker containers, you want to ignore devices from a specific manufacturer via MAC rules or you want to ignore devices on a specific IP range. diff --git a/docs/PERFORMANCE.md b/docs/PERFORMANCE.md index fd753d92..44ba494f 100755 --- a/docs/PERFORMANCE.md +++ b/docs/PERFORMANCE.md @@ -6,7 +6,7 @@ Most performance issues are caused by a big database or large log files. Enablin You can always check the size of your database and database tables under the Maintenance page. -![Db size check](/docs/img/PERFORMANCE/db_size_check.png) +![Db size check](./img/PERFORMANCE/db_size_check.png) > [!NOTE] > For around 100 devices the database should be approximately `50MB` and none of the entries (rows) should exceed the value of `10 000` on a healthy system. These numbers will depend on your network activity and settings. diff --git a/docs/PIHOLE_GUIDE.md b/docs/PIHOLE_GUIDE.md index 92c7c17b..b488442e 100755 --- a/docs/PIHOLE_GUIDE.md +++ b/docs/PIHOLE_GUIDE.md @@ -4,7 +4,7 @@ NetAlertX comes with 2 plugins suitable for integarting with your existing PiHol ## Approach 1: `DHCPLSS` Plugin - Import devices from the PiHole DHCP leases file -![DHCPLSS sample settings](/docs/img/PIHOLE_GUIDE/DHCPLSS_pihole_settings.png) +![DHCPLSS sample settings](./img/PIHOLE_GUIDE/DHCPLSS_pihole_settings.png) ### Settings @@ -25,7 +25,7 @@ Check the [DHCPLSS plugin readme](https://github.com/jokob-sk/NetAlertX/tree/mai ## Approach 2: `PIHOLE` Plugin - Import devices directly from the PiHole database -![DHCPLSS sample settings](/docs/img/PIHOLE_GUIDE/PIHOLE_settings.png) +![DHCPLSS sample settings](./img/PIHOLE_GUIDE/PIHOLE_settings.png) | Setting | Description | Recommended value | | :------------- | :------------- | :-------------| @@ -42,4 +42,4 @@ Check the [PiHole plugin readme](https://github.com/jokob-sk/NetAlertX/tree/main | `:/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). +Check out other [plugins](/front/plugins/README.md) that can help you discover more about your network or check how to scan [Remote networks](./REMOTE_NETWORKS.md). diff --git a/docs/PLUGINS_DEV.md b/docs/PLUGINS_DEV.md index 12316abe..ed783860 100755 --- a/docs/PLUGINS_DEV.md +++ b/docs/PLUGINS_DEV.md @@ -13,9 +13,9 @@ NetAlertX comes with a plugin system to feed events from third-party scripts int ### πŸŽ₯ Watch the video: > [!TIP] -> Read this guide [Development environment setup guide](/docs/DEV_ENV_SETUP.md) to set up your local environment for development. πŸ‘©β€πŸ’» +> Read this guide [Development environment setup guide](./DEV_ENV_SETUP.md) to set up your local environment for development. πŸ‘©β€πŸ’» -[![Watch the video](/docs/img/YouTube_thumbnail.png)](https://youtu.be/cdbxlwiWhv8) +[![Watch the video](./img/YouTube_thumbnail.png)](https://youtu.be/cdbxlwiWhv8) ### πŸ“Έ Screenshots @@ -503,7 +503,7 @@ Below are some general additional notes, when defining `params`: #### βš™ Setting object structure > [!NOTE] -> The settings flow and when Plugin specific settings are applied is described under the [Settings system](/docs/SETTINGS_SYSTEM.md). +> The settings flow and when Plugin specific settings are applied is described under the [Settings system](./SETTINGS_SYSTEM.md). Required attributes are: @@ -593,7 +593,7 @@ You can have any `"function": "my_custom_name"` custom name, however, the ones l | | - "before_config_save" - run before the config is marked as saved. Useful if your plugin needs to modify the `app.conf` file. | | `RUN_SCHD` | (required if you include "schedule" in the above `RUN` function) Cron-like scheduling is used if the `RUN` setting is set to `schedule`. | | `CMD` | (required) Specifies the command that should be executed. | -| `API_SQL` | (not implemented) Generates a `table_` + `code_name` + `.json` file as per [API docs](https://github.com/jokob-sk/NetAlertX/blob/main/docs/API.md). | +| `API_SQL` | (not implemented) Generates a `table_` + `code_name` + `.json` file as per [API docs](./API.md). | | `RUN_TIMEOUT` | (optional) Specifies the maximum execution time of the script. If not specified, a default value of 10 seconds is used to prevent hanging. | | `WATCH` | (optional) Specifies which database columns are watched for changes for this particular plugin. If not specified, no notifications are sent. | | `REPORT_ON` | (optional) Specifies when to send a notification. Supported options are: | @@ -776,8 +776,8 @@ The UI will adjust how columns are displayed in the UI based on the resolvers de } ``` -[screen1]: https://raw.githubusercontent.com/jokob-sk/NetAlertX/main/docs/img/plugins.png "Screen 1" -[screen2]: https://raw.githubusercontent.com/jokob-sk/NetAlertX/main/docs/img/plugins_settings.png "Screen 2" -[screen3]: https://raw.githubusercontent.com/jokob-sk/NetAlertX/main/docs/img/plugins_json_settings.png "Screen 3" -[screen4]: https://raw.githubusercontent.com/jokob-sk/NetAlertX/main/docs/img/plugins_json_ui.png "Screen 4" -[screen5]: https://raw.githubusercontent.com/jokob-sk/NetAlertX/main/docs/img/plugins_device_details.png "Screen 5" +[screen1]: https://raw.githubusercontent.com/jokob-sk/NetAlertX/main./img/plugins.png "Screen 1" +[screen2]: https://raw.githubusercontent.com/jokob-sk/NetAlertX/main./img/plugins_settings.png "Screen 2" +[screen3]: https://raw.githubusercontent.com/jokob-sk/NetAlertX/main./img/plugins_json_settings.png "Screen 3" +[screen4]: https://raw.githubusercontent.com/jokob-sk/NetAlertX/main./img/plugins_json_ui.png "Screen 4" +[screen5]: https://raw.githubusercontent.com/jokob-sk/NetAlertX/main./img/plugins_device_details.png "Screen 5" diff --git a/docs/RANDOM_MAC.md b/docs/RANDOM_MAC.md index 66412698..959649f4 100755 --- a/docs/RANDOM_MAC.md +++ b/docs/RANDOM_MAC.md @@ -1,53 +1,32 @@ # Privacy & Random MAC's -The latest versions of some operating systems (IOS and Android) incorporate a -new & interesting functionality to improve privacy: **Random MACs**. +Some operating systems incorporate randomize MAC addresses to improve privacy. -This functionality allows you to **hide the real MAC** of the device and -**assign a random MAC** when we connect to WIFI networks. +This functionality allows you to **hide the real MAC** of the device and **assign a random MAC** when we connect to WIFI networks. -This behavior is especially useful when connecting to WIFI's that we do not -know, but it **is totally useless when connecting to our own WIFI's** or known -networks. +This behavior is especially useful when connecting to WIFI's that we do not know, but it **is totally useless when connecting to our own WIFI's** or known networks. -**I recommend disabling this operation when connecting our devices to our own -WIFI's**, in this way, NetAlertX will be able to identify the device, and it -will not identify it as a new device every so often (every time IOS or Android -decides to change the MAC). +**I recommend disabling this on-device functionality when connecting our devices to our own WIFI's**, this way, NetAlertX will be able to identify the device, and it will not identify it as a new device every so often (every time iOS or Android randomizes the MAC). **Random MACs** are recognized by the characters "2", "6", "A", or "E" as the 2nd character in the Mac address. You can disable specific prefixes to be detected as random MAC addresses by specifying the `UI_NOT_RANDOM_MAC` setting. +## Windows + +![windows](./img/RANDOM_MAC/windows_random_mac.png) + + - [How to Disable MAC Randomization on Windows](https://www.androidphonesoft.com/blog/how-to-turn-off-random-mac-address-windows-10/) + ## IOS -![ios][ios] + +![ios](./img/RANDOM_MAC/ios_random_mac.png) - [Use private Wi-Fi addresses in iOS 14](https://support.apple.com/en-us/HT211227) ## Android -![Android][Android] + +![ios](./img/RANDOM_MAC/android_random_mac.jpg) - [How to Disable MAC Randomization in Android 10](https://support.boingo.com/s/article/How-to-Disable-MAC-Randomization-in-Android-10-Android-Q) - [How do I disable random Wi-Fi MAC address on Android 10](https://support.plume.com/hc/en-gb/articles/360052070714-How-do-I-disable-random-Wi-Fi-MAC-address-on-Android-10-) - -### License - GPL 3.0 - [Read more here](../LICENSE.txt) - -### Contact - Always use the Issue tracker for the correct fork, for example: - - [jokob-sk/NetAlertX](https://github.com/jokob-sk/NetAlertX/issues). Please also follow the guidelines on: - - - βž• [Pull Request guidelines](https://github.com/jokob-sk/NetAlertX/tree/main/docs#-pull-requests-prs) - - πŸ™ [Feature request guidelines](https://github.com/jokob-sk/NetAlertX/tree/main/docs#-feature-requests) - - πŸ› [Issue guidelines](https://github.com/jokob-sk/NetAlertX/tree/main/docs#-submitting-an-issue-or-bug) - - - ***Suggestions and comments are welcome*** - - - -[ios]: https://9to5mac.com/wp-content/uploads/sites/6/2020/08/how-to-use-private-wifi-mac-address-iphone-ipad.png?resize=2048,1009 "ios" -[Android]: ./img/android_random_mac.jpg "Android" - diff --git a/docs/README.md b/docs/README.md index 0ea92771..ceef2da0 100755 --- a/docs/README.md +++ b/docs/README.md @@ -3,7 +3,7 @@
:information_source: In the app hover over settings or fields/labels or click blue in-app ❔ (question-mark) icons to get to relevant documentation pages. - ![In-app help](/docs/img/GENERAL/in-app-help.png) + ![In-app help](./img/GENERAL/in-app-help.png)
@@ -17,7 +17,7 @@ There is also an in-app Help / FAQ section that should be answering frequently a #### πŸ’» Bare-metal / On-server (Experimental/community supported πŸ§ͺ) -- [(Experimental πŸ§ͺ) On-hardware instructions](https://github.com/jokob-sk/NetAlertX/blob/main/docs/HW_INSTALL.md) +- [(Experimental πŸ§ͺ) On-hardware instructions](./HW_INSTALL.md) - Alternative bare-metal install forks: - [leiweibau's fork](https://github.com/leiweibau/Pi.Alert/) (maintained) @@ -27,58 +27,58 @@ There is also an in-app Help / FAQ section that should be answering frequently a #### πŸ“₯ Initial Setup -- [Synology Guide](/docs/SYNOLOGY_GUIDE.md) -- [Subnets and VLANs configuration for arp-scan](/docs/SUBNETS.md) -- [Scanning Remote Networks](/docs/REMOTE_NETWORKS.md) -- [SMTP server config](/docs/SMTP.md) -- [Custom Icon configuration and support](/docs/ICONS.md) -- [Notifications](/docs/NOTIFICATIONS.md) -- [Better name resolution with Reverse DNS](/docs/REVERSE_DNS.md) -- [Network treemap configuration](/docs/NETWORK_TREE.md) -- [Backups](/docs/BACKUPS.md) +- [Synology Guide](./SYNOLOGY_GUIDE.md) +- [Subnets and VLANs configuration for arp-scan](./SUBNETS.md) +- [Scanning Remote Networks](./REMOTE_NETWORKS.md) +- [SMTP server config](./SMTP.md) +- [Custom Icon configuration and support](./ICONS.md) +- [Notifications](./NOTIFICATIONS.md) +- [Better name resolution with Reverse DNS](./REVERSE_DNS.md) +- [Network treemap configuration](./NETWORK_TREE.md) +- [Backups](./BACKUPS.md) - [Plugins overview](/front/plugins/README.md) #### πŸ› Debugging help & tips -- [Debugging tips](/docs/DEBUG_TIPS.md) -- [Debugging UI not showing](/docs/WEB_UI_PORT_DEBUG.md) -- [Invalid JSON errors debug help](/docs/DEBUG_INVALID_JSON.md) -- [Troubleshooting Plugins](/docs/DEBUG_PLUGINS.md) -- [File Permissions](/docs/FILE_PERMISSIONS.md) -- [Performance tips](/docs/PERFORMANCE.md) +- [Debugging tips](./DEBUG_TIPS.md) +- [Debugging UI not showing](./WEB_UI_PORT_DEBUG.md) +- [Invalid JSON errors debug help](./DEBUG_INVALID_JSON.md) +- [Troubleshooting Plugins](./DEBUG_PLUGINS.md) +- [File Permissions](./FILE_PERMISSIONS.md) +- [Performance tips](./PERFORMANCE.md) #### πŸ” Popular/Suggested -- [Home Assistant](/docs/HOME_ASSISTANT.md) -- [Bulk edit devices](/docs/DEVICES_BULK_EDITING.md) +- [Home Assistant](./HOME_ASSISTANT.md) +- [Bulk edit devices](./DEVICES_BULK_EDITING.md) #### βš™ System Management -- [Manage devices (legacy docs)](/docs/DEVICE_MANAGEMENT.md) -- [Random MAC/MAC icon meaning (legacy docs)](/docs/RANDOM_MAC.md) +- [Manage devices (legacy docs)](./DEVICE_MANAGEMENT.md) +- [Random MAC/MAC icon meaning (legacy docs)](./RANDOM_MAC.md) #### πŸ”Ž Examples -- [N8N webhook example](/docs/WEBHOOK_N8N.md) +- [N8N webhook example](./WEBHOOK_N8N.md) #### β™» Misc -- [Version history (legacy)](/docs/VERSIONS_HISTORY.md) -- [Reverse proxy (Nginx, Apache, SWAG)](/docs/REVERSE_PROXY.md) -- [Installing Updates](/docs/UPDATES.md) -- [Setting up Authelia](/docs/AUTHELIA.md) (DRAFT) +- [Version history (legacy)](./VERSIONS_HISTORY.md) +- [Reverse proxy (Nginx, Apache, SWAG)](./REVERSE_PROXY.md) +- [Installing Updates](./UPDATES.md) +- [Setting up Authelia](./AUTHELIA.md) (DRAFT) #### πŸ‘©β€πŸ’»For DevelopersπŸ‘¨β€πŸ’» -- [Setting up your DEV environment](/docs/DEV_ENV_SETUP.md) +- [Setting up your DEV environment](./DEV_ENV_SETUP.md) - [Server APP code structure](/server/README.md) -- [Database structure](/docs/DATABASE.md) -- [API endpoints details](/docs/API.md) -- [Plugin development guide](/docs/PLUGINS_DEV.md) -- [Settings system](/docs/SETTINGS_SYSTEM.md) -- [New Version notifications](/docs/VERSIONS.md) -- [Frontend development tips](/docs/FRONTEND_DEVELOPMENT.md) -- [Webhook secrets](/docs/WEBHOOK_SECRET.md) +- [Database structure](./DATABASE.md) +- [API endpoints details](./API.md) +- [Plugin development guide](./PLUGINS_DEV.md) +- [Settings system](./SETTINGS_SYSTEM.md) +- [New Version notifications](./VERSIONS.md) +- [Frontend development tips](./FRONTEND_DEVELOPMENT.md) +- [Webhook secrets](./WEBHOOK_SECRET.md) Feel free to suggest or submit new docs via a PR. @@ -137,8 +137,8 @@ Some additional context: Before submitting a new issue please spend a couple of minutes on research: -* Check [πŸ›‘ Common issues](https://github.com/jokob-sk/NetAlertX/blob/main/docs/DEBUG_TIPS.md#common-issues) +* Check [πŸ›‘ Common issues](./DEBUG_TIPS.md#common-issues) * Check [πŸ’‘ Closed issues](https://github.com/jokob-sk/NetAlertX/issues?q=is%3Aissue+is%3Aclosed) if a similar issue was solved in the past. -* When submitting an issue ❗[enable debug](https://github.com/jokob-sk/NetAlertX/blob/main/docs/DEBUG_TIPS.md)❗ +* When submitting an issue ❗[enable debug](./DEBUG_TIPS.md)❗ ⚠ Please follow the pre-defined issue template to resolve your issue faster. diff --git a/docs/REMOTE_NETWORKS.md b/docs/REMOTE_NETWORKS.md index 3a21ed14..9b29b1cc 100755 --- a/docs/REMOTE_NETWORKS.md +++ b/docs/REMOTE_NETWORKS.md @@ -2,7 +2,7 @@ By design, local network scanners such as `arp-scan` use ARP (Address Resolution Protocol) to map IP addresses to MAC addresses on the local network. Since ARP operates at Layer 2 (Data Link Layer), it typically works only within a single broadcast domain, usually limited to a single router or network segment. -To scan multiple locally accessible network segments, add them as subnets according to the [subnets](https://github.com/jokob-sk/NetAlertX/blob/main/docs/SUBNETS.md) documentation. +To scan multiple locally accessible network segments, add them as subnets according to the [subnets](./SUBNETS.md) documentation. ## Complex Use Cases @@ -38,7 +38,7 @@ If you have servers in different networks, you can set up separate NetAlertX ins If you don't need to discover new devices and only need to report on their status (`online`, `offline`, `down`), you can manually enter devices and check their status using the [`ICMP` plugin](https://github.com/jokob-sk/NetAlertX/blob/main/front/plugins/icmp_scan/), which uses the `ping` command internally. -For more information on how to add devices manually (or dummy devices), refer to the [Device Management](https://github.com/jokob-sk/NetAlertX/blob/main/docs/DEVICE_MANAGEMENT.md) documentation. +For more information on how to add devices manually (or dummy devices), refer to the [Device Management](./DEVICE_MANAGEMENT.md) documentation. To create truly dummy devices, you can use a loopback IP address (e.g., `0.0.0.0` or `127.0.0.1`) so they appear online. diff --git a/docs/SESSION_INFO.md b/docs/SESSION_INFO.md index 6d9a37ab..757a9746 100755 --- a/docs/SESSION_INFO.md +++ b/docs/SESSION_INFO.md @@ -2,7 +2,7 @@ The **Sessions Section** provides details about a device's connection history. This data is automatically detected and cannot be edited by the user. - ![Session info](/docs/img/SESSION_INFO/DeviceDetails_SessionInfo.png) + ![Session info](./img/SESSION_INFO/DeviceDetails_SessionInfo.png) --- @@ -57,6 +57,6 @@ When a new connection is detected, the system creates a session record: The session information is then used to display the device presence under **Monitoring** -> **Presence**. -![Monitoring Device Presence](/docs/img/SESSION_INFO/Monitoring_Presence.png) +![Monitoring Device Presence](./img/SESSION_INFO/Monitoring_Presence.png) diff --git a/docs/SETTINGS_SYSTEM.md b/docs/SETTINGS_SYSTEM.md index 128642b8..5c4362b0 100755 --- a/docs/SETTINGS_SYSTEM.md +++ b/docs/SETTINGS_SYSTEM.md @@ -10,11 +10,11 @@ The source of truth for user-defined values is the `app.conf` file. Editing the #### Settings database table -The `Settings` database table contains settings for App run purposes. The table is recreated every time the App restarts. The settings are loaded from the source-of-truth, that is the `app.conf` file. A high-level overview on the database structure can be found in the [database documentation](/docs/DATABASE.md). +The `Settings` database table contains settings for App run purposes. The table is recreated every time the App restarts. The settings are loaded from the source-of-truth, that is the `app.conf` file. A high-level overview on the database structure can be found in the [database documentation](./DATABASE.md). #### table_settings.json -This is the [API endpoint](/docs/API.md) that reflects the state of the `Settings` database table. Settings can be accessed with the: +This is the [API endpoint](./API.md) that reflects the state of the `Settings` database table. Settings can be accessed with the: * `getSetting(key)` JavaScript method @@ -74,4 +74,4 @@ Here's a high-level description of the code: _____________________ -[screen1]: https://raw.githubusercontent.com/jokob-sk/NetAlertX/main/docs/img/plugins_json_settings.png "Screen 1" \ No newline at end of file +[screen1]: https://raw.githubusercontent.com/jokob-sk/NetAlertX/main./img/plugins_json_settings.png "Screen 1" \ No newline at end of file diff --git a/docs/SUBNETS.md b/docs/SUBNETS.md index bedc0e95..9890ef51 100755 --- a/docs/SUBNETS.md +++ b/docs/SUBNETS.md @@ -8,17 +8,17 @@ You need to specify the network interface and the network mask. You can also con In this example, `--interface=eth0 192.168.1.0/24` represents a neighboring subnet. If this command returns no results, the network is not accessible due to your network or firewall restrictions. -If direct scans are not possible (Wi-Fi Extenders, VPNs and inaccessible networks), check the [remote networks documentation](https://github.com/jokob-sk/NetAlertX/blob/main/docs/REMOTE_NETWORKS.md). +If direct scans are not possible (Wi-Fi Extenders, VPNs and inaccessible networks), check the [remote networks documentation](./REMOTE_NETWORKS.md). > [!TIP] > You may need to increase the time between scans `ARPSCAN_RUN_SCHD` and the timeout `ARPSCAN_RUN_TIMEOUT` (and similar settings for related plugins) when adding more subnets. If the timeout setting is exceeded, the scan is canceled to prevent the application from hanging due to rogue plugins. -> Check [debugging plugins](/docs/DEBUG_PLUGINS.md) for more tips. +> Check [debugging plugins](./DEBUG_PLUGINS.md) for more tips. ## Example Values > [!NOTE] > Please use the UI to configure settings as it ensures the config file is in the correct format. Edit `app.conf` directly only when really necessary. -> ![Settings location](/docs/img/SUBNETS/subnets-setting-location.png) +> ![Settings location](./img/SUBNETS/subnets-setting-location.png) * **Examples for one and two subnets:** * One subnet: `SCAN_SUBNETS = ['192.168.1.0/24 --interface=eth0']` @@ -47,7 +47,7 @@ Specify the network filter, which **significantly** speeds up the scan process. The adapter will probably be `eth0` or `eth1`. (Check `System Info` > `Network Hardware`, or run `iwconfig` in the container to find your interface name(s)). -![Network hardware](/docs/img/SUBNETS/system_info-network_hardware.png) +![Network hardware](./img/SUBNETS/system_info-network_hardware.png) > [!TIP] > As an alternative to `iwconfig`, run `ip -o link show | awk -F': ' '!/lo|vir|docker/ {print $2}'` in your container to find your interface name(s) (e.g.: `eth0`, `eth1`): diff --git a/docs/SYNOLOGY_GUIDE.md b/docs/SYNOLOGY_GUIDE.md index d53bffda..e772a16d 100755 --- a/docs/SYNOLOGY_GUIDE.md +++ b/docs/SYNOLOGY_GUIDE.md @@ -9,18 +9,18 @@ The folders you are creating below will contain the configuration and the databa 1. Create a parent folder named `netalertx` 2. Create a `db` sub-folder -![Folder structure](/docs/img/SYNOLOGY/01_Create_folder_structure.png) -![Folder structure](/docs/img/SYNOLOGY/02_Create_folder_structure_db.png) -![Folder structure](/docs/img/SYNOLOGY/03_Create_folder_structure_db.png) +![Folder structure](./img/SYNOLOGY/01_Create_folder_structure.png) +![Folder structure](./img/SYNOLOGY/02_Create_folder_structure_db.png) +![Folder structure](./img/SYNOLOGY/03_Create_folder_structure_db.png) 3. Create a `config` sub-folder -![Folder structure](/docs/img/SYNOLOGY/04_Create_folder_structure_config.png) +![Folder structure](./img/SYNOLOGY/04_Create_folder_structure_config.png) 4. Note down the folders Locations: -![Getting the location](/docs/img/SYNOLOGY/05_Access_folder_properties.png) -![Getting the location](/docs/img/SYNOLOGY/06_Note_location.png) +![Getting the location](./img/SYNOLOGY/05_Access_folder_properties.png) +![Getting the location](./img/SYNOLOGY/06_Note_location.png) 5. Open **Container manager** -> **Project** and click **Create**. 6. Fill in the details: @@ -49,7 +49,7 @@ services: - PORT=20211 ``` -![Project settings](/docs/img/SYNOLOGY/07_Create_project.png) +![Project settings](./img/SYNOLOGY/07_Create_project.png) 7. Replace the paths to your volume and/or comment out unnecessary line(s): @@ -63,12 +63,12 @@ services: # - local/path/logs:/app/log <- commented out with # ⚠ ``` -![Adjusting docker-compose](/docs/img/SYNOLOGY/08_Adjust_docker_compose_volumes.png) +![Adjusting docker-compose](./img/SYNOLOGY/08_Adjust_docker_compose_volumes.png) 8. (optional) Change the port number from `20211` to an unused port if this port is already used. 9. Build the project: -![Build](/docs/img/SYNOLOGY/09_Run_and_build.png) +![Build](./img/SYNOLOGY/09_Run_and_build.png) 10. Navigate to `:20211` (or your custom port). -11. Read the [Subnets](/docs/SUBNETS.md) and [Plugins](/front/plugins/README.md) docs to complete your setup. \ No newline at end of file +11. Read the [Subnets](./SUBNETS.md) and [Plugins](/front/plugins/README.md) docs to complete your setup. \ No newline at end of file diff --git a/docs/VERSIONS.md b/docs/VERSIONS.md index 12185523..02978fbf 100755 --- a/docs/VERSIONS.md +++ b/docs/VERSIONS.md @@ -8,17 +8,17 @@ If you are not on the latest version, the app will notify you, that a new releas If any notification occurs and an email is sent, the email will contain a note that a new version is available. See the sample email below: -![Sample email if a new version is available](/docs/img/VERSIONS/new-version-available-email.png) +![Sample email if a new version is available](./img/VERSIONS/new-version-available-email.png) ### πŸ†• In the UI In the UI via a notification Icon and via a custom message in the Maintenance section. -![UI screenshot if a new version is available](/docs/img/VERSIONS/new-version-available-maintenance.png) +![UI screenshot if a new version is available](./img/VERSIONS/new-version-available-maintenance.png) For a comparison, this is how the UI looks like if you are on the latest stable image: -![UI screenshot if on latest version](/docs/img/VERSIONS/latest-version-maintenance.png) +![UI screenshot if on latest version](./img/VERSIONS/latest-version-maintenance.png) ## Implementation details diff --git a/docs/WEBHOOK_N8N.md b/docs/WEBHOOK_N8N.md index fc941682..5d04be0e 100755 --- a/docs/WEBHOOK_N8N.md +++ b/docs/WEBHOOK_N8N.md @@ -2,11 +2,11 @@ N8N can be used for more advanced conditional notification use cases. For example, you want only to get notified if two out of a specified list of devices is down. Or you can use other plugins to process the notifiations further. The below is a simple example of sending an email on a webhook. -![n8n workflow](/docs/img/WEBHOOK_N8N/n8n_workflow.png) +![n8n workflow](./img/WEBHOOK_N8N/n8n_workflow.png) ### Specify your email template See [sample JSON](https://github.com/jokob-sk/NetAlertX/blob/main/front/report_templates/webhook_json_sample.json) if you want to see the JSON paths used in the email template below -![Email template](/docs/img/WEBHOOK_N8N/n8n_send_email_settings.png) +![Email template](./img/WEBHOOK_N8N/n8n_send_email_settings.png) ``` Events count: {{ $json["body"]["attachments"][0]["text"]["events"].length }} @@ -14,7 +14,7 @@ New devices count: {{ $json["body"]["attachments"][0]["text"]["new_devices"].len ``` ### Get your webhook in n8n -![n8n webhook URL](/docs/img/WEBHOOK_N8N/n8n_webhook_settings.png) +![n8n webhook URL](./img/WEBHOOK_N8N/n8n_webhook_settings.png) ### Configure NetAlertX to point to the above URL -![NetAlertX config](/docs/img/WEBHOOK_N8N/Webhook_settings.png) +![NetAlertX config](./img/WEBHOOK_N8N/Webhook_settings.png) diff --git a/docs/WEB_UI_PORT_DEBUG.md b/docs/WEB_UI_PORT_DEBUG.md index 0b95b920..36b6af59 100755 --- a/docs/WEB_UI_PORT_DEBUG.md +++ b/docs/WEB_UI_PORT_DEBUG.md @@ -5,7 +5,7 @@ When opening an issue please: 1. Include a screenshot of what you see when accessing `HTTP:///20211` (or your custom port) -1. [Follow steps 1, 2, 3, 4 on this page](https://github.com/jokob-sk/NetAlertX/blob/main/docs/DEBUG_TIPS.md) +1. [Follow steps 1, 2, 3, 4 on this page](./DEBUG_TIPS.md) 1. Execute the following in the container to see the processes and their ports and submit a screenshot of the result: 1. `sudo apk add lsof` 1. `sudo lsof -i` @@ -13,7 +13,7 @@ When opening an issue please: 1. if you get `nginx: [emerg] bind() to 0.0.0.0:20211 failed (98: Address in use)` try using a different port number -![lsof ports](/docs/img/WEB_UI_PORT_DEBUG/container_port.png) +![lsof ports](./img/WEB_UI_PORT_DEBUG/container_port.png) ## 2. JavaScript issues @@ -48,4 +48,4 @@ In the container execute: > [!TIP] > You can try to start the container without mapping the `/app/config` and `/app/db` dirs and if the UI shows up then the issue is most likely related to your file system permissions or file ownership. -Please read the [Permissions troubleshooting guide](/docs/FILE_PERMISSIONS.md) and provide a screesnhot of the permissions and ownership in the `/app/db` and `app/config` directories. \ No newline at end of file +Please read the [Permissions troubleshooting guide](./FILE_PERMISSIONS.md) and provide a screesnhot of the permissions and ownership in the `/app/db` and `app/config` directories. \ No newline at end of file diff --git a/docs/img/android_random_mac.jpg b/docs/img/RANDOM_MAC/android_random_mac.jpg similarity index 100% rename from docs/img/android_random_mac.jpg rename to docs/img/RANDOM_MAC/android_random_mac.jpg diff --git a/docs/img/RANDOM_MAC/ios_random_mac.png b/docs/img/RANDOM_MAC/ios_random_mac.png new file mode 100755 index 00000000..41e1a5e2 Binary files /dev/null and b/docs/img/RANDOM_MAC/ios_random_mac.png differ diff --git a/docs/img/RANDOM_MAC/windows_random_mac.png b/docs/img/RANDOM_MAC/windows_random_mac.png new file mode 100755 index 00000000..8ef309bc Binary files /dev/null and b/docs/img/RANDOM_MAC/windows_random_mac.png differ diff --git a/docs/index.md b/docs/index.md index b3d1843d..b6cd9dea 100755 --- a/docs/index.md +++ b/docs/index.md @@ -8,33 +8,24 @@ --- -## πŸ“š Table of Contents +## Installation -{% include "_toc.md" %} +### Docker (Fully Supported) ---- - -## πŸ“₯ Installation - -### 🐳 Docker (Fully Supported) -The recommended installation method is via Docker. -πŸ‘‰ [Follow the official installation guide](https://github.com/jokob-sk/NetAlertX/blob/main/dockerfiles/README.md). - -### πŸ’» Bare-Metal / On-Server (Experimental - looking ofr maintainers) -- πŸ§ͺ [(Experimental) On-hardware installation](https://github.com/jokob-sk/NetAlertX/blob/main/docs/HW_INSTALL.md) -- Alternative bare-metal forks: - - βœ… [leiweibau's fork](https://github.com/leiweibau/Pi.Alert/) (maintained) - - ❌ [pucherot's original code](https://github.com/pucherot/Pi.Alert/) (unmaintained) +- [Follow the official installation guide](https://github.com/jokob-sk/NetAlertX/blob/main/dockerfiles/README.md). +### Bare-Metal +- πŸ§ͺ [(Experimental) On-hardware installation](./HW_INSTALL.md) (looking for maintainers) --- ## Help and Support Before opening an issue: -- πŸ” [Check common issues](https://github.com/jokob-sk/NetAlertX/blob/main/docs/DEBUG_TIPS.md#common-issues). + +- πŸ” [Check common issues](./DEBUG_TIPS.md#common-issues). - πŸ“Œ [Look at closed issues](https://github.com/jokob-sk/NetAlertX/issues?q=is%3Aissue+is%3Aclosed). -- ⚠ **Enable debugging** before reporting: [Debug Guide](https://github.com/jokob-sk/NetAlertX/blob/main/docs/DEBUG_TIPS.md). +- ⚠ **Enable debugging** before reporting: [Debug Guide](./DEBUG_TIPS.md). ❗ **Follow the issue template** for faster resolution. diff --git a/mkdocs.yml b/mkdocs.yml index 96a4974b..6a3082dd 100755 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -1,16 +1,23 @@ site_name: NetAlertX Docs site_url: https://jokob-sk.github.io/NetAlertX/ +repo_url: https://github.com/jokob-sk/NetAlertX/ +edit_uri: blob/main/docs/ +static_dir: docs/img nav: - Home: index.md - - Installation: - - Installation: HW_INSTALL.md - - Migration Guide: MIGRATION.md + - Installation: + - Installation options: INSTALLATION.md + - Docker Guide: https://github.com/jokob-sk/NetAlertX/blob/main/dockerfiles/README.md - Docker Compose: DOCKER_COMPOSE.md - Docker File Permissions: FILE_PERMISSIONS.md - Synology Guide: SYNOLOGY_GUIDE.md - Community Guides: COMMUNITY_GUIDES.md + - Bare-metal (Experimental): HW_INSTALL.md + - Migration Guide: MIGRATION.md + - Common issues: COMMON_ISSUES.md - Setup: - Subnets: SUBNETS.md + - Common issues: COMMON_ISSUES.md - Remote Networks: REMOTE_NETWORKS.md - Notifications Guide: NOTIFICATIONS.md - Emails: SMTP.md @@ -38,11 +45,65 @@ nav: - Debugging Web UI Port: WEB_UI_PORT_DEBUG.md - Development: - Environment Setup: DEV_ENV_SETUP.md + - Custom Plugins: PLUGINS_DEV.md - Frontend Development: FRONTEND_DEVELOPMENT.md - - Development: PLUGINS_DEV.md - Webhook Secret: WEBHOOK_SECRET.md - API: API.md - Database: DATABASE.md - Settings: SETTINGS_SYSTEM.md - Updates: UPDATES.md - - Versions: VERSIONS.md \ No newline at end of file + - Versions: VERSIONS.md + + +theme: + name: material + features: + - announce.dismiss + - content.action.edit + - content.action.view + - content.code.annotate + - content.code.copy + # - content.code.select + # - content.footnote.tooltips + # - content.tabs.link + - content.tooltips + # - header.autohide + # - navigation.expand + - navigation.footer + - navigation.indexes + # - navigation.instant + # - navigation.instant.prefetch + # - navigation.instant.progress + # - navigation.prune + - navigation.sections + - navigation.tabs + # - navigation.tabs.sticky + - navigation.top + - navigation.tracking + - search.highlight + - search.share + - search.suggest + - toc.follow + # - toc.integrate + palette: + - scheme: slate # Default to dark mode + primary: indigo # Dark blue + accent: deep-purple # Adjust accent color if needed + toggle: + icon: material/lightbulb + name: Switch to light mode + - scheme: default # Light mode (optional) + primary: black + accent: deep-purple + toggle: + icon: material/lightbulb-outline + name: Switch to dark mode +markdown_extensions: + - admonition +plugins: + - gh-admonitions + - search +font: + text: Roboto + code: Roboto Mono + favicon: https://raw.githubusercontent.com/jokob-sk/NetAlertX/main/front/img/NetAlertX_logo.png