NetAlertX/docs

Documentation overview

In the app hover over settings or fields/labels or click blue in-app ❔ (question-mark) icons to get to relevant documentation pages.

There is also an in-app Help / FAQ section that should be answering frequently asked questions.

📥 Installation

⚠ Only tested as a docker container - follow these instructions here.

Check out leiweibau's fork if you want to install Pi.Alert on the server directly or original instructions for pucherot's original code

📚 Table of contents

🐛 Debugging help & tips

• Debugging tips
• Invalid JSON errors debug help

🔝 Popular/Suggested

• Network treemap configuration
• Gmail as SMTP server for sending emails
• Subnets and VLANs configuration for arp-scan
• Home Assistant

⚙ System Management

• Manage devices (legacy docs)
• Random MAC/MAC icon meaning (legacy docs)
• Custom Icons configuration and support

🔎 Examples

• N8N webhook example

♻ Misc

• Version history (legacy)
• Reverse proxy (Nginx, Apache, SWAG)

👩‍💻For Developers👨‍💻

• APP code structure
• Database structure
• API endpoints details
• Plugin system details and how to develop your own
• Settings system
• New Version notifications

Feel free to suggest or submit new docs via a PR.

👨‍💻 Development priorities

Priorities from highest to lowest:

• 🔼 Fixing core functionality bugs not solvable with workarounds
• 🔵 New core functionality unlocking other opportunities (e.g.: plugins)
• 🔵 Refactoring enabling faster implementation of future functionality
• 🔽 (low) UI functionality & improvements (PRs welcome 😉)

Design philosophy: Focus on core functionality and leverage existing apps and tools to make PiAlert integrate into other workflows.

Examples:

1. Supporting apprise makes more sense than implementing multiple individual notification gateways
2. Implementing regular expression support across settings for validation makes more sense than validating one setting with a specific expression. 

UI-specific requests are a low priority as the framework picked by the original developer is not very extensible (and afaik doesn't support components) and has limited mobile support. Also, I argue the value proposition is smaller than working on something else.

Feel free to submit PRs if interested. try to keep the PRs small/on-topic so they are easier to review and approve.

That being said, I'd reconsider if more people and or recurring sponsors file a request 😉.

🙏 Feature requests

Please be as detailed as possible with workarounds you considered and why a native feature is the better way. This gives me better context and will make it more likely to be implemented. Ideally, a feature request should be in the format "I want to be able to do XYZ so that ZYX. I considered these approaches XYZ".

➕ Pull requests (PRs)

If you submit a PR please:

1. Check that your changes are backward compatible with existing installations and with a blank setup.
2. Existing features should always be preserved.
3. Keep the PR small, on-topic and don't change code that is not necessary for the PR to work
4. New features code should ideally be re-usable for different purposes, not be for a very narrow use-case.
5. New functionality should ideally be implemented via the Plugins system, if possible.

Suggested test cases:

• Blank setup with no DB or config
• Existing DB / config
• Sending a notification (e. g. Delete a device and wait for a scan to run) and testing all notification gateways, especially:
• Email, Apprise (e.g. via Telegram), webhook (e.g. via Discord), MQTT (e.g. via HomeAssitant)
• Saving settings
• Test a couple of plugins
• Check the Error log for anything unusual

Some additional context:

• Permanent settings/config is stored in the pialert.conf file
• Currently temporary (session?) settings are stored in the Parameters DB table as key-value pairs. This table is wiped during a container rebuild/restart and its values are re-initialized from cookies/session data from the browser.

🐛 Submitting an issue or bug

Before submitting a new issue please spend a couple of minutes on research:

• Check 🛑 Common issues
• Check 💡 Closed issues if a similar issue was solved in the past.
• When submitting an issue ❗enable debug❗

⚠ Please follow the pre-defined issue template to resolve your issue faster.