README.md

Important

⚠ This is a public archive and the active project has been renamed to NetAlertX and moved: jokob.sk/NetAlertX

• To differentiate from the upstream stale project
• To differentiate from other active forks
• To indicate this is not a Raspberry Pi-specific tool anymore

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

🐳 Docker (Fully supported)

• The main installation method is as a docker container - follow these instructions here.

💻 Bare-metal / On-server (Experimental/community supported 🧪)

• (Experimental 🧪) On-hardware instructions

• Alternative bare-metal install forks:

  • leiweibau's fork (maintained)
  • pucherot's original code (un-maintained)

📚 Table of contents

📥 Initial Setup

• Subnets and VLANs configuration for arp-scan
• SMTP server config
• Custom Icon configuration and support
• Better name resolution with Reverse DNS
• Network treemap configuration
• Backups

🐛 Debugging help & tips

• Debugging tips
• Debugging UI not showing
• Invalid JSON errors debug help
• Troubleshooting Plugins

🔝 Popular/Suggested

• Home Assistant
• Bulk edit devices

⚙ System Management

• Manage devices (legacy docs)
• Random MAC/MAC icon meaning (legacy docs)

🔎 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
• Frontend development tips
• Webhook secrets

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 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 Home Assistant)
• 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.