Adding proposed tag descriptions from #28

[retrohacker]

#28

[jlmitch5]

So do we not want to include the descriptions for what packages the images include? Here's what I had proposed earlier in that thread:

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.

[pesho]

Looks great 👍 Just a couple of suggestions:

1. Maybe it should be mentioned that -slim may require installing additional packages, for example if binary modules are used.
2. Most of the -slim section actually describes the default variant. Maybe that part should be moved to the default variant's section.

[pesho]

@jlmitch5 I think listing the packages one by one is redundant and will be difficult to maintain. A broad overview of the tags is more useful.

[jlmitch5]

Completely understand where you're coming from @pesho with this being difficult to maintain.

I will say that I'm not sure that the proposed file change would have answered my original question. Language like

If you are unsure about what your needs are, you probably want to use this one

would have had me going into the build-deps image to see what packages were actually included. If this was just me who had the issue, I wouldn't raise it, but I want to make sure that this would solve it for @davglass and @trodrigues who also indicated they had this issue, or at least others going forward.

[jlmitch5]

Actually, maybe we could link to the docker files that these are inheriting from in the sections?

Image Variants

The iojs images come in three flavors**, which inherit from the buildpack-deps images. Each is** designed for a specific use case.

[jlmitch5]

"Variants" (spelling)

[pesho]

@jlmitch5 listing the packages added by buildpack-deps one by one is not really useful information. For example, reading it, you won't easily realize that python is already installed (unless you remember that it's a dependency of mercurial). And most users won't really care that libxslt-dev is installed (that's just one example).

If you want to see all packages included in the image, just run the following:

docker run --rm -it iojs dpkg -l

Actually, maybe we could link to the docker files that these are inheriting from in the sections?

Yes, this is probably a good idea.

[retrohacker]

@jlmitch5 I totally agree that knowing which packages are installed is important (if not for security, but to quench our insatiable curiosity!). I also agree with @pesho that maintaining that list may become unmaintainable fairly quick. For the general discussion of "which should I use?" I think that the proposed wording answers that fairly well (which is, you should probably use the default tag). For those who want to know what these things are made of, perhaps stashing the output of dpkg --get-selections somewhere in the repo and hotlinking to it may be the answer?

Example output:

docker run -it iojs dpkg --get-selections

acl
adduser
apt
autoconf
automake
autotools-dev
base-files
base-passwd
...
xz-utils
zlib1g:amd64
zlib1g-dev:amd64

docker run -it iojs dpkg --get-selections | wc -l
405

[jlmitch5]

I did not even think about hierarchical packages being hidden @pesho, you're totally right!

The hot linking would be really cool @wblankenship. If that's too much of a step for a simple doc change, I understand it being not included. That could probably be part of a CI flow, but that's also a little bit crazy and excessive at the same time.

I still think linking back to the Docker Hub documentation for the buildpack-deps images would be cool, but I understand if it doesn't get put in.

My Docker workflow might be a little weird, but I tend to use it for development, and for that, I usually -v to a local dir and then just use containers as a runtime. I do mostly everything outside of the container (source control, file watching, etc.). If that's a typical thing people do, then maybe the Slim variant could get this in the docs as a use-case?

Thanks for your time and patience with me, I apologize if I'm getting too deep on this. I'm somewhat of a noob when it comes to contributing to large projects, and I want to be helpful, but I also don't want to waste y'alls time :)

[trodrigues]

This description seems a bit too complex to explain that slim has less packages than the default tag. I would suggest adding most of it to the description of the default tag such as:
"This tag is based off of buildpack-deps.buildpack-deps is designed for the average user of docker who has many images on thier system. It, by design, has a large number of extremely common debian packages. This reduces the number of packages that images that derive from it need to install, thus reducing the total size of all of your docker images on your system."

and keeping the description for slim something like:
"This image does not contain the common packages contained in the default tag. If you are working in an environment where only the iojs image will be deployed and you have space constraints, you can use this image, otherwise we highly recommend using the default image of this repository."

[trodrigues]

I think having just an explanation with no list of packages would be good enough. And yeah, a link to a a link to a generated list of packages would be great, but I think a link to the buildpack-deps images would suffice.

[retrohacker]

@jlmitch5 You aren't wasting time, in fact you are triggering a discussion that is getting documentation into the official repos 😄 This conversation was definitely needed!

The use case you described (using a container as a runtime environment for development) I believe would be perfect for the base tag. Unless you are exclusively using the iojs image, using multiple images built from build-packs:jessie will be much more space efficient than multiple images each built from debian:jessie. Docker uses a layered file system, and images can share layers. Inside a Dockerfile, (nearly?) every command creates a "layer" for that image. Having a single base image such as build-packs:jessie reduces the number of packages that need to collectively be installed in the RUN apt-get update && apt-get install ... layers for all of your images, thus reducing the size that the docker images take up on your filesystem.

That being said, if you exclusively use iojs you aren't gaining anything from a shared base image.

I like the idea of listing all of the packages that are contained in the image, but perhaps it would be more efficient to simply give the above command in documentation? Something like:

# Installed Packages

To view the packages installed in one of these containers, simply run:

`docker run -it iojs:[tag] dpkg --get-selections`

[yosifkit]

oooh, that sounds fun. Here is what I have started for all the official images: docker-library/docs#172 (work in progress).

[jlmitch5]

@wblankenship sweet, glad to be a non-nuisance! Your logic explaining why standard would be a good choice for my use case made good sense.

@yosifkit checked out your PR and it looks great. I think it would be pretty cool to add the Installed Packages section that @wblankenship mentioned to the official containers.

[Starefossen]

"The iojs Docker image comes in three flavors [...]"

[Starefossen]

A comprehensive list of all the installed packages are nice.. but maybe not super useful for most users? I would maybe argue that there should be a more Q&A style approach for more novice users as well.

I need x	Use image y
I need native addons	Use <version>
I need version control	Use <version>
I want to install my own system packages	Use <version>-slim
I am building derivative images	Use <version>-onbuild

[retrohacker]

I ❤️ the table. Is there a way we could make that work with docker-library/docs#172

[yosifkit]

Just a heads up: docker-library/docs#96 (comment).

Probably worth poking [email protected] to express interest 👍.

[Starefossen]

Thanks for the heads up @yosifkit!

[retrohacker]

Landed in docker-library/docs#172

[Starefossen]

Would it make sense to merge in docker-library/docs#172 to this repo @wblankenship ?

[retrohacker]

@Starefossen may not be a bad idea

[Starefossen]

I am closing this in favour of #52.