Skip to main content
Skip to main content
🚧 Work in Progress

Configure Your Java build & deploy pipeline

Zerops provides a customizable build and runtime environment for your Java application.

Add zerops.yml to your repository​

Start by adding zerops.yml file to the root of your repository and modify it to fit your application:

zerops:
  # define hostname of your service
  - setup: app
    # ==== how to build your application ====
    build:
      # REQUIRED. Set the base technology for the build environment:
      base: java@latest

      # OPTIONAL. Set the operating system for the build environment.
      # os: ubuntu

      # OPTIONAL. Customise the build environment by installing additional packages
      # or tools to the base build environment.
      # prepareCommands:
      #   - apt-get something
      #   - curl something else

      # REQUIRED. Build your application
      buildCommands:
        - ./mvnw clean install
      # REQUIRED. Select which files / folders to deploy after
      # the build has successfully finished
      deployFiles: target/app.jar

      # OPTIONAL. Which files / folders you want to cache for the next build.
      # Next builds will be faster when the cache is used.
      # cache: some_file

    # ==== how to run your application ====
    run:
      # OPTIONAL. Sets the base technology for the runtime environment:
      base: java@latest

      # OPTIONAL. Sets the internal port(s) your app listens on:
      ports:
        # port number
        - port: 8080

      # OPTIONAL. Customise the runtime Java environment by installing additional
      # dependencies to the base Java runtime environment.
      # prepareCommands:
      #   - apt-get something
      #   - curl something else

      # OPTIONAL. Run one or more commands each time a new runtime container
      # is started or restarted. These commands are triggered before
      # your Java application is started.
      # init:
      #  - rm -rf ./cache

      # REQUIRED. Your Java application start command
      start: java -jar target/app.jar

The top-level element is always zerops.

Setup​

The first element setup contains the hostname of your service. A runtime service with the same hostname must exist in Zerops. Zerops supports the definition of multiple runtime services in a single zerops.yml. This is useful when you use a monorepo. Just add multiple setup elements in your zerops.yml:

zerops:
  # definition for app service
  - setup: app
    build: ...
    run: ...

  # definition for api service
  - setup: api
    build: ...
    run: ...

Each service configuration contains at least two sections: build and run. Both sections are required to build and deploy your Java application in Zerops. If you'd like to use a readiness check, add an optional deploy section.

Build pipeline configuration​

base​

REQUIRED. Sets the base technology for the build environment.

Following options are available for Java builds:

  • java@17
  • java@21
  • java@latest
zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build:
      # REQUIRED. Sets the base technology for the build environment:
      base: java@latest
      ...

The base build environment contains , the selected version of Java, Zerops command line tool, git and wget.

Info

You can change the base environment when you need to. Just simply modify the zerops.yml in your repository.

If you need to install more technologies to the build environment, set multiple values as a yaml array. For example:

zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build:
      # REQUIRED. Sets the base technology for the build environment:
      base:
        - java@latest
      prepareCommands:
        - zsc add nodejs@latest
      ...

See the full list of supported build base environments.

To customise your build environment use the prepareCommands attribute.

os​

OPTIONAL. Sets the operating system for the build environment.

Following options are available:

  • alpine
  • ubuntu

Default value is alpine.

We are currently using following os version:

  • Ubuntu 22.04
Caution

The os version is fixed and cannot be customised.

prepareCommands​

OPTIONAL. Customises the build environment by installing additional dependencies or tools to the base build environment.

The base build environment contains:

To install additional packages or tools add one or more prepare commands:

zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build:
      # REQUIRED. Set the base technology for the build environment:
      base: java@latest

      # OPTIONAL. Customise the build environment by installing additional packages
      # or tools to the base build environment.
      prepareCommands:
        - apt-get something
        - curl something else
      ...

When the first build is triggered, Zerops will

  1. create a build container
  2. download your application code from your repository
  3. run the prepare commands in the defined order

The application code is available in the /var/www folder in your build container before the prepare commands are triggered. This allows you to use any file from your application code in your prepare commands (e.g. a configuration file).

Command exit code​

If any command fails, it returns an exit code other than 0 and the build is canceled. Read the build log to troubleshoot the error. If the command ends successfully, it returns the exit code 0 and Zerops triggers the following command. When all prepare commands are finished, your custom build environment is ready for the build phase.

Single or separated shell instances​

You can configure your prepare commands to be run in a single shell instance or multiple shell instances. The format is identical to build commands.

Cache of your custom build environment​

Some packages or tools can take a long time to install. Therefore, Zerops caches your custom build environment after each successful build where the prepare commands were used. When the second or following build is triggered, Zerops will use the build cache from the previous build if both following conditions are met:

  1. Content of the base and prepare attributes didn't change from the previous build
  2. The build cache wasn't invalidated in the Zerops GUI.

To invalidate the Zerops build cache go to your service detail in Zerops GUI, choose Service dashboard & runtime containers from the left menu and click on the Open pipeline detail button. Then click on the Invalidate build cache icon.

image

When the build cache is used, Zerops doesn't run the prepareCommands commands and the build of your application is faster.

buildCommands​

REQUIRED. Defines build commands.

zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build:
      # REQUIRED. Set the base technology for the build environment:
      base: java@latest

      # REQUIRED. Build your application
      buildCommands:
        - ./mvnw clean install
      ...

At least one command is required. Zerops triggers each command in the defined order in a dedicated build container.

Before the build commands are triggered the build container contains:

  1. base environment defined by the base attribute
  2. optional customisation of the base environment defined in the prepareCommands attribute
  3. your application code

Run build commands as a single shell instance​

Use following syntax to run all commands in the same environment context. For example, if one command changes the current directory, the next command continues in that directory. When one command creates an environment variable, the next command can access it. Suppose your mvnw executable file is in a cmd directory.

buildCommands:
  - |
    cd cmd
    ./mvnw clean install

Run build commands as a separate shell instances​

When the following syntax is used, each command is triggered in a separate environment context. For example, each shell instance starts in the home directory again. When one command creates an environment variable, it won't be available for the next command. Suppose your mvnw executable file is in a cmd directory.

buildCommands:
  - cd cmd
  - ./cmd/mvnw clean install

Command exit code​

If any command fails, it returns an exit code other than 0 and the build is canceled. Read the build log to troubleshoot the error. If the error log doesn't contain any specific error message, try to run your build with the -X debug option.

buildCommands:
  - ./mvnw -X clean install

If the command ends successfully, it returns the exit code 0 and Zerops triggers the following command. When all buildCommands are finished, the application build is completed and ready for the deploy phase.

deployFiles​

REQUIRED. Selects which files or folders will be deployed after the build has successfully finished. To filter out specific files or folders, use .deployignore file.

# REQUIRED. Select which files / folders to deploy after
# the build has successfully finished
deployFiles:
  - app.jar

Determines files or folders produced by your build, which should be deployed to your runtime service containers.

The path starts from the root directory of your project (the location of zerops.yml). You must enclose the name in quotes if the folder or the file name contains a space.

Examples​

Deploys a folder, and a file from the project root directory:

deployFiles:
  - api
  - app.jar

Deploys the whole content of the build container:

deployFiles: .

Deploys a folder, and a file in a defined path:

deployFiles:
  - ./path/to/file.txt
  - ./path/to/dir/

How to use a wildcard in the path​

Zerops supports the ~ character as a wildcard for one or more folders in the path.

Deploys all file.txt files that are located in any path that begins with /path/ and ends with /to/

deployFiles: ./path/~/to/file.txt

Deploys all folders that are located in any path that begins with /path/to/

deployFiles: ./path/to/~/

Deploys all folders that are located in any path that begins with /path/ and ends with /to/

deployFiles: ./path/~/to/

.deployignore​

Add a .deployignore file to the root of your project and specify which files and folders Zerops should ignore during deploy. The syntax is the same as of a .gitignore file.

Example to ignore src/file.txt file in deploy:

zerops.yml
zerops:
  - setup: app
    build:
      deployFiles: ./
.deployignore
src / file.txt;
Note

.deployignore file also works with zcli service deploy command.

cache​

OPTIONAL. Defines which files or folders will be cached for the next build.

# OPTIONAL. Which files / folders you want to cache for the next build.
# Next builds will be faster when the cache is used.
cache: file.txt

By default, Zerops doesn't cache the files in the build container. When the build phase is finished, the files and folders defined in the deployFiles attribute are saved and deployed to your runtime containers. Then, the build container is deleted. To speed the second and following build up, cache the files that can be used in the next build.

The cache attribute supports the ~ wildcard character.

envVariables​

OPTIONAL. Defines the environment variables for the build environment.

Enter one or more env variables in following format:

zerops:
  # define hostname of your service
  - setup: app
    # ==== how to build your application ====
    build:
      base: java@latest
        …

      # OPTIONAL. Defines the env variables for the build environment:
      envVariables:
        DB_NAME: db
        DB_HOST: db
        DB_USER: db
        DB_PASS: ${db_password}

Read more about environment variables in Zerops.

Runtime configuration​

base​

OPTIONAL. Sets the base technology for the runtime environment. If you don't specify the run.base attribute, Zerops keeps the current Java version for your runtime.

Following options are available for Java builds:

  • java@17
  • java@21
  • java@latest
zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build:
      # REQUIRED. Sets the base technology for the build environment:
      base: java@latest
      ...

    # ==== how to run your application ====
    run:
      # OPTIONAL. Sets the base technology for the runtime environment:
        base: java@latest
      ...

The base runtime environment contains , the selected major version of Java, Zerops command line tool, gitandwget`.

Info

You can change the base environment when you need to. Just simply modify the zerops.yml in your repository.

If you need to install more technologies to the runtime environment, set multiple values as a yaml array. For example:

zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build:
      # REQUIRED. Sets the base technology for the build environment:
      base: java@latest
      ...

    # ==== how to run your application ====
    run:
      # OPTIONAL. Sets the base technology for the runtime environment:
      base:
        - java@latest
      prepareCommands:
        - zsc add nodejs@latest
      ...

See the full list of supported run base environments.

To customise your build environment use the prepareCommands attribute.

os​

OPTIONAL. Sets the operating system for the runtime environment.

Following options are available:

  • alpine
  • ubuntu

Default value is alpine.

We are currently using following os version:

  • Ubuntu 22.04
Caution

The os version is fixed and cannot be customised.

ports​

OPTIONAL. Specifies one or more internal ports on which your application will listen.

Projects in Zerops represent a group of one or more services. Services can be of different types (runtime services, databases, message brokers, object storage, etc.). All services of the same project share a dedicated private network. To connect to a service within the same project, just use the service hostname and its internal port.

For example, to connect to a Java service with hostname = "app" and port = 8080 from another service of the same project, simply use app:8080. Read more about how to access a Java service.

Each port has following attributes:

parameterdescription
portDefines the port number. You can set any port number between 10 and 65435. Ports outside this interval are reserved for internal Zerops systems.
protocolOptional. Defines the protocol. Allowed values are TCP or UDP. Default value is TCP.
httpSupportOptional. httpSupport = true is the default setting for TCP protocol. Set httpSupport = false if a web server isn't running on the port. Zerops uses this information for the configuration of public access. httpSupport = true is available only in combination with the TCP protocol.

prepareCommands​

OPTIONAL. Customises the Java runtime environment by installing additional dependencies or tools to the runtime base environment.

The base Java environment contains , the selected major version of Java, Zerops command line tool and git and wget. To install additional packages or tools add one or more prepare commands:

zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build:
      ...

    # ==== how to run your application ====
    run:
      # OPTIONAL. Customise the runtime environment by installing additional packages
      # or tools to the base Java runtime environment.
      prepareCommands:
        - apt-get something
        - curl something else
      ...

When the first deploy with a defined prepare attribute is triggered, Zerops will

  1. create a prepare runtime container
  2. optionally: copy selected folders or files from your build container
  3. run the prepareCommands commands in the defined order

Command exit code​

If any command fails, it returns an exit code other than 0 and the deploy is canceled. Read the prepare runtime log to troubleshoot the error. If the command ends successfully, it returns the exit code 0 and Zerops triggers the following command. When all prepareCommands commands are finished, your custom runtime environment is ready for the deploy phase.

Cache of your custom runtime environment​

Some packages or tools can take a long time to install. Therefore, Zerops caches your custom runtime environment after the installation of your custom packages or tools is completed. When the second or following deploy is triggered, Zerops will use the custom runtime cache from the previous deploy if following conditions are met:

  1. Content of the build.addToRunPrepare and run.prepareCommands attributes didn't change from the previous deploy
  2. The custom runtime cache wasn't invalidated in the Zerops GUI.

To invalidate the Zerops custom runtime cache go to yyy

// TODO screenshot

When the prepare cache is used, Zerops doesn't create a prepare runtime container and executes the deployment of your application directly.

Single or separated shell instances​

You can configure your prepare commands to be run in a single shell instance or multiple shell instances. The format is identical to build commands.

Copy folders or files from your build container​

The prepare runtime container contains , the selected major version of Java, Zerops command line tool and git and wget.

The prepare runtime container does not contain your application code nor the built application. If you need to copy some folders or files from the build container to the runtime container (e.g. a configuration file) use the addToRunPrepare attribute in the build section.

zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build:
      ...
      addToRunPrepare: ./runtime-config.yml

    # ==== how to run your application ====
    run:
      # OPTIONAL. Customise the runtime environment by installing additional packages
      # or tools to the base Java runtime environment.
      prepareCommands:
        - apt-get something
        - curl something else
      ...

In the example above Zerops will copy the runtime-config.yml file from your build container after the build has finished into the new prepare runtime container. The copied files and folders will be available in the xxx folder in the new prepare runtime container before the prepare commands are triggered.

initCommands​

OPTIONAL. Defines one or more commands to be run each time a new runtime container is started or a container is restarted.

zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build: ...

    # ==== how to run your application ====
    run:
      # OPTIONAL. Run one or more commands each time a new runtime container
      # is started or restarted. These commands are triggered before
      # your Java application is started.
      initCommands:
        - rm -rf ./cache

These commands are triggered in the runtime container before your Java application is started via the start command.

Use init commands to clean or initialise your application cache or similar operations.

Caution

The init commands will delay the start of your application each time a new runtime container is started (including the horizontal scaling or when a runtime container is restarted.

Do not use the init commands for customising your runtime environment. Use the run:prepareCommands attribute instead.

Command exit code​

If any of the initCommands fails, it returns an exit code other than 0, but deploy is not canceled. After all init commands are finished, regardless of the status code, the application is started. Read the runtime log to troubleshoot the error.

Single or separated shell instances​

You can configure your initCommands to be run in a single shell instance or multiple shell instances. The format is identical to build commands.

envVariables​

OPTIONAL. Defines the environment variables for the runtime environment.

Enter one or more env variables in following format:

zerops:
  # define hostname of your service
  - setup: app
    # ==== how to run your application ====
    run:
      # OPTIONAL. Defines the env variables for the runtime environment:
      envVariables:
        DB_NAME: db
        DB_HOST: db
        DB_USER: db
        DB_PASS: ${db_password}

Read more about environment variables in Zerops.

start​

REQUIRED. Defines the start command for your Java application.

zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build: ...

    # ==== how to run your application ====
    run:
      # REQUIRED. Your Java application start command
      start: java -jar target/app.jar

We recommend starting your Java application using java -jar target/app.jar.

health check​

OPTIONAL. Defines a health check.

healthCheck requires either one httpGet object or one exec object.

httpGet​

Configures the health check to request a local URL using a HTTP GET method.

Following attributes are available:

ParameterDescription
portDefines the port of the HTTP GET request.
The readiness check will trigger a GET request on http://127.0.0.1:{port}/{path}
pathDefines the URL path of the HTTP GET request.
The readiness check will trigger a GET request on http://127.0.0.1:{port}/{path}
hostOptional. The readiness check is triggered from inside of your runtime container so it always uses the localhost (127.0.0.1). If you need to add a host to the request header, specify it in the host attribute.
schemeOptional. The readiness check is triggered from inside of your runtime container so no https is required.
If your application requires a https request, set scheme: https

Example:

zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build: ...

    # ==== how to run your application ====
    run:
      # REQUIRED. Your Java application start command
      start: java -jar target/app.jar

      # OPTIONAL. Define a health check with a HTTP GET request option.
      # Configures the check on http://127.0.0.1:80/status
      healthCheck:
        httpGet:
          port: 80
          path: /status

Read more about how the [health check works] in Zerops.

exec​

Configures the health check to run a local command. Following attributes are available:

ParameterDescription
commandDefines a local command to be run.
The command has access to the same environment variables as your Java application.
A single string is required. If you need to run multiple commands create a shell script or, use a multiline format as in the example below.

Example:

zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build: ...

    # ==== how to run your application ====
    run:
      # REQUIRED. Your Java application start command
      start: java -jar target/app.jar

      # OPTIONAL. Define a health check with a shell command.
      healthCheck:
        exec:
          command: |
            touch grass
            rm -rf life
            mv /outside/user /home/user

Read more about how the [health check works] in Zerops.

Deploy configuration​

readiness check​

OPTIONAL. Defines a readiness check. Read more about how the readiness check works in Zerops.

readinessCheck requires either one httpGet object or one exec object.

httpGet​

Configures the readiness check to request a local URL using a http GET method.

Following attributes are available:

ParameterDescription
portDefines the port of the HTTP GET request.
The readiness check will trigger a GET request on http://127.0.0.1:{port}/{path}
pathDefines the URL path of the HTTP GET request.
The readiness check will trigger a GET request on http://127.0.0.1:{port}/{path}
hostOptional. The readiness check is triggered from inside of your runtime container so it always uses the localhost (127.0.0.1). If you need to add a host to the request header, specify it in the host attribute.
schemeOptional. The readiness check is triggered from inside of your runtime container so no https is required.
If your application requires a https request, set scheme: https

Example:

zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build: ...

    # ==== how to deploy your application ====
    deploy:
      # OPTIONAL. Define a readiness check with a HTTP GET request option.
      # Configures the check on http://127.0.0.1:80/status
      readinessCheck:
        httpGet:
          port: 80
          path: /status

    # ==== how to run your application ====
    run: ...

Read more about how the readiness check works in Zerops.

exec​

Configures the readiness check to run a local command. Following attributes are available:

ParameterDescription
commandDefines a local command to be run.
The command has access to the same environment variables as your Java application.
A single string is required. If you need to run multiple commands create a shell script or, use a multiline format as in the example below.

Example:

zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build: ...

    # ==== how to deploy your application ====
    deploy:
      # OPTIONAL. Define a readiness check with a HTTP GET request option.
      # Configures the check on http://127.0.0.1:80/status
      readinessCheck:
        exec:
          command: |
            touch grass
            rm -rf life
            mv /outside/user /home/user

Read more about how the readiness check works in Zerops.

Docs theme & components by the amazing medusajs.com
© 2024 Zerops s.r.o..