Skip to content

Latest commit

 

History

History
191 lines (129 loc) · 6.67 KB

reinstallation.md

File metadata and controls

191 lines (129 loc) · 6.67 KB
Raw

Maintaining docker + docker-compose

A lot of issues raised on SensorsIot/IOTstack and the IOTstack Discord channel turn out to have improper installation of docker and/or docker-compose as their underlying cause. The hows and whys of this happening are not really important. These instructions are intended to help you overcome such problems.

You can follow these instructions even if you did not use PiBuilder to build your Raspberry Pi in the first place.

General caveats

It's important to realise that, sometimes, things just get so messed up under the hood of a Raspberry Pi that a complete rebuild is your best solution. If you try these instructions but you still can't resolve the problem, it's likely that a complete rebuild is in your future. That is, of course, PiBuilder's raison d'être.

Preparation

Clone PiBuilder onto your Raspberry Pi:

$ cd
$ git clone https://github.com/Paraphraser/PiBuilder.git

It does not matter whether or not you used PiBuilder to build your Raspberry Pi. The idea here is to make sure you have the latest and greatest version of PiBuilder on your Raspberry Pi. If you previously cloned PiBuilder, make sure it is up-to-date:

$ cd ~/PiBuilder
$ git pull origin master

The nuclear option – getting a clean slate

Uninstalling docker, docker-compose

  1. Is any part of IOTstack running? If yes, run:

    $ cd ~/IOTstack
$ docker-compose down

  2. Are any other containers running, such as might have been started with docker run? If yes, you need to terminate each one. Here's an example:

    • List any running containers:

       $ docker ps --format "table {{.ID}}\t{{.Names}}"
 CONTAINER ID   NAMES
 060c1cbe3606   grafana

    • To terminate Grafana by using its container ID:

       $ docker stop 060c1cbe3606
 060c1cbe3606
 $ docker rm -f 060c1cbe3606
 060c1cbe3606

      The reason for using the ID rather than the name is that containers started via docker run sometimes do not have meaningful names.

    Repeat this process until there are no more running containers.

  3. Uninstall docker and docker-compose:

    $ cd ~/PiBuilder/boot/scripts/helpers
$ ./uninstall_docker.sh
$ ./uninstall_docker-compose.sh
$ sudo reboot

    Notes:

    • It is safe to run both of these uninstall_ commands even if you are not sure whether docker and docker-compose are installed.
    • The reboot is important. Trying to re-install docker without first doing a reboot risks creating a mess on your system.

Re-installing docker, docker-compose

PiBuilder's 04_setup.sh script installs docker and docker-compose:

$ cd ~/PiBuilder/boot/scripts
$ ./04_setup.sh

Note:

The 04_setup.sh script ends with a reboot. To restart your IOTstack:

$ cd ~/IOTstack
$ docker-compose up -d

Upgrading docker

After Docker has been installed by the 04_setup.sh script, it is upgraded via apt. You can use the standard system maintenance commands:

$ sudo apt update
$ apt list --upgradable
$ sudo apt upgrade

Note:

  • If an apt upgrade installs a new version of docker, that will restart your stack. That's why the apt list command is in the middle - so you can see whether docker will be upgraded and decide whether to proceed or defer the upgrade.

Upgrading docker-compose

This is a bit complicated. Start by running this command:

$ docker-compose version

If the answer is 1.29.2 or earlier then you should follow the steps above at:

If you have just run the 04_setup.sh script (either because you have just done a PiBuilder installation or because you were following these instructions) then docker-compose will be at version 2.x.x.

Option 1: let apt do the work

Once docker-compose has been installed by the 04_setup.sh script, it can be upgraded via apt so you can use the standard system maintenance commands:

$ sudo apt update
$ sudo apt upgrade

Option 2: upgrade docker-compose by hand

The problem with letting apt do the work is there seem to be significant delays between new versions of docker-compose being released on GitHub and making their way into the apt repositories.

At the time of writing (2022-09-15):

  • the apt version is v2.10.2. It was released on 2022-08-27.
  • the releases page has advanced to v2.11.1.

If you need a more-recent version of docker-compose, proceed like this:

$ cd ~/PiBuilder/boot/scripts/helpers
$ ./uninstall_docker-compose.sh
$ sudo ./install_docker-compose.sh v2.11.1

Notes:

  1. Replace "v2.11.1" with whatever version you need. The leading "v" is required.
  2. This uninstall/upgrade sequence can also be used to downgrade to any v2.x.x.
  3. Once you have used the install_docker-compose.sh script to upgrade docker-compose, the apt method will no longer work. If you want to revert to the apt method, you will need option 3.

Option 3: go back to letting apt do the work

You've tried upgrading docker-compose by hand but you've decided to go back to letting apt do the work:

$ cd ~/PiBuilder/boot/scripts/helpers
$ ./uninstall_docker-compose.sh
$ ./install_docker-compose-plugin.sh

Thereafter, an apt update followed by an apt upgrade will update docker-compose-plugin as and when a new version is released via the apt repositories. This is significantly slower than the speed with which new releases appear on the releases page. The release schedule for docker-compose-plugin appears to be tied to the release schedule for docker-ce.