Merge pull request #21 from 0x2142/add-docs-site

Add mkdocs documentation

.github/workflows/publish-docs.yml

@@ -0,0 +1,28 @@
+name: Publish docs
+on:
+ push:
+ branches:
+ - main
+permissions:
+ contents: write
+jobs:
+ deploy:
+ runs-on: ubuntu-latest
+ steps:
+ - uses: actions/checkout@v4
+ - name: Configure Git Credentials
+ run: |
+ git config user.name github-actions[bot]
+ git config user.email 41898282+github-actions[bot]@users.noreply.github.com
+ - uses: actions/setup-python@v4
+ with:
+ python-version: 3.x
+ - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV 
+ - uses: actions/cache@v3
+ with:
+ key: mkdocs-material-${{ env.cache_id }}
+ path: .cache
+ restore-keys: |
+ mkdocs-material-
+ - run: pip install mkdocs-material 
+ - run: mkdocs gh-deploy --force

docs/changelog.md

@@ -0,0 +1,25 @@
+# Changelog
+
+## [v0.2.2](https://github.com/0x2142/frigate-notify/releases/tag/v0.2.2)
+ - Fix SMTP issue where code was ignoring `tls: false` config flag
+ - Fix issue where snapshots would only be sent to the first alerting method, if multiple were enabled 
+ - Update Debian image used for Docker image 
+
+## [v0.2.1](https://github.com/0x2142/frigate-notify/releases/tag/v0.2.1)
+ - Added Docker release build for ARM
+
+## [v0.2.0](https://github.com/0x2142/frigate-notify/releases/tag/v0.2.0)
+ - Add support for excluding cameras from alerts
+ - Added ability to set custom alert titles
+ - Added ability to set custom MQTT client ID
+ - Added ability to change MQTT port
+ - Migrate Discord alerts to use Embeds
+ - Improved SMTP & Gotify alerts to include a warning if a snapshot wasn't saved
+ - Add GitHub actions for automated release builds
+ - Added version number to startup logging
+
+## [v0.1.1](https://github.com/0x2142/frigate-notify/releases/tag/v0.1.1)
+ - Add support for MQTT authentication
+
+## [v0.1.0](https://github.com/0x2142/frigate-notify/releases/tag/v0.1.0)
+ - Initial release! 🎉

docs/config.md

@@ -0,0 +1,259 @@
+# Config
+
+This section will walk through the available configuration items.
+
+Configuration snippets will be provided throughout this page. Feel free to copy the full [Sample Config](#sample-config) at the bottom of this page to customize.
+
+## Frigate
+
+### Server
+
+- **server** (Required)
+ - IP or hostname of the Frigate NVR
+- **ignoressl** (Optional - Default: `false`)
+ - Set to `true` to allow self-signed certificates
+
+```yaml title="Config File Snippet"
+frigate:
+ server: nvr.your.domain.local
+ ignoressl: true
+```
+
+### WebAPI
+
+!!! note
+ Only one monitoring method can be configured, either `webapi` or `mqtt`. The other must be set to `enabled: false`.
+
+- **enabled** (Optional - Default: `false`)
+ - If set to `true`, Frigate events are collected by polling the web API
+- **interval** (Optional - Default: `30`)
+ - How frequently to check the Frigate web API for new events, in seconds 
+
+```yaml title="Config File Snippet"
+frigate:
+ webapi:
+ enabled: true
+ interval: 60
+```
+
+### MQTT
+
+!!! note
+ Only one monitoring method can be configured, either `webapi` or `mqtt`. The other must be set to `enabled: false`.
+
+- **enabled** (Optional - Default: `false`)
+ - If set to `true`, Frigate events are collected via an MQTT broker
+ - Note: This must be the same MQTT broker that Frigate is sending events to
+- **server** (Required)
+ - IP or hostname of the MQTT server
+ - If MQTT monitoring is enabled, this field is required
+- **port** (Optiona - Default: `1883`)
+ - MQTT service port
+- **clientid** (Optional - Default: `frigate-notify`)
+ - Client ID of this app used when connecting to MQTT
+ - Note: This must be a unique value & cannot be shared with other MQTT clients
+- **username** (Optional)
+ - MQTT username
+ - If username & password are not set, then authentication is disabled
+- **password** (Optional)
+ - MQTT password
+ - Required if `username` is set
+
+```yaml title="Config File Snippet"
+frigate:
+ mqtt: 
+ enabled: true
+ server: mqtt.your.domain.local
+ port: 1883
+ clientid: frigate-notify
+ username: mqtt-user
+ password: mqtt-pass
+```
+
+### Cameras
+
+- **exclude** (Optional)
+ - If desired, provide a list of cameras to ignore
+ - Any Frigate events on these cameras will not generate alerts
+ - If left empty, this is disabled & all cameras will generate alerts
+
+```yaml title="Config File Snippet"
+frigate:
+ cameras:
+ exclude:
+ - test_cam_01
+ - test_cam_02
+```
+
+## Alerting
+
+!!! note
+ Any combination of alerting methods may be enabled, though you'll probably want to enable at least one! 😅
+
+### General
+
+- **title** (Optional - Default: `Frigate Alert`)
+ - Title of alert messages that are generated (Email subject, etc)
+
+```yaml title="Config File Snippet"
+alerts: 
+ general:
+ title: Frigate Alert
+```
+
+### Discord
+
+- **enabled** (Optional - Default: `false`)
+ - Set to `true` to enable alerting via Discord webhooks
+- **webhook** (Required)
+ - Full URL of the desired Discord webhook to send alerts through
+ - Required if this alerting method is enabled
+ - Check [Discord's](https://support.discord.com/hc/en-us/articles/228383668-Intro-to-Webhooks) docs for how to create a webhook
+
+```yaml title="Config File Snippet"
+alerts: 
+ discord:
+ enabled: false
+ webhook: https://<your-discord-webhook-here>
+```
+
+### Gotify
+
+- **enabled** (Optional - Default: `false`)
+ - Set to `true` to enable alerting via Gotify
+- **server** (Required)
+ - IP or hostname of the target Gotify server
+ - Required if this alerting method is enabled
+- **token** (Required)
+ - App token associated with this app in Gotify
+ - Required if this alerting method is enabled
+- **ignoressl** (Optional - Default: `false`)
+ - Set to `true` to allow self-signed certificates
+
+```yaml title="Config File Snippet"
+alerts: 
+ gotify:
+ enabled: false
+ server: gotify.your.domain.local
+ token: ABCDEF
+ ignoressl: true
+```
+
+### SMTP
+
+- **enabled** (Optional - Default: `false`)
+ - Set to `true` to enable alerting via SMTP
+- **server** (Required)
+ - IP or hostname of the target SMTP server
+ - Required if this alerting method is enabled
+- **port** (Required)
+ - Port of the target SMTP server
+ - Required if this alerting method is enabled
+- **tls** (Optional - Default: `true`)
+ - Set to `false` if SMTP TLS is not required
+- **user** (Optional)
+ - Add SMTP username for authentication
+ - If username & password are not set, then authentication is disabled
+- **password** (Optional)
+ - Password of SMTP user
+ - Required if `user` is set
+- **recipient** (Required)
+ - Comma-separated list of email recipients
+ - Required if this alerting method is enabled
+
+```yaml title="Config File Snippet"
+alerts: 
+ smtp:
+ enabled: false
+ server: smtp.your.domain.local
+ port: 587
+ tls: true
+ user: test_user@your.domain.local
+ password: test_pass
+ recipient: nvr_group@your.domain.local, someone_else@your.domain.local
+```
+
+### Monitor
+
+If enabled, this application will check in with tools like [HealthChecks](https://github.com/healthchecks/healthchecks) or [Uptime Kuma](https://github.com/louislam/uptime-kuma) on a regular interval for health / status monitoring.
+
+- **enabled** (Optional - Default: `false`)
+ - Set to `true` to enable health checks
+- **url** (Required)
+ - URL path for health check service
+ - Required if monitoring is enabled
+- **interval** (Required)
+ - Frequency of check-in events
+ - Required if monitoring is enabled
+ > TODO: Set a default interval. Currently this is required to be manually specified.
+- **ignoressl** (Optional - Default: `false`)
+ - Set to `true` to allow self-signed certificates
+
+```yaml title="Config File Snippet"
+monitor:
+ enabled: false
+ url: 
+ interval: 
+ ignoressl: 
+```
+
+
+---
+
+
+## Sample Config { data-search-exclude }
+
+A full config file template has been provided below:
+
+```yaml
+frigate:
+ server: 
+ ignoressl: 
+
+ webapi:
+ enabled: 
+ interval: 
+ 
+ mqtt: 
+ enabled: 
+ server: 
+ port:
+ clientid:
+ username: 
+ password: 
+ 
+ cameras:
+ exclude:
+ - test_cam_01
+
+
+alerts: 
+ general:
+ title:
+
+ discord:
+ enabled: false
+ webhook: 
+ 
+ gotify:
+ enabled: false
+ server:
+ token: 
+ ignoressl:
+ 
+ smtp:
+ enabled: false
+ server: 
+ port: 
+ tls: 
+ user:
+ password:
+ recipient:
+
+
+monitor:
+ enabled: false
+ url: 
+ interval: 
+ ignoressl: 
+```

docs/index.md

@@ -0,0 +1,38 @@
+# Docs for Frigate-Notify
+
+Hi there, you've found the documentation site for [0x2142/frigate-notify](https://github.com/0x2142/frigate-notify). Thanks for your interest in the project! 
+
+If you get value out of this tool, please let me know by leaving a star: <a class="github-button" href="https://github.com/0x2142/frigate-notify" data-icon="octicon-star" data-show-count="true" aria-label="Star 0x2142/frigate-notify on GitHub"></a>
+
+## About the Project
+
+This project is designed to generate notifications based on [Frigate](https://github.com/blakeblackshear/frigate) NVR events.
+
+Currently Frigate only supports notifications through Home Assistant, which I'm not using right now. So I set out to build a simple notification app that would work with a standalone Frigate server.
+
+## Features 
+
+**Event Polling**
+
+- MQTT
+- Direct via Frigate API
+
+**Notification Methods**
+
+- Discord
+- Gotify
+- SMTP
+
+**Other**
+
+- Aliveness monitor via HTTP GET (for use with tools like [HealthChecks](https://github.com/healthchecks/healthchecks) or [Uptime Kuma](https://github.com/louislam/uptime-kuma))
+
+
+!!! tip
+ If you use this code & have any specific feature requests - please feel free to open an [issue](https://github.com/0x2142/frigate-notify/issues) with the details of what you would like to see added!
+
+ While this is a hobby project for me, I'll do my best to respond & update the code for anything reasonable.
+
+ Thanks again for being here! 😊
+
+<script async defer src="https://buttons.github.io/buttons.js"></script>