Describe how to build a Docker image with an example

[wienans]

• Pull Request adds the docker tag command to the docs for container registry.

For Context i was using a own container registry the first time and also didn't pushed any docker images to docker.io so i wasn't aware of the necessity of the docker tag command. i only tried to follow the instructions in the page and got the error:

"An image does not exist locally with the tag: {domain}/{owner}/{image}:{tag}"

[KN4CK3R]

That's only related if you want to push an image you did not create in the first place. Maybe reword it to something like

If you want to push an existing image, you must re-tag it.

And add it below the push command section because that should be part of a docker tutorial which the Gitea docs are not.

[wienans]

That's only related if you want to push an image you did not create in the first place. Maybe reword it to something like

If you want to push an existing image, you must re-tag it.

And add it below the push command section because that should be part of a docker tutorial which the Gitea docs are not.

Mhm okay. Actually I created that image myself. So not like I wanted to upload the Ubuntu latest or something

[wienans]

@lunny moved the part under the full push section and added it as in case of an error.

[KN4CK3R]

I don't want to block the change but for me this is comparable to:

"We have a command load <file> which loads the file." Now the user executes load /does/not/exist and the command tells them "Can't find the file /does/not/exist". Would you expect that the documentation of load has the part: "If the command tells you the file can't be found, you must rename/move the file to what you passed as parameter to load." I would not expect that in the docs.

We already have a chapter https://docs.gitea.com/usage/packages/container#image-naming-convention which describes how the image name must be structured.

[wienans]

@KN4CK3R the confusing thing for me as a relative basic user of docker was that for me the tag was „latest“ and I didn’t get automatically that I need to write a new tag where the i needed tongue the domain image and tag into it.

My idea was to improve the handling for newer users. And I would have found that info in the doc helpful. But I also don’t mind if you don’t merge it.

[KN4CK3R]

I think you read the docs and may or may not have noticed the chapter I linked. Could we improve that block, so you don't run into the problem?
For example in that chapter I did not mention the tag (besides the ignored case) only how the image name must be structured. Would have adding :{tag} behind the examples helped you?

[wienans]

I saw the chapter but i did not consider it helpful for my issue. Because I wasn’t aware that the „name“ of an image is also called tag? For me the tag was always the :{tag} like latest. For example name of the image ubuntu and tag latest. So I think the double meaning of the tag got me confused.

I thought the naming convention part was only relevant for the server so that there is a structure. Maybe I should have been more sceptical because actually I expected a cli of docker push image:tag remote-url/owner/image:tag or something to say I want to push this image with this tag to that remote. But the cli is obviously not like that. So how would docker push find out which image to push where. Only by naming the image like the remote full path… so at least that is what I deducted out of the info’s I found.

Maybe it would be an idea to write in the naming convention part something about that this is actually meant as the „tag“ to make the connection to docker tag. But in the end that’s a naming problem from docker…

[KN4CK3R]

Because I wasn’t aware that the „name“ of an image is also called tag?

No no no 😅 The name of an image is the part infront of the :tag. The tag is not mentioned in the docs because it's not relevant in the first place.

The "image name" is {domain}/{owner}/{image}. Maybe that's the confusing part in the docs because in the "image name" is an additional {image}? If you know Docker, that's not a problem, because you know {image} should be something like apache and the prefix is the url to the docker registry. But for new users that may not be clear. If we can find a better wording for the naming chapter I'm happy to change it.

[wienans]

Because I wasn’t aware that the „name“ of an image is also called tag?

No no no 😅 The name of an image is the part infront of the :tag. The tag is not mentioned in the docs because it's not relevant in the first place.

The "image name" is {domain}/{owner}/{image}. Maybe that's the confusing part in the docs because in the "image name" is an additional {image}? If you know Docker, that's not a problem, because you know {image} should be something like apache and the prefix is the url to the docker registry. But for new users that may not be clear. If we can find a better wording for the naming chapter I'm happy to change it.

Okay that at least is what I thought before my confusion started. But then I think the problem for starters is that docker cli itself is confusing in this parts. It returns can not find tag while pushing but actually it can not find the image, because the image does not even exist. Sure also the tag does not exist on that image. And then the command to „rename“ it is called docker tag.

Regarding doc improvement as soon as you know about all this the current docs are no problem. Without that for beginners or people like me which never got in touch with that specific part of docker, it might be not clear what exactly is meant with the naming convention and how to apply it. Clearly you could quickly google how to use external registry with docker and stackoverflow will give you the answer, but I think it is worth adding 3 lines to the docs to reduce that need.
So in this case I still would add the specific command to the docs. But after the conversation with you I would put it under naming convention as a command to how to name your image like it is requested from gitea. But I think you are against adding this command at all to the doc, aren’t you?

[techknowlogick]

Perhaps a disclaimer that the hostname portion is required? And that otherwise docker will default to use docker hub?

[wienans]

@KN4CK3R Maybe like this?

[GiteaBot]

I was unable to create a backport for 1.21. @wienans, please send one manually. 🍵

go run ./contrib/backport 29047
...  // fix git conflicts if any
go run ./contrib/backport --continue

[KN4CK3R]

Do we need a backport for the docs?

[delvh]

Yes, as they are versioned.