- Introduction
- Getting Started
- Gitpod Tutorial
- Use Cases
- Languages
- Configure
- Workspaces
- User settings
- Repositories
- Organizations
- Authentication
- Billing
- References
- .gitpod.yml
- IDEs & editors
- Integrations
- Gitpod CLI
- Gitpod API
- Gitpod URL
- Compatibility
- Enterprise
- Overview
- Setup and Preparation
- Deploying
- Configure your Gitpod Instance
- Administration
- Upgrading
- Background
- Reference
- Archive
- Help
- Contribute
- Troubleshooting
Java in Gitpod
Gitpod comes with great support for Java. This guide walks you through how to fully configure a Java application using Gitpod.
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
touch .gitpod.yml
- Create a custom Dockerfile
touch .gitpod.Dockerfile
- Reference your newly created Dockerfile in your
.gitpod.yml
image:
file: .gitpod.Dockerfile
- Update your
.gitpod.Dockerfile
to install your dependency versions
FROM gitpod/workspace-full
USER gitpod
RUN bash -c ". /home/gitpod/.sdkman/bin/sdkman-init.sh && \
sdk install java 17.0.3-ms && \
sdk default java 17.0.3-ms"
- Commit and push both
gitpod.yml
and.gitpod.Dockerfile
git commit -m "configuring gitpod with java" && git push
- Start a new workspace from the branch with the committed
.gitpod.Dockerfile
For example, opening: gitpod.io/#https://github.com/gitpod-io/gitpod
- Test your dependencies are correct in the new workspace
sdk current
If your changes are not taking effect, ensure your workspace is building from the correct context, where your
gitpod.yml
orgitpod.Dockerfile
are checked in to version control and are on the branch or commit that you are opening.
See configure Docker for more.
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
Example with Gradle
tasks:
- init: gradle build
Example with Maven
tasks:
- init: mvn package
- Optional: Validate by stopping and starting (restart) your workspace
gp stop
- Optional: Validate your commands by running
gp tasks
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
Example with Gradle
tasks:
- init: gradle build
command: gradle run
Example with Maven
tasks:
- init: mvn package
command: mvn exec:java
- Optional: Validate by stopping and starting (restart) your workspace
gp stop
- Optional: Validate your commands by running
gp tasks
gp tasks
Configuring environment variables
Gitpod supports encrypted, user-specific environment variables.
Environment variables are stored as part of your user 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 project and account settings.
See environment variables for more.
Configuring ports
When your project 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.
ports:
- port: 3000
onOpen: open-browser
See configuring ports for more
Configuring localhost
Your development application might rely on the localhost
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.
Example: Using the DEV_ENVIRONMENT_HOST
environment variable instead of localhost within the application, configured in the command
of the .gitpod.yml
start tasks.
tasks:
- command: |
export DEV_ENVIRONMENT_HOST=`gp url 3000`
java <application-entry>
- 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.
With VS Code Desktop, local port-forwarding is handled automatically and can be configured via the ports view within VS Code Desktop.
With IntelliJ IDEA using JetBrains Gateway you can setup remote port-forwarding manually.
Alternatively, by using local companion all workspace ports will be forwarded automatically.
See configuring ports for more.
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
.
vscode:
extensions:
- vscjava.vscode-java-pack
See .gitpod.yml reference for more.
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.
vscode:
extensions:
- vscjava.vscode-java-pack
See Debugging in Visual Studio Code and VS Code Java Extensions for more.
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
.
/.idea/*
!/.idea/runConfigurations
See JetBrains Run/Debug configuration documentation for more.
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
.
jetbrains:
intellij:
plugins:
- com.intellij.lang.jsgraphql
See .gitpod.yml reference for more.
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 the workspace
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 currently has early support for improved indexing performance with JetBrains IDEs that works out-of-the-box. You can enable this setting via the .gitpod.yml
.
Example: Index both the stable and latest of the IntelliJ IDE
jetbrains:
intellij:
prebuilds:
version: stable
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.
mkdir /home/gitpod/.m2
- Create a
settings.xml
and configurelocalRepository
withinworkspace
.
printf '<settings>\n <localRepository>/workspace/m2-repository/</localRepository>\n</settings>\n' > /home/gitpod/.m2/settings.xml
See prebuilds for more.
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.
ENV GRADLE_USER_HOME=/workspace/.gradle/
See prebuilds for more.
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 setup 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
To make opening Gitpod workspaces easier, install the Gitpod browser extension, which enables an “Open in Gitpod” button on GitHub, GitLab and Bitbucket.
See Browser Extension for more.
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
VS Code Desktop by default is not setup to sync your VS Code settings (e.g. your fonts, layouts, etc) with VS Code running in the browser of Gitpod. You can configure Gitpod to sync settings between browser and desktop by running the command palette action “Settings Sync: Enable signing in with Gitpod” from the Gitpod VS Code extension.
See VS Code settings sync for more.