updated player deployment for digiserver

2026-06-07 23:40:50 +03:00
parent b97372f74d
commit f674330b93
30 changed files with 3459 additions and 201 deletions
@@ -0,0 +1,343 @@
+# Player Deployment Configuration Guide
+
+## Overview
+
+This guide explains how to deploy Kiwy-Signage players to remote hosts using DigiServer's SSH deployment system with automatic configuration.
+
+## Key Changes
+
+### 1. **Deployment Location**
+Players are now deployed to the SSH user's home directory instead of system paths:
+- **Old Path**: `/opt/kiwy-signage`
+- **New Path**: `/home/[username]/kiwy-signage`
+
+**Advantages**:
+- ✅ No system administrator privileges required
+- ✅ User can manage and update their own player installation
+- ✅ Multiple users can each have their own player instance
+- ✅ Easier to backup and relocate player data
+
+### 2. **Automatic Configuration**
+
+When deploying a player, DigiServer automatically generates and deploys a `config.json` file with:
+- **Player Identity**: Name, ID, location
+- **Server Connection Details**: DigiServer URL and endpoints
+- **Authentication**: API key for secure communication
+- **Playback Settings**: Video/audio, resolution, refresh interval
+- **Network Configuration**: Timeouts and retry policies
+
+### 3. **Configuration File Structure**
+
+The generated `config.json` at `/home/[user]/kiwy-signage/config.json`:
+
+```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
+  }
+}
+```
+
+## Deployment Workflow
+
+### Step 1: SSH Connection Test
+```
+User Input:
+  - Hostname: 192.168.1.100 (or domain.com)
+  - Port: 22
+  - Username: player_user
+  - Password: user_password
+
+System:
+  - Tests SSH connectivity
+  - Verifies user credentials
+  - Returns: ✓ Success or ✗ Error
+```
+
+### Step 2: Player Configuration
+```
+User Input:
+  - Player Name: "Lobby Screen"
+  - Player Hostname: "lobby-1"
+  - Location: "Main Lobby"
+  - Quickconnect Code: (auto-generated if needed)
+  - Password: (for player management)
+
+System:
+  - Creates player record in database
+  - Generates Auth Code
+```
+
+### Step 3: Deployment (Auto-triggered)
+```
+Backend Process:
+  1. SSH to remote host
+  2. Create /home/player_user/kiwy-signage directory
+  3. Deploy Kiwy-Signage code via:
+     - rsync (if pre-staged code available) ← Preferred
+     - git clone (fallback)
+  4. Generate config.json with server connection details
+  5. Write config.json to deployment directory
+  6. Run install script (if present)
+```
+
+### Step 4: Result
+```
+Player is now:
+  ✅ Deployed to /home/[user]/kiwy-signage
+  ✅ Configured to connect to DigiServer
+  ✅ Ready to receive playlists and content
+  ✅ Can authenticate using config.json credentials
+
+User receives:
+  - Player Auth Code (for API authentication)
+  - Deployment status (success/failure)
+  - Next steps for player startup
+```
+
+## API Key Generation
+
+The system automatically generates a unique API key for each player:
+
+```python
+# Generation algorithm
+api_key = SHA256(f'{player_name}:{hostname}').hexdigest()[:32]
+
+# Example:
+# Input: "Lobby Screen" + "192.168.1.100"
+# Output: "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"
+```
+
+This ensures:
+- ✅ Consistent key (same for same player/host combination)
+- ✅ Unique per player instance
+- ✅ Deterministic (can be regenerated if lost)
+
+## Server URL Detection
+
+DigiServer automatically detects the correct URL using HTTP headers:
+
+```
+Priority (uses first available):
+1. X-Forwarded-Proto + X-Forwarded-Host (if behind proxy)
+2. Request scheme + host (direct connection)
+
+Examples:
+- http://localhost/digiserver
+- http://192.168.1.50/digiserver
+- https://digiserver.company.com
+```
+
+## Player Requirements
+
+### System Requirements
+- Linux operating system (Ubuntu 20.04+ recommended)
+- SSH server with password authentication enabled
+- git and rsync installed (for deployment)
+- ~500MB+ disk space for code
+- Python 3.8+ (if player is Python-based)
+
+### Network Requirements
+- Access to DigiServer on HTTP/HTTPS ports
+- Outbound internet access for NTP (time synchronization)
+- Optional: NFS or SMB for shared content storage
+
+### User Requirements
+- Regular user account (non-root preferred)
+- Home directory exists and is writable
+- SSH access via password or key
+
+## Manual Configuration
+
+If you need to manually configure a deployed player:
+
+### 1. Connect to player host
+```bash
+ssh player_user@hostname
+cd ~/kiwy-signage
+```
+
+### 2. Edit config.json
+```bash
+nano config.json
+```
+
+### 3. Modify any settings
+- Update server URL if DigiServer moved
+- Change player settings (resolution, refresh rate)
+- Adjust networking timeouts if needed
+
+### 4. Restart player
+```bash
+./restart-player.sh
+# or
+systemctl restart kiwy-signage  # if installed as service
+```
+
+## Troubleshooting
+
+### Deployment Failed: "SSH Connection Refused"
+- Check SSH service is running on remote host
+- Verify hostname/IP is correct
+- Confirm SSH port (default 22)
+- Check firewall allows SSH connections
+
+### Deployment Failed: "Directory Permission Denied"
+- Check `/home/[user]` directory exists
+- Verify user owns the directory
+- Run: `chmod 755 /home/[user]` if needed
+
+### Player Can't Connect to Server
+- Check config.json has correct server URL
+- Verify network connectivity from player to DigiServer
+- Check API key in config matches DigiServer database
+- Review DigiServer logs: `docker logs edp-digiserver`
+
+### "install.sh" not found
+- This is normal if repository doesn't include install script
+- Player deployment still succeeds
+- Manual setup may be required
+
+### rsync failed, using git clone instead
+- This is automatic fallback and works fine
+- Only happens if rsync not available on remote
+- Install rsync for faster deployments: `apt install rsync`
+
+## Performance Characteristics
+
+### With Pre-staged Code (rsync)
+- **Time**: 30-120 seconds
+- **Network**: 5-50MB
+- **Method**: Efficient file sync
+
+### Without Pre-staged Code (git clone)
+- **Time**: 2-5 minutes
+- **Network**: 50-200MB
+- **Method**: Full repository download
+
+## Security Considerations
+
+- ✅ SSH passwords transmitted over encrypted SSH
+- ✅ API keys generated from player identity
+- ✅ Config file stored locally on player
+- ✅ No passwords stored in config
+- ⚠️ Ensure SSH user has limited privileges
+- ⚠️ Restrict file permissions on player: `chmod 700 ~/kiwy-signage`
+
+## Next Steps
+
+1. **Deploy First Player**
+   - Go to http://localhost/digiserver/players/add
+   - Enter SSH credentials for test player
+   - Observe deployment process
+
+2. **Verify Deployment**
+   - SSH to player host
+   - Check: `ls -la ~/kiwy-signage/`
+   - Check: `cat ~/kiwy-signage/config.json`
+
+3. **Start Player Service**
+   - Follow player-specific startup guide
+   - Verify connection to DigiServer
+   - Monitor player logs
+
+4. **Create Content**
+   - Upload media to DigiServer
+   - Create playlists
+   - Assign to players
+   - Monitor playback via dashboard
+
+## API Reference
+
+### Deployment Endpoint
+```
+POST /api/deploy/player
+Content-Type: application/json
+
+{
+  "hostname": "192.168.1.100",
+  "username": "player_user",
+  "password": "user_password",
+  "player_name": "Lobby Screen",
+  "port": 22,
+  "deploy_path": null,  // Optional, defaults to /home/[user]/kiwy-signage
+  "repo_url": "https://gitea.moto-adv.com/ske087/Kiwy-Signage.git"
+}
+```
+
+### Response
+```json
+{
+  "success": true,
+  "message": "Deployment completed successfully",
+  "timestamp": "2026-06-07T10:30:00",
+  "steps": [
+    {
+      "step": "SSH Connection Test",
+      "status": "completed",
+      "message": "SSH connection successful",
+      "timestamp": "2026-06-07T10:30:01"
+    },
+    {
+      "step": "Create Deploy Directory",
+      "status": "completed",
+      "message": "Directory /home/player_user/kiwy-signage created",
+      "timestamp": "2026-06-07T10:30:02"
+    },
+    {
+      "step": "Deploy Code",
+      "status": "completed",
+      "message": "Code deployed via rsync",
+      "timestamp": "2026-06-07T10:30:45"
+    },
+    {
+      "step": "Configure Player",
+      "status": "completed",
+      "message": "Player configuration created",
+      "timestamp": "2026-06-07T10:30:46"
+    }
+  ]
+}
+```
+
+## Summary
+
+The new player deployment system provides:
+- 🎯 **Automated Configuration**: Player connects to DigiServer automatically
+- 📁 **User-level Deployment**: No system admin needed
+- 🚀 **Fast Deployment**: rsync for efficient transfers
+- 🔄 **Intelligent Fallback**: git clone if rsync unavailable
+- 🔐 **Secure**: SSH encryption + API keys
+- 📊 **Monitoring**: Track deployment steps and status
+
+Players deployed with this system are immediately ready to receive playlists and content from DigiServer.