jille / dockpin

A tool for pinning Docker image and apt package versions

Dockpin

Install dockpin with: go install github.com/Jille/dockpin@latest

Dockpin helps you achieve repeatable builds. It pins base images in your Dockerfile, and packages you install with apt-get.

dockpin docker pin -f Dockerfile rewrites your Dockerfile to use the latest digest for each image. Docker will then use exactly that image until you upgrade it.

Dockpin can also pin apt packages, though it's slightly more complex:

$ (echo postgresql-12; echo curl) > dockpin-apt.pkgs
$ dockpin apt pin

then you can change your apt-get update && apt-get install -y postgresql-12 curl && apt-get clean && rm -rf /var/lib/apt/lists/* in your Dockerfile to:

FROM ghcr.io/jille/dockpin AS dockpin
FROM ubuntu:focal
COPY --from=dockpin /bin/dockpin /usr/local/sbin/dockpin
COPY dockpin-apt.lock /tmp
RUN /usr/local/sbin/dockpin apt install -p /tmp/dockpin-apt.lock
[...]

Why repeatable builds?

If you do a small cherrypick, to fix a bug, and you're going to roll that out to prod with an accelerated push, you don't want to accidentally also pick up a new Python version.

Increasingly more people do pin versions, but never upgrade and stay on that version forever. That makes security folks shudder.

Dockpin aims to make it easy to move to new versions when you want.

Docker pinning

This is pretty easy. You can either make dockpin rewrite your Dockerfile in place:

$ dockpin docker pin [-f your.Dockerfile]

or control output yourself:

$ dockpin docker pin -f - < Dockerfile.template > Dockerfile

Apt pinning

You should create a file called dockpin-apt.pkgs which contains one Debian/Ubuntu package per line. After that you can run dockpin apt pin which generates dockpin-apt.lock, which contains the URLs and size/hash of each .deb file to use.

When you run dockpin apt install in your Dockerfile, it will read (only) dockpin-apt.lock and install all the listed packages at the pinned versions.

The easiest way to get the dockpin binary in your Docker build is by grabbing it from the ghcr.io/jille/dockpin image (as shown in the example at the top of this README).

Note that the Debian/Ubuntu archives will eventually delete the old package you pinned from their mirrors. At that point you'll get an error when you try to build (rather than a silent upgrade). You can reproduce your build by somehow finding the old .deb file and changing the lock file to point at whichever URL you put it at. You can also COPY it into /var/cache/apt/archives/ and dockpin apt install will use that without downloading.

We rely on apt(8) to figure out which dependencies you already have / need to install. However, that does mean that we need to do the pinning on the same base image as you'll run dockpin apt install. We try to guess this automatically by parsing your Dockerfile, but that might fail and you'll need to pass --base-image=ubuntu:focal (or whatever image you use).

dockpin's Issues

Document how to install the dockpin binary

Automatic updates of pinned versions

Dockpin makes it easy to update your pinned versions, but automatic is even better than easy.

Maybe we should talk to the dependabot folks and see if they can run dockpin apt pin for us. (Dependabot can already bump Dockerfile digests to the latest version. I only implemented that in Dockpin so you can pin before submitting, and because dependabot doesn't pin unpinned images.)

alpine/apk support

We now support apt, but we should also add apk support (Alpine Linux) because it's heavily used with Docker.

Support APT's Pre-Depends

Some installations currently fail (notably some Python stuff) because it uses Pre-Depends which dockpin doesn't handle correctly.

Make it easy to cache the used .deb files

The Debian/Ubuntu mirrors don't keep old package versions forever. (Not that long even.) We should make it easy for our users to store the .deb files they need somewhere, so they don't run into trouble when the mirrors remove the old versions.

Neat advantage is also that dockpin apt install can then run without internet access.

Support Docker COPY --from=$image

In Dockerfiles you can also use COPY --from=$image to copy files from another image. We should pin those too.

Support for docker-compose files

It'd be neat to make it pin a digest in docker-compose files so they can be used to deliver a specific version, and re-pin them if you want upgrades.

Use the actual base image for apt pinning

docker apt pin spins up a new Docker container. That container should run on the exact same Debian/Ubuntu version as your Dockerfile will use, to minimize unexpected behavior. (For example a new base image version no longer including a dependency of the package you want to install. It won't be in your lock file if it was already installed when you pinned.)

lint mode

I'd like to run this in CI as a linter and have some options & useful output to show me the packages/images that aren't pinned.

Requiring the developer to make a change locally and decide how to pin (either using this and automatically updating) or choose a version manually.

Bug: Chokes on FROM <alias>

If you alias an image like FROM ... AS img and later use it with FROM img, we need to recognize that as an alias and not try to resolve it as a real image.