Upsun User Documentation

Moving a Java application to Upsun

Try Upsun for 15 days
After that, enjoy the same, game-changing Upsun features for less with the First Project Incentive!ยน A monthly $19 perk!
ยนTerms and conditions apply
Activate your 15-day trial

It is common to have a Java application that you want to migrate to Upsun. Upsun supports several styles of Java application, such as monolith, microservices, stateful, and stateless.

Minimum Requirement Anchor to this heading

To run a Java application at Upsun you need:

Monolith/Single Application Anchor to this heading

To start a Java application, you need to understand the Upsun structure. You will need to configure your application, routes, and services.

Application Anchor to this heading

.upsun/config.yaml
applications:
    app:
        type: 'java:<VERSION>'

        hooks:
            build: [2]
        web:
            commands:
                start: [3]
  1. A Java version, e,g.: java:21
  2. Hooks define what happens when building the application. This build process typically generates an executable file such as a uber-jar. For example, mvn clean package.
  3. The commands key defines the command to launch the application. For example, java -jar file.jar.
  4. In the start’s command needs to receive the port where the application will execute thought the PORT environment. That’s best when your app follows the port bind principle. For example, java -jar jar --port=$PORT.

Route Anchor to this heading

.upsun/config.yaml
routes:
    "https://{default}/":
        type: upstream
        upstream: "app:http" [1]
    "https://www.{default}/":
        type: redirect
        to: "https://{default}/"

applications:
    app:
        type: 'java:<VERSION>'

        hooks:
            build: [2]
        web:
            commands:
                start: [3]
  1. It defines the application will link in the route. For example,"app:http".

Microservices Anchor to this heading

You have the option to use several languages in microservices. If you’re using Java there are several options to aggregate these services into a microservices:

Upsun supports multiple applications and there are two options:

  • One application YAML file to each application
  • Aggregate all applications in a single file with an .upsun/config.yaml file
Article Content
Microservices in the cloud, part two Source
Microservices in the cloud, part one Source
Multiple Applications Source
Configure multi-applications with .upsun/config.yaml Source

Access to managed services Anchor to this heading

Upsun provides managed services such as databases, cache and search engines. However, you can use a database or any services such as a transition process, just be aware of the firewall.

When applications need to access a service, it is important to include the relationships key. By default an application may not talk to any other container without a relationship explicitly allowing access.

To connect to a service from your deployed application, you need to pass the relationships information into your application’s configuration. The way to do so varies with the application. The most common mechanisms are listed below.

Overwrite Anchor to this heading

If you are using a framework that follows the Twelve-Factor App methodology, particularly the third point, you can configure the application directly from environment variables. Examples of such frameworks include Spring, Eclipse MicroProfile Config, Quarkus, and Micronauts.

Service credentials are available within the service environment variables, or the PLATFORM_RELATIONSHIPS environment variable.

Assuming the relationship postgresql is configured to grant access to a PostgreSQL service container, you can map the automatically generated environment variable (POSTGRESQL_HOST) to whatever your application expects to use:

.environment
export DB_HOST=$POSTGRESQL_HOST

This sets environment variables with the names your app needs, and the values from service environment variables.

This variable is a base64-encoded JSON object with keys of the relationship name and values of arrays of relationship endpoint definitions.

Upsun supports the jq tool, which allows to extract information from this JSON.

.environment
export DB_HOST=`echo $PLATFORM_RELATIONSHIPS | base64 --decode | jq -r ".postgresql[0].host"`

This sets environment variables with names your app needs and the values from PLATFORM_RELATIONSHIPS environment variable.

Article Source
Spring Data MongoDB Source
Jakarta EE/MicroProfile Config Source
Spring Data JPA Source
Payara JPA Source

To reduce the number of lines in the application file and to make it cleaner, you have the option to move the variable environment to another file: a .environment file.

Example:

You can obtain relationship information through the service environment variables themselves, or through the PLATFORM_RELATIONSHIPS environment variable. Say your application has a relationship named postgresql to a database service named postgresql:

.environment
export DB_HOST=${POSTGRESQL_HOST}
export DB_PASSWORD=${POSTGRESQL_PASSWORD}
export DB_USER=${POSTGRESQL_USERNAME}
export DB_DATABASE=${POSTGRESQL_PATH}
export JDBC=jdbc:postgresql://${HOST}/${DATABASE}
export JAVA_MEMORY=-Xmx$(jq .info.limits.memory /run/config.json)m
export JAVA_OPTS="$JAVA_MEMORY -XX:+ExitOnOutOfMemoryError"

This sets environment variables with the names your app needs, and the values from service environment variables.

This PLATFORM_RELATIONSHIPS variable is a base64-encoded JSON object with keys of the relationship name and values of arrays of relationship endpoint definitions.

Upsun supports the jq tool, which allows to extract information from this JSON.

.environment
export DB_HOST=`echo $PLATFORM_RELATIONSHIPS | base64 --decode | jq -r ".postgresql[0].host"`
export DB_PASSWORD=`echo $PLATFORM_RELATIONSHIPS | base64 --decode | jq -r ".postgresql[0].password"`
export DB_USER=`echo $PLATFORM_RELATIONSHIPS | base64 --decode | jq -r ".postgresql[0].username"`
export DB_DATABASE=`echo $PLATFORM_RELATIONSHIPS | base64 --decode | jq -r ".postgresql[0].path"`
export JDBC=jdbc:postgresql://${HOST}/${DATABASE}
export JAVA_MEMORY=-Xmx$(jq .info.limits.memory /run/config.json)m
export JAVA_OPTS="$JAVA_MEMORY -XX:+ExitOnOutOfMemoryError"

This sets environment variables with names your app needs and the values from PLATFORM_RELATIONSHIPS environment variable.

This .environment file can interact to each application file.

Example:

applications:
    # The app's name, which must be unique within the project.
    app:
        type: 'java:21'
        hooks:
            build: ./mvnw package -DskipTests -Dquarkus.package.uber-jar=true
        relationships:
            postgresql:
        web:
            commands:
                start: java -jar $JAVA_OPTS $CREDENTIAL -Dquarkus.http.port=$PORT jarfile.jar

Is this page helpful?