# Player Deployment Configuration - Implementation Summary

## Changes Made

### 1. **ssh_deploy.py** - Enhanced with Configuration Generation

#### New Function: `generate_player_config()`
```python
def generate_player_config(
    player_name: str,
    server_url: str,
    api_key: str,
    player_id: str = None,
    location: str = None
) -> str:
    """Generate player configuration JSON"""
```

**Features**:
- Creates complete player configuration for connecting to DigiServer
- Includes server URL, API endpoints, and authentication
- Configurable playback and networking settings
- Returns JSON string ready to write to config.json

#### Enhanced Function: `deploy_player_to_host()`
**New Parameters**:
- `deploy_path: str = None` - Defaults to `/home/[username]/kiwy-signage`
- `server_url: str = None` - DigiServer URL for player configuration
- `server_api_key: str = None` - API key for player authentication

**New Functionality**:
- Sets default deployment path to user's home directory
- Generates player configuration after code deployment
- Writes config.json to deployment directory
- Step 3.5: "Configure Player" - added to deployment steps

### 2. **api.py** - Updated Deploy Endpoint

#### Enhanced: `/api/deploy/player` Endpoint
**Changes**:
- Default `deploy_path` changed from `/opt/kiwy-signage` → `None` (uses `/home/[user]/kiwy-signage`)
- Added automatic server URL detection using HTTP headers
- Added automatic API key generation from player identity
- Pass server configuration to deployment function
- Added `hashlib` import for API key generation

**API Key Generation**:
```python
api_key = hashlib.sha256(f'{player_name}:{hostname}'.encode()).hexdigest()[:32]
```

**Server URL Detection**:
```python
scheme = request.headers.get('X-Forwarded-Proto', request.scheme)
host = request.headers.get('X-Forwarded-Host', request.host)
server_url = f"{scheme}://{host}/digiserver"
```

### 3. **New Documentation Files**

#### PLAYER_DEPLOYMENT_GUIDE.md
Complete guide including:
- Overview of deployment changes
- Deployment workflow with step-by-step process
- Configuration file structure and examples
- API key generation explanation
- Server URL detection logic
- Player requirements (system, network, user)
- Manual configuration instructions
- Comprehensive troubleshooting guide
- Security considerations
- API reference with examples

#### config.json.template
- Fully commented template for player configuration
- Explains all configuration options
- Shows default values and available choices
- Can be used as reference for manual setup

## Deployment Flow (Updated)

### Before (Old System)
```
SSH → Create /opt/kiwy-signage → Deploy code → Done
      (requires sudo/root)
```

### Now (New System)
```
SSH → Create /home/[user]/kiwy-signage → Deploy code → Generate config.json → Done
      (user-level permissions)
```

## Player Configuration Example

Generated automatically on deployment:

```json
{
  "player": {
    "name": "Lobby Screen",
    "id": "lobby-screen-01",
    "location": "Main Lobby",
    "version": "2.0"
  },
  "server": {
    "url": "http://digiserver-host/digiserver",
    "api_endpoint": "http://digiserver-host/digiserver/api",
    "authentication": {
      "type": "api_key",
      "key": "a1b2c3d4e5f6g7h8..."
    },
    "endpoints": {
      "playlists": "http://digiserver-host/digiserver/api/playlists",
      "content": "http://digiserver-host/digiserver/api/content",
      "schedule": "http://digiserver-host/digiserver/api/schedule",
      "heartbeat": "http://digiserver-host/digiserver/api/player/heartbeat",
      "logs": "http://digiserver-host/digiserver/api/player/logs"
    }
  },
  "playback": {
    "audio_enabled": true,
    "video_enabled": true,
    "max_resolution": "4K",
    "refresh_interval": 60,
    "rotation": "0"
  },
  "networking": {
    "timeout": 30,
    "retry_count": 3,
    "retry_delay": 5
  }
}
```

## Key Advantages

### 1. **User-Level Deployment**
- ✅ No root/sudo required on player host
- ✅ Players deployed to user home directory
- ✅ Better security model
- ✅ Multiple users can each have player instances

### 2. **Automatic Configuration**
- ✅ No manual setup needed
- ✅ Correct server URLs auto-detected
- ✅ Unique API keys generated per player
- ✅ Network settings optimized

### 3. **Flexible**
- ✅ Can override deploy path if needed
- ✅ Can manually edit config.json if required
- ✅ Supports different server URLs
- ✅ Works with proxies (X-Forwarded headers)

### 4. **Reliable**
- ✅ Intelligent fallback (rsync → git)
- ✅ Graceful error handling
- ✅ Comprehensive logging
- ✅ Step-by-step progress tracking

## Testing Checklist

- [ ] Deploy player to test host
- [ ] Verify `/home/[user]/kiwy-signage` created
- [ ] Check `config.json` exists with correct server URL
- [ ] Verify API key in config
- [ ] Test player can read config file
- [ ] Test player connects to DigiServer
- [ ] Verify heartbeat endpoint is called
- [ ] Check deployment logs for all steps

## File Changes Summary

| File | Changes |
|------|---------|
| `app/utils/ssh_deploy.py` | Added config generation, updated deploy function |
| `app/blueprints/api.py` | Added hashlib import, updated deploy endpoint |
| New: `PLAYER_DEPLOYMENT_GUIDE.md` | Complete deployment and configuration guide |
| New: `config.json.template` | Template for player configuration |

## Backward Compatibility

- ✅ Existing player deployments still work
- ✅ Can still specify custom deploy_path
- ✅ Falls back to git clone if rsync fails
- ✅ Install script still runs if present

## Next Steps

1. **Test Deployment**
   - Deploy test player to verify flow
   - Check configuration generation
   - Verify player can read config.json

2. **Player Integration**
   - Update player code to read config.json
   - Use server URL and API key from config
   - Implement API endpoints for content/playlists

3. **Monitoring**
   - Add player status dashboard
   - Monitor API usage
   - Track deployment history

4. **Enhancements**
   - Add config editing via API
   - Implement config templates
   - Add deployment history tracking