Installation and Setup
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.
Installation Architecture
Section titled “Installation Architecture”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
System Requirements
Section titled “System Requirements”The installation script supports Ubuntu 22.04 and 24.04 with the following requirements:
Component | Requirement | Detection Method |
---|---|---|
Operating System | Ubuntu 22.04/24.04 | uname check |
GPU | NVIDIA GPU | Driver installation |
Docker | Latest stable | docker --version |
CUDA | Version 12.8 | nvcc --version |
Python | 3.8+ | System package |
Node.js | 18.x | Package 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
Installation Script Components
Section titled “Installation Script Components”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
Installation Process
Section titled “Installation Process”Phase 1: System Dependencies
Section titled “Phase 1: System Dependencies”The installer first establishes the execution environment and installs core system dependencies:
Environment Detection
# User and home directory detectionREAL_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
Phase 2: Repository Setup
Section titled “Phase 2: Repository Setup”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
Phase 3: Python Environment
Section titled “Phase 3: Python Environment”Virtual environment creation and dependency installation:
Step | Command | Configuration File |
---|---|---|
Virtual Environment | python3 -m venv ~/venv | N/A |
Base Dependencies | pip install -r requirements.txt | requirements.txt |
Compute Dependencies | pip install --no-deps -r requirements-compute.txt | requirements-compute.txt |
Editable Install | pip 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
Phase 4: Wallet Configuration
Section titled “Phase 4: Wallet Configuration”The installer checks for existing Bittensor wallets and provides guidance for wallet creation:
WALLET_DIR="${HOME}/.bittensor/wallets"have_wallets=falseif [ -d "${WALLET_DIR}" ] && [ -n "$(ls -A "${WALLET_DIR}" 2>/dev/null)" ]; then have_wallets=truefi
Sources: scripts/installation_script/compute_subnet_installer.sh:566-600
Phase 5: Network Configuration
Section titled “Phase 5: Network Configuration”Firewall Setup UFW configuration with required ports:
Port | Protocol | Purpose |
---|---|---|
22 | TCP | SSH Access |
4444 | TCP | Validator Communication |
8091 | TCP | Default 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:
# SQLITE_DB_PATH configurationsed -i "s@^SQLITE_DB_PATH=.*@SQLITE_DB_PATH=\"${CS_PATH}/database.db\"@" "$env_path"
# WANDB_API_KEY configurationsed -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
Phase 6: Process Management
Section titled “Phase 6: Process Management”PM2 Configuration The miner process is launched using PM2 with comprehensive environment variables:
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
Configuration Options
Section titled “Configuration Options”Network Selection
Section titled “Network Selection”The installer supports both mainnet and testnet configurations:
Network | NetUID | Subtensor Network | Default Port |
---|---|---|---|
Mainnet | 27 | subvortex.info:9944 | 8091 |
Testnet | 15 | test | 8091 |
Sources: scripts/installation_script/compute_subnet_installer.sh:618-649
Automated Mode
Section titled “Automated Mode”The installer supports non-interactive execution:
./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
Verification
Section titled “Verification”Process Status
Section titled “Process Status”# Check PM2 process statuspm2 listpm2 logs subnet${NETUID}_miner
# Check log filestail -f ${CS_PATH}/pm2_out.logtail -f ${CS_PATH}/pm2_error.log
Network Registration
Section titled “Network Registration”# Register hotkey on networkbtcli 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
Troubleshooting
Section titled “Troubleshooting”Common Issues
Section titled “Common Issues”Docker Permission Errors
sudo usermod -aG docker $USERsudo systemctl restart docker
CUDA Environment Issues
The installer automatically configures CUDA paths in .bashrc
:
export PATH=/usr/local/cuda-12.8/bin:$PATHexport 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