Initial README

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.