enterprise_digital-platform/digiserver-v2/old_code_documentation/PLAYER_CONFIG_IMPLEMENTATION.md

Player Deployment Configuration - Implementation Summary

Changes Made

1. ssh_deploy.py - Enhanced with Configuration Generation

New Function: generate_player_config()

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:

api_key = hashlib.sha256(f'{player_name}:{hostname}'.encode()).hexdigest()[:32]

Server URL Detection:

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:

{
  "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