diff --git a/.github/workflows/publish-docs.yml b/.github/workflows/publish-docs.yml new file mode 100644 index 0000000..c07f300 --- /dev/null +++ b/.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 \ No newline at end of file diff --git a/docs/changelog.md b/docs/changelog.md new file mode 100644 index 0000000..c0b424b --- /dev/null +++ b/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! 🎉 \ No newline at end of file diff --git a/docs/config.md b/docs/config.md new file mode 100644 index 0000000..e0a4cab --- /dev/null +++ b/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:// +``` + +### 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: +``` \ No newline at end of file diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..b44b82c --- /dev/null +++ b/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: + +## 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! 😊 + + \ No newline at end of file diff --git a/docs/install.md b/docs/install.md new file mode 100644 index 0000000..6c47959 --- /dev/null +++ b/docs/install.md @@ -0,0 +1,47 @@ +# Install / Setup + +Both methods below will require a [configuration](config.md) file to be provided. A template can be found [here](config.md#sample-config) + +## Docker (Recommended) + +A Docker image is built with every release. Those images can be found [here](https://github.com/0x2142/frigate-notify/pkgs/container/frigate-notify). + +The app can be run as a container with the bundled [docker-compose.yml](https://github.com/0x2142/frigate-notify/blob/main/docker-compose.yml) file: + +```yaml +version: "3.0" +services: + frigate-notify: + image: ghcr.io/0x2142/frigate-notify:latest + volumes: + - /path/to/config:/app/config + restart: unless-stopped +``` + +Update `volumes` in the compose file to the location of the `config.yml` file. By default the app will check the `/app/config` directory for this file. + +The file name & path can also be modified by specifying a path via the `FN_CONFIGFILE` environment variable. + +Or optionally, run without docker compose: + +```bash +docker run -v /path/to/config.yml:/app/config.yml ghcr.io/0x2142/frigate-notify:latest +``` + +## Local + +Binary executables are provided with every [release](https://github.com/0x2142/frigate-notify/releases). + +Download the latest version & run with: + +```bash +./frigate-notify +``` + +By default, the app will look for a config file in the same directory named `config.yml`. + +You can manually specify a config file name or location with the `-c` flag: + +```bash +./frigate-notify -c +``` \ No newline at end of file diff --git a/example-config.yml b/example-config.yml index 152750c..0201053 100644 --- a/example-config.yml +++ b/example-config.yml @@ -64,6 +64,8 @@ alerts: server: # SMTP port port: + # Whether or not the SMTP server requires TLS (Default: true) + tls: # Sending address / username user: # SMTP password for above user diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 0000000..f749fd5 --- /dev/null +++ b/mkdocs.yml @@ -0,0 +1,61 @@ +# Site Info +site_name: Frigate-Notify +site_url: https://0x2142.github.io/frigate-notify +site_author: Matt Schmitz +repo_name: 0x2142/frigate-notify +repo_url: https://github.com/0x2142/frigate-notify + +# Site Theme +theme: + name: material + palette: + - scheme: slate + toggle: + icon: material/weather-sunny + name: Switch to light mode + - scheme: default + toggle: + icon: material/weather-night + name: Switch to dark mode + icon: + repo: fontawesome/brands/github + features: + - navigation.footer + - navigation.instant + - navigation.instant.progress + - navigation.tracking + - navigation.tabs + - navigation.expand + - navigation.indexes + - navigation.top + - toc.integrate + - content.code.copy + +# Site Nav +nav: + - Home: index.md + - Install: install.md + - Config: config.md + - Changelog: changelog.md + +# Extras +extra: + social: + - icon: fontawesome/brands/mastodon + link: https://0x2142.com/@matt + - icon: fontawesome/brands/twitter + link: https://twitter.com/0x2142 + - icon: fontawesome/brands/youtube + link: https://youtube.com/@0x2142 + - icon: material/web + link: https://0x2142.com + - icon: fontawesome/brands/github + link: https://github.com/0x2142 + +# Plugins +markdown_extensions: + - admonition + - abbr + - attr_list + - pymdownx.details + - pymdownx.superfences