Migrating Existing Maven Apps To Stack

Simple Case

1. git clone <...existing repo>
2. odo create java-openliberty my-component
3. odo push
4. odo log -f # wait for tests to run

General Migration Tips

• Upgrade to a recent (v3.x) liberty-maven-plugin version, e.g. io.openliberty.tools:liberty-maven-plugin:3.3-M4
  • Note if you are migrating from an older, 2.x version of liberty-maven-plugin (the net.wasdev.wlp.maven.plugins:liberty-maven-plugin:2.x plugin) , you may want to review these notes to understand differences between the 2.x and the 3.x plugin versions.
• The idea is that the Devfile establishes the Open Liberty version installed rather than the POM. This will work for simple cases but there are probably more unique, custom cases where the POM is written in a way that the override in the Devfile creates a conflict.

Advanced/Custom Tips

• If you need to call extra goals and phases before calling dev mode, you can edit the Devfile command, (below adding "pre-integration-test):

  - id: run
    exec:
      component: devruntime 
      commandLine: mvn -Dmaven.repo.local=/mvn/repository -Dliberty.runtime.version=20.0.0.9 -Ddebug=false -DhotTests=true -DcompileWait=3 pre-integration-test liberty:dev

• Certain goals that might be helpful in a full lifecycle build but you may wish to disable in dev mode. There are several "skip" parameters in liberty-maven-plugin goals such as -DskipLibertyPackage, -DskipTestServer. See docs for more info.

Gotchas

• Make sure to add /target to .gitignore (or .odoignore) especially if you are using the project outside of odo and containers (using "native" 'mvn'). Otherwise the whole target liberty install will get copied into the container which will dramatically slow things down.
• Use relative paths (not absolute paths) in both the Maven pom.xml and the Liberty server config. Since the stack builds and runs your application inside containers, the project root is subject to change.
• Define the Java compiler levels via Maven project properties to avoid issues with the defaults, e.g.:

    <properties>
        <maven.compiler.target>11</maven.compiler.target>
        <maven.compiler.source>11</maven.compiler.source>
    </properties>

Docker Build

• Account for deletion of quick-start-security.xml
• Docker build perfomed from target not src directory, could be different from other builds

Migrating from appsody java-openliberty stack

1. remove parent POM
2. add project properties defined in parent into application POM properties directly, e.g.:
   • plugin version properties
   • ports (if used)
   • Java compiler configuration
3. If you are planning on using the Cloud Pak for Applications pipelines, you also need to remove .appsody-config.yaml.
4. The absolute path of the project root has changed from the /project/user-app absolute path used in appsody for the project home. In appsody, this was used consistently across both appsody run and the pipeline build/deploy in appsody build. With odo/devfiles, the development container (used in odo push) uses the project root: /projects, by default, and does not typically match the absolute path of the stack build. This can be a concern if you are using Maven plugins, for example, to copy dependencies in place to the Open Liberty installation during inner loop runs or within the outer loop Docker build. To adjust for this and maintain flexibility within your project, you should use variables incorporating the path of the project root path. E.g. ${project.build.directory} in pom.xml and ${server.config.dir} in server.xml.

Example migration from appsody

A project initialized via appsody init java-openliberty might need to be migrated to:

<project>

    <!-- Remove parent 
      <parent>
        <groupId>dev.appsody</groupId>
        <artifactId>java-openliberty</artifactId>
        <version>[0.2, 0.3)</version>
        <relativePath/>
      </parent>
     -->

     <!-- Add properties defined in parent POM -->
    <properties>
        <version.maven-war-plugin>3.2.2</version.maven-war-plugin>
        <version.dockerfile-maven-plugin>1.4.10</version.dockerfile-maven-plugin>
        <version.maven-surefire-plugin>3.0.0-M1</version.maven-surefire-plugin>
        <version.maven-failsafe-plugin>3.0.0-M1</version.maven-failsafe-plugin>
        <http.port>9080</http.port>
        <https.port>9443</https.port>
        <app.name>${project.artifactId}</app.name>
        <maven.compiler.source>1.8</maven.compiler.source>
        <maven.compiler.target>1.8</maven.compiler.target>
    </properties>