Java Maven Source Code Deployment

Principle Document Reading

Interpretation of the principles of Kato to build Java Maven projects

Maven Project Identification Strategy

When the pom.xml file exists in the root directory of the source code and the Dockerfile does not exist, Kato will recognize the source code as a Java Maven project.

To build a Maven multi-module project, please directly refer to Java Maven multi-module source code build.

Verification Preparation

Before deploying the project to Kato, please follow the steps below for local verification. After the local build is successful, you can start to try to deploy the project on Kato.

  • The source code is hosted on Git or SVN server.

  • Check the local build environment and operating environment to determine the Maven version, JDK version, and whether OracleJDK is used.

mvn -v
java -version
  • Clear the local build cache. Generally, the local localRepository is located in ${HOME}/.m2/repository, please change the path of this folder temporarily after confirmation.
mv ${HOME}/.m2/repository ${HOME}/.m2/repository.bak
  • Execute the following build command, which is also the default command for Kato Java Maven project construction:
mvn -DskipTests clean dependency:list install

pom.xml Specification

  • The jar package method is recommended for SpringBoot project packaging.
  • The war package method is recommended for non-SpringBoot projects.

Compile and Run Environment Configuration

During the environment preparation stage, Kato needs to build and run the environment to be as unified as possible with the commonly used local build and run environment. Such as JDK version, Maven version, etc.

Graphical Settings

Kato supports graphical definition of the compilation and runtime environment, and the configuration is located on the build source page of the service component.

Modifications to these configurations need to be implemented through Build

  • Disable caching. Before the first successful build is completed, the switch should always be on and off by default.

  • Select the JDK (OpenJDK provided by default) and MAVEN version used for compiling and running. Be sure to use the version verified during verification preparation.

  • Choose a custom JDK download address, and you need to provide a path where the Kato server can download to download the JDK (it can be OracleJDK) installation package in tar.gz format.

  • When the build product is a war file, Tomcat and Jetty versions are also provided.

  • Disable Maven Mirror, this switch determines whether to proxy through rbd-repo (the default proxy is to the Alibaba Cloud maven repository). Once the switch is turned on, The MAVEN MIRROR OF configuration and MAVEN MIRROR URL configuration are all invalid. The repository address used during the build process will only depend on the definition in the pom.xml file (if there is no repositories definition in the file, it will be from the Maven central repository Pull dependencies).

  • MAVEN MIRROR OF configuration, used together with MAVEN MIRROR URL configuration, can define the behavior of pulling dependencies from the mirror private server during the build process. The default configuration is central, if set to *, all dependent packages will be pulled from the mirror repository address defined in the MAVEN MIRROR URL configuration.

  • MAVEN MIRROR URL configuration defines the repository private server address used during the build process. Kato does not support the local installation and deployment of jar packages. Please upload all required third-party jar packages to the repository private server. The default maven.gridworkz is the internal network resolution domain name of the rbd-repo component, which acts as a proxy for the Alibaba Cloud maven repository.

  • MAVEN build parameters and build command are two options, which compose the command executed for compilation. The default build command is mvn -DskipTests clean dependency:list install.

  • MAVEN build java parameter configuration is mainly used to specify the stack memory allocated during the build process. This configuration only affects the maven build process. The stack memory specified when the built component runs is specified by the ${JAVA_OPTS} variable.

  • Startup command, which specifies how Kato will start the current service component after the build process is completed. For details, see Startup Command Configuration Chapter.

Kato supports all the above configurations to be defined through code. The advantage of this is that by adding several configuration files to the source code repository, the definition of the compilation and runtime environment is completed, without any manual configuration, and automatic CI is completed.

system.properties

Add the system.properties file in the root directory of the source code to define the Maven version and JDK version. Be sure to use the version verified during verification preparation:

java.runtime.version=1.8
maven.version=3.3.1

The selection range of the two versions is as follows:

OptionsVersion
OpenJDK1.6, 1.7, 1.8, 1.9, 10, 11
Maven3.0.5, 3.1.1, 3.2.5, 3.3.1, 3.3.9

settings.xml (recommended)

Add the settings.xml file available for the user’s local build in the root directory of the source code to completely simulate the user’s local build settings, including the **repository private server settings **. This file is usually located in the ${M2_HOME}/conf or ${HOME}/.m2 directory of the user environment, and the configuration used by the user’s local build can be defined in it.

In the upcoming version of Kato v5.2.2, the settings of settings.xml will be added to the graphical settings.

mvnw

If your code root directory defines mvnw, this script will be used to start the Maven process. If the Maven version is specified, mvnw will be ignored. Build with default commands.

katofile

Add katofile in the root directory of the source code to define environment variables for the service components. More configuration during the build process can be defined by environment variables.

In the process of building the Kato source code, the variables starting with BUILD_ defined for the service component can be passed into the build environment for use. Some commonly used environment variables are as follows:

Environment VariablesDefault ValueDescription
BUILD_MAVEN_MIRROR_DISABLENULLDisable MAVEN MIRROR
BUILD_MAVEN_MIRROR_OFWhen centralis *, use the designated repository private server to pull all dependencies
BUILD_MAVEN_MIRROR_URLmaven.gridworkzUsed to specify the repository private server address
BUILD_MAVEN_CUSTOM_OPTS-DskipTestsMaven build parameters
BUILD_MAVEN_CUSTOM_GOALSclean dependency:list installMaven build parameters
BUILD_MAVEN_SETTINGS_URLNULLDownload settings.xml from the configuration address and use it to build the configuration
BUILD_MAVEN_JAVA_OPTS-Xmx1024mMAVEN build java parameter configuration
BUILD_ENABLE_ORACLEJDKNULLWhen true, you can customize the download address of the JDK installation package
BUILD_ORACLEJDK_URLNULLDefine the JDK installation package download address
BUILD_RUNTIMES_SERVERtomcat85Define the WEB SERVER used by the war package project

Start Command Configuration

After the Java Maven source code construction process is completed, Kato will automatically run the service component, which requires us to specify the startup command of the service component in advance.

Procfile Specification

Kato uses the Procfile file in the root directory of the source code to define the project startup command. For the specification of the Procfile file definition, please refer to Procfile.

The start command can be entered graphically in the service component construction source page. The command format entered here is required to be consistent with the Procfile, and the priority is higher than the Procfile in the source code root directory. After the input is completed, it will take effect the next time the current service component is constructed.

If the project does not define a Procfile file, the platform will generate a default Procfile based on the recognized project type by default.

The packaging method is war package, and the platform uses webapp-runner.jar to run the packaged war package.

Example:

web: java $JAVA_OPTS -jar ./webapp-runner.jar --port $PORT target/*.war

The packaging method is jar package.

Example:

web: java -Dserver.port=$PORT $JAVA_OPTS -jar target/*.jar

The above is the default Procfile, if you need to expand more startup parameters, you can customize the Procfile.

  • There is a space between web: and java
  • The end of the file cannot contain special characters
  • If it is a multi-module project, pay attention to the path of the compiled jar package or war package, the path is <submodule name>/targets/*.jar or <submodule name>/targets/*.war
  • $JAVA_OPTS: The platform will automatically set the value of Xmx and Xms according to the memory size of the application
  • $PORT: The listening port is determined according to the port set by the user on the platform, the default listening port is 5000

When the web server support is adjusted, the startup command needs to be adjusted to package into War:

  • When selecting different versions of tomcat web: java $JAVA_OPTS -jar ./webapp-runner.jar --port $PORT ./*.war
  • When selecting different versions of jetty web: java $JAVA_OPTS -jar ./jetty-runner.jar --port $PORT ./*.war
  • Need to configure the context path, you can specify webapp-runner parameter path through a custom Procfile
    • Example web: java $JAVA_OPTS -jar ./webapp-runner.jar --path <path path, example: /r6d> --port $PORT ./*.war

Web Service Support

If the Maven project is packaged into a war package, you need to configure Web service support.

Run the war package through the web service (tomcat or jetty), that is, through java -jar ./webapp-runner.jar ./*.war or java -jar ./jetty-runner.jar ./*.war Way to run.

Currently, you can set the web service version through the build source or define the webserver file in the source root directory

  1. Console build source configuration support version tomcat7, tomcat8, tomcat85, tomcat9, jetty7, jetty9
  2. Define the webserver version in the source root directory
    • webapp-runner-7.0.91.0.jar
    • webapp-runner-8.0.52.0.jar, webapp-runner-8.5.38.0.jar
    • webapp-runner-9.0.16.0.jar
    • jetty-runner-7.5.4.v20111024.jar,jetty-runner-9.4.0.v20161208.jar

The specific correspondence is as follows:

Web service supportWeb service versionCustom jar file name in Procfile
tomcat7webapp-runner-7.0.91.0.jarwebapp-runner.jar
tomcat8webapp-runner-8.0.52.0.jarwebapp-runner.jar
tomcat85 (default)webapp-runner-8.5.38.0.jarwebapp-runner.jar
tomcat9webapp-runner-9.0.16.0.jarwebapp-runner.jar
jetty7jetty-runner-7.5.4.v20111024.jarjetty-runner.jar
jetty9jetty-runner-9.4.0.v20161208.jarjetty-runner.jar

To select the tomcat7 version, you need to pay attention to make sure that the local can be run through java -jar ./webapp-runner-7.0.91.0.jar ./*.war.

For detailed configuration of webapp-runner, please refer to webapp-runner instruction manual

Other Instructions

If compiled into a war package, the war file will be decompressed to the /app/target/ directory by default during runtime. Adding configuration files to the war decompression path is not supported, otherwise the application will not start normally

Sample Demo Program

Example Spring Boot project: https://github.com/gridworkz/java-maven-demo

Common Problems

The project is relatively complicated, and cannot be compiled using the above method

At this time, it is recommended that you define your own Dockerfile for compiling and running environment control.

How to deal with compilation failure

Check the build log and get the reason for the compilation failure from the log. If your project needs to download dependent packages from the public network, it is more likely that the dependent package download will fail. If the network is unlimited, just try again.

The project dependency package has changed, but it is found not to take effect after compilation

If your dependent package has been correctly updated to the private server, consider that the local cache dependent package has not been updated. You can manually disable the cache and rebuild.

The project compiles successfully, but it runs abnormally after startup

  • Reason 1: The above-mentioned running command is set incorrectly, causing the container to fail to start. The solution is to set the startup command correctly.

  • Reason 2: Exit after the code has a problem running, refer to the component running log and judge the reason from the log content.

  • Reason 3: The memory allocation is too small and the component cannot start normally. The log phenomenon of this factor is that the component is starting and then suddenly exits. At this time, consider that insufficient memory settings lead to OOM.

After entering the container environment through the WEB terminal, directly execute the java -version version to 1.7.

The java command used to run the service component is located in /app/.jdk/bin/java This path is not in the $PATH.