Skip to content

Installation and Setup

Relevant Source Files

This document provides comprehensive installation instructions for setting up the NI Compute Subnet on Ubuntu systems. It covers system requirements, dependency installation, wallet configuration, and miner deployment using the automated installation script.

For information about validator-specific setup procedures, see Validator System. For details about the API service deployment, see Resource Allocation API.

The installation process follows a two-pass approach with clear separation between system-level dependencies and application-level configuration:

graph TD
    START["Installation Start"] --> SYSCHECK["System Requirements Check"]
    SYSCHECK --> DOCKER["Docker Installation"]
    DOCKER --> NVIDIA["NVIDIA Drivers & Container Runtime"]
    NVIDIA --> CUDA["CUDA 12.8 Installation"]
    CUDA --> BITTENSOR["Bittensor Framework"]
    BITTENSOR --> REBOOT{"Reboot Required?"}
    
    REBOOT -->|Yes| REBOOT_SYS["System Reboot"]
    REBOOT -->|No| WALLET_CHECK["Wallet Check"]
    REBOOT_SYS --> WALLET_CHECK
    
    WALLET_CHECK --> WALLET_EXISTS{"Wallet Exists?"}
    WALLET_EXISTS -->|No| WALLET_CREATE["Manual Wallet Creation"]
    WALLET_EXISTS -->|Yes| VENV_SETUP["Virtual Environment Setup"]
    WALLET_CREATE --> VENV_SETUP
    
    VENV_SETUP --> DEPS["Python Dependencies"]
    DEPS --> FIREWALL["UFW Firewall Configuration"]
    FIREWALL --> ENV_CONFIG["Environment Configuration"]
    ENV_CONFIG --> PM2_SETUP["PM2 Process Manager"]
    PM2_SETUP --> MINER_START["Miner Process Launch"]
    MINER_START --> COMPLETE["Installation Complete"]

Sources: scripts/installation_script/compute_subnet_installer.sh:1-805

The installation script supports Ubuntu 22.04 and 24.04 with the following requirements:

ComponentRequirementDetection Method
Operating SystemUbuntu 22.04/24.04uname check
GPUNVIDIA GPUDriver installation
DockerLatest stabledocker --version
CUDAVersion 12.8nvcc --version
Python3.8+System package
Node.js18.xPackage manager

The installer performs automatic detection and installation of missing components through the docker_installed(), nvidia_docker_installed(), and cuda_version_installed() functions.

Sources: scripts/installation_script/compute_subnet_installer.sh:93-95 , scripts/installation_script/compute_subnet_installer.sh:113-118 , scripts/installation_script/compute_subnet_installer.sh:154-160 , scripts/installation_script/compute_subnet_installer.sh:165-188

The compute_subnet_installer.sh script orchestrates the entire installation process through modular functions:

graph TB
    subgraph "System Dependencies"
        DOCKER_FUNC["docker_installed()"]
        NVIDIA_FUNC["nvidia_docker_installed()"] 
        CUDA_FUNC["cuda_version_installed()"]
        BTCLI_FUNC["btcli_installed()"]
    end
    
    subgraph "Configuration Functions"
        SETUP_NEEDRESTART["setup_needrestart()"]
        RUN_APT["run_apt_get()"]
        INSTALL_PKG["install_package()"]
        PAUSE_USER["pause_for_user()"]
    end
    
    subgraph "Wallet Management"
        WALLET_DIR["~/.bittensor/wallets"]
        WALLET_CHECK["Wallet Existence Check"]
    end
    
    subgraph "Environment Setup"
        VENV_DIR["~/venv"]
        ENV_FILE[".env Configuration"]
        WANDB_CONFIG["WANDB Integration"]
    end
    
    subgraph "Process Management"
        PM2_START["PM2 Process Launch"]
        FIREWALL_CONFIG["UFW Firewall Rules"]
        MINER_PROCESS["neurons/miner.py"]
    end
    
    DOCKER_FUNC --> NVIDIA_FUNC
    NVIDIA_FUNC --> CUDA_FUNC
    CUDA_FUNC --> BTCLI_FUNC
    BTCLI_FUNC --> WALLET_CHECK
    WALLET_CHECK --> VENV_DIR
    VENV_DIR --> ENV_FILE
    ENV_FILE --> WANDB_CONFIG
    WANDB_CONFIG --> FIREWALL_CONFIG
    FIREWALL_CONFIG --> PM2_START
    PM2_START --> MINER_PROCESS

Sources: scripts/installation_script/compute_subnet_installer.sh:113-203 , scripts/installation_script/compute_subnet_installer.sh:566-570 , scripts/installation_script/compute_subnet_installer.sh:681-732 , scripts/installation_script/compute_subnet_installer.sh:750-770

The installer first establishes the execution environment and installs core system dependencies:

Environment Detection

Terminal window
# User and home directory detection
REAL_USER=$(whoami)
USER_NAME="$REAL_USER"
HOME_DIR="$(eval echo "~$REAL_USER")"

Docker Installation The script installs Docker CE with NVIDIA container runtime support when not present:

Sources: scripts/installation_script/compute_subnet_installer.sh:97-110 , scripts/installation_script/compute_subnet_installer.sh:223-249 , scripts/installation_script/compute_subnet_installer.sh:251-272

CUDA 12.8 Installation Version-specific CUDA installation based on Ubuntu release:

Sources: scripts/installation_script/compute_subnet_installer.sh:274-330 , scripts/installation_script/compute_subnet_installer.sh:287-298 , scripts/installation_script/compute_subnet_installer.sh:299-313

The installer locates or clones the compute subnet repository:

graph LR
    GIT_CHECK["Git Repository Check"] --> REPO_ROOT["git rev-parse --show-toplevel"]
    REPO_ROOT --> SETUP_CHECK["setup.py/pyproject.toml Check"]
    SETUP_CHECK --> CLONE_REPO["git clone ni-compute"]
    CLONE_REPO --> CS_PATH["CS_PATH Variable Set"]
    CS_PATH --> VENV_CREATE["Virtual Environment Creation"]

Sources: scripts/installation_script/compute_subnet_installer.sh:334-395 , scripts/installation_script/compute_subnet_installer.sh:427-444

Virtual environment creation and dependency installation:

StepCommandConfiguration File
Virtual Environmentpython3 -m venv ~/venvN/A
Base Dependenciespip install -r requirements.txtrequirements.txt
Compute Dependenciespip install --no-deps -r requirements-compute.txtrequirements-compute.txt
Editable Installpip install -e .setup.py/pyproject.toml

Sources: scripts/installation_script/compute_subnet_installer.sh:446-464 , scripts/installation_script/compute_subnet_installer.sh:453-461

The installer checks for existing Bittensor wallets and provides guidance for wallet creation:

Terminal window
WALLET_DIR="${HOME}/.bittensor/wallets"
have_wallets=false
if [ -d "${WALLET_DIR}" ] && [ -n "$(ls -A "${WALLET_DIR}" 2>/dev/null)" ]; then
have_wallets=true
fi

Sources: scripts/installation_script/compute_subnet_installer.sh:566-600

Firewall Setup UFW configuration with required ports:

PortProtocolPurpose
22TCPSSH Access
4444TCPValidator Communication
8091TCPDefault Axon Port

Sources: scripts/installation_script/compute_subnet_installer.sh:610-655

Environment Configuration The installer configures the .env file with database and API settings:

Terminal window
# SQLITE_DB_PATH configuration
sed -i "s@^SQLITE_DB_PATH=.*@SQLITE_DB_PATH=\"${CS_PATH}/database.db\"@" "$env_path"
# WANDB_API_KEY configuration
sed -i "s@^WANDB_API_KEY=.*@WANDB_API_KEY=\"$WANDB_API_KEY\"@" "$env_path"

Sources: scripts/installation_script/compute_subnet_installer.sh:699-732 , scripts/installation_script/compute_subnet_installer.sh:718-720

PM2 Configuration The miner process is launched using PM2 with comprehensive environment variables:

Terminal window
pm2 start "${VENV_DIR}/bin/python3" \
--name "subnet${NETUID}_miner" \
-- \
"${CS_PATH}/neurons/miner.py" \
--netuid "${NETUID}" \
--subtensor.network "${SUBTENSOR_NETWORK}" \
--wallet.name "default" \
--wallet.hotkey "default" \
--axon.port "${AXON_PORT}"

Sources: scripts/installation_script/compute_subnet_installer.sh:750-770 , scripts/installation_script/compute_subnet_installer.sh:776-797

The installer supports both mainnet and testnet configurations:

NetworkNetUIDSubtensor NetworkDefault Port
Mainnet27subvortex.info:99448091
Testnet15test8091

Sources: scripts/installation_script/compute_subnet_installer.sh:618-649

The installer supports non-interactive execution:

Terminal window
./compute_subnet_installer.sh --automated

This mode uses environment variables for configuration and skips user prompts.

Sources: scripts/installation_script/compute_subnet_installer.sh:24-29 , scripts/installation_script/compute_subnet_installer.sh:539-561

Terminal window
# Check PM2 process status
pm2 list
pm2 logs subnet${NETUID}_miner
# Check log files
tail -f ${CS_PATH}/pm2_out.log
tail -f ${CS_PATH}/pm2_error.log
Terminal window
# Register hotkey on network
btcli subnet register --wallet.name default --wallet.hotkey default --netuid ${NETUID}

Sources: scripts/installation_script/compute_subnet_installer.sh:773-774 , scripts/installation_script/README.md:118-122

Docker Permission Errors

Terminal window
sudo usermod -aG docker $USER
sudo systemctl restart docker

CUDA Environment Issues The installer automatically configures CUDA paths in .bashrc:

Terminal window
export PATH=/usr/local/cuda-12.8/bin:$PATH
export LD_LIBRARY_PATH=/usr/local/cuda-12.8/lib64:$LD_LIBRARY_PATH

Wallet Not Found Ensure wallet exists at ~/.bittensor/wallets/<coldkey>/hotkeys/<hotkey> before running the second installation pass.

Sources: scripts/installation_script/compute_subnet_installer.sh:131-142 , scripts/installation_script/compute_subnet_installer.sh:315-326 , scripts/installation_script/README.md:127-140