Manage docker image references
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.builder
.circleci
.vscode
cmd/dockmoor
dockfmt
dockproc
dockref
docktst/dockreftst
test_images
.gitignore
.travis.yml
CHANGELOG.md
CONTRIBUTING.md
Dockerfile
Gopkg.lock
Gopkg.toml
README.adoc
ROADMAP.md
guess-quality.sh

README.adoc

dockmoor

Build Status (Circle CI) Coveralls statement coverage Go Report Card GitHub release Follow @MeneDev on Twitter

Once you found a nice dock, it’s time to moor ⚓️
dockmoor helps you to create reproducible builds with Docker.

Features

Implemented

  • pin image references to currently used version to make builds reproducible

  • list image references

  • find Dockerfiles

  • filter by various predicates, e.g. untagged, latest, RegEx-match

Upcomming

  • communicate with docker registries to find images that are not pulled

  • find outdated image references

  • update to newer major, minor or patch version respecting SemVer

  • other formats: docker-compose, GitLab CI, Circle CI, Travis CI, …​

Examples

Note: all digests are abbreviated for better readability

pin command

The pin command queries a Docker daemon (local or remote) for images matching the used image references and tries to choose the most precise one.

Note the Docker daemon only knows pulled images!
Future dockmoor versions will be able to query repositories, too.

Pin well-known image references by tag only

Add missing tags and update tags to the most strict version.

dockmoor pin --no-digest pin-examples/Dockerfile-nginx

Given the following multi-stage dockerfile:

# originally untagged
FROM nginx
# originally tagged 1.15
FROM nginx:1.15
# originally tagged 1
FROM nginx:1
# originally tagged 1.15-alpine-perl
FROM nginx:1.15-alpine-perl

RUN something

We can see that nginx employs a widely used tagging strategy: the tags 1 and 1.15 are updated when 1.15.6 is published. All three tags refer to the same image until 1.15.7 is published.
Additionally different variants are separated from the version by a hyphen.

Executing the command will change the file to:

# originally untagged
FROM nginx:1.15.6
# originally tagged 1.15
FROM nginx:1.15.6
# originally tagged 1
FROM nginx:1.15.6
# originally tagged 1.15-alpine-perl
FROM nginx:1.15.5-alpine-perl

RUN something

Tags are only changed when a more strict version is found that referrers to the exact same image. The pin command will never try to update tags to a different (e.g. later) version.

In this example 1.15.6 refers to the same image as 1 and 1.15.
However, 1.15-alpine-perl referred to the 1.15.5-alpine-perl.

This example uses the --no-digest flag to pin image references by tag only. While tags are the way we usually address different image versions, we’ll learn in the next example that there is a better way.

Other properties of the command:
stdout is empty
stderr is empty
exit code: 0

Pin well-known image references by tag and digest

Pinning image references by tag, like we did in the previous example, helps creating more reproducible builds. However, as we also saw in the previous example, tags can be overwritten!

Fortunately dockmoor allows us to use tags and digests to pin our images.

Digests are a direct result of the actual content of the images and thus cannot be overwritten.

This is the default and recommended format: the version conveys semantic information, the digest ensures immutability.

File after execution:

# originally untagged
FROM nginx:1.15.6@sha256:31b..91
# originally tagged 1.15
FROM nginx:1.15.6@sha256:31b..91
# originally tagged 1
FROM nginx:1.15.6@sha256:31b..91
# originally tagged 1.15-alpine-perl
FROM nginx:1.15.5-alpine-perl@sha256:9c6..ae

RUN something

stdout is empty
stderr is empty
exit code: 0

Pin all image references in a dockerfile

File before execution:

FROM menedev/testimagea:1
FROM menedev/testimagea:1.0
FROM menedev/testimagea:1.0.0
FROM menedev/testimagea:1.0.1
FROM menedev/testimagea:1.1.0
FROM menedev/testimagea:1.1.1
FROM menedev/testimagea:2
FROM menedev/testimagea:2.0
FROM menedev/testimagea:2.0.0
FROM menedev/testimagea:latest
FROM menedev/testimagea

RUN something

File after execution:

FROM menedev/testimagea:1.1.1@sha256:1e2..24
FROM menedev/testimagea:1.0.1@sha256:c27..4b
FROM menedev/testimagea:1.0.0@sha256:f38..df
FROM menedev/testimagea:1.0.1@sha256:c27..4b
FROM menedev/testimagea:1.1.0@sha256:bf1..96
FROM menedev/testimagea:1.1.1@sha256:1e2..24
FROM menedev/testimagea:2.0.0@sha256:3d4..a1
FROM menedev/testimagea:2.0.0@sha256:3d4..a1
FROM menedev/testimagea:2.0.0@sha256:3d4..a1
FROM menedev/testimagea:2.0.0@sha256:3d4..a1
FROM menedev/testimagea:2.0.0@sha256:3d4..a1

RUN something

stdout is empty
stderr is empty
exit code: 0

Pin image references with latest or no tag in a dockerfile

dockmoor pin --latest pin-examples/Dockerfile-testimagea

File after execution:

FROM menedev/testimagea:1
FROM menedev/testimagea:1.0
FROM menedev/testimagea:1.0.0
FROM menedev/testimagea:1.0.1
FROM menedev/testimagea:1.1.0
FROM menedev/testimagea:1.1.1
FROM menedev/testimagea:2
FROM menedev/testimagea:2.0
FROM menedev/testimagea:2.0.0
FROM menedev/testimagea:2.0.0@sha256:3d4..a1
FROM menedev/testimagea:2.0.0@sha256:3d4..a1

RUN something

stdout is empty
stderr is empty
exit code: 0

list command

All single file examples refer to a multi-stage build Dockerfile

List all image references where the tag ends in -test

Surrounding strings with / enables regular expression based matching.

dockmoor list --tag=/-test$/ Dockerfile

stdout:

image-name:1.12-test
image-name:1.11-test
docker.io/library/image-name:latest-test
example.com/image-name:1.12-test
example.com/image-name:latest-test@sha256:2c4..cf

stderr is empty
exit code: 0

List all image references with latest or no tag from a specific domain in file

You can use multiple predicates to filter the matching image references. In this example the domain predicate is used together wih the latest predicate. Predicates are connected to a conjunction: all predicates must match.

dockmoor list --domain=example.com --latest Dockerfile

stdout:

example.com/image-name:latest@sha256:2c4..cf
example.com/other-image
example.com/other-image:latest

stderr is empty
exit code: 0

List all image references in file

dockmoor list Dockerfile

stdout:

image-name
image-name:latest
image-name:1.12
image-name:1.12-test
image-name:1.11-test
image-name@sha256:2c4..cf
docker.io/library/image-name:1.12@sha256:2c4..cf
docker.io/library/image-name
docker.io/library/image-name:latest
docker.io/library/image-name:latest-test
example.com/image-name:1.12
example.com/image-name:1.12-test
example.com/image-name:1.12-testing
example.com/image-name:latest@sha256:2c4..cf
example.com/image-name:latest-test@sha256:2c4..cf
example.com/image-name@sha256:2c4..cf
example.com/other-image
example.com/other-image:latest

stderr is empty
exit code: 0

List all image references with latest or no tag in file

dockmoor list --latest Dockerfile

stdout:

image-name
image-name:latest
docker.io/library/image-name
docker.io/library/image-name:latest
example.com/image-name:latest@sha256:2c4..cf
example.com/other-image
example.com/other-image:latest

stderr is empty
exit code: 0

List all unpinned image references

dockmoor list --unpinned Dockerfile

stdout:

image-name
image-name:latest
image-name:1.12
image-name:1.12-test
image-name:1.11-test
docker.io/library/image-name
docker.io/library/image-name:latest
docker.io/library/image-name:latest-test
example.com/image-name:1.12
example.com/image-name:1.12-test
example.com/image-name:1.12-testing
example.com/other-image
example.com/other-image:latest

stderr is empty
exit code: 0

Use unix find to list all unpinned image references

find some-folder/ -type f -exec dockmoor list --unpinned {} \; | sort | uniq

stdout:

nginx
nginx:1.15.3
nginx:latest

stderr is empty
exit code: 0

Use unix find to list all image references with latest/no tags

find some-folder/ -type f -exec dockmoor list --latest {} \; | sort | uniq

stdout:

nginx
nginx:latest

stderr is empty
exit code: 0

Use unix find to list all image references

find some-folder/ -type f -exec dockmoor list {} \; | sort | uniq

stdout:

nginx
nginx:1.15.3
nginx:1.15.3-alpine@sha256:2c4..cf
nginx:latest
nginx@sha256:db5..44

stderr is empty
exit code: 0

contains command

Use unix find to list all files containing unpinned references

find some-folder/ -type f -exec dockmoor contains --unpinned {} \; -print

stdout:

stderr is empty
exit code: 0

Use unix find to list all files containing latest/no tags

find some-folder/ -type f -exec dockmoor contains --latest {} \; -print

stdout:

stderr is empty
exit code: Unresolved directive in cmdContains.adoc - include::../end-to-end/results/containsLatestInFolder.exitCode[]

Test the format of a file

The contains command returns with exit code 0 when an image reference was found that matches. Using the --any predicate allows to match any file with a supported format that contains at least one image reference.

dockmoor contains Dockerfile

stdout is empty
stderr is empty
exit code: 0

dockmoor contains some-folder/NotADockerfile

stdout is empty
stderr is empty
exit code: 4

Supported Formats

Usage

dockmoor [OPTIONS] <contains | list | pin> [command-OPTIONS]

Application Options

-l, --log-level Sets the log-level (one of NONE, ERROR, WARN, INFO, DEBUG)

--version Show version and exit

-r, --resolver Strategy to resolve image references (one of dockerd)

Commands

contains command

dockmoor [OPTIONS] contains [contains-OPTIONS] InputFile

Test if a file contains image references with matching predicates. Returns exit code 0 when the given input contains at least one image reference that satisfy the given conditions and is of valid format, non-null otherwise

Domain Predicates

Limit matched image references depending on their domain

--domain Matches all images matching one of the specified domains. Surround with '/' for regex i.e. /regex/.

Name Predicates

Limit matched image references depending on their name

--name Matches all images matching one of the specified names (e.g. "docker.io/library/nginx"). Surround with '/' for regex i.e. /regex/.

-f, --familiar-name Matches all images matching one of the specified familiar names (e.g. "nginx"). Surround with '/' for regex i.e. /regex/.

--path Matches all images matching one of the specified paths (e.g. "library/nginx"). Surround with '/' for regex i.e. /regex/.

Tag Predicates

Limit matched image references depending on their tag

--untagged Matches images with no tag

--latest Matches images with latest or no tag. References with digest are only matched when explicit latest tag is present.

--tag Matches all images matching one of the specified tag. Surround with '/' for regex i.e. /regex/.

Digest Predicates

Limit matched image references depending on their digest

--unpinned Matches unpinned image references, i.e. image references without digest.

--digest Matches all image references with one of the provided digests.

list command

dockmoor [OPTIONS] list [list-OPTIONS] InputFile

List image references with matching predicates. Returns exit code 0 when the given input contains at least one image reference that satisfy the given conditions and is of valid format, non-null otherwise

Domain Predicates

Limit matched image references depending on their domain

--domain Matches all images matching one of the specified domains. Surround with '/' for regex i.e. /regex/.

Name Predicates

Limit matched image references depending on their name

--name Matches all images matching one of the specified names (e.g. "docker.io/library/nginx"). Surround with '/' for regex i.e. /regex/.

-f, --familiar-name Matches all images matching one of the specified familiar names (e.g. "nginx"). Surround with '/' for regex i.e. /regex/.

--path Matches all images matching one of the specified paths (e.g. "library/nginx"). Surround with '/' for regex i.e. /regex/.

Tag Predicates

Limit matched image references depending on their tag

--untagged Matches images with no tag

--latest Matches images with latest or no tag. References with digest are only matched when explicit latest tag is present.

--tag Matches all images matching one of the specified tag. Surround with '/' for regex i.e. /regex/.

Digest Predicates

Limit matched image references depending on their digest

--unpinned Matches unpinned image references, i.e. image references without digest.

--digest Matches all image references with one of the provided digests.

pin command

dockmoor [OPTIONS] pin [pin-OPTIONS] InputFile

Change image references to a more reproducible format by adding version tags or digest

Domain Predicates

Limit matched image references depending on their domain

--domain Matches all images matching one of the specified domains. Surround with '/' for regex i.e. /regex/.

Name Predicates

Limit matched image references depending on their name

--name Matches all images matching one of the specified names (e.g. "docker.io/library/nginx"). Surround with '/' for regex i.e. /regex/.

-f, --familiar-name Matches all images matching one of the specified familiar names (e.g. "nginx"). Surround with '/' for regex i.e. /regex/.

--path Matches all images matching one of the specified paths (e.g. "library/nginx"). Surround with '/' for regex i.e. /regex/.

Tag Predicates

Limit matched image references depending on their tag

--untagged Matches images with no tag

--latest Matches images with latest or no tag. References with digest are only matched when explicit latest tag is present.

--tag Matches all images matching one of the specified tag. Surround with '/' for regex i.e. /regex/.

Digest Predicates

Limit matched image references depending on their digest

--unpinned Matches unpinned image references, i.e. image references without digest.

--digest Matches all image references with one of the provided digests.

Reference format

Control the format of references, defaults are sensible, changes are not recommended

--force-domain Includes domain even in well-known references

--no-name Formats well-known references as digest only

--no-tag Don’t include the tag in the reference

--no-digest Don’t include the digest in the reference

Output parameters

Output parameters

-o, --output Output file to write to. If empty, input file will be used.

Building locally and Contributing

Appreciated! See CONTRIBUTING for details.

Roadmap

Currently dockmoor is in a very eraly stage and under constant development.

To get an idea where the journey will go, take a look at the Roadmap