Play with Docker

Play Framework

What is the Play Framework? Play is an application framework popular for web applications and web services.

It offers non blocking requests, and many other innovative features and sub projects. The application code can be in either Java or Scala. And it runs on the JVM.

Docker

What is Docker? Docker is a virtualisation technology that create a simple abstraction layer to run containers for single use applications.

An application is dockerised by a DockerFile. The DockerFile describes what base image the application is built upon. E.g. a plain OS image such as Ubuntu Linux, or an image built on top of that with certain framework(s) already installed, e.g. Node.js, Django, etc. The DockerFile then describes further steps to build and run the application. Such as what further tools and frameworks to install, environment variables, what executable to run and ports to expose.

Downloading the internet

Play depends on a set of Ivy and Maven dependencies. And the application most likely depends on a further set of dependencies. And these dependencies have further transient dependencies.

These dependencies will all have to downloaded from central repositories. And you might need beyond 100 dependencies of a few megabytes each, so the total is often several hundred megabytes. On a fresh install where you need to download everything this is what is popularly is called downloading the internet.

Downloading this on a poor/slow internet connection is when you discover new profanities.

Obviously that is inefficient and on a local computer these dependencies are cached within a ~/.m2 or ~/.ivy2 folder. That way you only download new dependencies which is rare.

And at a organisational level you even prevent fresh installs from needing to download across the internet by using a local repository cache server, such as Artifactory, Nexus, etc.

Downloading the internet inside a Docker container

But when building a Play application with Docker, you do not have a pre populated ~/ivy2 folder. And if this is a public project you would not hard code in a dependency on a local maven repository server either.

So on each build it will download the internet. Every time.

Which is like frequently watching paint dry. And very frustrating when needing to test a new version if relying it on for Continuous Integration. It is also costly on network bandwidth.

This tutorial will discuss the possible solutions and work arounds to this problem.

Base image (FROM)

This bases the image on alpine:3.4 with Alpine Linux as the OS. Alpine is a very barebones OS with a small footprint and has become a very popular as a base Docker image.

Download and install Activator

The RUN wget ... part downloads Activator and install it. It removes the zip file to keep the footprint low. It also does this all in one RUN command to keep the changes within one Docker layer

You could include a pre downloaded zip file in your project folder. But for a public utility Dockerfile to avoid the suspicion of tampering of the zip file, I recommend the image downloads it from the source.

Application folders

• /opt/build: The application is built here and then later removed
• /opt/app: The compiled application is located here
• /etc/app: The configuration is copied here for ease of overriding
• /var/log/app: The application's logs

Executable

If you build Play with the stage command then Play framework creates executables in its target/universal/stage/bin folder. This Dockerfile renames the non Windows script and moves it to /opt/app/stage/bin/app.

Alternatively you can use the dist command, or SBT Assembly plugin to create a binary to execute.

You can extend the Entrypoint to include more configurations. E.g. an alternative configuration file:

Port

The application is available on port 9000. You can map that port to something else wherever you host your container. Port 9999 can also be exposed as a debug port.

Java base image

Instead of the OS only alpine image, you could use the OpenJDK one.

Activator base image

If you trust my Activator image you could save a further step by using it as a base image:

We use the minimal version of Activator. The dist version would mean a lot of unnecessary bloat in our Docker layer.

Mount Ivy & Maven folders

SBT will try to download all dependencies that it can not find in the local ~/ivy2 or ~/.m2 folders. If the binaries needed are present somehow in these folders you avoid downloading the internet.

I have with mixed success accomplished this by mounting my local ~/ivy2 or ~/.m2 folders into Docker.

It is not as simple as using the Volume parameter for Docker containers as it is the special Docker builder container that needs the folders present. Doing this varies on a Linux box, inside Vagrant and on a macOS/OSX machine with either boot2docker or xhyve/moby.

The problem is that you would have to do this on all clients that may build this image. So I do not recommend it.

I think some Continuous Integration providers such as CircleCI does this caching somehow in a better way.

Local repository

A better way is to tell SBT to first look in other locations before going across the internet to find dependencies. Such as a local maven repository server.

You can hard code in your projects build.sbt file the location of proxy repository resolvers:

But that is not very flexible so the prefered option is a special ~/.sbt/repositories file. The contents of this file depends on your set up. See the reference for examples. Below we have enabled local Ivy folders and proxy server called "special-repository", and commented out some other options. (Apologies about the small font, but the Ivy patterns are really stupidly long).

Create such a file in your projects conf folder. Then your Dockerfile may be altered like this:

Make sure the "COPY conf/repositories /root/.sbt/" line is before any Activator/SBT RUN commands.

Play base image

If you base your application on my Play Framework image, the dependencies for a plain Play application will be present. Which can be 80-100% of the dependencies you need. Your Dockerfile might look like:

If you don't want to use the image above you can create your own Play base image if you include this RUN step:

Which creates a plain play-scala application, builds it, downloads all dependencies for Play into ~/.ivy2, then deletes the application.

Application base image

If your application includes a lot of further dependencies, you might want to split the Dockerfile into an "application base" and a "application-main" image. That way the base is only built when framework or dependencies change, whilst the frequent code changes are only causing the main image to be built. Which should be a lot quicker.

Your base Dockerfile which might be located in sub folder of the project. It needs a build.sbt file which matches the projects, at least for the dependencies. The base Dockerfile might look something like this:

You may build and tag this as e.g.: yourorg/my-application-base. If many applications use the same dependencies this base image could be shared across these. The main Dockerfile might look something like:

This should now no longer download anything. As long as no dependencies are snapshots or different versions from the base image. It should only compile the application binary.

Manual binary build

You can build the JAR manually with e.g.:

Then a Dockerfile like this:

This is a much simpler Dockerfile. But is also much more fragile build as it depends on people and integration servers having pre-built the binary.

Integration server binary build

Most organisations will already be practicing the one-binary principle of building the JAR with continuous delivery processes. The project binary is built on a continuous integration server and uploaded to a Maven artifact repository.

Most likely you would assemble the one binary by adding SBT-Assembly to your projects plugins, and build the fat binary with:

To include that as part of the Docker build the Dockerfile might look like this:

The Dockerfile can be made smarter by querying your artifact repository for the latest version dynamically.

The start.sh file needs to call Java with the fat jar as classpath, alternatively with some options and then the start class of the application. (An example for a spray app).

Though many new projects are rethinking this process and move the one-binary principle from one JAR to one Docker image to avoid a two stage build process for each commit.

Run time configuration

You can override the configuration file used, per property or both.

Since we use Entrypoint (and not CMD) the command you run the image with only appends to that command, not replace it, which a CMD would do.

This executes the /opt/app/stage/bin/app but appends -Dconfig.file=/etc/app/docker.conf to it. The configuration file can be part of the application's source code in the conf folder, or it can be mounted as a Docker volume at runtime.

If you find all the application's Docker containers override with the same config file, then just modify the Dockerfile's Entrypoint:

Individual properties can also be overridden. Either via -DTHISPROPERTY=thisvalue or even better as a environment variable:

Then inside the conf/application.conf:

Image per environment

Some might prefer to bake different Docker images per environment. One way to do that is to use the ARG command.

For each build you need to specify what the ARG value is, e.g. staging, production, etc.