first draft of readme

2026-05-13 13:52:05 -05:00
parent 160d180b00
commit 90a2805339
1 changed files with 134 additions and 0 deletions
@@ -1,2 +1,136 @@
 # donetick-notifier

+A small PowerShell notifier for [Donetick](https://github.com/donetick/donetick) chores.
+
+The notifier checks the Donetick external API for chores, groups tasks that are overdue or due today, and sends summary notifications through an Apprise-compatible webhook.
+
+## What it does
+
+- Fetches chores from `https://<DONETICKHOST>:<DONETICKPORT>/eapi/v1/chore`.
+- Authenticates to Donetick with the `secretkey` header.
+- Sends one Apprise notification for overdue tasks, when any exist.
+- Sends one Apprise notification for tasks due today, when any exist.
+- Runs once and exits.
+
+Because the container runs once and exits, schedule it with cron, systemd timers, Kubernetes CronJobs, Gitea Actions, or another scheduler if you want recurring notifications.
+
+## Configuration
+
+All configuration is provided through environment variables.
+
+| Variable | Required | Description |
+| --- | --- | --- |
+| `DONETICKHOST` | Yes | Donetick host name or IP address. Do not include `https://`. |
+| `DONETICKPORT` | Yes | Donetick HTTPS port. |
+| `DONETICKAPIKEY` | Yes | Donetick external API key. Sent as the `secretkey` header. |
+| `APPRISEWEBHOOKURL` | Yes | Apprise webhook URL that accepts notification posts. |
+| `APPRISEWEBHOOKTAG` | Yes | Apprise tag value to include with each notification. |
+
+## Docker
+
+The published image is:
+
+```text
+docker.io/blinkfink182/donetick-notifier
+```
+
+### Run Once
+
+```sh
+docker run --rm \
+  --name donetick-notifier \
+  -e DONETICKHOST=host.docker.internal \
+  -e DONETICKPORT=8787 \
+  -e DONETICKAPIKEY=your-donetick-api-key \
+  -e APPRISEWEBHOOKURL=https://apprise.example.com/notify/config \
+  -e APPRISEWEBHOOKTAG=all \
+  docker.io/blinkfink182/donetick-notifier:latest
+```
+
+### Docker Compose
+
+```yaml
+services:
+  donetick-notifier:
+    container_name: donetick-notifier
+    image: docker.io/blinkfink182/donetick-notifier:latest
+    environment:
+      DONETICKHOST: host.docker.internal
+      DONETICKPORT: "8787"
+      DONETICKAPIKEY: your-donetick-api-key
+      APPRISEWEBHOOKURL: https://apprise.example.com/notify/config
+      APPRISEWEBHOOKTAG: all
+```
+
+Run it with:
+
+```sh
+docker compose run --rm donetick-notifier
+```
+
+If Donetick and Apprise are running on the same Docker network, use the service names instead of `host.docker.internal`.
+
+```yaml
+services:
+  donetick-notifier:
+    image: docker.io/blinkfink182/donetick-notifier:latest
+    environment:
+      DONETICKHOST: donetick
+      DONETICKPORT: "8787"
+      DONETICKAPIKEY: your-donetick-api-key
+      APPRISEWEBHOOKURL: http://apprise:8000/notify/config
+      APPRISEWEBHOOKTAG: all
+```
+
+## Build Locally
+
+```sh
+docker build -t donetick-notifier .
+```
+
+```sh
+docker run --rm \
+  -e DONETICKHOST=host.docker.internal \
+  -e DONETICKPORT=8787 \
+  -e DONETICKAPIKEY=your-donetick-api-key \
+  -e APPRISEWEBHOOKURL=https://apprise.example.com/notify/config \
+  -e APPRISEWEBHOOKTAG=all \
+  donetick-notifier
+```
+
+## Run Without Docker
+
+PowerShell 7 or newer is recommended.
+
+```powershell
+$env:DONETICKHOST = "donetick.example.com"
+$env:DONETICKPORT = "8787"
+$env:DONETICKAPIKEY = "your-donetick-api-key"
+$env:APPRISEWEBHOOKURL = "https://apprise.example.com/notify/config"
+$env:APPRISEWEBHOOKTAG = "all"
+
+pwsh ./Start-DoneTickNotifier.ps1
+```
+
+## CI/CD
+
+This repository includes Gitea workflows for:
+
+- Building and pushing the Docker image.
+- Running security checks with Gitleaks, Semgrep, and Trivy.
+- Creating Gitea issues for security findings when configured with a `GITEA_TOKEN`.
+- Sending Apprise notifications for Docker build success or failure.
+
+The Docker build workflow tags images as:
+
+| Branch or ref | Image tag |
+| --- | --- |
+| `main` | `latest` |
+| refs beginning with `v` | matching ref name, such as `v1.0.0` |
+| all other refs | `test` |
+
+## AI Assistance Disclosure
+
+OpenAI Codex was used to help create this README and the Gitea pipeline files in this repository.
+
+All released application code is written by the repository owner.