After my first post, a lot happened. First, the moment I moved my Dockerfile from my $projectDir root into a folder (docker/myapp/Dockerfile to declutter things), “everything” stopped working. A lot of tutorials and even the Transmode gradle docker plugin assume that your Dockerfile is in a standard location ($projectDir/Dockerfile) and if you step outside that, you’ll learn an awful lot about Docker build contexts and working directories.
To set some context, my application is a Spring Boot Java application (version 1.5.12-RELEASE). This became pertinent for me as a lot of the official Spring guides have defaulted to 2.x.x versions which have significant differences (notably the use of bootRepackage going away in favor of bootJar or bootWar).
So. I took a step back and yanked out the Transmode gradle plugin from my repository & embarked on learning how to do it all manually. A lot of the tasks listed below are very nicely handled by docker-compose but I figured that I needed to know the essentials first in order to troubleshoot when things go sideways. Here are the manual tasks:
- manually building my Docker images (the spring application + postgres).
- For the postgres image, I did not need to build one from scratch since there is an official image published on Dockerhub). You can read more about configuring the official image according to your needs.
- manually tagging and pushing both images to a remote registry (I practiced with both Dockerhub and the Heroku registry),
- manually setting up the network (this is a nice-to-have since apps in the same network are implicitly able to communicate with each other. Of course, the server needs to talk to the database so this was the first step)
- manually running the postgres application (since the database needs to be up before the server)
- manually running the server application
Once I verified that I could repeatedly perform steps 1 – 5, I decided to investigate the Palantir Gradle Docker plugin since I’d like to eventually get away from the lengthy Docker commands and move to gradle tasks for the entire process. The Palantir plugin is more robust than the Transmode plugin and in my opinion, it’s a little clearer to understand what is happening.
For the rest of this post, my focus will be on the image generation step and I’ll share my commands from the perspective of one whose Dockerfile is not in the typical location i.e. $projectDir/Dockerfile. Instead, my Dockerfile is located at $projectDir/docker/myapp/Dockerfile. I’ll outline the manual steps and the corresponding gradle task configuration (using the Palantir Gradle Docker plugin).
Building your Docker image for a 1.5.x Spring boot app
The basics of the Dockerfile (what is it, etc) are on the Docker docs. The biggest issue I ran into was getting the COPY task to work the same whether the step was manual or via the gradle task. The recommendation I can share is to use a placeholder argument for the location of the jar file to be copied. When manually generating your image, you will then pass in the value of the ARG. Here’s the full command which was run at the root of my project. Compare with the Spring guide configuration:
docker build --build-arg JAR_FILE=build/libs/AppServer-0.0.1-SNAPSHOT.jar -t myapp-server:beta -f docker\myapp-server\Dockerfile .
The -t flag sets the friendly name of the image you intend to build. -f sets the location of the Dockerfile and the last argument is a dot (this is important to set the working directory for Docker. Update this accordingly). Here's what my Dockerfile looks like.
In the official Spring guide to dockerizing your Spring app, you can also see how the ARG is declared and referenced in the COPY task later. Note: the official Spring guide is written with the Palantir Gradle Docker plugin and Spring 2.x.x in mind. So, I had to do things a little differently mainly:
- When setting up the Palantir Gradle Docker plugin, you need to specify the maven url (it's not in mavenCentral) so that bit me. I also opted to use the 'traditional' way of applying the plugin since the newer and more expressive way seems to have some kinks. As an aside, I've created a PR to include this bit of information to the guide.
- The gradle configuration in the guide could do with a bit more explanation i.e. the why. Nevertheless, with a lot of trial/error and reading various docs (Spring, Docker, Stackoverflow, etc), I was able to come up with a configuration that works for my Spring Boot application. Here are my settings
docker {
dependsOn bootRepackage
name "$dockerImageName:$dockerImageVersion"
tags "$dockerImageVersion"
//located in the build context which is a folder in build/docker
dockerfile file("docker/Dockerfile")
//directly reference the Jar file in the Dockerfile
def artifact = "$projectName-${projectVersion}.jar"
// copies artifact + Dockerfile to the build context
files "$libsDir/$artifact", "$projectDir/docker/$dockerImageName/Dockerfile"
//passing in the jar file location via --build-arg key=value
buildArgs(['JAR_FILE' : artifact])
pull false
noCache true
}
Compare with the Spring guide configuration:
docker {
dependsOn build
name "${project.group}/${bootJar.baseName}"
files bootJar.archivePath
buildArgs(['JAR_FILE': "${bootJar.archiveName}"])
}
- The main diferences are:
- What the docker task depends on. In my case, I depend on the bootRepackage task since within my file config setting, I'm fetching the generated jar file from my $libsDir to be copied into the Docker build context along with the Dockerfile from its original location.
- Another difference is the use of bootJar task which, for those of us still on 1.5.x, is absent.
- In the Palantir readme, you'll observe how the output of a task is fetched like so
files tasks.distTar.outputs, 'file1.txt', 'file2.txt'
. You may be tempted to do something like tasks.jar.outputs but your Spring application won't be packaged correctly although image generation will succeed (running a jar generated this way will result in an error message about the missing main class). My solution was to depend on the bootRepackage task in order to retrieve the full jar file from the expected location.
- I've attempted to comment the code in my docker task configuration but I welcome improvements for clarity/correction. A lot of the information I've gleaned is largely from trial/error. Finally, to run the gradle tasks, here's a verbose command I use which comes in handy when troubleshooting gradle tasks failures. gradlew clean docker --console=plain --stacktrace
Running your Docker app
Okay, we've got the image generation out of the way. It is important to validate that you can run the application before calling it a day. For my purposes, I need to validate that my image was generated correctly and that I could run it with all the needed environment variables (which includes api keys, secrets, and the like). To avoid leaking my secrets, I created a .env file in a location outside of my repository. I was able to run & validate my app two ways: manually and via docker-compose. Note: the Palantir plugin also has a way to programmatically setup your docker-compose file but that's a work in progress.
- Running my image manually with multiple arguments.
- TL;DR - docker run command
- Within my docker run command, I'm setting the container name ( --name myapp-server), linking it to my postgres container ( --link myapp-db unnecessary since they both belong to the same network but eh) , mapping volumes ( v C:/Users/jane/Repositories/Docker/myapp/logs:/usr/local/tomcat/logs), associating the container to a network ( --network myapp-network), setting up my ports, and passing my .env file ( --env-file ../Docker/myapp/environmentvariables-server.env ). Compare with the Spring guide configuration:
docker run -p 8080:8080 -p 8000:8000 --env-file ../Docker/myapp/environmentvariables-server.env --name myapp-server --link myapp-db --network myapp-network -v C:/Users/jane/Repositories/Docker/myapp/downloads/webpages:/usr/local/tomcat/downloads/webpages -v C:/Users/jane/Repositories/Docker/myapp/logs:/usr/local/tomcat/logs myapp-server:beta
- If all is right with your image, you should see the normal Spring startup messages. If you run into issues like the missing main class, verify you didn't fat-finger the commands like someone I know (mainly when using CMD in the Dockerfile, each argument has to be its own entry to the array) and verify your jar is a valid jar. You should be able to run your jar like any normal java app e.g. java -jar -Dfoo=bar myapp.jar.
- Running my image with docker-compose is super simple! Here's the latest incarnation of my docker-compose file.
In summary, it was fun learning how to generate and run my images the 'hard' way but I'll be sticking to docker-compose from now on. 🙂
Jane Talks Code 