Docs not clear on what the supported tags mean

[jlmitch5]

I was having trouble finding what the differences were for the various tags (standard, onbuild and slim). After browsing the various iojs dockerfiles (and the relevant buildpack-deps dockerfiles), it makes sense.

I wanted to propose an addition to the readme. I'm envisioning a Tag Details section that explains the difference between the standard and slim (gives details as to what packages standard gives you that slim doesn't). Happy to provide a pr, but wanted to check that this was wanted first.

[chorrell]

👍

I've been thinking about doing the same for Node docker image README as well. We recently added a wheezy variant and updated the slim variant to be leaner. A section that explains the differences between variants would be good.

[jlmitch5]

Okay cool, I'm going to work on this this evening @chorrell and I'll come to you with a draft to see what you think. Keeping the node/iojs container doc formats consistent would be a very good thing, I think :).

[jlmitch5]

@chorrell Here's what I'm thinking. I'm not thrilled with how the -onbuild tags are described, but having difficulty condensing that into something easily readable.

Tag Details

The official IOJS docker images augment the jessie buildpacks. The following packages are including in the various tag types the official iojs docker images support:

<version>-slim:

• These images include curl, wget and ca-certificates. Note that version control is not included out of the box.

<version>:

• These images include curl, wget, ca-certificates, bzr, git, mercurial, openssh-client, subversion, autoconf, build-essential, imagemagick, libbz2-dev, libcurl4-openssl-dev, libevent-dev, libffi-dev, libglib2.0-dev, libjpeg-dev, libmagickcore-dev, libmagickwand-dev, libmysqlclient-dev, libncurses-dev, libpq-dev, libreadline-dev, libsqlite3-dev, libssl-dev, libxml2-dev, libxslt-dev, libyaml-dev, zlib1g-dev.

<version>-onbuild:

• These images include all the packages from the <version>-tagged docker build, but will also install dependencies specified in a package.json file with npm and run npm start in the directory /usr/src/app, which it creates inside the container and copies a local directory you specify to.

[retrohacker]

iojs and node are not the only images with the -onbuild and -slim variants. It appears to be an unspoken standard at the moment.

The base version accommodates what is believed to be the standard use case, where you have a machine with a large number of docker images on it. In this case, a vast majority of the packages listed in your list above will be shared by most of those containers, thus having a single base image to build off dramatically reduces the overall size of all of the containers on that system.

The -slim variant is specifically designed for boxes where this image will be the only one deployed. I.E. if you have a service containerized and running on AWS all by itself, slim would probably be good for you.

-onbuild is for when you want to build an actual image from iojs, as opposed to starting a throwaway container. In this case FROM iojs:onbuild will usually be enough to package your image.

List of images with a -onbuild tag:

• rails
• jruby
• mono
• maven
• pypy
• iojs
• golang
• ruby
• python
• django
• node

Images using -slim:

• pypy
• iojs
• node
• ruby
• python

Perhaps we should attempt to have some sort of formal standard that onbuild and slim variants in the official repos adhere to (since it appears they already do)? //cc @tianon @jfrazelle

[jlmitch5]

Yes, the official docker images do share a fair bit and I think there's probably ways of standardizing this somewhat more. I also think there's some strange stuff going on wrt the build-deps standard image (does the iojs, or any of these images really need imagemagick by default?), but that's not really an issue w this repo.

But because it was brought up and we have some Docker maintainers cc'd in this (y'all rule btw!), I think there is a problem with standardizing this stuff across images of all languages. At the current moment, their seems to be a presumption of use-cases and also a somewhat delineated ability to cleanly and consistently state that "this official repo gets all the packages you expect plus these language-specific packages that you expect and will probably use 90% of the time".

Which brings me back to the real issue here--that I had to do some sleuthing into another repo to make the decision of if I needed the slim or the standard image, when that could be provided very easily by reading the README.md for this image either on Docker hub or github. In fact, if I was completely new to docker and this was the first image that I wanted to pull, I think I would be completely lost. At the same time, I now have started to realize that fixing this could make the documentation become out of sync with the actual packages being provided (if the builddeps upstream image does change what is available).

[trodrigues]

I just found this issue by looking for the answer to this same question: what do these tags mean?

I'd also like to see this being explained in the README, and while I do understand @jlmitch5 concern about it potentially getting outdated, until this becomes a standard documented somewhere else (and even then a link should be provided on the README), I think having this explanation would be better than nothing. Maybe together with a warning that it is dependent on the builddep images and it could potentially not reflect the actual provided dependencies.

[davglass]

I was looking for the difference between slim and onbuild too and had to look into the Dockerfiles to get the idea of the diff.

I like the README update that @jlmitch5 proposed, it reads well and answers some common questions.

Also, with upgrading to docker@1.5.0 the build command requires another CLI argument:

$ docker -v
Docker version 1.5.0, build a8a31ef

$ docker build -t iojs-app
docker: "build" requires 1 argument. See 'docker build --help'.

$ docker build --help

Usage: docker build [OPTIONS] PATH | URL | -

[yosifkit]

For the descriptions, I would love to have this for all images that have onbuild and/or slim versions.

@wblankenship would you mind if I take your description for iojs versions and make it generic for all the Official Images? We can have it automatically added to the docker hub readme based on whether these other tags exist.

[jlmitch5]

@davglass I think that you still need that param in older versions...it just used to be "." And now can be an absolute path? Might be wrong, I stopped following the progress of that issue in docker proper a few months ago unfortunately.

@yosifkit I think you might have been talking about my descriptions? @wblankenship was just referencing that these tags are common across several official images, not what was in 'em. Regardless, I think it'd be cool to generalize this language, though I don't know how that would work...pretty sure it's something that we would need to commit farther up the chain, and not just in the readme for the iojs image.

If we are ready for a pr, I can make it. If not and we want to go with something more general, feel free to take what I drafted and make it happen @yosifkit.

[retrohacker]

@yosifkit if you are referring to the open pull request aa25456

I think that would be a fantastic idea. 😄 It seems that this is a very frequent conversation. People often times people miss the point of buildpack-deps, especially since reading the Dockerfile gives very little insight into its benefits. Having a definitive document we can point to when these conversations pop up would be awesome!

[retrohacker]

@jlmitch5 I made commit request aa25456 a few days ago and failed to drop a link here and to open it as a pull request. It was built by combining previous discussions from: #9 and #5 along with the insight you provided above.

It is more of a proposal than an attempt at a final version. I find conversations like these are easier to digest in the form of a PR (line by line comments, etc). If we decide on a better format we can throw away aa25456 and open a new one.

[pesho]

pull request aa25456

@wblankenship why not make this into an actual PR? (right now it's just a commit in a branch)

[yosifkit]

Thanks @wblankenship and @jlmitch5. I'll work on a common one over in docker-library/docs and let you guys know what I come up with (and I hope that you make comments if I get off in the woods).

[retrohacker]

@pesho So I failed to post a link here AND actually open a PR 😉

[Starefossen]

Closing since the documentation of the tags was vastly improved in #52.