donetick-notifier/README.md

# donetick-notifier

> AI disclaimer: AI was used solely for creating this README, the Gitea pipelines, and the base of the webhook consumer.

A PowerShell-based notifier and webhook consumer for [Donetick](https://github.com/donetick/donetick) chores.

The project now has two runtime paths:

- A scheduled notifier that checks the Donetick external API for chores and sends Apprise-compatible summary notifications for overdue and due-today tasks.
- A webhook consumer that listens on port `8080`, accepts Donetick webhook payloads, and turns them into Apprise notifications.

## Features

- Fetches chores from `https://<DONETICKHOST>:<DONETICKPORT>/eapi/v1/chore`.
- Authenticates to Donetick with the `secretkey` header.
- Sends one notification for overdue chores when any exist.
- Sends one notification for chores due today when any exist.
- Accepts webhook events for `task.completed`, `task.reminder`, and `task.created`.
- Falls back to a generic notification for unknown webhook event types.
- Runs the scheduler and webhook listener together in the Docker container.
- Includes Gitea pipelines for Docker image publishing and security scanning.

## How It Runs

The container entrypoint is `main.sh`.

- `supercronic` runs `Start-DoneTickNotifier.ps1` on the schedule defined by `JOB_SCHEDULE`.
- `Start-DoneTickConsumer.ps1` runs in the foreground and listens on `http://+:8080/`.

The notifier and consumer both use `AppriseNotification.psm1` to send messages to the configured Apprise webhook.

## 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. |
| `JOB_SCHEDULE` | Yes for Docker | Cron expression used by the container scheduler, such as `0 8,17 * * *`. |
| `TZ` | No | Container timezone, such as `America/Chicago`. Recommended so notification hours match your local time. |

## Docker

The published image is `docker.io/blinkfink182/donetick-notifier`.

### Run

```sh
docker run -d \
  --name donetick-notifier \
  -p 8080:8080 \
  -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 \
  -e JOB_SCHEDULE="0 8,17 * * *" \
  -e TZ=America/Chicago \
  docker.io/blinkfink182/donetick-notifier
```

### Docker Compose

```yaml
services:
  donetick-notifier:
    container_name: donetick-notifier
    image: docker.io/blinkfink182/donetick-notifier
    ports:
      - 8080:8080
    environment:
      - DONETICKHOST=host.docker.internal
      - DONETICKPORT=8787
      - DONETICKAPIKEY=your-donetick-api-key
      - APPRISEWEBHOOKURL=https://apprise.example.com/notify/config
      - APPRISEWEBHOOKTAG=all
      - JOB_SCHEDULE=0 8,17 * * *
      - TZ=America/Chicago
```

Run it with:

```sh
docker compose up -d
```

If Donetick and Apprise are on the same Docker network, use service names instead of `host.docker.internal`.

```yaml
services:
  donetick-notifier:
    image: docker.io/blinkfink182/donetick-notifier
    ports:
      - 8080:8080
    environment:
      - DONETICKHOST=donetick
      - DONETICKPORT=8787
      - DONETICKAPIKEY=your-donetick-api-key
      - APPRISEWEBHOOKURL=http://apprise:8000/notify/config
      - APPRISEWEBHOOKTAG=all
      - JOB_SCHEDULE=0 8,17 * * *
      - TZ=America/Chicago
```

## Build Locally

```sh
docker build -t donetick-notifier .
```

```sh
docker run -d \
  --name donetick-notifier \
  -p 8080:8080 \
  -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 \
  -e JOB_SCHEDULE="0 8,17 * * *" \
  -e TZ=America/Chicago \
  donetick-notifier
```

## Run Without Docker

PowerShell 7 or newer is recommended.

Scheduled notifier:

```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
```

Webhook consumer:

```powershell
$env:APPRISEWEBHOOKURL = "https://apprise.example.com/notify/config"
$env:APPRISEWEBHOOKTAG = "all"

pwsh ./Start-DoneTickConsumer.ps1
```

The consumer listens on port `8080` by default. Stop either script with `Ctrl+C` when running interactively.

## CI/CD

This repository includes Gitea workflows for:

- Building and pushing the Docker image on manual dispatch.
- Tagging images as `latest` for `main`, as the ref name for `v*` tags, and as `test` for everything else.
- Running security checks with Gitleaks, Semgrep, and Trivy.
- Creating Gitea issues for security findings when `GITEA_TOKEN` is configured.
- Sending Apprise notifications for Docker build success or failure.

The security workflow runs on pushes, pull requests, and manual dispatch. On push, it also builds the image so Trivy can scan the resulting container.

## API References

The `Donetick/` directory contains request examples and collection metadata used to document and exercise the Donetick API while developing the notifier.