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, pip, git, curl)
  2. Create a dedicated service user (microdcworker)
  3. Set up the installation directory at /srv/microdcworker
  4. Create a Python virtual environment
  5. Install all Python dependencies
  6. Configure systemd service with security hardening
  7. Create configuration templates

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/                # Python virtual environment
├── logs/                # Application logs
├── backups/             # Auto-update backups
├── 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
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

The worker supports auto-updates by default. Updates are checked every 6 hours and applied automatically.

Manual Update

# Stop the service
sudo systemctl stop microdcworker

# Update the source files
cd /path/to/new/source
sudo cp -r src/* /srv/microdcworker/src/
sudo cp requirements.txt /srv/microdcworker/

# Update dependencies
sudo -u microdcworker /srv/microdcworker/venv/bin/pip install -r /srv/microdcworker/requirements.txt

# Restart
sudo systemctl start microdcworker

Disable Auto-Update

Edit the environment file:

AUTO_UPDATE_ENABLED=false

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.