diff --git a/docs/_docs/quick-starts/quick-start-windows.md b/docs/_docs/quick-starts/quick-start-windows.md index 2d38cf4d3..1970058e9 100644 --- a/docs/_docs/quick-starts/quick-start-windows.md +++ b/docs/_docs/quick-starts/quick-start-windows.md @@ -16,7 +16,10 @@ parent: Quick Starts - Windows 10/11 with WSL2 enabled - Docker Desktop for Windows - Git for Windows -- Python 3.6+ (for CueGUI) +- **Python 3.9** (required for Windows client components - see note below) + +{: .important } +> **Python 3.9 Requirement:** Windows client components (rqd, cuegui, cuesubmit) specifically require Python 3.9.x. This is due to binary wheel availability and compatibility with native dependencies like PySide2. See the [monsta_venv setup](#option-2-using-monsta_venv-recommended-for-python-39) for an easy way to configure the correct environment. ## Setup Steps @@ -67,10 +70,34 @@ You should see all services in "Up" state. ### 6. Install Python dependencies +There are two options for setting up Python dependencies on Windows: + +#### Option 1: Standard pip install + ```bash pip install pycue cuegui ``` +#### Option 2: Using monsta_venv (Recommended for Python 3.9) + +The `monsta_venv` directory provides a preconfigured Python 3.9 virtual environment setup specifically for Windows: + +1. Open PowerShell as Administrator +2. Navigate to the OpenCue repository: + ```powershell + cd OpenCue\monsta_venv + ``` +3. Run the setup script: + ```powershell + .\setup_windows_venv.ps1 + ``` +4. Activate the environment: + ```powershell + .\activate.ps1 + ``` + +See the [monsta_venv README](../../../monsta_venv/README.md) for detailed instructions and troubleshooting. + ### 7. Configure environment Set the Cuebot host: @@ -100,6 +127,18 @@ cuegui ## Troubleshooting +### Python 3.9 Issues + +**Python version mismatch:** +Windows client components require Python 3.9.x specifically. If you encounter module import errors or PySide2 issues: +1. Install Python 3.9 from [python.org](https://www.python.org/downloads/release/python-3913/) +2. Use the `monsta_venv` setup: `.\monsta_venv\setup_windows_venv.ps1` + +**PySide2 installation fails:** +```powershell +pip install PySide2==5.15.2.1 +``` + ### Docker not starting - Ensure virtualization is enabled in BIOS - Check that WSL2 is properly installed @@ -114,8 +153,15 @@ cuegui - Allocate more resources to Docker Desktop in Settings - Use WSL2 backend for better performance +### PowerShell script execution blocked +Run PowerShell as Administrator and execute: +```powershell +Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser +``` + ## Next Steps +- [monsta_venv README](../../../monsta_venv/README.md) - Detailed Windows Python 3.9 setup - [Installing CueSubmit](../getting-started/installing-cuesubmit.md) - [Submitting Jobs](../user-guides/submitting-jobs.md) - [Configuring RQD](../other-guides/customizing-rqd.md) diff --git a/monsta_venv/README.md b/monsta_venv/README.md new file mode 100644 index 000000000..bbb9f8957 --- /dev/null +++ b/monsta_venv/README.md @@ -0,0 +1,142 @@ +# monsta_venv - Windows Python 3.9 Virtual Environment Setup + +This directory provides Windows-specific Python 3.9 virtual environment setup for running OpenCue client components (rqd, cuegui). + +## Requirements + +- Windows 10/11 +- Python 3.9.x (required for Windows client components) +- Administrator privileges (for initial setup) + +## Quick Setup + +### Option 1: Automated Setup (Recommended) + +1. Open PowerShell as Administrator +2. Navigate to this directory: + ```powershell + cd path\to\OpenCue\monsta_venv + ``` +3. Run the setup script: + ```powershell + .\setup_windows_venv.ps1 + ``` + +### Option 2: Manual Setup + +1. Install Python 3.9: + - Download from [Python.org](https://www.python.org/downloads/release/python-3913/) + - During installation, check "Add Python to PATH" + - Select "Customize installation" and enable "pip" + +2. Create virtual environment: + ```powershell + cd path\to\OpenCue\monsta_venv + py -3.9 -m venv venv + ``` + +3. Activate the environment: + ```powershell + .\venv\Scripts\Activate.ps1 + ``` + +4. Install dependencies: + ```powershell + pip install -r requirements.txt + ``` + +## Activating the Environment + +### PowerShell +```powershell +.\monsta_venv\activate.ps1 +``` + +### Command Prompt +```cmd +monsta_venv\activate.bat +``` + +## Running Client Components + +After activating the environment: + +### RQD (Render Queue Daemon) +```powershell +$env:CUEBOT_HOSTNAME = "your-cuebot-server" +rqd -c ..\sandbox\rqd_windows.conf +``` + +### CueGUI +```powershell +$env:CUEBOT_HOSTS = "your-cuebot-server" +cuegui +``` + +### CueSubmit +```powershell +$env:CUEBOT_HOSTS = "your-cuebot-server" +cuesubmit +``` + +## Troubleshooting + +### Python 3.9 Not Found +If Python 3.9 is not in your PATH, specify the full path: +```powershell +C:\Python39\python.exe -m venv venv +``` + +### PowerShell Execution Policy +If scripts are blocked, run PowerShell as Administrator and execute: +```powershell +Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser +``` + +### Module Import Errors +Ensure all dependencies are installed: +```powershell +pip install -r requirements.txt +``` + +### PySide2/Qt Issues +For CueGUI Qt issues: +```powershell +pip uninstall PySide2 +pip install PySide2==5.15.2.1 +``` + +### gRPC Connection Issues +1. Verify CUEBOT_HOSTNAME is set correctly +2. Check firewall allows port 8443 (gRPC) and 8444 (RQD) +3. Test connectivity: + ```powershell + Test-NetConnection -ComputerName your-cuebot-server -Port 8443 + ``` + +## Directory Structure + +``` +monsta_venv/ +├── README.md # This file +├── requirements.txt # Python dependencies +├── setup_windows_venv.ps1 # Automated setup script +├── activate.ps1 # PowerShell activation script +├── activate.bat # Command Prompt activation script +└── venv/ # Virtual environment (created during setup) +``` + +## Python Version Requirement + +**Important:** Windows client components specifically require Python 3.9.x due to: +- Binary wheel availability for PySide2 on Windows +- Compatibility with psutil and other native dependencies +- Tested and verified operation with OpenCue client tools + +Python versions 3.10+ may have issues with some dependencies on Windows. + +## See Also + +- [Quick Start for Windows](../docs/_docs/quick-starts/quick-start-windows.md) +- [Hybrid RQD Setup](../docs/_docs/developer-guide/hybrid-rqd-setup.md) +- [OpenCue Documentation](https://www.opencue.io/docs/) diff --git a/monsta_venv/activate.bat b/monsta_venv/activate.bat new file mode 100644 index 000000000..88e54ae5f --- /dev/null +++ b/monsta_venv/activate.bat @@ -0,0 +1,22 @@ +@echo off +REM OpenCue Windows Virtual Environment Activation Script + +set SCRIPT_DIR=%~dp0 +set VENV_ACTIVATE=%SCRIPT_DIR%venv\Scripts\activate.bat + +if exist "%VENV_ACTIVATE%" ( + call "%VENV_ACTIVATE%" + echo OpenCue virtual environment activated! + echo. + echo Available commands: + echo cuegui - Launch CueGUI + echo cuesubmit - Launch CueSubmit + echo rqd - Start RQD daemon + echo cueadmin - Command-line admin tool + echo. + echo Remember to set CUEBOT_HOSTS environment variable: + echo set CUEBOT_HOSTS=your-cuebot-server +) else ( + echo ERROR: Virtual environment not found! + echo Run setup_windows_venv.ps1 first. +) diff --git a/monsta_venv/activate.ps1 b/monsta_venv/activate.ps1 new file mode 100644 index 000000000..7ec47cae9 --- /dev/null +++ b/monsta_venv/activate.ps1 @@ -0,0 +1,20 @@ +# OpenCue Windows Virtual Environment Activation Script +$ScriptDir = Split-Path -Parent $MyInvocation.MyCommand.Path +$VenvActivate = Join-Path $ScriptDir "venv\Scripts\Activate.ps1" + +if (Test-Path $VenvActivate) { + & $VenvActivate + Write-Host "OpenCue virtual environment activated!" -ForegroundColor Green + Write-Host "" + Write-Host "Available commands:" -ForegroundColor Cyan + Write-Host " cuegui - Launch CueGUI" -ForegroundColor White + Write-Host " cuesubmit - Launch CueSubmit" -ForegroundColor White + Write-Host " rqd - Start RQD daemon" -ForegroundColor White + Write-Host " cueadmin - Command-line admin tool" -ForegroundColor White + Write-Host "" + Write-Host "Remember to set CUEBOT_HOSTS environment variable:" -ForegroundColor Yellow + Write-Host " `$env:CUEBOT_HOSTS = `"your-cuebot-server`"" -ForegroundColor White +} else { + Write-Host "ERROR: Virtual environment not found!" -ForegroundColor Red + Write-Host "Run setup_windows_venv.ps1 first." -ForegroundColor Yellow +} diff --git a/monsta_venv/requirements.txt b/monsta_venv/requirements.txt new file mode 100644 index 000000000..6da7d4db8 --- /dev/null +++ b/monsta_venv/requirements.txt @@ -0,0 +1,30 @@ +# OpenCue Windows Client Requirements +# Python 3.9.x required for Windows client components + +# Core dependencies +grpcio>=1.48.0 +grpcio-tools>=1.48.0 +protobuf>=3.19.0,<4.0.0 + +# OpenCue Python packages (installed from local source) +# These will be installed by setup script from the repository root +# pycue +# pyoutline +# rqd +# cuegui +# cuesubmit +# cueadmin + +# GUI dependencies (for CueGUI) +PySide2==5.15.2.1 + +# RQD dependencies +psutil>=5.8.0 +future>=0.18.3 + +# CueNIMBY dependencies +pynput>=1.7.6 + +# Utility dependencies +PyYAML>=5.4.0 +six>=1.16.0 diff --git a/monsta_venv/setup_windows_venv.ps1 b/monsta_venv/setup_windows_venv.ps1 new file mode 100644 index 000000000..478a6224a --- /dev/null +++ b/monsta_venv/setup_windows_venv.ps1 @@ -0,0 +1,251 @@ +# OpenCue Windows Python 3.9 Virtual Environment Setup Script +# This script creates and configures a Python 3.9 virtual environment for OpenCue client components + +param( + [switch]$SkipPythonCheck, + [switch]$Force +) + +$ErrorActionPreference = "Stop" + +# Script directory +$ScriptDir = Split-Path -Parent $MyInvocation.MyCommand.Path +$VenvDir = Join-Path $ScriptDir "venv" +$RepoRoot = Split-Path -Parent $ScriptDir + +Write-Host "========================================" -ForegroundColor Cyan +Write-Host "OpenCue Windows Environment Setup" -ForegroundColor Cyan +Write-Host "========================================" -ForegroundColor Cyan +Write-Host "" + +# Check for Python 3.9 +if (-not $SkipPythonCheck) { + Write-Host "Checking for Python 3.9..." -ForegroundColor Yellow + + $Python39 = $null + + # Try py launcher first + try { + $pyVersion = & py -3.9 --version 2>&1 + if ($pyVersion -match "Python 3\.9") { + $Python39 = "py -3.9" + Write-Host " Found Python 3.9 via py launcher: $pyVersion" -ForegroundColor Green + } + } catch { + # py launcher not available or Python 3.9 not found + } + + # Try python39 command + if (-not $Python39) { + try { + $pyVersion = & python39 --version 2>&1 + if ($pyVersion -match "Python 3\.9") { + $Python39 = "python39" + Write-Host " Found Python 3.9: $pyVersion" -ForegroundColor Green + } + } catch { + # python39 not available + } + } + + # Try python command and check version + if (-not $Python39) { + try { + $pyVersion = & python --version 2>&1 + if ($pyVersion -match "Python 3\.9") { + $Python39 = "python" + Write-Host " Found Python 3.9: $pyVersion" -ForegroundColor Green + } + } catch { + # python not available + } + } + + # Check common installation paths + if (-not $Python39) { + $CommonPaths = @( + "$env:LOCALAPPDATA\Programs\Python\Python39\python.exe", + "C:\Python39\python.exe", + "$env:ProgramFiles\Python39\python.exe" + ) + + foreach ($path in $CommonPaths) { + if (Test-Path $path) { + $pyVersion = & $path --version 2>&1 + if ($pyVersion -match "Python 3\.9") { + $Python39 = $path + Write-Host " Found Python 3.9 at: $path" -ForegroundColor Green + break + } + } + } + } + + if (-not $Python39) { + Write-Host "" + Write-Host "ERROR: Python 3.9 not found!" -ForegroundColor Red + Write-Host "" + Write-Host "Please install Python 3.9 from:" -ForegroundColor Yellow + Write-Host " https://www.python.org/downloads/release/python-3913/" -ForegroundColor Cyan + Write-Host "" + Write-Host "Installation tips:" -ForegroundColor Yellow + Write-Host " - Check 'Add Python to PATH' during installation" -ForegroundColor White + Write-Host " - Select 'Customize installation' and enable pip" -ForegroundColor White + Write-Host "" + exit 1 + } +} else { + $Python39 = "python" + Write-Host "Skipping Python version check..." -ForegroundColor Yellow +} + +# Check if venv already exists +if (Test-Path $VenvDir) { + if ($Force) { + Write-Host "Removing existing virtual environment..." -ForegroundColor Yellow + Remove-Item -Recurse -Force $VenvDir + } else { + Write-Host "" + Write-Host "Virtual environment already exists at: $VenvDir" -ForegroundColor Yellow + Write-Host "Use -Force to recreate it." -ForegroundColor Yellow + Write-Host "" + Write-Host "To activate the existing environment:" -ForegroundColor Green + Write-Host " .\venv\Scripts\Activate.ps1" -ForegroundColor Cyan + Write-Host "" + exit 0 + } +} + +# Create virtual environment +Write-Host "" +Write-Host "Creating virtual environment..." -ForegroundColor Yellow + +if ($Python39 -eq "py -3.9") { + & py -3.9 -m venv $VenvDir +} else { + & $Python39 -m venv $VenvDir +} + +if (-not (Test-Path $VenvDir)) { + Write-Host "ERROR: Failed to create virtual environment!" -ForegroundColor Red + exit 1 +} + +Write-Host " Virtual environment created at: $VenvDir" -ForegroundColor Green + +# Activate virtual environment +Write-Host "" +Write-Host "Activating virtual environment..." -ForegroundColor Yellow +$ActivateScript = Join-Path $VenvDir "Scripts\Activate.ps1" +& $ActivateScript + +# Upgrade pip +Write-Host "" +Write-Host "Upgrading pip..." -ForegroundColor Yellow +& python -m pip install --upgrade pip + +# Install requirements +Write-Host "" +Write-Host "Installing requirements..." -ForegroundColor Yellow +$RequirementsFile = Join-Path $ScriptDir "requirements.txt" +& pip install -r $RequirementsFile + +# Install OpenCue packages from source +Write-Host "" +Write-Host "Installing OpenCue packages from source..." -ForegroundColor Yellow + +$Packages = @("pycue", "pyoutline", "rqd", "cuegui", "cuesubmit", "cueadmin") + +foreach ($pkg in $Packages) { + $PkgPath = Join-Path $RepoRoot $pkg + if (Test-Path $PkgPath) { + Write-Host " Installing $pkg..." -ForegroundColor White + & pip install -e $PkgPath + } else { + Write-Host " WARNING: $pkg not found at $PkgPath" -ForegroundColor Yellow + } +} + +# Create activation scripts +Write-Host "" +Write-Host "Creating activation scripts..." -ForegroundColor Yellow + +# PowerShell activation script +$ActivatePs1Content = @" +# OpenCue Windows Virtual Environment Activation Script +`$ScriptDir = Split-Path -Parent `$MyInvocation.MyCommand.Path +`$VenvActivate = Join-Path `$ScriptDir "venv\Scripts\Activate.ps1" + +if (Test-Path `$VenvActivate) { + & `$VenvActivate + Write-Host "OpenCue virtual environment activated!" -ForegroundColor Green + Write-Host "" + Write-Host "Available commands:" -ForegroundColor Cyan + Write-Host " cuegui - Launch CueGUI" -ForegroundColor White + Write-Host " cuesubmit - Launch CueSubmit" -ForegroundColor White + Write-Host " rqd - Start RQD daemon" -ForegroundColor White + Write-Host " cueadmin - Command-line admin tool" -ForegroundColor White + Write-Host "" + Write-Host "Remember to set CUEBOT_HOSTS environment variable:" -ForegroundColor Yellow + Write-Host " `$env:CUEBOT_HOSTS = `"your-cuebot-server`"" -ForegroundColor White +} else { + Write-Host "ERROR: Virtual environment not found!" -ForegroundColor Red + Write-Host "Run setup_windows_venv.ps1 first." -ForegroundColor Yellow +} +"@ + +$ActivatePs1Path = Join-Path $ScriptDir "activate.ps1" +$ActivatePs1Content | Out-File -FilePath $ActivatePs1Path -Encoding UTF8 + +# Batch activation script +$ActivateBatContent = @" +@echo off +REM OpenCue Windows Virtual Environment Activation Script + +set SCRIPT_DIR=%~dp0 +set VENV_ACTIVATE=%SCRIPT_DIR%venv\Scripts\activate.bat + +if exist "%VENV_ACTIVATE%" ( + call "%VENV_ACTIVATE%" + echo OpenCue virtual environment activated! + echo. + echo Available commands: + echo cuegui - Launch CueGUI + echo cuesubmit - Launch CueSubmit + echo rqd - Start RQD daemon + echo cueadmin - Command-line admin tool + echo. + echo Remember to set CUEBOT_HOSTS environment variable: + echo set CUEBOT_HOSTS=your-cuebot-server +) else ( + echo ERROR: Virtual environment not found! + echo Run setup_windows_venv.ps1 first. +) +"@ + +$ActivateBatPath = Join-Path $ScriptDir "activate.bat" +$ActivateBatContent | Out-File -FilePath $ActivateBatPath -Encoding ASCII + +Write-Host " Created activate.ps1" -ForegroundColor Green +Write-Host " Created activate.bat" -ForegroundColor Green + +# Summary +Write-Host "" +Write-Host "========================================" -ForegroundColor Cyan +Write-Host "Setup Complete!" -ForegroundColor Green +Write-Host "========================================" -ForegroundColor Cyan +Write-Host "" +Write-Host "To activate the environment:" -ForegroundColor Yellow +Write-Host " PowerShell: .\monsta_venv\activate.ps1" -ForegroundColor White +Write-Host " CMD: monsta_venv\activate.bat" -ForegroundColor White +Write-Host "" +Write-Host "To run OpenCue client tools:" -ForegroundColor Yellow +Write-Host " 1. Set the Cuebot server:" -ForegroundColor White +Write-Host " `$env:CUEBOT_HOSTS = `"your-cuebot-server`"" -ForegroundColor Cyan +Write-Host "" +Write-Host " 2. Run the desired tool:" -ForegroundColor White +Write-Host " cuegui - Graphical interface" -ForegroundColor Cyan +Write-Host " cuesubmit - Job submission tool" -ForegroundColor Cyan +Write-Host " rqd - Render queue daemon" -ForegroundColor Cyan +Write-Host " cueadmin - Admin commands" -ForegroundColor Cyan +Write-Host ""