What does sbt-native-packager's docker:publishLocal do?

Question

The docs say:

To build an image and store it in the local Docker server, use

docker:publishLocal

I'm just getting started with Docker and am not familiar with the concept of a "local Docker server". What is that and where should I look for the output of docker:publishLocal?

Answer 1

Docker server

The main components of Docker are described here: https://docs.docker.com/introduction/understanding-docker/#what-are-the-major-docker-components

What is described as a "Docker server" is the "Docker daemon" in the linked description. A Docker daemon runs on your local machine, and is usually the main point of contact for commands which are run by the docker binary.

Docker daemons perform a number of tasks including:

• starting containers
• stopping containers
• querying container status
• building images (the "filesystem" for a container)
• pushing images to the Docker index, or another image server (to make the image visible from outside your build machine)
• managing containers, restarting them if they stop

sbt-native-packager mappings of tasks to Docker actions

publishLocal

SBT uses the task named publishLocal to publish assets to local Ivy/Maven repositories (this is something that only exists on your machine).

The Docker support in sbt-native-packager tries to use the same task in a Docker context, so that sbt docker:publishLocal builds an image on your local Docker server. Just like publishing to Ivy or Maven locally, this action allows the image to be visible locally for development, but does not make it visible outside your local machine.

In practice, it maps to the command docker build -t "${projectName}:${version}"

You can then use this image with docker run "${projectName}:${version}", but only on your local machine.

publish

SBT uses the task named publish to publish assets to remote Ivy/Maven repositories. This requires extra configuration, to describe where to publish the image.

sbt-native-packager also tries to map this task to an appropriate action in a Docker context. So the plugin does a build of the image locally, followed by pushing the image to the appropriate remote image repository.

For this to work, you need to add the dockerRepository setting.

If this is set to a string without slashes, e.g. "username1", this will add "username1/" to the image name. When an attempt to push the image occurs, Docker will try to push the image to the public Docker registry at https://registry.hub.docker.com/ in the account of "username1".

If it is set to a string with slashes, e.g. "my.server1/username1", this will also add that string to the image name. This is similar to the previous case, except the Docker server will try to find a server called "my.server1" in DNS, and push to that instead of the public Docker registry.

In practice, it maps to

docker build -t "${dockerRepository}/${projectName}:${version}" . // working directory at `target/docker/stage` docker push "${dockerRepository}/${projectName}:${version}"

You can then use this image from your local machine, or other machines, with docker run "${dockerRepository}/${projectName}:${version}".

stage

The stage task creates a directory which contains all the files for the Docker image, in a format ready for sending to your Docker daemon. This directory is target/docker/stage. If you change your working directory to here and run docker build ., you would build an image using the contents of that directory.

Answer 2

Found the source code. It seems that docker:publishLocal maps to docker build -t [dockerTarget]

I'm using Play 2.3, which appears from the source currently is using sbt-native-packager 0.7.1. I'm not sure how to confirm that's the version I'm actually using from the SBT console. Docker support was added in 0.7.2, so I guess that's why I don't see anything happening. It appears to be silently do nothing in 0.7.1. I'm not sure why that is. I'd expect it to fail or something.

Submitted a change to upgrade Play to 0.7.2 though it was more difficult than I expected. Using sbt-native-packager 0.7.2, I now see some output located in target/docker/