Skip to content

ubuntu: add instructions for updating package repositories #10285

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

Open
thaJeztah wants to merge 1 commit into
base: main
Choose a base branch
from
Open

ubuntu: add instructions for updating package repositories #10285

Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
53 changes: 53 additions & 0 deletions install/linux/docker-ce/ubuntu.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -40,6 +40,25 @@ versions:
Docker Engine - Community is supported on `x86_64` (or `amd64`), `armhf`, `arm64`, `s390x`
(IBM Z), and `ppc64le` (IBM Power) architectures.

### Intermediate (non-LTS) Ubuntu versions

Ubuntu intermediate (non-LTS) releases are [supported for 9 months](https://ubuntu.com/about/release-cycle){: target="_blank" class="_" },
after which they reach end-of-life (EOL). The package repositories at download.docker.com
may contain packages for older Ubuntu releases that reached EOL. These packages
may be outdated, and do not receive updates (including security updates).

For production use, we recommend installing the latest Ubuntu LTS version. If you
are running a non-LTS version of Ubuntu, make sure to upgrade to the latest supported
version. Be aware that Docker's release cycle may not align with Ubuntu releases,
which means that packages for the latest Ubuntu release may not be available at
the day of release. Before installing or upgrading, verify that Docker packages
are available for your version of Ubuntu.

When upgrading your Ubuntu version on a machine that already has Docker installed,
the `apt` repository may need to be updated to match the upgraded Ubuntu version.
Refer to the [update the repository after upgrading Ubuntu versions](#update-the-repository-after-upgrading-ubuntu-versions)
section below for details.

### Uninstall old versions

Older versions of Docker were called `docker`, `docker.io`, or `docker-engine`.
Expand Down Expand Up @@ -304,6 +323,40 @@ Continue to [Post-installation steps for Linux](/install/linux/linux-postinstall
to allow non-privileged users to run Docker commands and for other optional
configuration steps.

### Update the repository after upgrading Ubuntu versions

When upgrading your version of Ubuntu, the URL of the package repository may have
to be updated to match the Ubuntu version you have installed. Use the `apt-cache policy`
command to find the repository that is currently configured. The example below
shows that `apt` is configured to install packages for Ubuntu `disco` (19.04):

```bash
apt-cache policy | grep docker

500 https://download.docker.com/linux/ubuntu disco/stable amd64 Packages
origin download.docker.com
```

If the Ubuntu version in the output does not match the version you have installed,
the repository URL needs to be updated. To update the package repository to match
your current version, either removing all lines containing `download.docker.com`
in `/etc/apt/sources.list`, or use the `add-apt-repository --remove` command:

```bash
sudo add-apt-repository --remove "deb {{ download-url-base }} disco stable"
Copy link
Member Author

@thaJeztah thaJeztah Feb 13, 2020

Choose a reason for hiding this comment

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

@seemethere @tianon wondering if there's a way to remove all download.docker.com (using a wildcard?) references, and if we should add such a step to the get.docker.com installation script.

Copy link
Contributor

@tianon tianon Feb 13, 2020

Choose a reason for hiding this comment

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

IMO we should just make sure get.docker.com always uses the same filename, which solves the issue in a simpler way for folks who use the script.

We could do something clever here with find+sed to remove all references, but I think just an example grep to help them find the offending entries would be cleaner (and puts the onus of accidentally screwing up sources.list on the user instead 😅😇).

Copy link
Member Author

@thaJeztah thaJeztah Feb 13, 2020

Choose a reason for hiding this comment

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

IMO we should just make sure get.docker.com always uses the same filename, which solves the issue in a simpler way for folks who use the script.

You mean; instead of having separate directories/repositories for each version of the distro (disco, xenial, ..), have all packages in the same location (not exactly sure how the indexes work internally for .deb repositories 😅)? Or do you mean; make sure we always write the repository to a file inside /etc/apt/sources.list.d instead of append it to /etc/apt/sources.list/ ?

We could do something clever here with find+sed to remove all references, but I think just an example grep to help them find the offending entries would be cleaner (and puts the onus of accidentally screwing up sources.list on the user instead

Yes, so that was my main train of thought with using the add-apt-repository --remove utility to just remove it (assuming that's relatively safe, and wouldn't do harm to other repositories), followed by adding the new / right repository.

I could have a look at providing a grep example, or just keep it at "do whatever you usually do, but you likely want to be looking in this file" (as I have currently tried to write it); wdyt?

Copy link
Contributor

@tianon tianon Feb 13, 2020

Choose a reason for hiding this comment

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

Or do you mean; make sure we always write the repository to a file inside /etc/apt/sources.list.d instead of append it to /etc/apt/sources.list/ ?

Yeah, I just mean /etc/apt/sources.list.d/docker.list consistently like @seemethere mentioned. 👍

I could have a look at providing a grep example, or just keep it at "do whatever you usually do, but you likely want to be looking in this file" (as I have currently tried to write it); wdyt?

Yeah, my thought was something as simple as grep -rnF 'docker.com' /etc/apt/sources.list*, which should tell them where they've got an entry for it already:

$ grep -rnF 'docker.com' /etc/apt/sources.list*
/etc/apt/sources.list.d/docker.list:1:deb [ arch=amd64 ] https://download.docker.com/linux/debian buster stable

I'm definitely a fan of avoiding add-apt-repository because IMO it's extraneous (and isn't installed in minimal systems).

```

Verify that the repository was removed:

```bash
apt-cache policy | grep docker
```

After removing the old repository, continue with the steps outlined in [set up the
repository](#set-up-the-repository) to configure the correct package repository
for your Ubuntu version and to update or install the latest Docker release.


#### Upgrade Docker Engine - Community

To upgrade Docker Engine - Community, download the newer package file and repeat the
Expand Down