Bug 1252097

Summary:	Some minor tweaks to "man Dockerfile".
Product:	[Fedora] Fedora	Reporter:	Robert P. J. Day <rpjday>
Component:	docker	Assignee:	Sally <somalley>
Status:	CLOSED CURRENTRELEASE	QA Contact:	Fedora Extras Quality Assurance <extras-qa>
Severity:	low	Docs Contact:
Priority:	unspecified
Version:	22	CC:	adimania, admiller, dwalsh, ichavero, jcajka, jchaloup, lsm5, miminar, vbatts
Target Milestone:	---
Target Release:	---
Hardware:	Unspecified
OS:	Unspecified
Whiteboard:
Fixed In Version:		Doc Type:	Bug Fix
Doc Text:		Story Points:	---
Clone Of:		Environment:
Last Closed:	2016-02-16 19:57:57 UTC	Type:	Bug
Regression:	---	Mount Type:	---
Documentation:	---	CRM:
Verified Versions:		Category:	---
oVirt Team:	---	RHEL 7.3 requirements from Atomic Host:
Cloudforms Team:	---	Target Upstream Version:
Embargoed:

Description Robert P. J. Day 2015-08-10 17:21:29 UTC

* Format of FROM instruction: In addition to the two variations shown in the man page, I understand there is also a "image@digest" form.

* Minor nit -- might be useful to add that MAINTAINER can also take a general URL that represents the owner of the Dockerfile, like http://fedoraproject.org/wiki/Cloud

* "There can be only one CMD in a Dockerfile." Well, no, there *can* be more than one but, as you point out in the next line, only the last one counts. I would reword that as, "There should be only one CMD in a Dockerfile."

* Apparently, the LABEL instruction can also accept a space instead of an equal sign -- that's not mentioned in the man page.

* Under "ENV", "RUN" is not in bold as are "ENTRYPOINT" and "CMD".

* Under "ADD", I don't see any mention that it can handle tarballs.

  I think that's it.

Comment 1 Robert P. J. Day 2015-08-21 11:45:58 UTC

  Couple more observations on "man Dockerfile", even though I think that entire page could be rewritten.

  First, there is no mention that both COPY and ADD can take archive-type arguments (tar, gzip, bzip2); *however*, I just learned that such archive files will be automatically unpacked only if they're local -- archives copied via URL will NOT be automatically unpacked. (Side note: https://labs.ctl.io/dockerfile-add-vs-copy/ is a decent blog post basically saying don't use ADD at all, and it makes a compelling argument.)

  Also, it might be worth mentioning that LABEL is useful not only for adding arbitrary metadata to an image, but in the context of atomic hosts as explained here:

https://github.com/projectatomic/atomic/

But that's a judgment call.

Comment 2 Daniel Walsh 2015-08-23 10:11:01 UTC

I think adding the information on ADD/COPY would be appropriate.  Adding information on LABEL, might be controversial, since we use it for tooling but not in docker in general.  Might be able to list some potential use cases of LABEL though.

Comment 3 Sally 2015-09-03 11:26:32 UTC

submitted https://github.com/docker/docker/pull/16043

Comment 4 Robert P. J. Day 2015-09-03 11:28:56 UTC

Seems to be a missing ] here:

LABEL [<key>[ <value>]

Comment 6 Sally 2015-09-05 12:33:05 UTC

merged https://github.com/docker/docker/pull/16043 (and fixed errant [) :)

Comment 7 Daniel Walsh 2015-09-06 10:53:15 UTC

Fixed in docker-1.9