ske087/enterprise_digital-platform

Fork 0

Files

T

ske087 f674330b93 updated player deployment for digiserver

2026-06-07 23:40:50 +03:00

9.1 KiB

Raw Blame History

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:

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

# 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

ssh player_user@hostname
cd ~/kiwy-signage

2. Edit config.json

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

./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

Deploy First Player
- Go to http://localhost/digiserver/players/add
- Enter SSH credentials for test player
- Observe deployment process
Verify Deployment
- SSH to player host
- Check: ls -la ~/kiwy-signage/
- Check: cat ~/kiwy-signage/config.json
Start Player Service
- Follow player-specific startup guide
- Verify connection to DigiServer
- Monitor player logs
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

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

9.1 KiB Raw Blame History