Technical stack user guide

What is an application

The SOFABoot project created by New project according to the documentation on the official website is Local execution. The SOFABoot project is packaged as a {XXX}-executable.jar file locally and stored in the target directory of the project root directory. This fat JAR file is an application on the SOFAStack platform. In the cloud, applications need to be associated with the environment in which they run in order to function as intended. For more information about how to associate an application with a technology stack, see Associate technology stack and deploy application.

What is a technology stack?

On the SOFAStack Platform, a Technology stack refers to the complete set of frameworks and ancillary resources that an application depends on. It defines dependency information for application deployment and operations, primarily including:

• Operating system and version

• Development framework type and version

• Application startup and deployment scripts

• Environmental parameters

Official technology stack download

Click Official Technology Stack.

Naming rules for technology stacks

When you publish an application, you cannot change the technology stack architecture after you select it. However, you can update the version number of the technology stack under this architecture to obtain the latest features. Each technology stack architecture has a corresponding technology stack, which produces a variety of different versions as features iterate and requirements change.

Take the technology stack SOFA_Boot_1.0.7-j180t2114 as an example. The naming rules for SOFABoot technology stacks are described as follows:

• 1.0.7: refers to the version of the technology stack.

  For more information, see Release notes.

• j180: refers to JDK version 1.8.0 (more specifically 1.8.0_131 in the technology stack, not ajdk, and does not support coroutine).

• t2114: refers to tengine version 2.1.14.

Development Framework and Technology Stack

For SOFABoot 3.x, the supported technology stacks and recommend technology stacks are as follows:

• JDK version: ≥ JDK 8

• Technology stack version: ≥ 1.0.6-j180t2114

Development framework and supported technology stack configuration diagram:

Technology stack directory structure

The technology stack directory contains the following subfolders:

• conf/: Stores the configuration file of the technology stack. is an optional file. The content can be empty.

• lifecycle/: Stores the lifecycle code. In theory, you can write these lifecycle scripts in any language. All file names in the lifecycle directory must start with the dedicated prefix ac_ and have no suffix. Currently, the naming of the following files is fixed:

  • ac_setup: the installation script on which the technology stack depends. The main code logic is to read files in the resources directory, decompress, install, and configure environment variables.

  • ac_init_env: optional. Used to handle related tasks before deployment.

  • ac_deploy: Startup script for the application package. The core startup command is: java -jar appname.jar

  • ac_check_service: optional. Chects whether the application is started.

  • ac_shutdown: Stop the application.

• resources/: stores technology stack dependencies and lifecycle code dependencies. If your technology stack is simple enough to require no dependencies, the resources folder can be empty.

Example

The file structure of the sofaboot-1.0.7 technology stack package provided by default is as follows:

sofaboot_buildpack_1.0.7-j180t2114 // No conf folder by default
├── lifecycle // The lifecycle code.
│ ├── ac_setup
│ ├── ac_init_env
│ ├── ac_deploy
│ ├── ac_check_service
│ └ ── ac_shutdown
└ ── resources // Dependencies of the technology stack and lifecycle code
├── centos6.5 // The dependency of the technology stack on the CentOS 6.5 operating system.
│ ├── cronolog-1.7.0-0.x86_64.rpm
│ ├── jdk-1.8.0_131-normal-1.x86_64.rpm
│├── nginx-gray-module-0.0.2.rpm
│ └ ── tengine-2.0.0-12298.el6u0.x86_64.rpm
├── centos7.2 // The dependency of the technology stack on the CentOS 7.2 operating system.
│ ├── cronolog-1.7.0.tgz
│ ├── jdk-1.8.0_131-normal-1.x86_64.rpm
│├── nginx-gray-module-0.0.2.rpm
│ └ ── tengine-proxy-2.1.14.rpm
├── check_service.sh
├── deploy.sh
├── nginx.sh
├── stopApp.sh
├── util.py
└── util.sh 

Create a technology stack package

To package a technology stack, perform the following steps:

1. Create a technology stack directory.

2. Create technology stack lifecycle scripts and related dependencies in the directory.

3. Compress all scripts and related dependencies in the directory into a .tgz file to generate a technology stack package. In the following example, the technology stack directory is assumed to be named sofaboot-buildpack.

   $ cd sofaboot-buildpack
   $ tar -cvzf sofaboot-buildpack.tgz ./*
   // ./*: package all files in the current directory. 

   Note

   The name of the .tgz file is independent of the actual technology stack name.

Technology stack and application deployment process

Package and upload the application to SOFAStack. For more information about how to deploy the application, see Associate technology stack and deploy application.

Features supported by the technology stack

To publish a SOFABoot application, you must Associate technology stack and deploy application. The SOFABoot technology stack supports the following features:

• Use the java -jar {XXXXX-executable.jar} command to start the JAR file. {XXXXX-executable.jar} the fat JAR file generated after the project is compiled and run. The path of the JAR file on the ECS instance is as follows:

  • Default upload path: /home/admin/release/run

  • Executables path: /home/admin/app-run

• You can specify a configuration center address by -D dynamic parameters during cloud deployment. By default, the address of the registry is spliced and passed to the Java process.

• Supports setting java_opts as JVM startup parameters in the code. For more information, see JVM parameter configuration.

• Specify the startup parameters based on the name of the workspace where the current ECS resides, that is, the workspace_name and tenant_name in the /etc/metafile file. For more information, see Technology stack configuration.

• Use the tenginx-conf/tengine.conf file to configure Tengine startup parameters. For more information, see Tengine static configuration.

• If no java -jar process is detected after the application is published, a failure is returned in the health check phase.

• The address of the configuration center specified by the com.alipay.confreg.url configuration items is valid only for the tenant that has the VPN or Express Connect circuit enabled. When the application is deployed to Alibaba Cloud ECS, the technology stack automatically completes this setting. If necessary, you can specify this configuration items by -D the parameter.

• Supports setting ports for custom health check. Configuration method: Configure ac.healthcheck.port in Application Instance Environment Parameters.

• Supports setting the timeout period for custom health check. Configuration method: Configure the ac.healthcheck.timeout in the environment parameters of the application instance. Unit: seconds.

Technology stack configuration solution

We agreed to put all environment-related configurations in the resources directory of the deployable module in the application code. A deployable module refers to a module that uses a spring-boot-maven-plugin to package a fat JAR, such as a web module in a SOFABoot web project.

Configure properties

Single Environment

Global configuration can be implemented by resources/config/application.properties.

Multi-environment

Before a project is released, developers may need to frequently switch between the development environment, test environment, pre-release environment, and production environment. With the configuration of the profile, you can provide corresponding configurations for different workspaces while using the same set of code, eliminating the trouble of packaging multiple times. The configuration mode varies slightly depending on the version of the SOFABoot technology stack.

The configuration file takes effect with priority, which fully refers to the profile mechanism of Spring Boot. For more information, see Profiles.

To configure multiple environments, perform the following steps:

1. Log on to the cloud server and query the tenant_name and workspace_name information in the /etc/mefile.

   Note

   After the iteration of the new version, you can query the preceding information in the SOFAStack console with a few clicks.

2. Create multiple properties files in the resources/config/ directory of the local project.

   • Create a configuration file for a tenant workspace: The file is named in the format of application-{tenant_name}_{workspace_name}.properties.

     • The {tenant_name} is the tenant name. Its value comes from the tenant_name in the /etc/metafile file.

     • {workspace_name} is the name of the workspace. Its value comes from the workspace_name in the /etc/metafile file.

     • Example: Assume that the tenant name {tenant_name} is tenant1234 and the workspace name {workspace_name} is dev. The naming format is application-tenant1234_dev.properties. The first delimiter is a hyphen and the second delimiter is a underscores.

   • Custom Configuration File: You can customize multiple properties files.

     • Naming Method: application-{profile}.properties. The {profile} is a placeholder, indicating the name of the workspace.

     • Configuration Method: You must add key-value pairs: spring.profiles.include={profile1},{profile2} to the application.properties. {profile} are placeholders. Separate multiple {profile} with commas (,).

     • Example: The custom workspaces named testDev and testProd are named in the following format: application-testDev.properties and application-testProd.properties.

3. Package and upload the local project to the cloud server for release. For more information, see Technology stack and application deployment process.

4. Run the command to make the desired configuration file take effect. The following two methods are available: default and custom.

   • Default mode: When the server starts, the default command is -Dspring.profiles.active={workspace_name},{tenant_name}_{workspace_name}.

   • Custom validation method: For more information, see the following steps.

     1. On the cloud server, run the cd /home/admin/app-run command through a remote connection to go to the directory where the application release package is located.

     2. Execute the command java -jar -Dspring.profiles.active={profile} xxxxx-executable.jar. The following table describes the parameters.

        • The {profile} is a placeholder to indicate the workspace that is expected to take effect.

        • xxxxx-executable.jar to the name of the release package in the /home/admin/app-run directory.

Log configuration

Configure path

The configuration files are all under deployable modules. Deployable modules refer to modules that are packaged in spring-boot-maven-plugin, such as the web module in the SOFABoot web project. The log configuration file path is: resources/logback-spring.xml.

Configuration file name source

Because the SOFA middleware technology stack uses Spring Boot for the solution of log configuration, the Maven dependency spring-boot-starter-logging needs to be introduced. This dependency uses logback.xml for log printing by default, so the name of the log configuration file uses logback-spring.xml.

Log dependency

• The log dependency is spring-boot-starter-logging.

• This dependency uses logback to print logs by default.

• By default, this dependency is added to the pom.xml file of the deployable module in the SOFABoot project created by following the instructions in New project on the official website.

Effective method

• Add a <springProfile> tag to the logback-spring.xml configuration file and use the name={profile1,profile2} attribute to define the runtime environment for that segment of the configuration.

• Configure: spring.profiles.active={profile} in application.properties. As long as the profile contains the value corresponding to name, the configuration will be activated.

Example:

<springProfile name="dev,test">
    <appender name="DEV-TEST-APPENDER" class="ch.qos.logback.core.rolling.RollingFileAppender">
        ...
     </appender>
</springProfile>

• springProfile the corresponding environment is dev,test

• In- application.properties configuration: After spring.profiles.active=dev or spring.profiles.active=test, this configuration is activated.

• When activated, the DEV-TEST-APPENDER defined in the <appender> tag can be referenced through the <appender-ref> tag.

Tengine static configuration

You can use the Tengine static configuration file to configure the following:

• Access to resources

• Forwarding of traffic on a specified port

Configure path

The configuration files are all under deployable modules. Deployable modules refer to modules that are packaged in spring-boot-maven-plugin, such as the web module in the SOFABoot web project.

• Tengine configuration file path: tenginx-conf/tengine.conf.

• Package Path: BOOT-INF/classes.

Effective method

When the SOFABoot technology stack is used to automatically publish and deploy on the SOFAStack platform, the technology stack reads the configuration in the tenginx-conf/tengine.conf and starts tengine based on the configuration.

JVM parameter configuration

JVM configuration requirements

When you start an application on different ECS instances, the heap sizes that you need to specify may be different. This requires you to select different JVM parameters based on the memory size of the ECS instance.

JVM configuration rules

You can set JVM parameters on different ECS instances by providing multiple files whose names start with java_opts.

With regard to java_opts documents, the agreed rules are as follows.

• Storage path: the src/main/resources directory of the application code. The classpath root directory in the fat JAR package to be deployed.

• Multi-file support: If there are multiple files, the file name starts with java_opts, and the memory size ID is used as the suffix, and the memory size is an integer. Such as java_opts_2g, java_opts_4g, etc.

• Default processing:

  • If the correct java_opts_?g file cannot be found, the java_opts file is read by default.

  • If there is no java_opts file, it is equivalent to no JVM parameters.

Configure shell script hooks

Hook configuration requirements

The SOFABoot technology stack allows you to add hook scripts to application code. You can add a hook script to enable the application to perform other operations before starting the Java program. For example, you can start a Python script or add a .so file to an environment variable. The technology stack calls the functions in these scripts when the application is deployed.

Hook configuration rules

The hook script configuration rules are as follows:

• Script path: Must be src/main/resources/hook.sh. That is, the script needs to be deployed under the classpath root directory in the fat JAR package (i. e., the deployable module).

• Invocation timing: Declare the function to be invoked in the hook.sh script. The invocation timing varies with the function name.

  • before_appstart_hook: Before the application starts

  • after_appstart_hook: After the application starts

  • Functions with other names are not called

• Other execution logic: The hook.sh script does not contain execution logic other than shell function declarations. Otherwise, the execution logic is triggered each time the hook function is called.

• If you do not need this function, you can not provide hook scripts.

Hook. sh example:

function before_appstart_hook {
    echo 'before_appstart_hook executed'
}

function after_appstart_hook {
    echo 'after_appstart_hook executed'
}