prvng_extensions/taskservs/development/desktop/README.md

# Desktop Task Service

## Overview

The Desktop task service provides a complete minimal desktop environment installation for running GUI applications on cloud instances. It includes support for multiple desktop environments, VNC remote access, and a curated set of essential applications including the Zed editor.

## Features

### Desktop Environments
- **XFCE** (default) - Lightweight and customizable
- **GNOME** - Modern and user-friendly  
- **KDE** - Feature-rich and powerful
- **LXDE** - Ultra-lightweight
- **MATE** - Traditional desktop experience

### Display Managers
- **LightDM** (default) - Lightweight display manager
- **GDM** - GNOME display manager
- **SDDM** - Simple desktop display manager

### Remote Access
- **VNC Server** - Remote desktop access via VNC protocol
  - Configurable resolution and color depth
  - Password protection support
  - Service management through systemd
- **RustDesk** - Modern cross-platform remote desktop with excellent performance
  - Direct P2P connection or custom server support
  - Built-in security and encryption
  - Multi-platform client support
  - Auto-start service management
- **SSH Server** - Secure command line and tunnel access
  - Hardened configuration with fail2ban protection
  - Key-based and password authentication options
  - User access controls and restrictions
  - Automatic firewall configuration

### Applications

#### Editors
- **Zed** - High-performance, multiplayer code editor (default)
- **Nano** - Simple terminal text editor
- **Vim** - Advanced terminal text editor

#### Development Tools
- **Git** - Version control system
- **Build Essential** - Compilation tools and libraries

#### Browsers
- **Firefox** - Web browser

#### Terminals
- **XFCE4 Terminal** (default) - Terminal emulator

#### Media & Graphics
- **VLC** - Media player
- **GIMP** - Image editing

#### Office
- **LibreOffice** - Office suite

#### Utilities
- **htop** - System monitor
- **curl/wget** - Download tools
- **tree** - Directory tree viewer

## Configuration

### Basic Configuration
```kcl
desktop: DesktopServer = {
    name: "my-desktop"
    run_user: {
        name: "myuser"
        home: "/home/myuser"
    }
    desktop_env: {
        type: "xfce"
        display_manager: "lightdm"
        resolution: "1920x1080"
    }
    vnc: {
        enabled: true
        port: 5901
        geometry: "1920x1080"
        depth: 24
    }
    rustdesk: {
        enabled: true
        port: 21116
        hbbr_port: 21117
    }
    ssh: {
        enabled: true
        port: 22
        password_auth: true
        key_auth: true
    }
}
```

### Advanced Configuration
```kcl
desktop: DesktopServer = {
    name: "development-desktop"
    run_user: {
        name: "developer"
        home: "/home/developer"
        shell: "/bin/bash"
    }
    desktop_env: {
        type: "gnome"
        display_manager: "gdm"
        resolution: "2560x1440"
        theme: "Adwaita-dark"
    }
    applications: {
        editors: ["zed", "vim", "nano"]
        browsers: ["firefox"]
        development: ["git", "build-essential", "docker"]
        terminals: ["gnome-terminal"]
    }
    graphics: {
        driver: "nvidia"
        acceleration: true
        compositing: true
    }
    vnc: {
        enabled: true
        port: 5902
        password: "secure_vnc_password"
        geometry: "2560x1440"
        depth: 32
    }
    rustdesk: {
        enabled: true
        port: 21116
        hbbr_port: 21117
        custom_server: "rustdesk.mycompany.com"
        permanent_password: "permanent_access_pass"
        allow_guest: false
    }
    ssh: {
        enabled: true
        port: 2222
        password_auth: true
        key_auth: true
        root_login: "no"
        max_auth_tries: 3
        allowed_users: ["developer", "admin"]
    }
    auto_login: true
}
```

## Usage

### Deploy Desktop Environment
```bash
./core/nulib/provisioning taskserv create desktop --infra <infrastructure-name>
```

### List Available Desktop Options
```bash
./core/nulib/provisioning taskserv list
```

### SSH to Desktop Server
```bash
./core/nulib/provisioning server ssh <desktop-server>
```

### Connect via VNC
1. Connect to server via VNC client (port 5901 by default)
2. Use configured VNC password if set
3. Desktop environment will start automatically

### Start/Stop VNC Service
```bash
# Start VNC service
systemctl start vncserver@1.service

# Stop VNC service  
systemctl stop vncserver@1.service

# Check VNC service status
systemctl status vncserver@1.service
```

### Connect via RustDesk
1. **Get RustDesk ID**: Run `sudo -u <desktop-user> rustdesk --get-id` on server
2. **Get temporary password**: Run `sudo -u <desktop-user> rustdesk --password` on server
3. **Download RustDesk client** from [rustdesk.com](https://rustdesk.com)
4. **Connect using ID and password** from steps 1-2

#### RustDesk Service Management
```bash
# Start RustDesk service for user
sudo -u <desktop-user> systemctl --user start rustdesk.service

# Stop RustDesk service
sudo -u <desktop-user> systemctl --user stop rustdesk.service

# Check RustDesk service status
sudo -u <desktop-user> systemctl --user status rustdesk.service
```

### Connect via SSH
```bash
# Basic SSH connection
ssh <desktop-user>@<server-ip> -p <ssh-port>

# SSH with X11 forwarding (for running GUI apps over SSH)
ssh -X <desktop-user>@<server-ip> -p <ssh-port>

# SSH with compression and forwarding
ssh -XC <desktop-user>@<server-ip> -p <ssh-port>

# Create SSH tunnel for VNC (more secure)
ssh -L 5901:localhost:5901 <desktop-user>@<server-ip> -p <ssh-port>
```

#### SSH Key-based Authentication
```bash
# Generate SSH key pair (on client)
ssh-keygen -t ed25519 -C "user@client-machine"

# Copy public key to server
ssh-copy-id -i ~/.ssh/id_ed25519.pub <desktop-user>@<server-ip> -p <ssh-port>

# Connect using key
ssh -i ~/.ssh/id_ed25519 <desktop-user>@<server-ip> -p <ssh-port>
```

## Supported Operating Systems

- Ubuntu 20.04+ / Debian 11+
- CentOS 8+ / RHEL 8+ / Fedora 35+

## Requirements

### Minimum System Requirements
- **RAM**: 2GB (4GB recommended)
- **Storage**: 20GB (40GB recommended for development)
- **CPU**: 2 cores (4 cores recommended)
- **Network**: Internet access for package installation

### For Graphics Acceleration
- Compatible GPU with proper drivers
- Additional VRAM for high-resolution displays

## Zed Editor Integration

The desktop environment includes Zed editor with:
- Pre-configured settings for development
- Language server protocol (LSP) support
- Git integration
- Terminal integration
- Desktop shortcut creation
- Multi-user support

### Zed Configuration Location
- System: `/usr/local/bin/zed`
- User config: `~/.config/zed/settings.json`
- Desktop shortcut: `~/Desktop/zed.desktop`

## Troubleshooting

### VNC Connection Issues
```bash
# Check VNC service status
systemctl status vncserver@1.service

# Restart VNC service
systemctl restart vncserver@1.service

# Check VNC logs
journalctl -u vncserver@1.service
```

### Desktop Environment Issues
```bash
# Check display manager status
systemctl status lightdm  # or gdm/sddm

# Restart display manager
systemctl restart lightdm

# Check X server logs
cat /var/log/Xorg.0.log
```

### Application Installation Issues
```bash
# Update package lists
apt update  # Ubuntu/Debian
dnf update  # Fedora/RHEL

# Check for broken packages
apt --fix-broken install  # Ubuntu/Debian

# Clear package cache
apt clean  # Ubuntu/Debian
dnf clean all  # Fedora/RHEL
```

### RustDesk Connection Issues
```bash
# Check RustDesk service status
sudo -u <desktop-user> systemctl --user status rustdesk.service

# Check RustDesk logs
journalctl --user -u rustdesk.service

# Restart RustDesk service
sudo -u <desktop-user> systemctl --user restart rustdesk.service

# Check firewall ports
sudo ufw status  # Ubuntu/Debian
sudo firewall-cmd --list-ports  # CentOS/RHEL/Fedora

# Get current RustDesk ID and password
sudo -u <desktop-user> rustdesk --get-id
sudo -u <desktop-user> rustdesk --password
```

### SSH Connection Issues
```bash
# Check SSH service status
systemctl status ssh  # Ubuntu/Debian
systemctl status sshd  # CentOS/RHEL/Fedora

# Check SSH configuration
sshd -t

# View SSH logs
journalctl -u ssh  # Ubuntu/Debian
journalctl -u sshd  # CentOS/RHEL/Fedora

# Check fail2ban status (if installed)
fail2ban-client status sshd

# Test SSH connection with verbose output
ssh -v <desktop-user>@<server-ip> -p <ssh-port>
```

## Security Considerations

### VNC Security
- VNC connections are not encrypted by default
- Consider using SSH tunneling for secure VNC access:
  ```bash
  ssh -L 5901:localhost:5901 <desktop-user>@<server-ip>
  ```
- Use strong VNC passwords
- Consider firewall rules to restrict VNC access

### RustDesk Security
- RustDesk uses end-to-end encryption by default
- Connections are secure without additional tunneling
- Consider using custom RustDesk server for better control
- Permanent passwords should be strong and rotated regularly
- Disable guest access in production environments

### SSH Security
- Automatic fail2ban protection against brute force attacks
- Key-based authentication is more secure than password-only
- Regular security updates are automatically configured
- SSH hardening applied with secure defaults:
  - Root login restricted to key-only or disabled
  - Maximum authentication attempts limited
  - Connection timeouts configured
- Consider changing default SSH port (22) for additional security

### General Security
- Regular security updates are recommended
- Use strong passwords for all accounts
- Consider network-level restrictions (VPN, firewall rules)
- Monitor system logs regularly for suspicious activity
- Keep desktop applications updated

## Performance Optimization

### For Low-Resource Systems
- Use LXDE or XFCE desktop environments
- Disable compositing effects
- Reduce VNC color depth to 16-bit
- Limit background applications

### For High-Performance Systems
- Use GNOME or KDE for full features
- Enable graphics acceleration
- Use higher VNC color depth (24/32-bit)
- Enable compositing effects