raphaelbleier · raphaelbleier · Nov 13, 2025 · Nov 13, 2025 · Nov 13, 2025 · Nov 13, 2025
diff --git a/CHANGELOG-v2.1.md b/CHANGELOG-v2.1.md
@@ -0,0 +1,232 @@
+# Changelog - Version 2.1.0
+
+## 🎉 Release Highlights
+
+Version 2.1.0 fixes critical Docker authentication issues and introduces Home Assistant integration mode for advanced deployment scenarios.
+
+---
+
+## 🐛 Bug Fixes
+
+### Fixed: Docker Spotify Authentication Failure
+
+**Issue**: Running SpotifyToWLED in Docker resulted in authentication error:
+```
+ERROR - ✗ Spotify authentication failed: [Errno 98] Address already in use
+```
+
+**Root Cause**: 
+- SpotifyOAuth's default behavior attempts to start a local HTTP server for OAuth callback
+- This conflicts with Flask app already running on port 5000
+- In Docker/headless environments, the browser-based auth flow is not suitable
+
+**Solution Implemented**:
+1. Added `/callback` route in Flask application to handle OAuth redirects
+2. Modified SpotifyOAuth initialization with `open_browser=False` parameter
+3. Implemented persistent token caching in `/config/.spotify_cache`
+4. Created web-based authentication flow with UI button
+5. Added API endpoints for OAuth URL generation and callback handling
+
+**Impact**: 
+- ✅ Spotify authentication now works in Docker containers
+- ✅ Tokens persist across container restarts (no re-authentication needed)
+- ✅ User-friendly authentication via web interface
+- ✅ Fully compatible with headless/server environments
+
+---
+
+## ✨ New Features
+
+### Home Assistant Integration Mode
+
+Added dual-mode support for Home Assistant addon:
+
+#### Standalone Mode (Default)
+- Runs complete SpotifyToWLED application within Home Assistant
+- Self-contained with no external dependencies
+- Original behavior preserved for existing users
+- Best for single Home Assistant instances
+
+#### Integration Mode (New)
+- Lightweight HTTP proxy to external Docker server
+- Share one SpotifyToWLED instance across multiple Home Assistant installations
+- Significantly reduced resource usage in Home Assistant
+- Centralized configuration and management
+- Perfect for multi-instance or Portainer deployments
+
+**Configuration Example**:
+```yaml
+# Standalone Mode
+mode: "standalone"
+spotify_client_id: "your_client_id"
+spotify_client_secret: "your_secret"
+wled_ips:
+  - "192.168.1.100"
+
+# Integration Mode
+mode: "integration"
+server_url: "http://192.168.1.50:5000"
+```
+
+**Benefits**:
+- 🔋 Reduced CPU/memory usage in Home Assistant
+- 🔄 Easy updates through centralized Docker management
+- 🏢 Enterprise-friendly for multiple HA instances
+- 🎯 Better separation of concerns
+
+---
+
+## 🔧 Technical Changes
+
+### Application Core
+
+**`app/utils/spotify_manager.py`**:
+- Added `cache_path` parameter to constructor
+- Implemented `get_auth_url()` method for OAuth flow initiation
+- Implemented `handle_callback()` method for OAuth code exchange
+- Set `open_browser=False` in SpotifyOAuth initialization
+- Automatic cache path resolution using config directory
+
+**`app/routes/web.py`**:
+- Added `/callback` route for Spotify OAuth redirect handling
+- Added `/api/spotify/auth-url` endpoint for authorization URL generation
+- Error handling for OAuth failures
+- Flash messages for user feedback
+
+**`app/core/sync_engine.py`**:
+- Added `get_spotify_auth_url()` method
+- Added `handle_spotify_callback()` method
+- Integration with SpotifyManager OAuth methods
+
+**`app/templates/index.html`**:
+- Added "Authenticate with Spotify" button
+- Conditional display based on authentication status
+- User-friendly messaging for auth status
+
+**`app/static/js/app.js`**:
+- Added `authenticateSpotify()` function
+- Handles auth URL fetching and redirection
+- Error display for auth failures
+
+### Home Assistant Addon
+
+**`homeassistant/spotifytowled/config.json`**:
+- Added `mode` configuration option (standalone/integration)
+- Added `server_url` for integration mode
+- Made Spotify credentials optional (not needed in integration mode)
+- Version bumped to 2.1.0
+- Updated schema for new options
+
+**`homeassistant/spotifytowled/run.sh`**:
+- Mode detection and branching logic
+- Standalone mode: runs full application (original behavior)
+- Integration mode: creates HTTP proxy using Flask
+- Proxy implementation forwards all requests to external server
+- Automatic installation of `requests` library for proxy
+
+### Documentation
+
+**`README.md`**:
+- Added v2.1 feature highlights
+- Updated setup instructions with authentication steps
+- Added Spotify redirect URI configuration
+
+**`DOCKER.md`**:
+- Added "Initial Setup and Spotify Authentication" section
+- Step-by-step authentication guide
+- Token caching explanation
+
+**`HOMEASSISTANT.md`**:
+- Complete rewrite with dual-mode documentation
+- Pros/cons comparison of each mode
+- Separate installation guides for both modes
+- Integration mode setup instructions
+
+**`homeassistant/spotifytowled/README.md`**:
+- Dual-mode feature documentation
+- Configuration examples for both modes
+- Troubleshooting for integration mode
+
+---
+
+## 🔒 Security
+
+### CodeQL Analysis: ✅ PASSED
+- **Python**: 0 vulnerabilities found
+- **JavaScript**: 0 vulnerabilities found
+
+### Security Improvements:
+- OAuth tokens stored in persistent volume (not in code)
+- Redirect URI validation through Spotify Developer Console
+- No credentials stored in container layers
+- Secure token caching mechanism
+
+---
+
+## 📦 Migration Guide
+
+### From v2.0 to v2.1
+
+**Docker Users**:
+1. Pull latest image: `docker pull ghcr.io/raphaelbleier/spotifytowled:latest`
+2. Stop container: `docker stop spotifytowled`
+3. Remove container: `docker rm spotifytowled`
+4. Recreate with same volumes (preserves config)
+5. Access web UI and click "Authenticate with Spotify"
+6. Your config and WLED devices are preserved
+
+**Home Assistant Users (Standalone)**:
+1. Update addon from Home Assistant
+2. Configuration automatically migrates (adds `mode: standalone`)
+3. No manual changes needed
+4. Restart addon
+
+**Home Assistant Users (Migrating to Integration)**:
+1. Deploy Docker server separately (see DOCKER.md)
+2. Configure Docker server via web UI
+3. Update HA addon config:
+   ```yaml
+   mode: "integration"
+   server_url: "http://your-docker-server:5000"
+   ```
+4. Restart addon
+5. Remove Spotify credentials from HA config (now in Docker server)
+
+### Backward Compatibility
+- ✅ All v2.0 configurations work without changes
+- ✅ Default behavior unchanged (standalone mode)
+- ✅ No breaking changes to API or configuration structure
+
+---
+
+## 🐞 Known Issues
+
+None identified in this release.
+
+---
+
+## 👥 Contributors
+
+- **raphaelbleier** - Maintainer
+- GitHub Copilot - Code assistance
+
+---
+
+## 📅 Release Date
+
+November 13, 2024
+
+---
+
+## 🔗 Links
+
+- **Repository**: https://github.com/raphaelbleier/SpotifyToWled
+- **Docker Hub**: ghcr.io/raphaelbleier/spotifytowled
+- **Issues**: https://github.com/raphaelbleier/SpotifyToWled/issues
+- **Documentation**: See README.md, DOCKER.md, and HOMEASSISTANT.md
+
+---
+
+## 🙏 Acknowledgments
+
+Thanks to all users who reported the Docker authentication issue and provided feedback!
diff --git a/DOCKER.md b/DOCKER.md
@@ -26,6 +26,33 @@ docker run -d \
 docker-compose up -d
 ```
 
+## Initial Setup and Spotify Authentication
+
+After deploying the container, you need to authenticate with Spotify:
+
+1. **Access the web interface**: `http://your-server-ip:5000`
+
+2. **Configure Spotify Credentials**:
+   - Get credentials from [Spotify Developer Dashboard](https://developer.spotify.com/dashboard)
+   - In the Spotify Dashboard, add redirect URI: `http://your-server-ip:5000/callback`
+   - Enter Client ID and Client Secret in the web UI
+   - Click "Save Configuration"
+
+3. **Authenticate with Spotify**:
+   - Click the "Authenticate with Spotify" button
+   - Log in with your Spotify account
+   - Authorize the application
+   - You'll be redirected back to the app
+
+4. **Add WLED Devices**:
+   - Enter your WLED device IP addresses
+   - Click "Add Device" for each one
+
+5. **Start Sync**:
+   - Click "Start Sync" to begin syncing colors
+
+**Note:** The authentication token is cached in `/config/.spotify_cache`, so you won't need to re-authenticate unless the token expires or you change credentials.
+
 ## Deploying on Portainer
 
 ### Method 1: Using Docker Compose (Recommended)

diff --git a/HOMEASSISTANT.md b/HOMEASSISTANT.md
@@ -4,9 +4,40 @@ This guide explains how to integrate SpotifyToWLED with Home Assistant.
 
 ## Installation Methods
 
-### Method 1: Home Assistant Add-on (Recommended)
+You can run SpotifyToWLED with Home Assistant in two ways:
 
-The easiest way to run SpotifyToWLED on Home Assistant is using the official add-on.
+### Method 1: Standalone Add-on (All-in-One)
+
+Run the complete SpotifyToWLED application within Home Assistant. Best for simple setups.
+
+**Pros:**
+- Everything in one place
+- No external dependencies
+- Easy to configure
+
+**Cons:**
+- Uses more Home Assistant resources
+- Separate config per HA instance
+
+### Method 2: Integration Mode (Connect to Docker Server)
+
+Connect your Home Assistant to an external SpotifyToWLED Docker server. Best for advanced setups.
+
+**Pros:**
+- Lighter on Home Assistant resources
+- Share one server across multiple HA instances
+- Centralized management via Portainer
+- Easier to update and maintain
+
+**Cons:**
+- Requires external Docker server
+- Additional setup step
+
+---
+
+## Standalone Add-on Installation
+
+The easiest way to run SpotifyToWLED is using the official add-on in standalone mode.
 
 #### Step 1: Add Repository
 
@@ -29,6 +60,7 @@ The easiest way to run SpotifyToWLED on Home Assistant is using the official add
 2. Fill in your settings:
 
 ```yaml
+mode: "standalone"
 spotify_client_id: "your_client_id_here"
 spotify_client_secret: "your_client_secret_here"
 wled_ips:
@@ -53,15 +85,55 @@ color_extraction_method: "vibrant"
 
 - Click **Open Web UI** button
 - Or access via Ingress in Home Assistant
-- Configure Spotify credentials and WLED devices
 
-### Method 2: Docker Container in Home Assistant
+---
+
+## Integration Mode Installation
+
+This method assumes you already have SpotifyToWLED running in Docker (via Portainer or docker-compose).
+
+### Step 1: Deploy SpotifyToWLED Docker Server
+
+First, set up the Docker server following the [Docker Deployment Guide](DOCKER.md).
+
+**Quick Docker setup:**
+```bash
+docker run -d \
+  --name spotifytowled \
+  -p 5000:5000 \
+  -v $(pwd)/config:/config \
+  -v $(pwd)/data:/data \
+  --restart unless-stopped \
+  ghcr.io/raphaelbleier/spotifytowled:latest
+```
+
+Configure it via the web UI at `http://your-docker-host:5000`
+
+### Step 2: Install Home Assistant Add-on
+
+Follow steps 1-2 from "Standalone Add-on Installation" above.
+
+### Step 3: Configure Integration Mode
+
+1. Go to the **Configuration** tab
+2. Set configuration to integration mode:
+
+```yaml
+mode: "integration"
+server_url: "http://192.168.1.50:5000"
+```
+
+Replace `192.168.1.50` with your Docker server's IP address.
+
+3. Click **Save**
+
+### Step 4: Start and Access
 
-If you prefer to run as a standalone Docker container:
+1. Click **Start**
+2. Click **Open Web UI** - it will proxy to your Docker server
+3. All configuration is done on the Docker server
 
-1. Install **Portainer** add-on from Home Assistant
-2. Follow the [Docker Deployment Guide](DOCKER.md)
-3. Access at `http://homeassistant.local:5000`
+**Note:** In integration mode, the Spotify credentials and WLED devices are configured on the Docker server, not in the Home Assistant addon config.
 
 ## Getting Spotify Credentials