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.
# wireless-regdb + iw are required for setting the WiFi regulatory domain
# in Step 9 (without it the AP runs at heavily reduced TX power).
sudo apt install -y git git-lfs jq make network-manager wireless-regdb iw \
  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 (DNS + dual-logging cache)
sudo mkdir -p /etc/docker
echo '{"dns": ["9.9.9.9", "149.112.112.112"], "log-opts": {"cache-disabled": "false", "cache-max-size": "10m"}}' | 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: Set Up Centralized Logging

This sets up rsyslog to capture Docker container logs to persistent files at /var/log/whitebox/:

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

Step 7: 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 an M.2 Wi-Fi adapter is installed
  • Take the first available M.2 Wi-Fi adapter and create a file at /etc/systemd/network/10-wlan-ap.link to ensure predictable naming for the access point (wlan-ap)
  • Reload udev rules
  • Warn you that a reboot is required for changes to take effect

Step 8: Set Up udev Rules for SDR Devices

cd /whitebox  # or wherever you cloned the repository
sudo make setup-sdr-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 9: Set Up Wi-Fi Access Point (Orange Pi only)

First, set the WiFi regulatory domain. Without this the kernel defaults to the world-regulatory domain (00), which caps TX power and restricts channel selection — clients then see "full bars" but the AP itself is whispering, producing flaky connections. Replace XX with your ISO 3166-1 alpha-2 country code (same value as COUNTRY_CODE in .env):

WIFI_COUNTRY=XX

# Apply now, and persist across reboots
sudo iw reg set "$WIFI_COUNTRY"
echo "options cfg80211 ieee80211_regdom=${WIFI_COUNTRY}" | \
  sudo tee /etc/modprobe.d/cfg80211.conf
if [ -f /etc/default/crda ]; then
  sudo sed -i "s/^REGDOMAIN=.*/REGDOMAIN=${WIFI_COUNTRY}/" /etc/default/crda
fi

Then create the access point:

# 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.
# 2.4 GHz channel 6 is the widest-compatible AP setting across SBC radios.
# If your M.2 radio is verified to support 5 GHz in AP mode, swap in
# `wifi.band a wifi.channel 149` for lower congestion.
# wifi.powersave 2 = disabled: prevents the radio sleeping between packets,
# which otherwise adds 50-200ms latency spikes to bursty traffic.
sudo nmcli connection add type wifi ifname wlan-ap con-name "whitebox-ap" \
  autoconnect yes \
  ssid "whitebox" \
  wifi.mode ap \
  wifi.band bg \
  wifi.channel 6 \
  wifi.powersave 2 \
  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 10: 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 11: 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 12: 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