How to Migrate a Java Application to Upsun

Migrating a Java application (such as Spring Boot, Quarkus, or a standard Maven/Gradle project) to Upsun is straightforward. Instead of dealing with infrastructure provisioning, you define your application, dependencies, and start commands in a single declarative YAML file.

This guide outlines the core steps to containerize and deploy your Java application on Upsun.

Step 1: Prepare Your Project

Upsun expects your application to be managed by a standard build tool like Maven or Gradle. Ensure your project builds successfully locally (e.g., via mvn clean package or gradle build) and produces a runnable .jar or .war artifact.

Important Note: Upsun routes external traffic to your application via a dynamically assigned port. Your Java application must be configured to listen on the port defined by the $PORT environment variable.

• Spring Boot: This is often handled by adding server.port=${PORT:8080} to your application.properties.

Step 2: Create the Upsun Configuration File

At the root of your Git repository, create an .upsun/config.yaml file. This single file defines your application container, your services (databases, caches), and how the web routes traffic.

Here is a standard template for a Java application:

applications:
    myapp:
        # 1. Define the runtime environment
        type: 'java:17' # Or java:21, java:11, etc.
        
        # 2. Allocate persistent disk space (if needed for uploads, otherwise optional)
        disk: 1024
        
        # 3. Define the build phase
        hooks:
            build: |
                set -e
                # Build the application using Maven (or Gradle)
                mvn clean package -DskipTests
                
        # 4. Define how to start the application
        web:
            commands:
                # The start command should dynamically set the max heap size (-Xmx) based on the container limits
                start: |
                    java -Xmx$(jq .info.limits.memory /run/config.json)m \
                    -XX:+ExitOnOutOfMemoryError \
                    -jar target/my-application.jar

Step 3: Understanding the Configuration

The Build Hook (hooks.build)

During the build phase, the container has a writable file system but no access to services (like databases). The Upsun java container images come pre-installed with both Maven and Gradle.

• Replace mvn clean package with ./gradlew build if you are using the Gradle wrapper.

The Start Command (web.commands.start)

This is the most critical part of running Java in a containerized environment.

• Dynamic Memory (-Xmx): If you don't limit the JVM's memory, it may try to consume more RAM than your container is allocated, causing an Out-Of-Memory (OOM) kill. The command $(jq .info.limits.memory /run/config.json)m dynamically reads the allocated RAM of your specific container at runtime and sets the max heap size accordingly.

• -XX:+ExitOnOutOfMemoryError: This ensures that if the JVM runs out of memory, the process completely exits. Upsun will then automatically restart the container, preventing it from hanging in a broken, unresponsive state.

Step 4: Add Services (Optional)

If your Java application requires a database (like PostgreSQL or MariaDB), you can append it to the same .upsun/config.yaml file and link it to your app via a relationship.

# Add this block to define the database
services:
    db:
        type: postgresql:15

# Add this block inside your 'applications.myapp' definition to link them
applications:
    myapp:
        relationships:
            database: "db:postgresql"

Upsun will inject the connection credentials into the $PLATFORM_RELATIONSHIPS environment variable at runtime. You can parse this variable in your Java application or use environment variables in the hooks.deploy phase to pass them to your framework.

Step 5: Deploy

Once your .upsun/config.yaml is ready, simply commit the file and push it to your Upsun project.

git add .upsun/config.yaml
git commit -m "Add Upsun configuration"
git push upsun main

Upsun will read the configuration, download your dependencies via Maven/Gradle, build the .jar file, provision the container, and start your application automatically.