Add deb822 apt sources to install section in Debian manual #23249

LLdaniel · 2025-08-15T08:37:44Z

Description

With Debian Trixie released the new apt sources format RFC822 is now the default.
This PR proposes a way to take this new format into account.

The goal would be to have the follwoing docker.sources:

$ cat /etc/apt/sources.list.d/docker.sources 
Types: deb
URIs: https://download.docker.com/linux/debian/
Suites: trixie
Components: stable
Signed-By: /etc/apt/keyrings/docker.gpg

Related issues or tickets

#15382 and #23231

Reviews

I am happy to change my PR if needed. Currently I was not sure if we should keep both formats or make the new deb822 format as default.
Maybe we could move the legacy format into an info box?

netlify · 2025-08-15T08:37:49Z

✅ Deploy Preview for docsdocker ready!

Name	Link
🔨 Latest commit	`e1d7d33`
🔍 Latest deploy log	https://app.netlify.com/projects/docsdocker/deploys/69075e019188ea0008d58058
😎 Deploy Preview	https://deploy-preview-23249--docsdocker.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

eshattow · 2025-08-15T15:56:18Z

content/manuals/engine/install/debian.md

     $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \
     sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
+
+   # Add the repository to Apt sources (new deb822 format, introduced with Trixie):


deb822 format was introduced in apt version 1.1 ten years before the release of Trixie

oh 😅 , thanks for that comment.
Did not know that, I can adjust the comment together with possible other review comments.

Maybe we should just say:

# Add the repository to Apt sources (deb822 format)

Drop this comment and the use of non-deb822 format sources

Addressed with 7e2650e

(Hope it is still ok to keep the original comment, which just stated # Add the repository to Apt sources:. The paragraph seemed to me a bit lonely without the comment. At least explanations about (non-)deb822 are gone now).

stalb · 2025-09-20T14:25:56Z

content/manuals/engine/install/debian.md

+   URIs: https://download.docker.com/linux/debian/\n\
+   Suites: $(. /etc/os-release && echo "$VERSION_CODENAME")\n\
+   Components: stable\n\
+   Signed-By: /etc/apt/keyrings/docker.gpg" | \


Suggested change

Signed-By: /etc/apt/keyrings/docker.gpg" | \

Signed-By: /etc/apt/keyrings/docker.asc" | \

Just a typo correction

Wrong way around. This should be a machine-readable file not ASCII export.

All right, then .gpg should be fine. Kept that in the newest commit 7e2650e

@LLdaniel @eshattow, the fact is, if you download an ASCII armored key, you have to dearmor it before using the binary version of the key.

So either you have to use the docker.asc (armored ASCII version), or you have to dearmor it first to get the binary docker.gpg version of the key!

Thanks for clarifying! Now I switched back to the originally used .asc.
But if you prefer gpg --dearmor I can also include that. Just let me know. 👍

Agreed, the armored version is much nicer for users to manage (and is what I personally use on my own systems).

For even more added context from the wiki page:

The reason why we avoid ASCII-Armored files is that they can only be used by SecureApt in version 1.4 or later (which appeared in stretch).

(even stretch LTS has been EOL since 2022, so we're extremely fine here)

content/manuals/engine/install/debian.md

make use of heredoc for better readability Co-authored-by: David Karlsson <[email protected]>

dvdksn

Looks good to me, thanks. Maybe @thaJeztah / @tianon could you help double-check? 🙇

eshattow · 2025-11-03T16:11:43Z

Looks good to me, thanks. Maybe @thaJeztah / @tianon could you help double-check? 🙇

It is wrong though. Look at https://wiki.debian.org/DebianRepository/UseThirdParty for the recommendations how this should be done.

tianon · 2025-11-03T16:34:11Z

It looks fine to me for documentation given to users - @eshattow can you be more specific about what you'd change?

tianon · 2025-11-03T16:36:19Z

(I don't think you meant for them to, but your comments in this thread are coming off pretty aggressive FYI)

stalb · 2025-11-03T17:41:23Z

@tianon, I think @eshattow just says it's better to use the de-armored version of the key (docker.gpg), since the ASCII-armored version will not work in versions older than Debian 12 or Ubuntu 22.04, which indeed is a real problem.

Simply add a line to generate the de-armored version of the key....

eshattow · 2025-11-04T06:06:30Z

It looks fine to me for documentation given to users - @eshattow can you be more specific about what you'd change?

There should not be ascii-armoured key installed to the user system. The guide recommended use of curl and sequoia are recent progressions to coincide with the stable release of Debian 13 Trixie.

(I don't think you meant for them to, but your comments in this thread are coming off pretty aggressive FYI)

I appreciate your code review. If the contributor for this pull request does not implement the required suggestions there is a pull request I have filed to get this done. I can follow up with any needed changes.

tianon · 2025-11-04T06:55:24Z

There should not be ascii-armoured key installed to the user system.

I'm not sure where you're getting such a strong exclusion from in that wiki page (if it's there, it's incorrect and should be fixed 😅).

From the relevant documentation in APT itself: 👀

https://manpages.debian.org/trixie/apt/apt-secure.8.en.html#USER_CONFIGURATION

Alternatively, keys may be placed in /etc/apt/keyrings for local keys, or /usr/share/keyrings for keys managed by packages, and then referenced by Signed-By: /etc/apt/keyrings/example-archive-keyring.asc option in a .sources file or using deb [signed-by=/etc/apt/keyrings/example-archive-keyring.asc] ... in the legacy .list format. This may be useful for APT versions prior to 2.4, which do not support embedded keys. ASCII-armored keys must use an extension of .asc, and unarmored keys an extension of .gpg.

the ASCII-armored version will not work in versions older than Debian 12 or Ubuntu 22.04

I'm confused by this - Ubuntu 20.04 is EOL (back in May), so 22.04 is the oldest Ubuntu that this needs to work on, and it does: 😅

$ docker run -it --rm --pull=always ubuntu:22.04
22.04: Pulling from library/ubuntu
Digest: sha256:09506232a8004baa32c47d68f1e5c307d648fdd59f5e7eaa42aaf87914100db3
Status: Image is up to date for ubuntu:22.04
root@ffb1c8368383:/# apt-get update &> /dev/null
root@ffb1c8368383:/# apt-get install -y ca-certificates curl &> /dev/null
root@ffb1c8368383:/# install -m 0755 -d /etc/apt/keyrings
root@ffb1c8368383:/# curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
root@ffb1c8368383:/# chmod a+r /etc/apt/keyrings/docker.asc
root@ffb1c8368383:/# tee /etc/apt/sources.list.d/docker.sources <<EOF
> Types: deb
> URIs: https://download.docker.com/linux/ubuntu
> Suites: $(. /etc/os-release && echo "$VERSION_CODENAME")
> Components: stable
> Signed-By: /etc/apt/keyrings/docker.asc
> EOF
Types: deb
URIs: https://download.docker.com/linux/ubuntu
Suites: jammy
Components: stable
Signed-By: /etc/apt/keyrings/docker.asc
root@ffb1c8368383:/# apt-get update
Get:1 https://download.docker.com/linux/ubuntu jammy InRelease [48.5 kB]
Get:2 https://download.docker.com/linux/ubuntu jammy/stable amd64 Packages [70.3 kB]
Hit:3 http://archive.ubuntu.com/ubuntu jammy InRelease                         
Hit:4 http://security.ubuntu.com/ubuntu jammy-security InRelease               
Hit:5 http://archive.ubuntu.com/ubuntu jammy-updates InRelease
Hit:6 http://archive.ubuntu.com/ubuntu jammy-backports InRelease
Fetched 119 kB in 43s (2767 B/s)
Reading package lists... Done

Similarly, Debian 11 is the oldest version of Debian that this needs to work on (even LTS for Debian 10 ended in June of 2024), and it does there too:

$ docker run -it --rm --pull=always debian:11
11: Pulling from library/debian
Digest: sha256:05bc4300f29708b0e6f4fa006ed3d16930baae91613416937c39e79dd9a095ac
Status: Image is up to date for debian:11
root@f7e21b97024e:/# apt-get update &> /dev/null
root@f7e21b97024e:/# apt-get install -y ca-certificates curl &> /dev/null
root@f7e21b97024e:/# install -m 0755 -d /etc/apt/keyrings
root@f7e21b97024e:/# curl -fsSL https://download.docker.com/linux/debian/gpg -o /etc/apt/keyrings/docker.asc
root@f7e21b97024e:/# chmod a+r /etc/apt/keyrings/docker.asc
root@f7e21b97024e:/# tee /etc/apt/sources.list.d/docker.sources <<EOF
> Types: deb
> URIs: https://download.docker.com/linux/debian
> Suites: $(. /etc/os-release && echo "$VERSION_CODENAME")
> Components: stable
> Signed-By: /etc/apt/keyrings/docker.asc
> EOF
Types: deb
URIs: https://download.docker.com/linux/debian
Suites: bullseye
Components: stable
Signed-By: /etc/apt/keyrings/docker.asc
root@f7e21b97024e:/# apt-get update
Hit:1 http://deb.debian.org/debian bullseye InRelease
Hit:2 http://deb.debian.org/debian-security bullseye-security InRelease
Hit:3 http://deb.debian.org/debian bullseye-updates InRelease
Get:4 https://download.docker.com/linux/debian bullseye InRelease [43.0 kB]
Get:5 https://download.docker.com/linux/debian bullseye/stable amd64 Packages [63.9 kB]
Fetched 107 kB in 0s (297 kB/s)     
Reading package lists... Done

So even with my "Debian hat" on, I think this change is great as-is and that recommending and using both deb822 and armored keys is very sane and very reasonable for all actively supported versions of both Debian and Ubuntu. 👍 🙇

LLdaniel added 2 commits August 15, 2025 10:11

add deb822 apt sources to install section in Debian

7ecb568

remove whitespaces in final sources file

3876ed7

LLdaniel requested review from ArthurFlag and thaJeztah as code owners August 15, 2025 08:37

github-actions bot added area/engine Issue affects Docker engine/daemon area/install Relates to installing a product labels Aug 15, 2025

eshattow reviewed Aug 15, 2025

View reviewed changes

stalb reviewed Sep 20, 2025

View reviewed changes

remove non-deb822 format sources

7e2650e

LLdaniel requested a review from usha-mandya as a code owner September 22, 2025 09:49

use armored ascii key instead of .gpg

2bc7ca9

eshattow mentioned this pull request Oct 27, 2025

Debian install doc updates (block indent, apt UI, Deb822 and cleanup) #23612

Closed

dvdksn reviewed Oct 28, 2025

View reviewed changes

content/manuals/engine/install/debian.md Outdated Show resolved Hide resolved

Update content/manuals/engine/install/debian.md

e1d7d33

make use of heredoc for better readability Co-authored-by: David Karlsson <[email protected]>

dvdksn approved these changes Nov 3, 2025

View reviewed changes

dvdksn merged commit feec852 into docker:main Nov 4, 2025
15 checks passed

This was referenced Nov 4, 2025

Compliance with Deb822: Deprecated sources.list use .sources instead #15382

Closed

APT install instructions for Debian 13 #23231

Closed

	Signed-By: /etc/apt/keyrings/docker.gpg" \| \
	Signed-By: /etc/apt/keyrings/docker.asc" \| \

Add deb822 apt sources to install section in Debian manual #23249

Add deb822 apt sources to install section in Debian manual #23249

Uh oh!

Conversation

LLdaniel commented Aug 15, 2025

Description

Related issues or tickets

Reviews

Uh oh!

netlify bot commented Aug 15, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for docsdocker ready!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

dvdksn left a comment

Choose a reason for hiding this comment

Uh oh!

eshattow commented Nov 3, 2025

Uh oh!

tianon commented Nov 3, 2025

Uh oh!

tianon commented Nov 3, 2025

Uh oh!

stalb commented Nov 3, 2025

Uh oh!

eshattow commented Nov 4, 2025

Uh oh!

tianon commented Nov 4, 2025

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

netlify bot commented Aug 15, 2025 •

edited

Loading