Skip to content

Ubuntu Setup Guide

This guide walks you through installing the MicroDC Worker on Ubuntu as a systemd service.

Prerequisites

  • Ubuntu 20.04 LTS or newer (22.04/24.04 recommended)
  • Root/sudo access
  • Python 3.8 or higher (3.10+ recommended)
  • Internet connection for downloading dependencies

Quick Install

# Clone the worker repository
git clone https://gitlab.com/microdc/worker.git
cd microhub_worker

# Run the automated setup script
sudo ./ubuntu_setup.sh

The script will:

  1. Install system dependencies (Python 3.12, git, curl) and uv (installed system-wide to /usr/local/bin)
  2. Create a dedicated service user (microdcworker)
  3. Set up the installation directory at /srv/microdcworker
  4. Create the virtual environment with uv venv --seed
  5. Install Python dependencies with uv pip install
  6. Configure the systemd service with security hardening
  7. Create configuration templates

Re-running sudo ./ubuntu_setup.sh on an existing install is safe — it migrates an older pip/venv deployment to uv in place (stopping the service first and restarting it after).

Optional components

The installer can also provision two opt-in components (prompted interactively, or via flags):

Flag What it does
sudo ./ubuntu_setup.sh --with-vllm Installs a dedicated vLLM env at /srv/microdcworker/vllm-env (Python 3.12, large CUDA download — GPU hosts only) for the native vLLM engine.
sudo ./ubuntu_setup.sh --with-podman Sets up Podman for container / container_stream jobs. Equivalent standalone script: sudo ./setup_podman.sh.

Tip: generate a hardware-tuned worker.yaml instead of hand-editing the reference config with python scripts/generate_config.py (see the config wizard).

Post-Installation Configuration

1. Configure API Credentials

Edit the environment file with your API key:

sudo nano /srv/microdcworker/config/environment

Set the required values:

# Server connection (REQUIRED)
MICRODC_SERVER_URL=https://api.microdc.ai
MICRODC_API_KEY=mdc_wrk_xxxxx  # Your API key from MicroDC console

2. Configure Inference Engine

The worker needs an inference engine to process jobs. Ollama is recommended:

# Install Ollama
curl -fsSL https://ollama.ai/install.sh | sh

# Start Ollama
sudo systemctl enable ollama
sudo systemctl start ollama

# Pull a model
ollama pull llama3.1:8b

Update the environment file with Ollama settings:

MICRODC_ENGINE=ollama
OLLAMA_BASE_URL=http://localhost:11434

3. Start the Worker

# Start the service
sudo systemctl start microdcworker

# Enable auto-start on boot
sudo systemctl enable microdcworker

# Verify it's running
sudo systemctl status microdcworker

Service Management

Command Description
sudo systemctl start microdcworker Start the worker
sudo systemctl stop microdcworker Stop the worker
sudo systemctl restart microdcworker Restart the worker
sudo systemctl status microdcworker Check status
sudo journalctl -u microdcworker -f View live logs
sudo journalctl -u microdcworker --since "1 hour ago" View recent logs

Directory Structure

After installation, the directory structure is:

/srv/microdcworker/
├── config/
│   ├── worker.yaml      # Main configuration file
│   └── environment      # Environment variables (API keys)
├── src/                 # Application source code
├── venv/                # Virtual environment (created by uv)
├── vllm-env/            # Dedicated vLLM env (only with --with-vllm)
├── uv-python/           # uv-managed Python interpreters (e.g. 3.12 for vLLM)
├── .cache/              # uv / model caches (kept inside the hardened unit)
├── logs/                # Application logs
├── backups/             # Auto-update backups (only when auto-update is enabled)
├── requirements.txt     # Python dependencies
└── setup.py             # Package setup

Configuration Files

Environment File (/srv/microdcworker/config/environment)

# Required Settings
MICRODC_SERVER_URL=https://api.microdc.ai
MICRODC_API_KEY=your_api_key_here

# Engine Configuration
MICRODC_ENGINE=ollama
OLLAMA_BASE_URL=http://localhost:11434

# Optional: Worker Identification
WORKER_ID=worker-1
WORKER_NAME=My Worker
WORKER_ORG=default

# Optional: Auto-Update (DISABLED by default — opt in to enable)
# AUTO_UPDATE_ENABLED=true
# UPDATE_CHECK_INTERVAL=21600  # 6 hours

# Optional: Logging
LOG_LEVEL=INFO
HEARTBEAT_INTERVAL=30

Worker Config (/srv/microdcworker/config/worker.yaml)

The YAML config file provides additional options. See config/default.yaml for all available settings.

GPU Support

NVIDIA GPU

# Verify GPU is detected
nvidia-smi

# The worker automatically detects NVIDIA GPUs
# No additional configuration needed

No GPU (CPU Only)

The worker runs fine on CPU-only systems. Ensure your pulled models are appropriate for CPU inference:

# Smaller models work better on CPU
ollama pull llama3.2:3b
ollama pull phi3:mini

Firewall Configuration

If you have a firewall enabled, ensure the worker can reach:

  • Your MicroDC server (default: port 443 for HTTPS)
  • Ollama (default: localhost:11434)
# If using ufw
sudo ufw allow out 443/tcp

Troubleshooting

Worker Won't Start

  1. Check the logs:
sudo journalctl -u microdcworker -n 50 --no-pager
  1. Verify configuration:
sudo cat /srv/microdcworker/config/environment
  1. Test manually:
sudo -u microdcworker /srv/microdcworker/venv/bin/python -m src.core.cli status

Authentication Errors

  1. Verify your API key is correct
  2. Check the server URL is reachable:
curl -I https://api.microdc.ai/health
  1. Credentials are saved in ~/.microdc/worker_credentials.json after first successful registration

Ollama Connection Issues

  1. Verify Ollama is running:
sudo systemctl status ollama
curl http://localhost:11434/api/tags
  1. Check if models are available:
ollama list

Permission Issues

The service runs as the microdcworker user. Ensure file permissions are correct:

sudo chown -R microdcworker:microdcworker /srv/microdcworker
sudo chmod 750 /srv/microdcworker/config
sudo chmod 640 /srv/microdcworker/config/environment

Updating the Worker

Auto-update is disabled by default. The recommended way to update is to pull the latest code and re-run the installer (it migrates the venv and restarts the service):

cd /path/to/worker
git pull
sudo ./ubuntu_setup.sh

Enable Auto-Update (opt-in)

If you want the worker to check for and apply updates automatically (every 6 hours, with backup/rollback), edit the environment file:

AUTO_UPDATE_ENABLED=true

Uninstalling

# Stop and disable the service
sudo systemctl stop microdcworker
sudo systemctl disable microdcworker

# Remove systemd service file
sudo rm /etc/systemd/system/microdcworker.service
sudo systemctl daemon-reload

# Remove installation directory
sudo rm -rf /srv/microdcworker

# Remove service user (optional)
sudo userdel -r microdcworker

Security Notes

The systemd service includes security hardening:

  • NoNewPrivileges: Prevents privilege escalation
  • PrivateTmp: Isolated temporary directory
  • ProtectSystem: Read-only system directories
  • ProtectHome: No access to home directories
  • ReadWritePaths: Only /srv/microdcworker is writable

Keep your API key secure and never commit it to version control.