1.1.1.1. Docker environment

This page outlines the steps to set up a Docker environment for building with the Proximie SDK.

Prerequisites

  • Ubuntu 22.04 or 24.04

  • Docker Engine; see Install Docker Engine on Ubuntu.

  • Ubuntu should be configured to use the XOrg/X11 display server, rather than Wayland; you can check this by running echo $XDG_SESSION_TYPE in a terminal – it should return x11.

Pull or build the Docker image

  1. Extract the Proximie SDK release archive to a directory of your choice, and open a terminal in that directory.

  2. Either:

    • Pull the pre-built image from Docker Hub (recommended):

      samples/environment/docker/scripts/pull_image.sh

      By default, this will pull the latest Ubuntu 24.04-based image appropriate for your hardware architecture. You can download older versions, Ubuntu 22.04-based images, or images for a different architecture by passing options; run pull_image.sh -h to see the options.

    • Or, use the provided Dockerfile to build the image:

      samples/environment/docker/scripts/build_image.sh

      This will take a while, depending on your system; the Docker build includes building Boost.

Create and start a container

To run a new container with the Proximie SDK environment, execute the following command:

samples/environment/docker/scripts/run_new_container.sh

By default this will run a container with a random name, configuring it to integrate with your host system’s X11 and PulseAudio for GUI applications and audio support. This container will persist if not removed, preserving any changes made during its lifetime, including across reboots.

This default behaviour can be customized; pass -h to see the help message for available options.

If you run a docker container manually without using the provided script, ensure that you set up X11 and PulseAudio integration as described in the script, as well as mounting or copying the Proximie SDK directory into the container.

Start an existing container

If you have a pre-existing container, e.g. one created as described in the previous section, you can start it with:

samples/environment/docker/scripts/start_existing_container.sh -n <container_name>

Replace <container_name> with the name of your existing container.

Using your container

The new container script exposes the extracted Proximie SDK directory to the container at /root/proximie-sdk, allowing you to access the SDK files directly from within the container.

Whether you created a new container or started an existing one, your terminal should now be attached to the container’s shell. You can now run commands as if you were in a normal Ubuntu environment, with the Proximie SDK and its dependencies available. For example, you can run one of the included samples:

samples/bin/hello-sdk

Our recommendation is to use Microsoft Visual Studio Code with the Dev Containers extension to “attach to a running container”. This allows you to browse and modify the container filesystem, and use VS Code in the usual way, including features like CMake builds, intellisense, debugging, etc. directly within the container environment.

A good next step is to build the included samples, which will help you verify that the environment is set up correctly. See Included samples for details on how to build the samples.