Windows Setup Guide¶

This guide walks you through installing the MicroDC Worker on Windows.

Prerequisites¶

Windows 10/11 (64-bit)
Python 3.8 or higher (3.10+ recommended)
Administrator access for service installation
Internet connection for downloading dependencies

Installation Options¶

Option 1: Manual Installation (Recommended)¶

1. Install Python¶

Download and install Python from python.org:

Check "Add Python to PATH" during installation
Check "Install pip"

Verify installation:

python --version
pip --version

2. Install Git (Optional but Recommended)¶

Download from git-scm.com or use winget:

winget install Git.Git

3. Clone or Download the Worker¶

# Using Git
git clone https://gitlab.com/microdc/worker.git
cd microhub_worker

# Or download and extract the ZIP file

4. Create Virtual Environment¶

# Create virtual environment
python -m venv venv

# Activate it
.\venv\Scripts\Activate.ps1

# If you get an execution policy error, run:
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

5. Install Dependencies¶

# Upgrade pip
pip install --upgrade pip setuptools wheel

# Install the worker package
pip install -e .

# Or install with all extras
pip install -e ".[all]"

6. Configure the Worker¶

Create a configuration directory:

mkdir $env:USERPROFILE\.microdc

Set environment variables (PowerShell):

# Set for current session
$env:MICRODC_SERVER_URL = "https://api.microdc.ai"
$env:MICRODC_API_KEY = "mdc_wrk_xxxxx"
$env:MICRODC_ENGINE = "ollama"
$env:OLLAMA_BASE_URL = "http://localhost:11434"

# Set permanently (requires admin for system-wide)
[Environment]::SetEnvironmentVariable("MICRODC_API_KEY", "mdc_wrk_xxxxx", "User")

Or create a .env file in the project directory.

7. Install Ollama¶

Download Ollama for Windows from ollama.ai:

# After installation, pull a model
ollama pull llama3.1:8b

8. Run the Worker¶

# Make sure virtual environment is activated
.\venv\Scripts\Activate.ps1

# Start the worker
python -m src.core.cli start

Option 2: Running as a Windows Service¶

For production deployments, you can run the worker as a Windows service using NSSM (Non-Sucking Service Manager).

1. Install NSSM¶

# Using Chocolatey
choco install nssm

# Or download from https://nssm.cc/download

2. Create the Service¶

# Install the service
nssm install MicroDCWorker

# In the GUI that opens:
# Path: C:\path\to\microhub_worker\venv\Scripts\python.exe
# Startup directory: C:\path\to\microhub_worker
# Arguments: -m src.core.cli start

3. Configure Environment Variables¶

nssm set MicroDCWorker AppEnvironmentExtra `
    "MICRODC_SERVER_URL=https://api.microdc.ai" `
    "MICRODC_API_KEY=mdc_wrk_xxxxx" `
    "MICRODC_ENGINE=ollama" `
    "OLLAMA_BASE_URL=http://localhost:11434"

4. Configure Logging¶

nssm set MicroDCWorker AppStdout C:\path\to\microhub_worker\logs\stdout.log
nssm set MicroDCWorker AppStderr C:\path\to\microhub_worker\logs\stderr.log

5. Start the Service¶

nssm start MicroDCWorker

Option 3: Using Task Scheduler¶

For simpler deployments, use Windows Task Scheduler:

Open Task Scheduler (taskschd.msc)
Create a new task:
Name: MicroDC Worker
Run whether user is logged on or not: Check
Run with highest privileges: Check
Triggers: At startup
Actions: Start a program
Program: C:\path\to\microhub_worker\venv\Scripts\python.exe
Arguments: -m src.core.cli start
Start in: C:\path\to\microhub_worker
Settings:
If the task fails, restart every: 1 minute
Attempt to restart up to: 3 times

Directory Structure¶

Recommended installation structure:

C:\MicroDCWorker\
├── config\
│   └── worker.yaml      # Configuration file
├── src\                 # Application source code
├── venv\                # Python virtual environment
├── logs\                # Application logs
├── backups\             # Auto-update backups
├── requirements.txt
└── setup.py

Configuration¶

Environment Variables¶

Variable	Description	Default
`MICRODC_SERVER_URL`	MicroDC server URL	`https://api.microdc.ai`
`MICRODC_API_KEY`	Your worker API key	Required
`MICRODC_ENGINE`	Inference engine	`ollama`
`OLLAMA_BASE_URL`	Ollama server URL	`http://localhost:11434`
`LOG_LEVEL`	Logging level	`INFO`
`HEARTBEAT_INTERVAL`	Heartbeat frequency (seconds)	`30`
`AUTO_UPDATE_ENABLED`	Enable auto-updates	`true`

Setting Permanent Environment Variables¶

PowerShell (User Level):

[Environment]::SetEnvironmentVariable("MICRODC_API_KEY", "your_key", "User")
[Environment]::SetEnvironmentVariable("MICRODC_ENGINE", "ollama", "User")

PowerShell (System Level - requires Admin):

[Environment]::SetEnvironmentVariable("MICRODC_API_KEY", "your_key", "Machine")

GUI Method:

Press Win + R, type sysdm.cpl, press Enter
Go to "Advanced" tab
Click "Environment Variables"
Add variables under "User variables" or "System variables"

GPU Support¶

NVIDIA GPU¶

Install the latest NVIDIA drivers
Verify GPU detection:

nvidia-smi

The worker automatically detects NVIDIA GPUs

AMD GPU (Limited Support)¶

AMD GPU support depends on the inference engine. Check Ollama documentation for AMD compatibility.

Firewall Configuration¶

Ensure Windows Firewall allows:

Outbound HTTPS (port 443) to your MicroDC server
Ollama (localhost:11434 - usually no firewall rule needed)

# Allow outbound HTTPS (usually allowed by default)
New-NetFirewallRule -DisplayName "MicroDC Worker Outbound" -Direction Outbound -Protocol TCP -RemotePort 443 -Action Allow

Troubleshooting¶

Python Not Found¶

Ensure Python is in your PATH:

# Check if Python is in PATH
$env:PATH -split ";" | Where-Object { $_ -like "*Python*" }

# Add Python to PATH if needed
$env:PATH += ";C:\Users\YourUser\AppData\Local\Programs\Python\Python310"

Virtual Environment Activation Fails¶

If you see "execution of scripts is disabled":

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Ollama Connection Issues¶

Verify Ollama is running:

# Check if Ollama process is running
Get-Process ollama -ErrorAction SilentlyContinue

# Test the API
Invoke-RestMethod -Uri "http://localhost:11434/api/tags"

If Ollama isn't running, start it from the Start Menu or:

ollama serve

Authentication Errors¶

Verify your API key is set correctly:

echo $env:MICRODC_API_KEY

Check credentials file:

cat $env:USERPROFILE\.microdc\worker_credentials.json

Service Won't Start¶

Check NSSM logs:

nssm status MicroDCWorker

Check application logs in the configured log directory
Try running manually to see errors:

.\venv\Scripts\python.exe -m src.core.cli start

Permission Errors¶

Run PowerShell as Administrator if you encounter permission issues with:

Installing system-wide environment variables
Creating services
Writing to protected directories

Updating the Worker¶

Auto-Update¶

Auto-updates are enabled by default. The worker checks for updates every 6 hours.

Manual Update¶

# Stop the service (if running as service)
nssm stop MicroDCWorker

# Activate virtual environment
.\venv\Scripts\Activate.ps1

# Pull latest changes (if using Git)
git pull

# Update dependencies
pip install -e .

# Restart service
nssm start MicroDCWorker

Using the Update Script¶

.\scripts\update\update_worker.ps1 -DownloadUrl "https://..." -NewVersion "0.2.0"

Uninstalling¶

Remove Service¶

nssm stop MicroDCWorker
nssm remove MicroDCWorker confirm

Remove Files¶

# Remove installation directory
Remove-Item -Recurse -Force C:\MicroDCWorker

# Remove credentials (optional)
Remove-Item -Recurse -Force $env:USERPROFILE\.microdc

Remove Environment Variables¶

[Environment]::SetEnvironmentVariable("MICRODC_API_KEY", $null, "User")
[Environment]::SetEnvironmentVariable("MICRODC_ENGINE", $null, "User")

Performance Tips¶

Use an SSD: Faster model loading and better overall performance
Allocate sufficient RAM: Large models require significant memory
GPU acceleration: Use NVIDIA GPU with CUDA for best inference speed
Disable Windows Defender scanning for the installation directory (optional, for performance)

Security Notes¶

Store API keys securely using environment variables, not in code
Use a dedicated user account for running the service
Keep Windows and Python updated for security patches
Consider using Windows Credential Manager for sensitive data