Document non-registry usage

[christianbauer]

The example https://github.com/gesellix-docker/gradle-docker-plugin-example/blob/master/build.gradle uses a registry. This is not the easiest, most trivial case for a build that uses Docker, which would be this:

1. Remove an old image
2. Build a new image
3. Stop existing container of image
4. Remove existing container of image
5. Start new container with image

Hence:

task rmImage(type: DockerRmiTask) {
    imageId = "foo"
}

task buildImage(type: DockerBuildTask) {
    dependsOn rmImage
    imageName = "foo"
    buildContextDirectory = file("/tmp/foo")
}

task stopContainer(type: DockerStopTask) {
    dependsOn buildImage
    containerId = "foo"
}

task rmContainer(type: DockerRmTask) {
    dependsOn stopContainer
    containerId = "foo"
}

task runContainer(type: DockerRunTask) {
    dependsOn rmContainer
    imageName = "foo"
    containerName = "foo"
}

And because of the very very confusing property/tag names in the tasks, and the forced pull in DockerClient#run(), this doesn't work at all:

:deployment:runContainer (Thread[main,5,main]) started.
:deployment:runContainer
Executing task ':deployment:runContainer' (up-to-date check took 0.0 secs) due to:
Task has not declared any outputs.
running run...
run container
pull image 'foo'...
using docker at 'http://localhost:4243'
response: HTTP/1.1 200 OK
[error:Error: image foo not found, errorDetail:[message:Error: image foo not found]]
:deployment:runContainer FAILED
:deployment:runContainer (Thread[main,5,main]) completed. Took 0.667 secs.

FAILURE: Build failed with an exception.

• What went wrong:
  Execution failed for task ':deployment:runContainer'.

  Cannot access last() element from an empty List

I don't want to upload or download anything to my registry for a trivial image build/run step.

[gesellix]

Well, please let me explain that the example doesn't try to show a most trivial build, but to show most features while still being realistic. Said that, I'd like to divide your suggestions/issues, just to make sure I got them right:

• show a trivial use case
• exclude push/pull to/from a registry in the example
• running a container fails due to pulling the image before creating a container
• confusing task properties

For the first two suggestions: yes, I can add another example just like you showed in your request. One nitpicking would be that I wouldn't prefer to make the buildImage task dependent on the rmImage task. This would effectively remove any implicit caching of image layers, which is a very important Docker feature imho.

I understand the third entry as problem in situations where you never push your images to a registry. So, the simplest solution would be to make the pull optional, and disabled by default.

The fourth entry in the above list is a bit harder. If you have any actual suggestions on renaming the task properties, please tell me.

I'd like to split this issue into three separate issues, is that ok for you?

[christianbauer]

This is for CI, so replacing the old image at some point is typical, after a successful integration test run for example. Whether I want to upload the resulting image to a repository is dependent on why the build was made, usually only after a release tag event etc. I think the naming of properties imageId/imageName/containerId/containerName/tag could be improved, for example, I had to read the source to see what "tag" does.

[gesellix]

... replacing the old image at some point is typical ...

Sure, but I would cleanup the old image after creating a new image. Otherwise one of the Docker features would essentially be disabled. I admit that this kind of optimization also depends on the use case and on the actual image build instructions.

...upload the resulting image to a repository is dependent on why the build was made...

That's ok for me, it's only a matter of changing the example script and just like you mentioned highly dependent on the actual use case.

... naming of properties...

It's a bit hard to find good property names while trying to keep them consistent with the official Docker documentation. But if I got you right, you would suggest to normalize the Id and Name postfixes? I could just remove them, which would fit to most examples of the Docker client syntax.

For the special case of tag I would expect the user to know what it means, given Docker repositories/images/containers as context. Or do you have other ideas to help people intuitively know how to use it?

[christianbauer]

I guess we agree that using a registry should be optional, especially for the most common steps, in whatever order. The "tag" I think was only available as a separate attribute in one of the tasks, which seems inconsistent to me. Caveat: I don't know the docker remote API and I'm currently trying to avoid learning it.

[gesellix]

Ok, so I'll start with splitting this issue and adding your example to the gradle-docker-plugin-example project without using the registry - which implies that I have to make the "pull before run" optional first. Stay tuned for updates! :)

[gesellix]

• run container should pull only when necessary docker-client#8
• document use case without registry gradle-docker-plugin-example#1
• rename task properties #14

[gesellix]

@christianbauer could you please review the three issues linked in my recent comment? In case there's something missing, please add a comment on the dedicated issue. Thanks!

[gesellix]

@christianbauer the issue regarding the run task to only pull when necessary has been fixed with the plugin version 2014-12-19T07-53-18.

[gesellix]

@christianbauer a simple build script has been added to the example project at https://github.com/gesellix-docker/gradle-docker-plugin-example/tree/master/build-and-run-locally

[gesellix]

the issue with confusing task property names will be handled in #14, so I'll close this issue here. Thanks for your feedback!