Deploy with Docker Compose

GISNav utilizes several Docker Compose services to establish its various deployment configurations. These services are orchestrated through a Makefile to improve convenience and facilitate adoption.

This page provides details on how to build and deploy these services, allowing for customization of GISNav's deployments beyond the capabilities provided by the Makefile.

Prerequisites

Docker Compose

You will need to have the Docker Compose plugin installed.

NVIDIA Container Toolkit Optional

You will need to have the NVIDIA Container Toolkit installed.

GISNav source code

Create a colcon workspace:

mkdir -p ~/colcon_ws/src

Clone latest version of GISNav and dependencies to colcon workspace:

cd ~/colcon_ws/src
git clone --branch v0.68.1 https://github.com/hmakelin/gisnav.git
git clone --branch 2.8.0 https://github.com/mavlink/mavros.git
git clone --branch release/1.14 https://github.com/px4/px4_msgs.git

Compose project name Optional

You must set the COMPOSE_PROJECT_NAME environment variable to have the value gisnav at minimum for the shell that you are running docker compose commands from. It is important that all Docker image and container names have the string gisnav in them since for example the expose-xhost Makefile recipe depends on this string being present to expose the X server only to the appropriate containers.

Persistent Recommended

echo "export COMPOSE_PROJECT_NAME=gisnav" >> ~/.bashrc
source ~/.bashrc

Current session

export COMPOSE_PROJECT_NAME=gisnav

Current shell only

COMPOSE_PROJECT_NAME=gisnav

This step is optional since the docker compose example commands on this page will use the -p gisnav option to ensure the project name is always specified.

Compose file stack

To improve maintainability, the Docker Compose configuration is split into multiple files.

A script that comes with the Debian package and is included in the source code helps you define the required configuration overlays for your specific system. Use the below examples to source the GISNAV_COMPOSE_FILES environment variable by directly invoking the script in the source code repository (you do not have to install the Debian package):

Persistent Recommended

source ~/colcon_ws/src/gisnav/debian/gisnav/usr/lib/gisnav/export_compose_files.sh ~/colcon_ws/src/gisnav/docker
echo "export GISNAV_COMPOSE_FILES=$GISNAV_COMPOSE_FILES" >> ~/.bashrc

Current session

source ~/colcon_ws/src/gisnav/debian/gisnav/usr/lib/gisnav/export_compose_files.sh ~/colcon_ws/src/gisnav/docker

You can then check that you are correctly parsing the Compose file stack by inspecting the resolved configuration in canonical format:

cd ~/colcon_ws/src/gisnav/docker
docker compose -p gisnav $GISNAV_COMPOSE_FILES config

Example deployments

The interdependencies between different services are hard-coded into the Docker Compose file using the depends_on key and typically you will need to start only a few services explicitly to get everything up and running.

Mock GPS demo

To deploy the mock GPS demonstration introduced locally without using the Makefile, follow the below steps to create, start, and shutdown the required containers. These steps simply repeat what the demo Makefile recipe would do.

Build images

cd ~/colcon_ws/src/gisnav/docker
docker compose $GISNAV_COMPOSE_FILES -p gisnav build gisnav px4

Create containers

cd ~/colcon_ws/src/gisnav/docker
docker compose $GISNAV_COMPOSE_FILES -p gisnav create gisnav px4

Expose X server to containers

This method is more secure as it only exposes the X server to containers with names containing "gisnav":

for containerId in $(docker ps -f name=gisnav -aq); do
    xhost +local:$(docker inspect --format='{{ .Config.Hostname }}' $containerId)
done

A recipe to expose the X server is also included in the Makefile expose-xhost target:

cd ~/colcon_ws/src/gisnav/docker
make expose-xhost

This method is easier but less secure as it exposes the X server to any client:

xhost +

Start containers

cd ~/colcon_ws/src/gisnav/docker
docker compose $GISNAV_COMPOSE_FILES -p gisnav start gisnav px4

Stop containers

cd ~/colcon_ws/src/gisnav/docker
docker compose $GISNAV_COMPOSE_FILES -p gisnav stop gisnav px4

Local development

When deploying for local development, the difference to deploying mock GPS demo is that we do not include the gisnav service which is assumed to be launched directly on the Docker host.

Remember to expose X server

Remember to expose your X server to your containers to ensure any GUIs are displayed properly.

Build images and create containers

cd ~/colcon_ws/src/gisnav/docker
docker compose $GISNAV_COMPOSE_FILES -p gisnav create --build \
    px4 \
    rviz

Start containers

cd ~/colcon_ws/src/gisnav/docker
docker compose $GISNAV_COMPOSE_FILES -p gisnav start \
    px4 \
    rviz

Stop containers

cd ~/colcon_ws/src/gisnav/docker
docker compose -p gisnav stop \
    px4 \
    rviz

After you have your supporting services deployed, you might be interested in launching a local GISNav app.

Private registry

Warning: Untested, not implemented

This is a suggested model for deploying Docker images which may be non-distributable, whether for licensing or other reasons, to a companion computer on a local network.

Todo

• Missing example commands, including building cross-platform images
• Should be moved to HIL section as this mainly concerns deployment on companion computers?

You can push the built Docker images to a private (or even air-gapped) Docker registry to simplify deployment to a companion computer.

The docker/docker-compose.yaml file uses the environment variables in the docker/.env file to determine the registry host, user namespace and port. These can be all changed to point to your private registry.