This is aimed for those who want to try out the client in docker and thinks it's a bit too complicated.
I will try to explain the basic concepts and how to get up and running.
My preferred distro is Debian 11 (bullseye) and this guide will be tailored for it, but there should only be small differences to others.
Images are usually hosted on a registry, for example hub.docker.com, from where you can pull them to your system.
They are the complete software bundled to run an application, in this case a debian image and a lot of packages installed that is required for satnogs-client.
Container is the running instance of an image and is basically an isolated environment where you run the app.
They are always start fresh from the image and can be modified, but it's non-persistent so after a stop any changes are lost.
Volumes is either a persistent storage for containers or bind-mounted to your host for configuration or storage.
Compose This is the main difference from the old guide, where everything is controlled with the docker-compose. In this file all the different services (essentially containers) are specified and all it's settings and relationships between them. The containers exist on a separate network in this configuration, so rigctld runs in its own container and the satnogs-client talks to it over this network. What this means is that you don't need a bunch of scripts to start/stop/update everything. It also means that you don't run several services in the same container. By default, it creates a stack that is named after the directory the compose file is located in.
Stack In this context, is the resulting containers, network, volumes etc. that is created and controlled with compose.
You will need to install the udev rules and blacklists on the host to make sure the devices get the proper permissions.
Additional software such as SoapySDR is not needed on the host, but can certainly be installed or if you already have a working ansible install etc.
Make sure to keep the host clock synchronized, this is absolutely essential and easily solved with ntp.
sudo apt install ntpThe individual sdr packages comes with udev rules and blacklists, but to simplify this and make the permissions the coherent we have compiled a custom list to accomplish this.
It uses the plugdev group and mode 0660 on all the devices.
Do note that any installed packages on the host, like rtl-sdr will possibly conflict with these, ymmv.
Basically just copy the 10-satnogs.rules to /etc/udev/rules.d/ and satnogs-blacklist.conf to /etc/modprobe.d/
(these are located in the lsf directory under this repo)
sudo cp 10-satnogs.rules /etc/udev/rules.d/
sudo cp satnogs-blacklist.conf /etc/modprobe.d/Reboot is the simplest way to apply these, manually doing rmmod and sudo udevadm control --reload-rules && sudo udevadm trigger also possible.
See the docker installation at the bottom of this page.
Start with creating a directory with a name representing the station, this will be shown in several places in the resulting stack. It is also separates multiple stations running on the same host.
mkdir -p station-351
cd station-351
wget https://github.com/kng/satnogs-client-docker/raw/main/lsf/docker-compose.yml
wget -O station.env https://github.com/kng/satnogs-client-docker/raw/main/lsf/station.env-distThe file station.env contains all the station variables (earlier in /etc/default/satnogs-client), some of the variables that is important to the function of the stack is located in the compose file.
Use your favourite editor to configure this:
nano station.envMake sure to populate all the lines that are not commented out as these are the important ones. Also note that the values should not be escaped with quotes or ticks.
User guide for satnogs-client configuration.
The docker-compose (on some systems it's docker compose without the hyphen) is the program controlling the creation, updating, building and termination of the stack.
The basic commands you will use is docker-compose up -d and docker-compose down.
When you edit the compose file or configuration it will try to figure out what needs to be done to bring the stack in sync of what has changed.
For example editing the SDR gain, it will recreate and restart the client but not rigctld.
Starting the stack (and updating after changed config):
docker-compose up -dStopping the stack:
docker-compose downUpdating the images and bringing the stack up:
docker-compose pull
docker-compose up -dOver time there will be old images accumulating, these can be removed with docker image prune -af
Inside each container, the logs are output to stdout, which makes them visible from outside the container in the logs. Starting to monitor the running stack:
docker-compose logs -fIf you want to run commands inside the containers, this can be done with the following command:
docker-compose exec satnogs_client bashThe container can be any of the running services, not possible in stopped container thou. Exit with Ctrl-D or typing exit.
In the maxed yml there's some additional services that can be run, for example rotator and auto-scheduler.
These can be copied in to the docker-compose.yml to be activated, do note additions in the section environment: in the service satnogs_client needs to be added as well.
In the past, the experimental setting switched the station software over to bleeding edge, but the drawback was that you could not go back to stable if there were issues. This is no longer the case, as these are separated in images and they can easily be switched between as often you like.
Editing the docker-compose.yml and going down to the satnogs_client service, the image: key specifies the image used.
In this case simply comment out the stable image and uncomment the unstable, or change to any other tag that might be available in the future.
Do note that this might break due to fundamental changes, like the recent switch to uid 500 instead of 999.
You also need to match the hamlib versions, 4.0 for client version 1.x and hamlib 4.5.4 for client version 2.x.
satnogs_client:
image: docker pull librespace/satnogs-client:master
user: '500'The available tags you can use is listed on gitlab registry and on dockerhub, two tags are available today: master and master-unstable.
Recreate the container with the usual docker-compose up -d
The addons image is documented here, there is a lot more functionality than just the gr-satellites integration.
The gr-satellites integration and addons can be activated by changing the image: in the service satnogs_client as seen in the commented lines below the default image.
Two images exist today, :lsf-addons which is bases on the stable :master, and :lsf-dev-addons which is based on experimental :master-unstable.
Some additional settings is needed to activate its functionality, simply remove the comment (#) in front of the following lines in station.env:
SATNOGS_PRE_OBSERVATION_SCRIPT=satnogs-pre {{ID}} {{FREQ}} {{TLE}} {{TIMESTAMP}} {{BAUD}} {{SCRIPT_NAME}}
SATNOGS_POST_OBSERVATION_SCRIPT=satnogs-post {{ID}} {{FREQ}} {{TLE}} {{TIMESTAMP}} {{BAUD}} {{SCRIPT_NAME}}
UDP_DUMP_HOST=0.0.0.0
Please note that the -pre/-post scripts need to exist in the image, else observations will fail, so make sure to comment out the above lines if you go back to the default image.
There is a lot more functionality in the addons, please check out the repo for the latest information.
TODO, building images, choosing own repos etc.
TODO, separating the directories by station name, adressning the rtl-sdr by ID.
If you are using Debian 12 bookworm the installation should be pretty straightforward as the packages are new enough.
sudo apt install docker.io apparmor docker-compose
sudo adduser $(whoami) dockerIn Debian 11 bullseye there is a docker package, but compose is too old, so we need to install it from backports:
sudo apt install docker.io apparmor
sudo apt -t bullseye-backports install docker-compose
sudo adduser $(whoami) dockerRe-login for the group permission to take effect.
The reason for using backports is the version of compose in bullseye is 1.25 and lacks cgroup support, the backport is version 1.27
If your dist doesn't have backports, enable with this, and try the installation of docker-compose again:
echo "deb http://deb.debian.org/debian bullseye-backports main contrib non-free" | sudo tee /etc/apt/sources.list.d/backports.list
sudo apt-key adv --keyserver keyserver.ubuntu.com --recv-keys 648ACFD622F3D138 0E98404D386FA1D9
sudo apt updateIf you cannot get a good compose version with your dist, please follow the official guide.
I made a small script to fetch the latest compose and buildx (YMMV) update-docker-cli.sh:
wget https://github.com/kng/satnogs-client-docker/raw/main/addons/update-docker-cli.sh
chmod 0755 update-docker-cli.sh
./update-docker-cli.shRecommended install: Portainer
docker volume create portainer_data
docker run -d \
-p 8000:8000 \
-p 9443:9443 \
--name portainer \
--restart=always \
-v /var/run/docker.sock:/var/run/docker.sock \
-v portainer_data:/data \
portainer/portainer-ce:latestThen browse to https://127.0.0.1:9443 (change to the correct host on the network) and follow the instruction, use local socket in the "Get started" section.
Refer to docker installation on how to get the latest installed on your system.
Short version, ymmv: Base image: Rasperry Pi OS 64bit or 32bit Lite (bullseye):
# already installed: ca-certificates curl lsb-release
# optional: tmux uidmap
sudo apt update
sudo apt upgrade -y
sudo apt install -y ca-certificates curl gnupg lsb-release git
curl -fsSL https://download.docker.com/linux/debian/gpg | sudo gpg --dearmor -o /etc/apt/trusted.gpg.d/docker.gpg
echo "deb https://download.docker.com/linux/debian $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin
# add user to docker group, avoid needing sudo, re-login to apply
sudo adduser $(whoami) docker