Portable development environment with Docker and IntelliJ

Mateusz Joniak
October 15, 2018

For many developers, managing the environment required to work productively is a quite tedious task.

Sure, the IDE does the lion’s share of preparations for you. But still, you need to install a specific version of the database, then make sure you have the right compiler and runtime environment. In some cases, you would also have to work on a given version of the operating system. Gods help you if you find yourself in the hell of “hidden” dependencies, like libraries you’re supposed to have installed separately. Configuring all of this takes hours, so forget about first-day productivity, and if you fail, all you’re going to get are some cryptic error messages that you have to type into Google. Sounds familiar?

This becomes even more problematic when you’re part of a team. How can you make sure everyone is working with the same configuration? Sometimes even differences between minor Java versions can cause different app behavior. Sometimes your code won’t even run on your colleague’s workstation, because there’s a bug in her older JRE version. And who knows what will happen on the production server, which has even different config - say, Linux, as opposed to the Windows 10 you’re using?

All this tangled mess could be solved by virtualization. However, full-blown VMs have their share of problems, most of them are performance and network-related.

So let’s explore some alternatives.

Enter Docker

Docker is a lightweight, OS-level virtualization engine. Your application is packaged together with all its dependencies, configuration files, tools, and whatnot in an “image”. Then, you can run the whole package on any system, and Docker ensures everything works as intended. Therefore, you can be sure the behavior is the same everywhere.

Images are described in Dockerfiles: small text files with minimal syntax, that allow you to specify what components you need in the package. Everyone using the same Dockerfile will get the same version of JVM, same config files, etc. Additionally, you can also set-up Docker on your production machine to run the application from the same image, so there are no surprises after deployment.

First steps

First, you need to download Docker from https://store.docker.com/. There are available installations for Windows, Mac and several Linux distros. So go there and find what you need. Unfortunately, you will probably have to create an account before downloading.

IntelliJ IDEA is an extremely popular IDE for all JVM languages, like Java, Scala, and Kotlin. It also has variants for web development, Python, and even .NET. So if you don’t have it already, you can obtain a free copy of the Community edition on https://www.jetbrains.com/idea/download.

If you want those two to work together, you also need a Docker integration plugin. It can be installed from IntelliJ, just go to File -> Settings -> Plugins.

Before using Docker, your user account must belong to the docker-users group. If you’re on Windows, you need to do this manually: find the Computer Management in the Start menu, run it with Admin privileges, and then go to Local Users and Groups. Find your account and add it to docker-users. Afterward, you need to login to Windows again to refresh your group membership.

Docker settings on Windows

Another thing is, sadly, the current Docker integration plugin version doesn’t handle encryption properly. This problem can be circumvented if you disable TLS on the Docker daemon socket. Right click on Docker in the tray, select Settings and then enable the checkbox “Expose daemon without TLS”. Don’t do it on production though.

Now, assuming you have an app and want to try it out with Docker, you can add a Dockerfile to the project. For more info on the syntax and capabilities, take a look at the documentation.

Below a simple Dockerfile for a Spring Boot application.

FROM openjdk:10-jdk-slim
ADD build/libs/your_app_file.jar app.jar
ADD build/resources/main/application.yml application.yml
ENTRYPOINT ["java","-jar","/app.jar"]

First, you can declare the base image using the FROM instruction. In this case, it will download an OpenJDK 10 setup from the official repository.

ADD instructions allow you to copy specific files from host to the image. Those can be compiled JARs, config files, etc. You can also specify environment variables through ENV.

Finally, let’s set the ENTRYPOINT. This is the command that will be run when the container (deployed image) starts.

Of course, this is only an elementary example. Dockerfiles come with great flexibility and give you a lot of options. So feel free to explore and experiment.

If you open the Dockerfile in IntelliJ with the plugin installed, it will automatically add a Run Configuration that you can use to deploy and test the container.

Dockerfile Run Configuration in IntelliJ


Each container runs in isolation, which means that by default you can’t access your application’s ports from outside. However, in contrast to full VMs, Docker makes it very easy to connect your container with the network: you only need to forward some ports.

If you’re using IntelliJ, this can be done via editing the Port Bindings section in Run Configuration.

Setup the Port Bindings

Typically, you need to bind the TCP port that your app is listening on, to the corresponding port on the host. For example, in a Spring Boot web app, you would need to bind the TCP 8080 socket.

If you want to use the debugger (more on this in the next section), the relevant port - in our example, TCP 5005 - should be forwarded as well.

Another thing to remember is that now localhost always refers to the container, not the host system. Therefore, if you have a local DB instance on your computer, you won’t be able to connect to it from your app.

To solve this, you can either use a specific address defined by your Docker distribution: docker.for.win.localhost on Windows, docker.for.mac.localhost on Mac, or host.docker.internal, which should work on both systems.


Ok, so you can now run your dockerized app straight from the IDE. But there always comes the point in your professional life, when just staring at the code is not enough to find this irritating heisenbug that’s been ruining your team’s blood for the last few weeks. You need to sit down, attach an old-fashioned debugger, and hunt the beast down in the impenetrable jungle that your codebase has somehow become.

Unfortunately, the tooling does not provide us with too many options in this area. The only working solution is to set up the containerized JDK for remote debugging.

You would need to modify the Dockerfile’s ENTRYPOINT:

ENTRYPOINT ["java","-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=*:5005","-jar","/app.jar"]

Now, the virtual machine will be listening for a debugger connection on TCP 5050. This socket needs to be exposed as described before.

Next, you need to manually add a new Debug Config in IntelliJ, using the Remote template. Default settings with port 5005 should work correctly.

Remote debugging template

Remember that this only works if the app is already running. So you need to first deploy the container with standard Run Configuration, and only then attach the remote debugger.


All in all, if you frequently face issues related to synchronizing your environment and config with your colleagues, or between your development computer and production server, dockerizing may be the way to go.

However, because the toolset is still in many ways immature, debugging can be quite clunky. Moreover, at the moment the plugin is a bit glitchy. You may notice disappearing logs and other bugs.

Therefore, it may be best to take a middle road and keep developing the software traditionally, while only testing the changes in the dockerized environment before committing to the common repo or deploying to the server.

Now, let's talk about your project!

We don't have one standard offer.
Each project is unique, rest assured that we will approach the next one full of energy and engagement.