Prerequisites
This guide assumes familiarity with: Docker, YAML, Linux, Bash and Linux environment variables.Getting started / Quick Start
To see a full working Java application, take a look at gitpod-io/spring-petclinic. To update an existing Java application, follow the steps below in this guide.
Installing dependencies
The default base image
The default Gitpod workspace image default is workspace-full based on Ubuntu. Along with other languages and tools, this base image includes:- SDKMAN!
v5.16.0
(sdk version
) - Java
v11.0.16
(java -version
) - Gradle
v7.5.1
(gradle -version
) - Maven
v3.8.6
(mvn -version
)
We discuss how to set up a custom base image later in the guide.
Updating Java, Maven & Gradle
For alternative versions to those provided in the Gitpod base image, with SDKMAN! you can quickly update your dependencies:sdk install <candidate> [version]
Important: Dynamically swapping Java, Maven or Gradle versions manually is a quick way to explore Gitpod. However, for day-to-day development strongly recommend to add explicit dependency versions in your gitpod.yml or Dockerfile.
Updating Java version
sdk list java
- to see available java versionssdk install java 18.0.1.fx-zulu
- to install a specific version
Updating Maven version
sdk list maven
- to see available maven versionssdk install maven 3.8.6
- to install a specific version
Updating Gradle version
sdk list gradle
- to see available gradle versionssdk install gradle 7.4.1
- to install a specific version
Setting up a custom Dockerfile
To ensure Gitpod workspaces always start with the correct dependencies, configure a Dockerfile:
- Create a
.gitpod.yml
- Create a custom Dockerfile
- Reference your newly created Dockerfile in your
.gitpod.yml
- Update your
.gitpod.Dockerfile
to install your dependency versions
- Commit and push both
gitpod.yml
and.gitpod.Dockerfile
- Start a new workspace from the branch with the committed
.gitpod.Dockerfile
gitpod.io/#https://github.com/gitpod-io/gitpod
- Test your dependencies are correct in the new workspace
If your changes are not taking effect, ensure your workspace is building from the correct context, where yourSee configure Docker for more.gitpod.yml
orgitpod.Dockerfile
are checked in to version control and are on the branch or commit that you are opening.
Build and run your application
Building a Java application
To build your application, you’ll need to configure a start task. Start tasks are processes that are initiated on every workspace start. Depending on your project setup, start tasks can be used to build your application, run your application directly, or start any necessary tools for the application to run, such as starting database processes.- Add the command to build your application to your
.gitpod.yml
- Optional: Validate by stopping and starting (restart) your workspace
- Optional: Validate your commands by running
gp tasks
Tip: If you’re using VS Code Browser or VS Code Desktop, then your tasks will open as terminal windows. You can configure their layout using the openMode property.
We are using the init
property so that we can perform application building during a prebuild, for increased performance. We’ll discuss prebuilds more later on.
See start tasks and .gitpod.yml reference for more.
Running a Java application
To run your application, you have two options:- Update your start task command - Starting your application using the
command
start task will run the start process on workspace start. With both VS Code Browser and VS Code Desktop, tasks are automatically opened in the terminal(s). With IntelliJ / JetBrains Gateway, configured tasks can be viewed by runninggp tasks
in the workspace. - Use a run / launch configuration - Alternatively, you can commit a run/debug configuration in IntelliJ IDEA or a launch configuration in VS Code as a way to start your application.
Using start tasks to run Java
- Add a
command
for starting your application to your.gitpod.yml
- Optional: Validate by stopping and starting (restart) your workspace
- Optional: Validate your commands by running
gp tasks
Configuring environment variables
Gitpod supports storing encrypted, user or repository-specific environment variables.
Environment variables are stored as part of your user or repository settings and can be used to set access tokens, or pass any other kind of user-specific information to your workspaces. You can set environment variables using
gp env
, or in your repository and account settings.
See environment variables for more.
Configuring ports
When your repository starts a service that listens on a given port, Gitpod automatically serves traffic to this port of your application on an authenticated URL. If you want to configure ports, such as: their visibility, what Gitpod does when it detects a new port being available, etc, you can do that in the ports section of the .gitpod.yml configuration file. For example, add the following to your.gitpod.yml
to configure port 3000
to open in your browser on workspace start.
Configuring localhost
Your development application might rely on thelocalhost
hostname to effectively run.
To ensure your localhost address works with Gitpod, you have two options:
- Replace localhost references - Swap
localhost
references within the application with the output ofgp url <port>
, typically via an environment variable.
DEV_ENVIRONMENT_HOST
environment variable instead of localhost within the application, configured in the command
of the .gitpod.yml
start tasks.
- Setup localhost port forwarding - Connect your local machine with your running workspace means that you don’t need to replace localhost references, to do that you’ll need to configure port forwarding. Port forwarding is useful if you’re working with a framework that needs localhost, and the application cannot be reconfigured.


Configuring VS Code extensions
To set default plugins to be installed for all users starting a workspace for the project, add a list of the JetBrains plugin identifiers to your.gitpod.yml
under vscode.extensions
.
.gitpod.yml
Configuring VS Code Launch configurations
Launch configurations can be shared by committing the.vscode/launch.json
file to version control. To use a launch configuration with Java, need Java version 11 or above, and some VS Code extensions. Assuming you have configured your base image with a compatible JDK version as described above, a simple way to get set up is by adding the Extension Pack for Java will configure the correct VS Code extensions. Alternatively, you can selectively choose the extensions to install.
.gitpod.yml
Configuring JetBrains Run/Debug configurations
To share your run/debug configurations, you can commit their definitions to source control. Since the.idea
folder contains lots of information used for IntelliJ (which can include sensitive information or secrets) you may wish to ignore the .idea
from version control, and explicitly allow .idea/runConfigurations
.
Add run/debug configurations to git, by adding the following to your .gitignore
.
Configuring JetBrains Plugins
To set default extensions to be installed for all users starting a workspace for the project, add a list of the VS Code extension identifiers to your.gitpod.yml
.
.gitpod.yml
Optimising Java Applications
Gitpod prebuilds reduce wait time by installing dependencies or running builds before you start a new workspace. By default, Gitpod prepares prebuilt workspaces for all changes on the default branch and pull/merge requests coming from the same repository. However, prebuilds save only theworkspace
directory, any files stored outside of the workspace directory will be lost. For Java applications, we recommend to execute build commands within an init
startup task.
See prebuilds and start tasks for more.
Optimising JetBrains indexing
JetBrains prebuilds support (via gitpod.yml) is currently in
Alpha · Send
feedback.
.gitpod.yml
.
Example: Index both the stable and latest of the IntelliJ IDE
.gitpod.yml
Caching Maven dependencies
The default cache location for Maven is the.m2
directory. However, since this location is by default outside of the /workspace
directory caches will not be stored as part of a prebuild.
If you are using the workspace-full image, Maven caching configuration is already enabled.
To configure Maven caching, add the following to your custom Dockerfile.
- Create an
.m2
directory in the users (gitpod
) home directory.
- Create a
settings.xml
and configurelocalRepository
withinworkspace
.
Caching Gradle dependencies
The default location of the gradle home is$USER_HOME/.gradle
, however, since this location is by default outside of the /workspace
directory caches will not be stored as part of a prebuild.
If you are using the workspace-full image, Gradle caching configuration is already enabled.
To configure Gradle caching, add the following to your custom Dockerfile.
Personalizing Gitpod
All settings introduced so far, such as.gitpod.yml
and Dockerfile
apply for all users using of the gitpod project. To apply personalisation, consider setting up dotfiles, the Gitpod Browser Extension,
Dotfiles
Dotfiles allow you to set up per-user configurations in your Gitpod workspace, such as modifying your shell and adding command aliases. To configure Gitpod to use your own dotfiles for all your workspaces, enter the URL of a public dotfiles repository in your Gitpod preferences. See dotfiles for more.Browser Extension

Configure your IDE or editor
With Gitpod, you can work with VS Code Browser, VS Code Desktop or JetBrains IDEs, such as IntelliJ IDEA. Setting your preference ensures all future workspaces start with the chosen IDE or editor. Visit the preferences page to configure these settings. See IDEs & Editors for more.VS Code Desktop Settings Sync


Enable Settings Sync with Gitpod