feat: add deployment workflows for web, Android, Docker, macOS, and Linux

2026-03-30 22:00:36 -04:00
parent f5e69fa9cd
commit ab17324f85
13 changed files with 971 additions and 0 deletions
@@ -0,0 +1,189 @@
+# Web Deployment Guide
+
+This guide covers deploying Dibby Wemo Manager as a web service using Docker containers.
+
+## Quick Start
+
+### Using Docker Compose (Recommended)
+
+1. **Build and deploy with one command:**
+   ```bash
+   # Linux/macOS
+   ./scripts/web-deploy.sh
+   
+   # Windows
+   powershell -ExecutionPolicy Bypass -File scripts/web-deploy.ps1
+   ```
+
+2. **Or manually:**
+   ```bash
+   # Build the Docker image
+   docker build -t reg.dev.nervesocket.com/dibbly:latest .
+   
+   # Start with Docker Compose
+   docker-compose -f web-compose.yml up -d
+   ```
+
+3. **Access the web interface:**
+   - Local: http://localhost:3456
+   - Mobile: http://YOUR_IP:3456
+
+## Configuration
+
+### Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `DATA_DIR` | `/data` | Persistent data directory for device configs and rules |
+| `PORT` | `3456` | HTTP port for the web interface |
+
+### Docker Compose Options
+
+The `web-compose.yml` includes several production-ready features:
+
+- **Persistent Data**: Uses Docker volumes to store device configurations and rules
+- **Health Checks**: Automatic monitoring of service health
+- **Restart Policy**: Automatically restarts if the service crashes
+- **Network Isolation**: Runs in a dedicated Docker network
+
+### Networking Considerations
+
+#### Wemo Device Discovery
+
+Wemo devices use SSDP (Simple Service Discovery Protocol) which requires special networking:
+
+- **Linux**: Use `network_mode: host` for automatic device discovery
+- **macOS/Windows**: Host networking isn't supported - add devices manually via the web UI
+
+To enable host networking on Linux, uncomment this line in `web-compose.yml`:
+```yaml
+network_mode: host
+```
+
+#### Port Configuration
+
+The service runs on port 3456 by default. To change it:
+
+1. Update the port mapping in `web-compose.yml`
+2. Set the `PORT` environment variable
+3. Restart the service
+
+## Management
+
+### View Logs
+```bash
+docker-compose -f web-compose.yml logs -f
+```
+
+### Stop Service
+```bash
+docker-compose -f web-compose.yml down
+```
+
+### Update Service
+```bash
+# Pull latest image and restart
+docker-compose -f web-compose.yml pull
+docker-compose -f web-compose.yml up -d
+```
+
+### Backup Data
+```bash
+# Backup persistent data
+docker run --rm -v dibbly-data:/data -v $(pwd):/backup alpine tar czf /backup/dibbly-backup.tar.gz -C /data .
+
+# Restore data
+docker run --rm -v dibbly-data:/data -v $(pwd):/backup alpine tar xzf /backup/dibbly-backup.tar.gz -C /data
+```
+
+## Web Interface Features
+
+The web interface provides full parity with the desktop application:
+
+- **Device Management**: Discover, add, and control Wemo devices
+- **Scheduling**: Create and manage device schedules
+- **Real-time Updates**: WebSocket-based live status updates
+- **Mobile Optimized**: Responsive design for phones and tablets
+- **Dark Mode**: Automatic theme detection
+
+### API Endpoints
+
+The service exposes a REST API for integration:
+
+- `GET /api/devices` - List all devices
+- `POST /api/devices/discover` - Discover new devices
+- `GET/POST /api/devices/{host}/{port}/state` - Control device state
+- `GET/POST/PUT/DELETE /api/dwm-rules` - Manage scheduling rules
+- `GET /api/scheduler/status` - Get scheduler status
+
+## Troubleshooting
+
+### Common Issues
+
+1. **Devices not discovered automatically**
+   - On macOS/Windows, add devices manually via the web UI
+   - On Linux, ensure host networking is enabled
+
+2. **Service not accessible**
+   - Check if port 3456 is available
+   - Verify Docker is running
+   - Check firewall settings
+
+3. **Data persistence issues**
+   - Ensure the Docker volume `dibbly-data` exists
+   - Check permissions on the data directory
+
+### Health Checks
+
+The service includes built-in health checks. Monitor status:
+```bash
+docker-compose -f web-compose.yml ps
+```
+
+### Performance
+
+For optimal performance:
+- Use host networking on Linux for faster device discovery
+- Ensure adequate disk space for data persistence
+- Monitor memory usage with multiple devices
+
+## Security
+
+### Network Security
+
+- The service binds to `0.0.0.0` by default
+- Consider using a reverse proxy (nginx/traefik) for production
+- Implement authentication if exposing to the internet
+
+### Data Protection
+
+- Device configurations are stored in `/data`
+- Regular backups are recommended
+- Consider encrypting the data volume in production
+
+## Production Deployment
+
+For production environments, consider:
+
+1. **Reverse Proxy**: Use nginx or Traefik for SSL termination
+2. **Authentication**: Add authentication layer
+3. **Monitoring**: Implement proper logging and monitoring
+4. **Backups**: Automated backup strategy
+5. **High Availability**: Multiple instances with load balancing
+
+Example nginx configuration:
+```nginx
+server {
+    listen 443 ssl;
+    server_name your-domain.com;
+    
+    ssl_certificate /path/to/cert.pem;
+    ssl_certificate_key /path/to/key.pem;
+    
+    location / {
+        proxy_pass http://localhost:3456;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+    }
+}
+```