Missing documentation on how to properly specify image names / tags

[kastl-ars]

Dear all,

I am missing a simple documentation on how to properly use "image names" when building images.

(To be clear, docker.io/some/thing would be a name while latest would be a tag, at least in the following description. Unfortunately those are used interchangeable sometimes which is confusing...)

Imagine running something like the following:

pack build my-app ...

This results in a local image that is named docker.io/library/my-app and has the latest tag.

Running pack build localhost/whatever/my-app does not result in an image using localhost/whatever/my-app as the name, but prefixes it again with docker.io...

In contrast, building an image with podman build -t my-app . (using a Dockerfile) results in an image called localhost/my-app, i.e. it names the image using localhost to make sure it cannot be pushed accidentally.

Question

What would be the proper way to have pack build an image that is called localhost/my-app or localhost/something/my-app, without the docker.io prefix?

(I know I can add additional tags, but I want to avoid having multiple tags for the same image).

Can someone cleanup the confusion, please?

Kind Regards,
Johannes

[lMysticl]

Your observation is correct: this is an image-reference parsing issue, not a missing pack option.

The current pack release, v0.40.8, depends on go-containerregistry v0.21.5 and parses tag references through that library. Its parser does not recognize bare localhost as a registry component, so:

localhost/whatever/my-app

is normalized as a Docker Hub repository path.

The reliable single-tag workaround is to make the registry component explicit with a port:

pack build localhost:5000/whatever/my-app

Without --publish, pack still saves the image only to the local daemon; it does not push it to a registry, so no local registry needs to be running.

Creating the exact bare name localhost/whatever/my-app directly with the current release is not possible. The upstream fix to recognize bare localhost is still open: go-containerregistry #2322.

References: pack v0.40.8 dependency, tag parsing in pack, and pack export behavior.

[kastl-ars]

Thanks for the detailed answer!

[kastl-ars]

I have not used docker in a long time, but did Docker not just use the name without any prefix when building with docker build -t something:latest .? I take it that would also not be possible as pack always uses docker.io/library as a prefix in this case?

(I just want to understand the behaviour, as it might confuse new pack users...)