Update Debian install documentation

[MichaIng]

Proposed changes

"the 64-bit version of one of these Debian or Raspbian versions" might be confusing, since there is no 64-bit Raspbian, which is naturally an armv6hf (32-bit) only repository. The 64-bit Raspberry Pi OS uses the regular arm64 Debian repository. Remove the 64-bit mention from this sentence, as the supported architectures are listed below. Add "Raspbian Buster" explicitly to the supported OS list.

Do not use the deprecated "apt-key" command to add the repository key. Use "gpg --dearmor" instead to install the key as separate file into /etc/apt/trusted.gpg.d/. This fixes issue #11851. The deprecation warning can be seen e.g. in the Debian man pages: https://manpages.debian.org/testing/apt/apt-key.8.en.html

Do not use the "add-apt-repository" command to add the repository list. It does not work on Raspbian, due to a missing template file: https://github.com/RPi-Distro/repo/issues/160 Moreover, the passed command line arguments are the exact content that needs to be added to the list file, hence can be used with a simple "echo". EDIT: Fixed/implemented with: #11990

The manual repository install can be done on Raspbian as well, but the URL path needs to be adjusted. Since "lsb_release" cannot be used to print the distribution ID in lower case, to not add further string manipulation commands, instructions for Debian and Raspbian are separated into two tabs. The three tabs for the three supported package architectures have been merged by using "$(dpkg --print-architecture)". A note has been added to replace this command substitution, if a foreign architecture is wanted. It could be removed completely to let DPkg choose the native architecture automatically, or the next best added foreign architecture, if the native one is not provided by the repository. With this change, the method can be used on Raspbian, hence the information about which method is supported by which distribution, has been removed.

Do not expect the lsb_release command to be present, add the lsb-release package to the dependency list instead. ~"software-properties-common" is not required anymore as "add-apt-repository" is not used. To assure that the "gpg" command is available and the key can be handled by the system, add the "gnupg" package as well.~ EDIT: Fixed/implemented with: #11990

The apt-cache madison docker-ce example output has been updated to show current packages available on Debian Buster.

To support Debian and Raspbian, the MkDocs "download-url-base" variable has been truncated and "/debian" resp. "/raspbian" needs to be added literally when calling it.

The leading free spaces from the docker.list creation commands have been removed:

$ echo \
  "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

=>

$ echo \
"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

The reason is what with the spaces inside of the double quoted part, when copying the code, it will create additional free spaces inside of the resulting list file. IMO the leading command prompt sign $ could be removed as well, as it should be clear enough that it is a console command block, and this would enable one to copy the whole block. MkDocs even allows to add a little copy button to the top-right of the block. But that is a design choice as well, so I left it as it is.

[netlify[bot]]

Deploy preview for docsdocker ready!

Built with commit f59f4d963b1de8f41f1b440e0cc46f0a3d629aca

https://deploy-preview-12331--docsdocker.netlify.app

[netlify[bot]]

Deploy preview for docsdocker ready!

Built with commit 2081ad13dee9c7ca1120fedb09737e39e90aec4e

https://deploy-preview-12331--docsdocker.netlify.app

[MichaIng]

I recognised #11990 too late. As mentioned here I suggest to merge #11990 first and I'll merge and fix conflicts here afterwards to keep the tabs/support restructure for Raspbian.

[MichaIng]

Okay, the PR has been updated to include and resolve conflicts with #11990. It's main purpose is now to enable the manual repository key and list install on Raspbian, which is generally working pretty fine.

When the content itself is approved, I'll squash the commits and update the commit text.

[MichaIng]

Indeed, practically Ubuntu and Debian in this case are not further away from each other than Raspbian and Debian are. It's basically the distro path element in the repository URL, and of course the example apt-cache madison outputs nothing more, isn't it?

We had a similar discussion for our docs, whether very similar instructions should get their own page/tab or share the same with tabs only where they differ, the first being easier to maintain and the second easier to follow for users. Your idea with the includes actually sounds good. So you mean a shared template for Ubuntu, Debian and Raspbian, and then the differing blocks as includes and the differing single strings as variables or so? Sounds great, but you'll know better what is possible with your build software.

Also having a dedicated "Raspbian" page/link in the navigation likely makes Raspberry Pi users find it more certain to be the right docs for their system.

It would also fix some of the minor inconsistencies (e.g. currently we point to https://download.docker.com/linux/debian/gpg, but could point to https://download.docker.com/linux/raspbian/gpg, although the content of those are likely always gonna be the same)

At first I had two tabs for that as well, but actually it's the same key anyway, even the one inside the ubuntu dir is the same. Sadly the Fedora-family key is a different one, otherwise https://download.docker.com/linux/gpg could be used to have one key for all distros 🙂.

[usha-mandya]

@MichaIng Thanks for the PR. The master branch has been renamed to main. Some of the existing PRs have been automatically closed as a result of this change. Could you create a new PR against our latest docs if the suggested changes are still relevant? Thank you.

[MichaIng]

Jep, it got many conflicts anyway. I'll review current docs and in case redo the PR when I find time.