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