1.1.2. Docker environment

Proximie provides a Docker image containing a pre-configured environment for building with the Proximie SDK.

1.1.2.1. 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.

1.1.2.2. Obtaining the Docker image

While the Proximie SDK Docker image can be simply pulled from our Docker repository, we recommend using the scripts included in the Proximie SDK release archive (see SDK release archives) to pull (or build) the image and run containers.

The scripts contain additional functionality to ensure that the container is configured to integrate with your host system GUI and media subsystems.

Extract the Proximie SDK release archive to a directory of your choice, and open a terminal in that directory.
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

1.1.2.3. 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.

1.1.2.4. 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.

1.1.2.5. Installation of Dependencies

One of the advantages of using the provided Docker image is that it already includes all dependencies required to build and run applications using the Proximie SDK, so no additional setup is required. If you are using your own Docker image, you can either follow the instructions in the Host environment section to set up the necessary dependencies, or adapt the Dockerfile provided in the SDK release archive to build an image with the necessary dependencies.

1.1.2.6. 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.

Running the sample applications

As the release archive includes pre-built sample applications, you can run one of these to verify that the environment is set up correctly. For example, you can run the hello-sdk sample application using:

/root/proximie-sdk/samples/bin/hello-sdk

Building the sample applications

In order to verify that your environment is set up correctly for building applications including the SDK, you can build the included samples; see Building the samples for details.