Initial README
This commit is contained in:
parent
66476a23b1
commit
8a0e14f1f6
1 changed files with 108 additions and 2 deletions
110
README.md
110
README.md
|
@ -1,3 +1,109 @@
|
|||
# caldav-email-reminders
|
||||
# CalDAV Email Reminder Service
|
||||
|
||||
a lightweight, self-hosted service that polls a CalDAV calendar and sends email reminders for upcoming events with `VALARM` email actions.
|
||||
This project provides a self-contained, Dockerized email reminder system that polls a CalDAV calendar, extracts scheduled email alarms (`VALARM` with `ACTION:EMAIL`), and delivers reminder emails based on their defined trigger times. It is designed as a workaround for CalDAV servers that either do not support email reminders or are unreliable in doing so.
|
||||
|
||||
## Features
|
||||
|
||||
- Pulls events from one or more CalDAV calendars using standard `REPORT` queries
|
||||
|
||||
- Expands recurring events using `RRULE` and supports date-only and timezone-aware events
|
||||
|
||||
- Identifies and schedules `VALARM` blocks with `ACTION:EMAIL`
|
||||
|
||||
- Sends email reminders using SMTP with support for SSL or STARTTLS
|
||||
|
||||
- Uses a lightweight SQLite database for state tracking and deduplication
|
||||
|
||||
- Configurable via `.env` and runs entirely within Docker
|
||||
|
||||
- Emits all logs to Docker stdout (`docker logs`) — no syslog or cron daemon needed
|
||||
|
||||
- Handles long-term sync and dispatch via simple background loops
|
||||
|
||||
|
||||
## How It Works
|
||||
|
||||
1. **sync.py**:
|
||||
|
||||
- Discovers calendar URLs (or uses those provided).
|
||||
|
||||
- Downloads `.ics` files for all VEVENTs.
|
||||
|
||||
- Extracts `VALARM` blocks with `ACTION:EMAIL`.
|
||||
|
||||
- Calculates trigger times based on `TRIGGER` + `DTSTART`.
|
||||
|
||||
- Stores scheduled reminders in SQLite.
|
||||
|
||||
2. **dispatch.py**:
|
||||
|
||||
- Runs periodically to find due reminders.
|
||||
|
||||
- Sends emails via SMTP.
|
||||
|
||||
- Marks each reminder as sent to prevent duplicates.
|
||||
|
||||
3. **entrypoint.sh**:
|
||||
|
||||
- Exports environment variables.
|
||||
|
||||
- Starts two background loops:
|
||||
|
||||
- Syncs calendar events every `SYNC_INTERVAL` seconds.
|
||||
|
||||
- Dispatches reminders every `DISPATCH_INTERVAL` seconds.
|
||||
|
||||
|
||||
## Requirements
|
||||
|
||||
- Docker
|
||||
|
||||
- A CalDAV server with accessible credentials
|
||||
|
||||
- SMTP credentials for an outbound mail service
|
||||
|
||||
|
||||
## Environment Variables
|
||||
|
||||
Place these in a `.env` file in the root of your project:
|
||||
|
||||
```env
|
||||
...
|
||||
```
|
||||
|
||||
## Building the Docker Image
|
||||
|
||||
```bash
|
||||
docker build -t caldav-reminder .
|
||||
```
|
||||
|
||||
## Running the Container
|
||||
|
||||
```bash
|
||||
docker run -d --rm \
|
||||
--env-file .env \
|
||||
-v caldav_reminder_db:/data \
|
||||
--name caldav-cron \
|
||||
caldav-reminder
|
||||
```
|
||||
|
||||
All output is logged to stdout and can be viewed with:
|
||||
|
||||
```bash
|
||||
docker logs -f caldav-cron
|
||||
```
|
||||
|
||||
## Notes
|
||||
|
||||
- The database stores event UIDs, last-modified timestamps, and reminder entries to avoid duplicate processing.
|
||||
|
||||
- Recurring events are expanded into individual trigger times within a sliding window.
|
||||
|
||||
- Email reminders are only sent for future occurrences not yet marked as sent.
|
||||
|
||||
- This project assumes a single recipient address (`EMAIL_TO`) for simplicity.
|
||||
|
||||
|
||||
## License
|
||||
|
||||
\[MIT License\] or other appropriate license of your choosing.
|
Loading…
Reference in a new issue