Setting up pibs software with Docker

This setup is suitable for installation on a real pib and can be used as development enviromnent. Given experience with docker this setup is recommended over using the local installation.

Alternatively to installing pib’s software using the setup script as described here, it is possible to run the software stack using Docker. For a comprehensive overview and introduction to Docker check out the official documentation.

Note: As pib requires access to the speakers, microphone, USB devices (camera) and GPIO pins (motors), Docker for Windows and macOS are not supported as they do not have hardware support.

Software Overview

The pib software stack consists of two components: The backend, found in the pib-backend repository and the frontend (called Cerebra), found in the cerebra repository.

Cerebra is a web application developed using AngularJS. The backend consists of ROS2 Humble, a Flask API for configuration management and the Tinkerforge brick daemon that provides an API layer to control the motors of pib within ROS2.

Installation

Docker can either be set up with the provided installation script (Step 1.1.1) or by installing Docker manually (Step 1.1.2). Given experience with docker, step 1.1.2 is recommended.

1.1.1 With docker setup script

If you want to use Docker to setup a development enviroment on your own PC, it is strongly recommeded to install Docker yourself as described in Step 1.1.2 to avoid unwanted changes to your system settings.

The setup script in the pib-backend repository will automatically install the docker engine on Ubuntu, clone the necessary GitHub repositories, start the containers and apply the various system settings to the operating system that happen during the local installation (adjusting power mode, screen resolution on a Rasbperry Pi and more).

It can be executed using:

# Using the stable version
$ bash setup-pib.sh

# Using a specific nightly build
$ bash setup-pib.sh -b=<pib_backend_branch> -f=<cerebra_branch>

After the execution, the pib-backend and cerebra repository can be found inside a newly created app directory found in the home directory.

1.1.2 Without docker setup script

The software can also be installed without using the provided setup script:

1.2 Setting up the Voice Assistant

To setup the voice assistant functionality, create a password.env file in the root directory of pib-backend. This file (even if empty) is required for the containers to start. To use the voice assistant following parameters are required:

TRYB_URL_PREFIX=<base_url_tryb>

1.3 Common docker commands

For a more comprehensive overview of docker commands, check out this cheatsheet for the Docker CLI and this cheatsheet for docker-compose.

To run or stop docker containers, navigate with the terminal to either the cerebra or pib-backend directorys and run:

# start containers according to the docker-compose.yaml in the same directory
$ docker compose up

# run docker containers in detached mode (will keep running, even when closing the terminal)
$ docker compose up -d

# use profiles
$ docker compose --profile <profile_name1> --profile <profile_name2> up
# example, running the full pib-backend stack
$ docker compose --profile camera --profile motors profile voice_assistant up

# stop detached containers
$ docker compose down

# rebuild containers (e.g., after modifying the source code)
$ docker compose up --build --force-recreate

Show containers:

1.4 Final steps

After starting the docker containers for both, pib-backend and cerebra, you will be able to access Cerebra under localhost:8080 in your webbrowser of choice.