Skip to content

Update Debian install documentation #12331

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
MichaIng wants to merge 5 commits into from
Closed

Update Debian install documentation #12331

Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
1145ee6
Update Debian install documentation
MichaIng Feb 14, 2021
ba531fb
Merge branch 'master' into patch-1
MichaIng Mar 2, 2021
4a9fbbd
Merge branch 'master' into patch-1
MichaIng Mar 2, 2021
cc818cb
Add linebreak
MichaIng Apr 24, 2021
2081ad1
Merge branch 'master' into patch-1
MichaIng Apr 24, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
63 changes: 25 additions & 38 deletions engine/install/debian.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,8 +19,7 @@ To get started with Docker Engine on Debian, make sure you

### OS requirements

To install Docker Engine, you need the 64-bit version of one of these Debian or
Raspbian versions:
To install Docker Engine, you need one of these Debian or Raspbian versions:

- Debian Bullseye 11 (testing)
- Debian Buster 10 (stable)
Expand Down Expand Up @@ -50,7 +49,7 @@ You can install Docker Engine in different ways, depending on your needs:
- Most users
[set up Docker's repositories](#install-using-the-repository) and install
from them, for ease of installation and upgrade tasks. This is the
recommended approach, except for Raspbian.
recommended approach.

- Some users download the DEB package and
[install it manually](#install-from-a-package) and manage
Expand All @@ -59,22 +58,16 @@ You can install Docker Engine in different ways, depending on your needs:

- In testing and development environments, some users choose to use automated
[convenience scripts](#install-using-the-convenience-script) to install Docker.
This is currently the only approach for Raspbian.

### Install using the repository

Before you install Docker Engine for the first time on a new host machine, you need
to set up the Docker repository. Afterward, you can install and update Docker
from the repository.

> **Raspbian users cannot use this method!**
>
> For Raspbian, installing using the repository is not yet supported. You must
> instead use the [convenience script](#install-using-the-convenience-script).

#### Set up the repository

{% assign download-url-base = "https://download.docker.com/linux/debian" %}
{% assign download-url-base = "https://download.docker.com/linux" %}

1. Update the `apt` package index and install packages to allow `apt` to use a
repository over HTTPS:
Expand All @@ -93,7 +86,7 @@ from the repository.
2. Add Docker's official GPG key:

```console
$ curl -fsSL {{ download-url-base }}/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg
$ curl -fsSL {{ download-url-base }}/debian/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg
```

3. Use the following command to set up the **stable** repository. To add the
Expand All @@ -104,48 +97,42 @@ from the repository.
> Debian distribution, such as `helium`. Sometimes, in a distribution
> like BunsenLabs Linux, you might need to change `$(lsb_release -cs)`
> to your parent Debian distribution. For example, if you are using
> `BunsenLabs Linux Helium`, you could use `stretch`. Docker does not offer any guarantees on untested
> `BunsenLabs Linux Helium`, you could use `stretch`. Docker does not offer any guarantees on untested
> and unsupported Debian distributions.

> **Note**: The `dpkg --print-architecture` sub-command below returns the native
> package architecture of your Debian distribution, such as `arm64`. If you want to install
> Docker for a foreign package architecture, replace `$(dpkg --print-architecture)`
> with e.g. `armhf` or `arm64`.

Comment on lines +103 to +107
Copy link
Member

@thaJeztah thaJeztah Mar 2, 2021

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm wondering if we should keep this note; would this be a common situation? Perhaps we should keep this as an exercise for the "advanced user", as it would likely not be a standard situation.

Reason why I'm leaning towards removing it, is that the "notes" (targeting non-standard situations) now take up more space than the actual instructions for the "standard" case;

Screenshot 2021-03-02 at 16 49 29

If we do think it's useful, perhaps we should move it inside each tab, and as a "non note", e.g.

The instruction above automatically configures the package repository for your
machine's native architecture. If you want to install Docker for a foreign
package architecture, replace `$(dpkg --print-architecture)` with the desired
architecture, such as `armhf` or `arm64`.

Copy link
Author

@MichaIng MichaIng Mar 2, 2021

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

As stated above, IMO the "arch=" tag could be removed, leaving it up to DPkg to simply pull the native architecture of the installed OS/distro. Especially with dpkg --print-architecture the outcome should be exactly the same. If someone has some special setup, where parts of the system intentionally consists of different architecture binaries, one must have known about that "arch=" tag before and will know if/how to apply it. But using it, matches to what the installer does: https://github.com/docker/docker-install/blob/master/install.sh#L379

Else I agree that the notes take too much space, so removing only the note about it should be fine as well. I added it mainly to be consistent with the note about the lsb_release command substitution note.

An alternative would be collapsible notes, if you have the pymdownx.details Markdown extension enabled?

Could be achieved with <details><summary> HTML5 tags manually as well.

If we do think it's useful, perhaps we should move it inside each tab,

But this doesn't "solve" the issue that the notes are much larger than the command block and adds the inconsistency that dpkg --print-architecture is explained inside the tab, while lsb_release is explained outside, even that for both basically the same is true: It is fine in 99% of cases and in the remaining rare cases, admin must have known already about their limitation on that system 😉.

Copy link
Author

@MichaIng MichaIng Apr 24, 2021 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@thaJeztah
To push this a bit:

  • I played with the details tag and it would require some more CSS to make it nice, which is out of scope for this PR.
  • Moving the note as text into the tab doubles the code and does not solve the issue that text blocks are larger than the command block. If only the blue note style is to prominent, then we could also un-note the two notes and leave them where they are.
  • I personally do not like to use two command substitutions but explain only one of them. Either we explain both or none, would be my very personal preference 😄. But I follow your preference, of course!

I finally suggest to remove dpkg --print-architecture completely, the note and also the code.

It is a no-op, as DPkg anyway installs packages for the major architecture (output of dpkg --print-architecture), even if the version was lower. Only if a package is not available for the major architecture, it looks into foreign architecture lists. Declaring the architecture explicitly would break that automatic behaviour, even that it is most likely wanted: Hypothetically a new ARMv9 architecture may be created that is backwards-compatible to ARMv8=arm64 and the Docker repo does not yet ship binaries for it. If arm64 is added as foreign architecture, without declaring the architecture in the list file, DPkg would automatically install the arm64 package that runs on that system. If arm64 were incompatible with that hypothetical ARMv9 CPU, then the admin would not add arm64 as foreign architecture, so that APT/DPkg would error out with a meaningful error message.

<ul class="nav nav-tabs">
<li class="active"><a data-toggle="tab" data-target="#x86_64_repo">x86_64 / amd64</a></li>
<li><a data-toggle="tab" data-target="#armhf_repo">armhf</a></li>
<li><a data-toggle="tab" data-target="#arm64_repo">arm64</a></li>
<li class="active"><a data-toggle="tab" data-target="#debian_repo">Debian</a></li>
<li><a data-toggle="tab" data-target="#raspbian_repo">Raspbian</a></li>
</ul>
<div class="tab-content">
<div id="x86_64_repo" class="tab-pane fade in active" markdown="1">
<div id="debian_repo" class="tab-pane fade in active" markdown="1">

```console
$ echo \
"deb [arch=amd64 signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] {{ download-url-base }} \
$(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
"deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] \
{{ download-url-base }}/debian \
$(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
```

</div>
<div id="armhf_repo" class="tab-pane fade" markdown="1">
<div id="raspbian_repo" class="tab-pane fade" markdown="1">

```console
$ echo \
"deb [arch=armhf signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] {{ download-url-base }} \
$(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
```

</div>
<div id="arm64_repo" class="tab-pane fade" markdown="1">

```console
$ echo \
"deb [arch=arm64 signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] {{ download-url-base }} \
$(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
"deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] {{ download-url-base }}/raspbian \
$(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
```

</div>
</div> <!-- tab-content -->

#### Install Docker Engine

This procedure works for Debian on `x86_64` / `amd64`, `armhf`, `arm64`, and Raspbian.

1. Update the `apt` package index, and install the _latest version_ of Docker
Engine and containerd, or go to the next step to install a specific version:

Expand All @@ -169,14 +156,14 @@ This procedure works for Debian on `x86_64` / `amd64`, `armhf`, `arm64`, and Ras
```console
$ apt-cache madison docker-ce

docker-ce | 5:18.09.1~3-0~debian-stretch | {{ download-url-base }} stretch/stable amd64 Packages
docker-ce | 5:18.09.0~3-0~debian-stretch | {{ download-url-base }} stretch/stable amd64 Packages
docker-ce | 18.06.1~ce~3-0~debian | {{ download-url-base }} stretch/stable amd64 Packages
docker-ce | 18.06.0~ce~3-0~debian | {{ download-url-base }} stretch/stable amd64 Packages
docker-ce | 5:20.10.3~3-0~debian-buster | {{ download-url-base }}/debian buster/stable amd64 Packages
docker-ce | 5:20.10.2~3-0~debian-buster | {{ download-url-base }}/debian buster/stable amd64 Packages
docker-ce | 18.06.3~ce~3-0~debian | {{ download-url-base }}/debian buster/stable amd64 Packages
docker-ce | 18.06.2~ce~3-0~debian | {{ download-url-base }}/debian buster/stable amd64 Packages
```

b. Install a specific version using the version string from the second column,
for example, `5:18.09.1~3-0~debian-stretch `.
for example, `5:20.10.3~3-0~debian-buster`.

```console
$ sudo apt-get install docker-ce=<VERSION_STRING> docker-ce-cli=<VERSION_STRING> containerd.io
Expand Down Expand Up @@ -209,7 +196,7 @@ If you cannot use Docker's repository to install Docker Engine, you can download
`.deb` file for your release and install it manually. You need to download
a new file each time you want to upgrade Docker.

1. Go to [`{{ download-url-base }}/dists/`]({{ download-url-base }}/dists/){: target="_blank" rel="noopener" class="_" },
1. Go to [`{{ download-url-base }}/debian/dists/`]({{ download-url-base }}/debian/dists/){: target="_blank" rel="noopener" class="_" },
choose your Debian version, then browse to `pool/stable/`, choose `amd64`,
`armhf`, or `arm64`, and download the `.deb` file for the Docker Engine
version you want to install.
Expand Down