Home

BlueOS-bootstrap

Function

BlueOS-bootstrap is responsible for making sure BlueOS-core is running as expected, as well as gracefully restarting core during BlueOS updates and if it is detected to have unexpectedly stopped/crashed. For an update the current core image gets shut down and the newly installed image gets started in its place, whereas in the case of a crash bootstrap reverts to running a known working core image, which is currently the one tagged as factory (which is whatever it was first flashed with), so that it's at least possible to access the interface.

Codebase

BlueOS-bootstrap is open source, and lives within the broader BlueOS GitHub repository. Issues can be used to report bugs or suggest features, and Pull Requests fixing bugs or adding new features are welcomed.

BlueOS is set up with a GitHub Action that automatically builds and deploys a BlueOS-bootstrap image when changes are pushed to the GitHub repository. If you want to make use of that functionality you'll need a DockerHub account, and will need to specify your DockerHub username (DOCKER_USERNAME) and password (DOCKER_PASSWORD) in your fork's GitHub secrets.

Updating

⚠️ BlueOS-bootstrap is a critical component of running BlueOS, and can significantly affect the system stability. It should only be updated when necessary, and preferably at times where the onboard computer hardware is accessible in case something goes wrong. For normal users it is strongly recommended to only update BlueOS-bootstrap to match stable releases of BlueOS, and even then only if there is a known issue an update is expected to fix or improve.

BlueOS-bootstrap versions are built at the same time as BlueOS-core versions, and they get bundled together in the Raspberry Pi images that can be flashed onto an SD card to install BlueOS onto it. For official BlueOS releases it is possible to update the BlueOS-bootstrap image to match the BlueOS release through the BlueOS Version chooser, and is the recommended process.

Manually updating to a non-matched and/or custom bootstrap image requires using the Terminal:

# drop down from blueos-core into the underlying operating system:
red-pill
# get the running bootstrap container id
CURRENT_BOOTSTRAP_CONTAINER=$(docker ps -aq --filter name=blueos-bootstrap)
# stop the bootstrap container (takes 10 seconds)
docker stop $CURRENT_BOOTSTRAP_CONTAINER
# remove the container from local memory
# (the underlying image remains on the system, unused)
docker container rm $CURRENT_BOOTSTRAP_CONTAINER
# specify the Docker image source (use your account if testing a change)
BOOTSTRAP_REPO=bluerobotics
BOOTSTRAP_IMAGE=blueos-bootstrap
# specify the new version to use (e.g. 1.1.0-beta.27, or master)
NEW_BOOTSTRAP_VERSION=1.1.0-beta.27
# start running the new version
# (will automatically download if it's not already available locally)
docker run \
    -d -t \
    --restart unless-stopped \
    --name blueos-bootstrap \
    --net=host \
    -v /root/.config/blueos/bootstrap:/root/.config/bootstrap \
    -v /var/run/docker.sock:/var/run/docker.sock \
    -e BLUEOS_CONFIG_PATH=/root/.config/blueos \
    $BOOTSTRAP_REPO/$BOOTSTRAP_IMAGE:$NEW_BOOTSTRAP_VERSION
# view the logs, to check for any error or progress messages
docker logs -f $BOOTSTRAP_IMAGE
# press ctrl+c to return to the terminal, and you're done
# if you want, type 'exit' or 'logout' to return to the BlueOS-core container

Edit this page on GitHub

← Advanced Usage