Skip to content

Manual Installation

If you prefer not to use the automated installation script, you can set up Whitebox manually by following these steps.

Installation Steps

Step 1: Install Prerequisites

# Update package lists
sudo apt update -y

# Apply Ubuntu release updates & security fixes
sudo apt dist-upgrade -y

# Install required packages
sudo apt install -y git git-lfs jq docker.io docker-compose

# Add current user to docker group (or create whitebox user - see Step 4)
sudo usermod -aG docker $USER

Step 2: Configure Docker DNS

This prevents DNS resolution issues when building Docker images on networks with local DNS resolvers:

# Create or update Docker daemon configuration
sudo mkdir -p /etc/docker
echo '{"dns": ["9.9.9.9", "149.112.112.112"]}' | sudo tee /etc/docker/daemon.json

# Restart Docker to apply changes
sudo systemctl restart docker

# Set hostname to whitebox
sudo hostnamectl set-hostname whitebox

# Create whitebox user
sudo useradd -m -s /bin/bash -G sudo whitebox

# Set password for whitebox user
sudo passwd whitebox

# Add user to docker group
sudo usermod -aG docker whitebox

Step 5: Clone Whitebox Repository

# Clone to /whitebox directory (recommended for production)
sudo git clone https://gitlab.com/whitebox-aero/whitebox /whitebox
sudo chown -R whitebox:whitebox /whitebox

# Or clone to your home directory (for testing)
cd ~
git clone https://gitlab.com/whitebox-aero/whitebox
cd whitebox

Step 6: Configure Network Interface Naming (Orange Pi only)

This step disables predictable network interface naming, which is required for the Wi-Fi access point setup.

cd /whitebox  # or wherever you cloned the repository
sudo make setup-network

This command will:

  • Check if you're running on an Orange Pi
  • Update /etc/kernel/cmdline to add net.ifnames=0 biosdevname=0 parameters
  • Run u-boot-update to apply the changes to the boot configuration
  • Configure network interface naming to use traditional names (eth0, wlan0)
  • Warn you that a reboot is required for changes to take effect

Step 7: Set Up udev Rules for SDR Devices

cd /whitebox  # or wherever you cloned the repository
sudo make setup-udev

This command will:

  • Download the required udev rules for Stratux/SDR devices
  • Install them to the correct location
  • Reload the udev rules automatically

Step 8: Set Up Wi-Fi Access Point (Orange Pi only)

# Check if the connection already exists and delete it
if nmcli connection show "whitebox-ap" &>/dev/null; then
  sudo nmcli connection delete "whitebox-ap"
fi

# Create Wi-Fi access point using NetworkManager
sudo nmcli connection add type wifi ifname wlan0 con-name "whitebox-ap" \
  autoconnect yes \
  ssid "whitebox" \
  wifi.mode ap \
  wifi.band bg \
  ipv4.method shared \
  ipv4.addresses 10.42.0.1/24 \
  wifi-sec.key-mgmt wpa-psk \
  wifi-sec.psk "whitebox"

# Activate the access point
sudo nmcli connection up whitebox-ap

Step 9: Create .env file

cd /whitebox  # or wherever you cloned the repository

# Create .env file and populate required variables
# Refer to .env.example for examples
cp .env.example .env

# Edit .env to set env vars as needed and save the file
nano .env

Step 10: Build & Deploy Whitebox Services

# Deploy all services
docker compose up -d

If you'd like to force all containers to be re-created even if there are no changes to apply to them, you can use --force-recreate:

docker compose up -d --force-recreate

Step 11: Post-Installation

  1. Connect Hardware: Attach the USB Wi-Fi adapter, two SDR devices, and GPS module to your device
  2. Reboot (especially if you configured network interface naming): sudo reboot
  3. Connect to Wi-Fi: Join the whitebox network (password: whitebox)
  4. Access Whitebox: Open your browser and go to http://10.42.0.1
  5. Unplug Ethernet: Disconnect the ethernet cable to take Whitebox offline
  6. Optional: Build cardboard enclosure for easy transport (see Cardboard Enclosure Guide)

Next Steps