Docker

Installation

Docker

It is highly recommended that you use the latest version of Docker, rather than the one available from your systems default package repositories.

A quick way to install the latest version of Docker is by using the convenience script:

curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh

To be able to run docker commands as your non-root user (recommended), run:

sudo usermod -aG docker $(whoami)

You will need to logout and log back in afterwards to pick up the changes to group membership.

Configuring chasemapper and creating a log directory

horusmapper.cfg should be configured as per the guidelines in README.md. An example horusmapper.cfg can be found here.

Also ensure that an empty directory named log_files is available if you wish to retain log files.

A quick way to create these files, assuming you want to store them in your home directory, is:

mkdir -p ~/chasemapper/log_files
mkdir -p ~/Maps
curl -o ~/chasemapper/horusmapper.cfg https://raw.githubusercontent.com/projecthorus/chasemapper/master/horusmapper.cfg.example

Making sure to edit ~/chasemapper/horusmapper.cfg to your requirements.

If you are intending to use offline maps see here.

Running the container

docker run \
  -d \
  -t \
  --name chasemapper \
  --restart="always" \
  --device=/dev/ttyACM0 \
  --network=host \
  -v ~/chasemapper/horusmapper.cfg:/opt/chasemapper/horusmapper.cfg:ro \
  -v ~/chasemapper/log_files/:/opt/chasemapper/log_files/ \
  -v ~/Maps/:/opt/chasemapper/Maps/ \
  ghcr.io/projecthorus/chasemapper:latest

Substitute ~/chasemapper/horusmapper.cfg, ~/chasemapper/log_files/ and ~/Maps/ in the above command with the relevant local paths on your Docker host if not storing these in your home directory as per the above examples.

--device=/dev/ttyACM0 should reflect the location of your GPS device (e.g. this could be /dev/ttyUSB0). If not using a GPS device, remove this line.

--restart="always" will result in the container automatically restarting after a failure or host system reboot.

Once running, you can access the Web UI through http://<docker-host>:5001.

Debian / Raspbian Buster Users - IMPORTANT

If you are running Debian or Raspbian Buster, there is a known library incompatibility issue which will cause our docker images to not run, and may result in errors along the lines of:

Fatal Python error: init_interp_main: can't initialize time
Python runtime state: core initialized
PermissionError: [Errno 1] Operation not permitted

If you can't update to a more recent version of Raspbian (recommended!) then the solutions listed here should help resolve the issues: https://docs.linuxserver.io/faq#resolution-2

Other useful commands

Pulling the latest version of the container

docker pull ghcr.io/projecthorus/chasemapper:latest

You must then remove and recreate the container to use the newly pulled version, for example:

docker pull ghcr.io/projecthorus/chasemapper:latest
docker stop chasemapper
docker rm chasemapper
docker run \
  -d \
  --name chasemapper \
  --restart="always" \
  --device=/dev/ttyACM0 \
  --network=host \
  -v ~/chasemapper/horusmapper.cfg:/opt/chasemapper/horusmapper.cfg:ro \
  -v ~/chasemapper/log_files/:/opt/chasemapper/log_files/ \
  -v ~/Maps/:/opt/chasemapper/Maps/ \
  ghcr.io/projecthorus/chasemapper:latest

Make sure to set your USB GPS device as appropriate!

Restarting the container

Restarting the container is useful for picking up changes to horusmapper.cfg.

docker restart chasemapper

Stoping the container

docker stop chasemapper

Removing the container

docker rm chasemapper

Viewing the containers logs

All logs

docker logs chasemapper

Last 50 lines

docker logs --tail 50 chasemapper

Following the logs in real-time

docker logs --tail 50 --follow chasemapper

Opening a shell within an existing running container

docker exec -it chasemapper /bin/bash

Docker Compose

If you wish to use Docker Compose instead of the docker CLI, the following basic docker-compose.yml can be used as a starting point:

services:
  chasemapper:
    container_name: chasemapper
    devices:
      - /dev/ttyACM0
    image: ghcr.io/projecthorus/chasemapper:latest
    network: host
    restart: always
    tty: true
    volumes:
      - ./horusmapper.cfg:/opt/chasemapper/horusmapper.cfg:ro
      - chasemapper_logs:/opt/chasemapper/log_files/

volumes:
  chasemapper_logs:

horusmapper.cfg should be configured as per the guidelines in README.md. An example horusmapper.cfg can be found here.

/dev/ttyACM0 should reflect the location of your GPS device (e.g. this could be /dev/ttyUSB0). If not using a GPS device, remove the device section.

For help getting started with Docker Compose, @mikenye's ADS-B Reception, Decoding & Sharing with Docker guide is a great resource.