docs: Pin docker to version 18.06

Docker 18.09 removed devicemapper support but did not provide an
alternative. This can cause problems for users so update the install
docs to install Docker at version 18.06 (the last version that supports
devicemapper).

This is a temporary solution until either docker provide an alternative
or we find a way to work around the Docker feature being removed.

Note the extra logic required for Fedora since 18.06 is not available
for that release.

Fixes #373.

Signed-off-by: James O. D. Hunt <[email protected]>

Author: jodh-intel

.ci/test-install-docs.sh

@@ -225,7 +225,18 @@ test_alternative_install_methods()
 
 run_tests()
 {
+	# If docker was installed by default, zap it.
+	$mgr -v remove-docker
+
 	test_distro_install_guide
+
+	# Remove docker in preparation for the next test.
+
+	# This is required # since docker may have been pinned (to ensure a
+	# particular version is installed). But when a package is pinned, you
+	# cannot change it (although you can remove it).
+	$mgr -v remove-docker
+
 	test_alternative_install_methods
 }
 

install/docker/centos-docker-install.md

@@ -5,13 +5,24 @@
 > - This guide assumes you have
 >   [already installed the Kata Containers packages](../centos-installation-guide.md).
 
-1. Install the latest version of Docker with the following commands:
-
-   > **Note:** This step is only required if Docker is not installed on the system.
+1. Install Docker with the following commands:
+
+   > **Notes:**
+   >
+   > - This step is only required if Docker is not installed on the system.
+   > - Newer versions of Docker have
+   >   [removed devicemapper support](https://github.com/kata-containers/documentation/issues/373)
+   >   so the commands below install the latest version which includes
+   >   devicemapper support.
+   > - To remove the lock on the docker package to allow it to be updated:
+   >   ```sh
+   >   $ sudo yum versionlock delete docker-ce
+   >   ```
 
    ```bash
    $ sudo yum-config-manager --add-repo https://download.docker.com/linux/centos/docker-ce.repo
-   $ sudo yum -y install docker-ce
+   $ sudo yum -y install 'docker-ce-18.06.1.ce-3*' yum-plugin-versionlock
+   $ sudo yum versionlock docker-ce
    ```
 
    For more information on installing Docker please refer to the

install/docker/debian-docker-install.md

@@ -6,16 +6,27 @@
 >   [already installed the Kata Containers packages](../debian-installation-guide.md).
 > - this guide allows for installation with `systemd` or `sysVinit` init systems
 
-1. Install the latest version of Docker with the following commands:
-
-   > **Note:** This step is only required if Docker is not installed on the system.
+1. Install Docker with the following commands:
+
+   > **Notes:**
+   >
+   > - This step is only required if Docker is not installed on the system.
+   > - Newer versions of Docker have
+   >   [removed devicemapper support](https://github.com/kata-containers/documentation/issues/373)
+   >   so the commands below install the latest version which includes
+   >   devicemapper support.
+   > - To remove the lock on the docker package to allow it to be updated:
+   >   ```sh
+   >   $ sudo apt-mark unhold docker-ce
+   >   ```
 
    ```bash
    $ sudo apt-get -y install apt-transport-https ca-certificates curl gnupg2 software-properties-common  
    $ curl -fsSL https://download.docker.com/linux/$(. /etc/os-release; echo "$ID")/gpg | sudo apt-key add -
    $ sudo add-apt-repository "deb https://download.docker.com/linux/$(. /etc/os-release; echo "$ID") $(lsb_release -cs) stable"
    $ sudo apt-get update
-   $ sudo apt-get -y install docker-ce
+   $ sudo -E apt-get -y install --allow-downgrades docker-ce='18.06.1~ce~3-0~debian'
+   $ sudo apt-mark hold docker-ce
    ```
 
    For more information on installing Docker please refer to the

install/docker/fedora-docker-install.md

@@ -5,14 +5,28 @@
 > - This guide assumes you have
 >   [already installed the Kata Containers packages](../fedora-installation-guide.md).
 
-1. Install the latest version of Docker with the following commands:
-
-   > **Note:** This step is only required if Docker is not installed on the system.
+1. Install Docker with the following commands:
+
+   > **Notes:**
+   >
+   > - This step is only required if Docker is not installed on the system.
+   > - Newer versions of Docker have
+   >   [removed devicemapper support](https://github.com/kata-containers/documentation/issues/373)
+   >   so the commands below install the latest version which includes
+   >   devicemapper support.
+   > - To remove the lock on the docker package to allow it to be updated:
+   >   ```sh
+   >   $ sudo dnf versionlock delete docker-ce
+   >   ```
 
    ```bash
+   $ source /etc/os-release
    $ sudo dnf config-manager --add-repo https://download.docker.com/linux/fedora/docker-ce.repo
    $ sudo dnf makecache
-   $ sudo dnf -y install docker-ce
+   $ docker_pkg='docker-ce-18.06.1.ce-3*'
+   $ [ "$VERSION_ID" -gt 28 ] && docker_pkg=docker-ce
+   $ sudo dnf -y install $docker_pkg python3-dnf-plugin-versionlock
+   $ sudo dnf versionlock docker-ce
    ```
 
    For more information on installing Docker please refer to the

install/docker/opensuse-docker-install.md

@@ -5,13 +5,24 @@
 > - This guide assumes you have
 >   [already installed the Kata Containers packages](../opensuse-installation-guide.md).
 
-1. Install the latest version of Docker with the following commands:
-
-   > **Note:** This step is only required if Docker is not installed on the system.
+1. Install Docker with the following commands:
+
+   > **Notes:**
+   >
+   > - This step is only required if Docker is not installed on the system.
+   > - Newer versions of Docker have
+   >   [removed devicemapper support](https://github.com/kata-containers/documentation/issues/373)
+   >   so the commands below install the latest version which includes
+   >   devicemapper support.
+   > - To remove the lock on the docker package to allow it to be updated:
+   >   ```sh
+   >   $ sudo zypper removelock docker
+   >   ```
 
    ```bash
    $ sudo zypper -n install libcgroup1
-   $ sudo zypper -n install docker
+   $ sudo zypper -n install -f docker-18.06.1_ce-51.1
+   $ sudo zypper addlock docker
    ```
 
    For more information on installing Docker please refer to the

install/docker/ubuntu-docker-install.md

@@ -5,17 +5,28 @@
 > - This guide assumes you have
 >   [already installed the Kata Containers packages](../ubuntu-installation-guide.md).
 
-1. Install the latest version of Docker with the following commands:
-
-   > **Note:** This step is only required if Docker is not installed on the system.
+1. Install Docker with the following commands:
+
+   > **Notes:**
+   >
+   > - This step is only required if Docker is not installed on the system.
+   > - Newer versions of Docker have
+   >   [removed devicemapper support](https://github.com/kata-containers/documentation/issues/373)
+   >   so the commands below install the latest version which includes
+   >   devicemapper support.
+   > - To remove the lock on the docker package to allow it to be updated:
+   >   ```sh
+   >   $ sudo apt-mark unhold docker-ce
+   >   ```
 
    ```bash
    $ sudo -E apt-get -y install apt-transport-https ca-certificates software-properties-common
    $ curl -sL https://download.docker.com/linux/ubuntu/gpg | sudo apt-key add -
    $ arch=$(dpkg --print-architecture)
    $ sudo -E add-apt-repository "deb [arch=${arch}] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable"
    $ sudo -E apt-get update
-   $ sudo -E apt-get -y install docker-ce
+   $ sudo -E apt-get -y install --allow-downgrades docker-ce='18.06.1~ce~3-0~ubuntu'
+   $ sudo apt-mark hold docker-ce
    ```
 
    For more information on installing Docker please refer to the