SPR is built to run on systems capable of running Ubuntu and Docker. For also developing on-device, systems should have 32-64GB of writable storage and 8GB of RAM. With less RAM, building from ram disks should be disabled (see the README).
Base System Setup
NOTE This guide shows how to setup and run SPR using Docker. See the Raspberry Pi 4 Setup Guide for running SPR using a prebuilt image.
Download and install Ubuntu Server
Skip this step if you already have a base system setup.
For Running on a Raspberry Pi you can download the 22.04 Ubuntu image here. For other hardware, download an Ubuntu server installer for your architecutre (arm64 or amd64), then boot the device into the installer.
SPR has been tested on Ubuntu 20.04, 21.10, and the 22.04 release.
Write image to SD-card or USB
You can flash the image with a tool such as Balena Etcher @ https://www.balena.io/etcher/
If you prefer to write the image using the command line:
# On a mac, write the image to the external disk (rdiskX).
# Be careful to make sure you identify your removable drive correctly.
$ xzcat ubuntu-22.0-4-preinstalled-server-arm64+raspi.img.xz | dd of=/dev/rdiskX bs=$[1024*1024]
Boot the system and login, the default credentials are
Fetch the SPR repository
# On the booted system
git clone https://github.com/spr-networks/super
Prepare the Ubuntu Install for SPR base/setup.sh
#if using a flash drive
#or if using an sdcard the following script reduces disk usage
# base/setup-sdcard.sh #this setup will reduce writes from log files
Inside the super directory, copy
cp -R base/template_configs configs
./configs/scripts/gen_coredhcp_yaml.sh > configs/dhcp/coredhcp.yml
./configs/scripts/gen_watchdog.sh > configs/watchdog/watchdog.conf
Verify the main config
configs/base/config.sh is correct. Ensure that
WANIF matches the name of the outbound interface if not using the builtin ethernet port.
Also, consider disabling
UPSTREAM_SERVICES_ENABLE=1 if you do not want the API and SSH exposed to the WAN port.
Start the services (this script runs
docker-compose up -d):
Testing containers are built and published to GitHub's Container Registry, and can be run without building on the device. If you would instead like to build everything from source, proceed to the next section.
To see logs:
docker-compose logs -f
Run SPR dev release
If you want to get the latest features and updates you can switch to the dev release of SPR by setting the
RELEASE_CHANNEL environment variables:
export RELEASE_VERSION="latest" RELEASE_CHANNEL="-dev"
RELEASE_VERSION variable can also be used to run specific versions:
Building the project
SPR can be built on device, however there is a small gotcha.
Because SPR uses
nftables exclusively, and docker is made to work with
which the SPR install disables for docker, a fixup script is needed.
The script installs minimal docker forwarding rules. Once SPR is running this is no longer needed. However, is SPR fails to run and you need to build with docker, you may need to run this script again.
#fix forwarding rules for Docker
If something went wrong with with a cached stage, it is possible to specify
sudo ./build_docker_compose.sh --no-cache
A specific service can also be built by passing it as an argument (
To run the local build:
Check dns-Corefile to tweak DNS server configuration as well as the hostapd settings in
It is possible to use SPR's DNS server for the host system's DNS requests too, by updating the resolv.conf file.
sudo echo -e "nameserver 127.0.0.1" > /etc/resolv.conf
Sign in to the Web UI
Connect to the IP of the device from the wired WAN interface in a browser, SPR is using mDNS and you should be able to reach it @ http://spr.local.
A setup screen should show up asking you to set up interfaces and assign a username and password.