Skip to main content
Basis ships two Docker image targets. Both are defined in docker/Dockerfile and built from ubuntu:focal — Ubuntu 20.04 LTS, the last release with ROS 1 support.

basis-env

Base development image with Clang 18, CMake, Protobuf, and Python tooling.

basis-env-ros

Extends basis-env with ROS 1 Noetic packages for ROS-enabled builds.

​
What’s included

​
basis-env

ComponentDetails
Clang 18Compiler, clang++, clangd, clang-format, clang-tidy, lldb — set as the default CC/CXX
CMakeInstalled from the Kitware APT repository (replaces any pre-existing system CMake)
Protobuflibprotobuf-dev and protobuf-compiler
Build toolsmake, ninja-build, ccache, git, libstdc++-11-dev
Debugginglibdw-dev (for stack traces), lldb
Foxglove bridge depslibasio-dev, libssl-dev, libwebsocketpp-dev
Pythonpip with jsonschema, pyyaml, jinja2 (used by code generation)
UserA basis user with passwordless sudo and video group membership

​
basis-env-ros

Built on top of basis-env and additionally installs:
  • ros-noetic-roscpp-serialization
  • ros-noetic-std-msgs
  • ros-noetic-sensor-msgs (for tests)
  • rapidjson-dev (for rosx_introspection)

​
Building the images

Use docker/build-env.sh from the repository root: 
./docker/build-env.sh
This builds basis-env unconditionally. It then builds basis-env-ros unless the environment variable BASIS_ENABLE_ROS is set to 0: 
# Build only the base image, skip the ROS image
BASIS_ENABLE_ROS=0 ./docker/build-env.sh
You can pass additional docker build flags after the script arguments: 
# Pass --no-cache to force a clean rebuild
./docker/build-env.sh --no-cache
The full commands run internally are: 
docker build --tag basis-env --target basis-env -f docker/Dockerfile .
docker build --tag basis-env-ros --target basis-env-ros -f docker/Dockerfile .

​
Running the container

Use docker/run-env.sh: 
./docker/run-env.sh
If a container named basis is already running, this attaches to it via docker exec. Otherwise it starts a new container: 
docker run \
  -v $BASIS_ROOT:/basis \
  -v $BASIS_ROOT/../deterministic_replay:/deterministic_replay \
  --privileged \
  --name basis \
  --rm \
  -it \
  basis-env-ros \
  /bin/bash
Key details:
  • The repository root is mounted at /basis inside the container.
  • A deterministic_replay sibling directory (if present) is mounted at /deterministic_replay.
  • The container runs with --privileged to support hardware access (e.g., cameras via the video group).
  • The container is removed on exit (--rm).
  • The working directory inside the container is /basis.
You can pass extra Docker arguments via BASIS_DOCKER_ADDITIONAL_ARGS: 
BASIS_DOCKER_ADDITIONAL_ARGS="--gpus all" ./docker/run-env.sh

​
Building Basis inside the container

Once inside the container, build with CMake:
1

Create a build directory

mkdir -p /basis/build && cd /basis/build
2

Configure with CMake

cmake /basis
Or with options — see the table below.
3

Build

cmake --build . --parallel
4

Install

cmake --install .
Installs to /opt/basis/ by default.

​
CMake options

OptionDefaultDescription
BASIS_ENABLE_ROSOFFEnable ROS 1 Noetic support. Adds the BASIS_ENABLE_ROS=1 compile definition and sets BASIS_ROS_ROOT to /opt/ros/noetic.
BASIS_ENABLE_TESTINGON when top-levelBuild unit and integration tests. Enables CTest.
BASIS_INSTALL_DIR/opt/basisInstallation prefix for binaries, libraries, and plugins.
cmake /basis \
  -DBASIS_ENABLE_ROS=ON \
  -DBASIS_ENABLE_TESTING=OFF
Use Ninja for faster incremental builds inside the container:
cmake /basis -GNinja
cmake --build . --parallel

​
Environment setup

The container’s .bashrc sources /basis/bash/source_env.sh automatically. This script configures the runtime environment for installed Basis binaries: 
export BASIS_ROOT=/opt/basis/
export PATH=${PATH}:${BASIS_ROOT}/bin
export LD_LIBRARY_PATH=${LD_LIBRARY_PATH}:${BASIS_ROOT}/lib:${BASIS_ROOT}/plugins/serialization:${BASIS_ROOT}/plugins/transport:${BASIS_ROOT}/unit
To load this in a shell outside the container, source it manually: 
source /opt/basis/bash/source_env.sh

Build docs developers (and LLMs) love

Get started for freeTalk to us