Docker

1. Installation

Note that these instructions assume you are starting from a 'fresh' Raspbian or Debian-like system installation. If you're using a Raspberry Pi there are plenty of good guides online on how to get setup, such as this one from the Raspberry Pi Foundation.

1.1. Docker

It is highly recommended that you use the latest version of Docker, rather than the one available from your systems default package repositories. If your system has docker installed already (Can you run a docker ps command and get some kind of response?) then you might want to uninstall these packages. On Debian-based system (Debian/Ubuntu/Raspbian), you can do this by running:

sudo apt-get remove docker-engine docker docker.io docker-ce docker-ce-cli docker-compose-plugin

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.

1.2. RTL-SDR Kernel Blacklisting

The RTL DVB kernel modules must first be blacklisted on the Docker host. RTL-SDR itself is not required on the Docker host. This can be accomplished using the following commands:

echo 'blacklist dvb_usb_rtl28xxu' | sudo tee /etc/modprobe.d/blacklist-dvb_usb_rtl28xxu.conf
sudo modprobe -r dvb_usb_rtl28xxu

If the modprobe -r command errors, a reboot may be required to unload the module.

1.3. Configuring radiosonde_auto_rx and creating a log directory

station.cfg should be configured as per Configuration-Settings. An example station.cfg can be found here.

Also ensure that an empty directory named log 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 ~/radiosonde_auto_rx/log
curl -o ~/radiosonde_auto_rx/station.cfg https://raw.githubusercontent.com/projecthorus/radiosonde_auto_rx/master/auto_rx/station.cfg.example

Make sure to edit ~/radiosonde_auto_rx/station.cfg to your requirements. e.g. if operating from a terminal, run nano ~/radiosonde_auto_rx/station.cfg to edit the file. It running from a GUI version of Raspbian, you can just open this file in a text editor.

1.4. Running the container

Make sure you have created the log directory and station.cfg file as per the above steps before running this command!

docker run \
  -d \
  --name radiosonde_auto_rx \
  --restart="always" \
  --device=/dev/bus/usb \
  --network=host \
  -v ~/radiosonde_auto_rx/station.cfg:/opt/auto_rx/station.cfg:ro \
  -v ~/radiosonde_auto_rx/log/:/opt/auto_rx/log/ \
  ghcr.io/projecthorus/radiosonde_auto_rx:latest

Note that the above is one single command spread across multiple lines. Copy and paste it into your terminal. If you want to use the testing branch, then replace latest with testing in the above command.

Once this is run, the auto_rx Docker image will automatically start on system boot.

Substitute ~/radiosonde_auto_rx/station.cfg and ~/radiosonde_auto_rx/log/ 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.

--restart="always" will result in the container automatically restarting after a failure or host system reboot, so you don't need to run this command again unless updating the docker image (see below).

You can check the status of the container by checking the log output:

docker logs --tail 50 --follow radiosonde_auto_rx

Once running, you can access the Web UI through http://<docker-host>:5000. If accessing a auto_rx instance running on a local machine, that address would be http://localhost:5000.

Debian / Raspbian Buster/Stretch Users - IMPORTANT

If you are running Debian or Raspbian Buster (or even older), 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

You can confirm you are experiencing this by running: docker logs radiosonde_auto_rx

If you can't update to a more recent version of Raspbian (please do...) then a quick solution is to log-in to the Raspberry Pi via SSH (or otherwise), and run the commands:

wget http://ftp.us.debian.org/debian/pool/main/libs/libseccomp/libseccomp2_2.5.1-1~bpo10+1_armhf.deb
sudo dpkg -i libseccomp2_2.5.1-1~bpo10+1_armhf.deb

Note that the above URL is valid for 32-bit Raspbian, running on a RPI 2/3/4 and Zero W2 only. For stations running on an original Zero W, you will probably need to use this link: http://ftp.us.debian.org/debian/pool/main/libs/libseccomp/libseccomp2_2.5.1-1~bpo10+1_armel.deb (untested)

Then, re-start the container by running:

docker stop radiosonde_auto_rx
docker start radiosonde_auto_rx

2. Other useful commands

2.1. Pulling the latest version of the container (Updating)

docker pull ghcr.io/projecthorus/radiosonde_auto_rx:latest

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

docker pull ghcr.io/projecthorus/radiosonde_auto_rx:latest
docker stop radiosonde_auto_rx
docker rm radiosonde_auto_rx
docker run \
  -d \
  --name radiosonde_auto_rx \
  --restart="always" \
  --device=/dev/bus/usb \
  --network=host \
  -v ~/radiosonde_auto_rx/station.cfg:/opt/auto_rx/station.cfg:ro \
  -v ~/radiosonde_auto_rx/log/:/opt/auto_rx/log/ \
  ghcr.io/projecthorus/radiosonde_auto_rx:latest

You can also switch to the testing branch of auto_rx by replacing latest with testing in the above commands.

Make sure to check the Configuration File Changelog for changes you may need to make to your station.cfg file.

2.2. Restarting the container

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

docker restart radiosonde_auto_rx

2.3. Stopping the container

docker stop radiosonde_auto_rx

2.4. Removing the container

docker rm radiosonde_auto_rx

2.5. Viewing the containers logs

All logs

docker logs radiosonde_auto_rx

Last 50 lines

docker logs --tail 50 radiosonde_auto_rx

Following the logs in real-time

docker logs --tail 50 --follow radiosonde_auto_rx

Opening a shell within an existing running container

docker exec -it radiosonde_auto_rx /bin/bash

3. Docker Compose (Advanced)

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:
  radiosonde_auto_rx:
    container_name: radiosonde_auto_rx
    devices:
      - /dev/bus/usb
    image: ghcr.io/projecthorus/radiosonde_auto_rx:latest
    network: host
    restart: always
    volumes:
      - ~/radiosonde_auto_rx/station.cfg:/opt/auto_rx/station.cfg:ro
      - ~/radiosonde_auto_rx/log/:/opt/auto_rx/log