Configure an application in a specific programming language, such as Java, Python, Go, and Node.js - CloudOps Orchestration Service

By default, the application management feature uses Heroku Cloud Native Buildpacks (CNBs) at version heroku/builder:24 to build applications. This topic describes how to configure applications in Java, Python, Go, Node.js , including required files, runtime version pinning, and Procfile usage.

Notes on configuring container images and containers

Configure environment variables when you build a container image

Add a project.toml file to specify build-time environment variables such as MAVEN_OPTS.

Note
For more information about project.toml, see the Introduction to project.toml section of this topic.
Configure environment variables to pass container runtime parameters

Container runtime parameters are passed to applications through environment variables. Make sure your code reads parameters from environment variables. When you deploy a container, specify environment variables for the container. Application management stores those variables in the env file and passes them to the container process using the --env-file option.

Application configurations

The application management feature can directly deploy code repositories in the following programming languages. Each section below describes the required files and configuration options for that language.

Java

Requirements for applications

Java applications must meet the following requirements:

The root directory of the code repository must contain a pom.xml file.
Build the application with Maven or Gradle.
The application's JDK version must be supported.

Configuration notes

OpenJDK versions

OpenJDK major versions 8, 11, 17, 21, and 22 are supported. CNBs install the latest minor version of the specified major version.

Note
Specify the OpenJDK major version for your application. If you skip this, CNBs install the current default long-term support (LTS) version, which changes over time and may cause build failures when the default is updated.

To pin a version, add the system.properties Java property file to the root directory of the application. The following example pins the application to OpenJDK 21:
```
java.runtime.version=21
```
Maven options

Use the MAVEN_OPTS environment variable to apply Maven settings. Add a project.toml file to the root directory to set this variable.

CNBs support Maven 3.9 by default. If your application requires a different Maven version, use the Maven Wrapper (mvnw) instead. CNBs detect and use the mvnw file in the project root.

Run the following command to set up Maven Wrapper:
```
mvn wrapper:wrapper # Generate the .mvn directory, the mvnw, and the mvnw.cmd file.
git add .mvn mvnw mvnw.cmd
git commit -m "support maven wrapper"
git push origin # Submit the branch to the code repository.
```
Procfile

A Procfile declares the process type and startup command for an application. For more information about Procfile syntax and process types, see the Introduction to Procfiles section of this topic. For Spring Boot applications, a Procfile overrides the default startup process. The following example shows a typical Procfile for Spring Boot:
```
web: java -Dserver.port=$PORT $JAVA_OPTS -jar target/demo-0.0.1-SNAPSHOT.jar
```

Sample projects

GitHub: github-java-springboot-demo
Gitee: gitee-java-springboot-demo

For more information, see buildpacks-jvm.

Python

Requirements for applications

The root directory of the source code repository must contain a requirements.txt or poetry.lock file.

Configuration notes

Python versions

CNBs install the latest Python version (currently 3.13) by default. To use a different version, add a .python-version file to the root directory and specify the target version:
```
$ cat .python-version
3.13
```
Procfile

A Procfile is a plain text file in the root directory that declares the process type and startup command. The following example shows a Procfile for a Python application using Gunicorn:
```
web: gunicorn --config gunicorn.conf.py gettingstarted.wsgi
```
Note
A Procfile is not required for simple applications, but add one to Python applications to make the startup command explicit and avoid relying on auto-detection. For more information, see the Introduction to Procfiles section.

Sample projects

GitHub: github-python-falcon-demo
Gitee: gitee-python-falcon-demo

For more information, see buildpacks-python.

Go

Requirements for applications

Go applications must meet the following requirements:

The root directory of the code repository must contain a go.mod file. The module name in the go.mod file must contain at least one forward slash (/).
Go 1.16 or later is required for compilation. Go modules must be used for dependency management.

Note
CNBs support only Go modules for dependency management. Third-party dependency managers such as dep, godep, govendor, and glide are not supported.

Configuration notes

Go versions

CNBs read the Go version from the go directive in go.mod. A major-version identifier such as go 1.17 resolves to the latest patch release in that series available at build time. To pin to a specific patch release, specify the full version (for example, go 1.17.13).

The following entry selects the latest available Go 1.17.x release at build time:
```
go 1.17
```
Dependency management
- If the root directory contains a vendor/modules.txt file, CNBs use the Go modules in the vendor directory instead of downloading them.
- If no vendor/modules.txt file is present, CNBs download Go modules before compilation.
Package installation

CNBs build all main packages detected in the project.

Sample projects

GitHub: github-go-web-demo
Gitee: gitee-go-web-demo

For more information, see buildpacks-go.

Node.js

Requirements for applications

Node.js applications must meet the following requirements:

A valid package.json file must be present in the root directory for CNBs to detect the application.
A valid npm, yarn, or pnpm lock file must be present to install dependencies.

Configuration notes

Node.js versions

Set the engines.node field in package.json to pin the Node.js version. If no version is specified, CNBs install the latest LTS version, which changes over time and may cause unexpected build behavior.

The following example pins the application to the latest Node.js 20.x release:

{
  "engines": {
    "node": "20.x"
  }
}

Note

The engines.node field supports the same semantic version syntax as package.json. Pin the Node.js version to prevent unexpected changes when the default LTS version is updated.

Sample projects

GitHub: github-nodejs-express-demo
Gitee: gitee-nodejs-express-demo

For more information, see buildpacks-nodejs.

PHP

Requirements for applications

PHP applications must meet the following requirements:

PHP 8.2, 8.3, and 8.4 are supported.
The root directory of the application repository must contain both composer.json and composer.lock files.

Configuration notes

PHP

Specify the PHP runtime version in composer.json. The following example requires PHP 8.2.0 or later:

{
  "require": {
    "php": "^8.2.0"
  }
}

Sample projects

GitHub: github-php-demo
Gitee: gitee-php-demo

For more information, see buildpacks-php and php-support.

Ruby

Requirements for applications

The root directory of the code repository must contain valid Gemfile and Gemfile.lock files.

Configuration notes

Ruby versions

Specify the Ruby version in the Gemfile and update Gemfile.lock accordingly:
1. Specify the Ruby version in Gemfile:
```
ruby "3.3.0"
```
2. Update Gemfile.lock:
```
$ bundle update --ruby
```
3. Verify the Ruby version in Gemfile.lock:
```
RUBY VERSION
   ruby 3.3.0p0
```
  If no Ruby version is found in Gemfile.lock, Buildpacks install the default Ruby version. Specify a version to prevent unexpected changes when the default is updated.
Bundler versions

Specify the Bundler version in Gemfile.lock to lock the bundler to a known-good version. Example:
```
BUNDLED WITH
   2.5.6
```
If no Bundler version is found in Gemfile.lock, Buildpacks install the default Bundler version. Specify a version to prevent unexpected changes when the default is updated.

Sample projects

GitHub:
Gitee:

For more information, see buildpacks-ruby and application-contract.md.

Introduction to project.toml and Procfile

Click to view the introduction to and configurations of project.toml
- Introduction to project.toml
  
  project.toml, also known as the project descriptor, is a plain text file stored in the project root directory. Use it to configure a code repository in detail — for example, to specify which buildpacks to use, which files to include or exclude, and how environment variables are set during the build. For more information, see project.toml.
- project.toml configurations
  
  The project.toml file supports the following key configurations. For a full reference, see Use project.toml.
  - Configure environment variables when you build an image
    
    Create or update project.toml in the project root directory. The following example sets MAVEN_OPTS and a second environment variable:
    
    [_] schema-version = "0.2" # Required. Schema version 0.1 does not support build env. [[io.buildpacks.build.env]] name = "MAVEN_OPTS" value = "-Xms128m -Xmx512m" [[io.buildpacks.build.env]] name = "The name of Environment Variable 2" value = "The value of Environment Variable 2"
  - Optional. Specify the project.toml builder
    
    Application management uses a default builder. To override it, specify a builder in project.toml:
    
    [io.buildpacks] builder = "cnbs/sample-builder:noble"
Click to view the introduction to and format of Procfile
- Introduction to Procfile
  
  A Procfile is a plain text file with no file extension, placed in the root directory of an application. It overrides the default startup process for applications in any programming language. For more information, see Procfile.
- Procfile format
  
  Each line in a Procfile declares one process type using the following format:
```
PROCESS_TYPE: COMMAND
```
  Replace the placeholders as follows:
  - Replace PROCESS_TYPE with the process type, such as web, worker, or custom.
  - Replace COMMAND with the command used to start that process type, such as gunicorn -b :$PORT main:app.