4.9 KiB
Executable File
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
Popular/Suggested
- Debugging tips
- API endpoints details
- Plugin system details and how to develop your own
- Network tree map 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
Misc
- New Version notifications
- Version history (legacy)
- Invalid JSON errors debug help
- Database structure
- Reverse proxy with SWAG
Feel free to suggest or submit new docs via a PR.
👨💻 Development priorities
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
- UI improvements
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 expressions support across settings for validation makes more sense than validating one setting with a specific expression.
UI specific requests are 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:
- Check that your changes are backward compatible with existing installations and with a blank setup.
- Existing features should always be preserved.
- Keep the PR small, on-topic and don't change code that is not necessary for the PR to work
- New features code should ideally be re-usable for different purposes, not be for a very narrow use-case.
- 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.conffile - Currently temporary (session?) settings are stored in the
ParametersDB table as key-value pairs. This table is wiped during a container rebuild/restart and it's values 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.