first version

2025-03-26 03:09:49 +01:00
parent d14e7a4446
commit 95a5b893ec
6 changed files with 495 additions and 2 deletions
--- a/README.md
+++ b/README.md
@@ -1,3 +1,133 @@
-# flic-webpush-localstack
+# Flic Button Web Push Notification Service

-AWS Lambda function using LocalStack in Docker that receives HTTP requests from Flic buttons and sends WebPush notifications.
+## Overview
+This application provides a dockerized solution for handling Flic smart button events and sending web push notifications to a Progressive Web App (PWA).
+
+## Features
+- Webhook endpoint for Flic button events
+- Web Push notification support
+- Configurable button actions
+- Subscription management
+
+## Prerequisites
+- Docker
+- Docker Compose
+- Traefik network
+- Curl or Postman for testing
+
+## Setup
+
+### 1. Generate VAPID Keys
+Run the VAPID key generation script:
+```bash
+python generate_vapid_keys.py
+```
+This will create a `.env` file with VAPID keys.
+
+### 2. Configure Flic Buttons
+Edit the `.env` file to add your Flic button serial numbers:
+```
+FLIC_BUTTON1_SERIAL=your_button1_serial
+FLIC_BUTTON2_SERIAL=your_button2_serial
+FLIC_BUTTON3_SERIAL=your_button3_serial
+```
+
+### 3. Docker Compose Configuration
+```yaml
+version: '3'
+services:
+  flic-webpush:
+    build: .
+    volumes:
+      - ./subscriptions.json:/app/subscriptions.json
+    networks:
+      - traefik
+    labels:
+      - "traefik.enable=true"
+      - "traefik.http.routers.flic-webpush.rule=Host(`flic.yourdomain.com`)"
+
+networks:
+  traefik:
+    external: true
+```
+
+### 4. Endpoints
+- `/flic-webhook`: Receive Flic button events
+- `/subscribe`: Add web push subscriptions
+
+## Testing Webhooks
+
+### Simulating Flic Button Events
+You can test the webhook endpoint using curl or Postman. Here are example requests:
+
+#### Button 1 Event (Home Lights On)
+```bash
+curl -X POST http://localhost:8080/flic-webhook \
+     -H "Content-Type: application/json" \
+     -d '{
+         "serial": "your_button1_serial",
+         "event": "click",
+         "timestamp": "'$(date -u +"%Y-%m-%dT%H:%M:%SZ")'"
+     }'
+```
+
+#### Button 2 Event (Security System Arm)
+```bash
+curl -X POST http://localhost:8080/flic-webhook \
+     -H "Content-Type: application/json" \
+     -d '{
+         "serial": "your_button2_serial",
+         "event": "double_click",
+         "timestamp": "'$(date -u +"%Y-%m-%dT%H:%M:%SZ")'"
+     }'
+```
+
+#### Button 3 Event (Panic Alert)
+```bash
+curl -X POST http://localhost:8080/flic-webhook \
+     -H "Content-Type: application/json" \
+     -d '{
+         "serial": "your_button3_serial",
+         "event": "long_press",
+         "timestamp": "'$(date -u +"%Y-%m-%dT%H:%M:%SZ")'"
+     }'
+```
+
+### Adding a Web Push Subscription
+To test the subscription endpoint:
+```bash
+curl -X POST http://localhost:8080/subscribe \
+     -H "Content-Type: application/json" \
+     -d '{
+         "endpoint": "https://example.com/push-endpoint",
+         "keys": {
+             "p256dh": "base64-public-key",
+             "auth": "base64-auth-secret"
+         }
+     }'
+```
+
+### Debugging Tips
+- Check container logs: `docker logs flic-webpush`
+- Verify subscription file: `cat subscriptions.json`
+- Ensure correct button serial numbers in `.env`
+
+## Button Actions
+- Button 1: Home Lights On
+- Button 2: Security System Arm
+- Button 3: Panic Alert
+
+## Logging
+Configurable via `LOG_LEVEL` in `.env`
+
+## Security Considerations
+- Keep VAPID keys secret
+- Use HTTPS
+- Validate and sanitize all incoming webhook requests
+- Implement proper authentication for production use
+
+## Troubleshooting
+- Ensure all environment variables are correctly set
+- Check network connectivity
+- Verify Traefik configuration
+- Validate button serial numbers match between configuration and webhook