How to use a custom Java distribution on Gitpod

Maciej Walkowiak

Nov 9, 2022

The default Gitpod workspace-full image comes with preinstalled Java development tools like SDKMan, Maven and Gradle.

When you execute java --version in the terminal, you’ll find out that the current Java version is Java 11 (at the time of writing this blog post).

Since SDKMan is installed, you can easily switch to a different Java version with:

But this change will be reflected only in your current workspace. If someone else opens the Gitpod workspace for the same Gitpod repository or if you recreate the workspace, Java will be back to 11, and the version you installed with SDKMan will be gone.

There are at least two ways to configure the Java version for each new Gitpod workspace.

Set Java version with .gitpod.yml

Gitpod workspaces can be configured with .gitpod.yml. We can specify startup task(s) that will execute shell commands for us:

This is almost good. The problem is that sdk install prompts the user to set the installed version as a default. There’s no flag to run the command in non-interactive mode, but there is a hacky workaround:

The drawback is that this command takes some time to run and is executed every time the workspace is created.

Instead, we can create a custom workspace image that will be built only once.

Set Java version with workspace image

Gitpod gives an option to use a custom Docker image on which the workspace runs. Let’s create one that uses Java 17 by default:

Remove the before task from .gitpod.yml and instead set the image.file property to .gitpod.Dockerfile.

Next, create a file .gitpod.Dockerfile. If you are happy with the default Gitpod workspace image, you can use it as a base.

Let’s break it down:

1. It is recommended to use a specific Docker image tag for a base image. Go to https://hub.docker.com/r/gitpod/workspace-full and look for the latest tag, then use it in FROM command in the Dockerfile.
2. Change shell to bash, source SDKMan init so that sdk command becomes available, and run sdk install like we previously did in the .gitpod.yml:

Then, when you create a new repository with these files, only on the first run, Gitpod builds an image:

.. and once the workspace is ready:

Example output:

Use a JDK that is unavailable in SDKman

What if the JDK we want to use is not available in SDKMan? Since we are using a Dockerfile, we can write shell scripts.

As an example, let’s use JetBrains distribution of the OpenJDK. Use the following .gitpod.Dockerfile contents:

Let’s break it down:

1. Download JetBrains Runtime release from https://github.com/JetBrains/JetBrainsRuntime/releases/
2. Unpack it and move to /opt/

Now, two important points:

3. export JAVA_HOME is effectively overwriting the one set by SDKMan
4. Add JDK bin directory to $PATH. It is important to put it before what’s already been there so that the new JDK bin is before the SDKMan path.

Finally, use .gitpod.Dockerfile from your .gitpod.yml:

And follow see it in action!

Once you recreate the workspace, and the new image is built:

Example output:

That’s all folks!