Build & deploy pipeline

Configure the pipeline

Zerops provides a customizable build and runtime environment for your application. Start by adding a zerops.yaml file to the root of your repository and modify it to fit your application.

Here is a basic example for a Node.js application:

zerops:
  - setup: api
    build:
      base: nodejs@20
      buildCommands:
        - npm i
        - npm run build
      deployFiles: ./dist
      cache: node_modules
    run:
      base: nodejs@20
      start: npm start

The zerops.yaml in your repository tells Zerops how to build and deploy your application. When the build & deploy pipeline triggers for the Node.js service named api, Zerops will:

1. Create a build environment with Node.js v.20 preinstalled
2. Run build commands: npm i, npm run build
3. Create a runtime environment with Node.js v.20 preinstalled
4. Deploy the built artifact from the ./dist folder to runtime containers
5. Cache the ./node_modules folder for faster subsequent builds
6. Start your application using npm start

Learn more about zerops.yaml parameters for your runtime:

🚀Know more about zerops.yaml for your Runtime

Node.jsPHPPythonGo.NETRust

Trigger the pipeline

Automatically

Trigger the build & deploy pipeline automatically with each push to the selected branch or with a new tag. Create a new runtime service and connect it to your GitHub or GitLab repository.

Github Integration via Zerops GUI

Manually

Start a new build & deploy pipeline manually using the Zerops CLI. The zcli service push command uploads your application code, builds and deploys your application in Zerops.

The command triggers the build pipeline defined in zerops.yaml. The zerops.yaml file must be in the working directory (current directory by default, changeable with the --workingDir flag).

zCLI uploads all files and subdirectories from the working directory to Zerops and starts the build pipeline. If a .gitignore file exists, Zerops interprets it and ignores the defined files and folders.

Push command parameters

Usage:
  zcli push [flags]

Flags:
      --archiveFilePath string   If set, zCLI creates a tar.gz archive with the application code in the required path relative
                                 to the working directory. By default, no archive is created.
      --deployGitFolder          If set, zCLI the .git folder is also uploaded. By default, the .git folder is ignored.
  -h, --help                     the service push command.
      --projectId string         If you have access to more than one project, you must specify the project ID for which the
                                 command is to be executed.
      --serviceId string         If you have access to more than one service, you must specify the service ID for which the
                                 command is to be executed.
      --versionName string       Adds a custom version name. Automatically filled if the VERSIONNAME environment variable exists.
      --workingDir string        Sets a custom working directory. Default working directory is the current directory. (default "./")
      --zeropsYamlPath string    Sets a custom path to the zerops.yaml file relative to the working directory. By default zCLI
                                 looks for zerops.yaml in the working directory.

If you want to deploy your already built application to Zerops, use the zcli service deploy command instead.

Build phase

Zerops starts a temporary build container and executes these steps:

1. Install build environment - Sets up the runtime and tools
2. Download source code - From GitHub ↗, GitLab ↗ or via Zerops CLI
3. Customize environment - Runs optional preparation commands
4. Execute build commands - Compiles and packages your application
5. Upload artifacts - Stores build output in internal Zerops storage
6. Cache files - Optionally caches selected files for faster future builds

Zerops automatically deletes the build container after the build finishes or fails.

Build hardware resources

All runtime services use the same hardware resources for build containers:

HW resource	Minimum	Maximum
CPU cores	1	5
RAM	8 GB	8 GB
Disk	1 GB	100 GB

Build containers start with minimum resources and scale vertically up to maximum capacity as needed.

Info

Build container resources are not charged. Build costs are covered by the standard Zerops project fee.

Build time limit

The entire build pipeline has a 1 hour time limit. After 1 hour, Zerops terminates the build pipeline and deletes the build container.

Customize the build environment

All runtime services start with a default build environment based on the build.base attribute in zerops.yaml. Install additional packages or tools by adding build.prepareCommands to your configuration.

Learn more about customizing build environments:

🚀Customize your build environment of your Runtime

Node.jsPHPPythonGo.NETRustJava

Runtime prepare phase (optional)

When your application requires additional system packages, libraries, or tools in the runtime environment, Zerops allows you to build a custom runtime image. This optional phase occurs after the build phase and before deployment.

When to use custom runtime images

Build custom runtime images when you need:

• System packages or libraries for runtime operations (e.g., apk add imagemagick for image processing)
• Library dependencies for interpreted languages or dynamically linked binaries
• System-level tools or utilities your application requires
• Customized base operating system or additional software layers

Configuration

Configure custom runtime images in your zerops.yml file using these fields:

run.os + run.base

Specify the operating system and base packages for your custom runtime image:

run:
  os: alpine # or ubuntu
  base: nodejs@20 # specify your runtime and version

run.prepareCommands

Define commands that customize your runtime image. These commands run inside a fresh base container:

run:
  prepareCommands:
    - sudo apk add --no-cache imagemagick
    - sudo apt-get update && apt-get install -y some-package  # for Ubuntu

Zerops creates the custom runtime image from this container after all commands complete successfully.

build.addToRunPrepare

Copy specific files from the build phase to the runtime prepare phase. This is useful when you need source files during runtime preparation:

build:
  addToRunPrepare:
    - package.json
    - requirements.txt
    - config/runtime-setup.sh

These files are packed immediately after build.buildCommands finish and become available during the runtime prepare phase.

How it works

When you trigger the first deploy with defined run.prepareCommands, Zerops:

1. Creates prepare container - Based on run.os and run.base
2. Copies build files - Files specified in build.addToRunPrepare (if any)
3. Runs prepare commands - Executes run.prepareCommands in order
4. Creates runtime image - Builds custom runtime image from the prepared container
5. Uses for deployment - Deploys your application using this custom runtime image

Custom runtime image caching

Zerops caches custom runtime images to optimize deployment times. The runtime prepare phase is skipped and cached images are reused when:

• It is not the first deployment of your service
• None of these zerops.yaml fields changed since the last deployment:
  • run.os or run.base
  • run.prepareCommands
  • build.addToRunPrepare
• File contents specified in build.addToRunPrepare remain unchanged
• The custom runtime image cache hasn't been manually invalidated

Manual cache invalidation

To invalidate the custom runtime image cache, go to your service detail in the Zerops GUI, choose Pipelines & CI/CD settings section from the left menu, and click on the button under Pipeline #. Then click on the Clear runtime prepare image button.

Learn more about building custom runtime images:

🚀Build custom runtime images for your Runtime

Node.jsPHPPythonGo.NETRustJava

Warning

Do not include your application code in the custom runtime image, as your built application code is deployed automatically into fresh containers.

Shared storage mounts are also not available during the runtime prepare phase.

Deploy phase

Application artifacts

After the build phase completes, Zerops stores the application artifact in internal storage and deletes the build container.

For manual deployments using Zerops CLI, the application artifact is also uploaded to internal storage.

Zerops uses the stored artifact to deploy identical versions of your application whenever a new container starts:

• During new application version deployments
• When applications scale horizontally
• When runtime containers fail and new containers start automatically

First deploy

For initial deployments, Zerops starts one or more runtime containers based on your service auto scaling settings.

Zerops executes these steps for each new container:

1. Install runtime environment - Sets up the runtime (or uses a custom runtime image if configured)
2. Download application artifact - Retrieves build output from internal storage
3. Run initialization - Executes optional init commands
4. Start application - Launches your app using the start command
5. Check readiness - Waits for readiness check to succeed (if configured)
6. Activate container - Container becomes active and receives incoming requests

Services with multiple containers deploy in parallel.

Info

If your application needs initialization in each runtime container, add init commands to zerops.yaml.

Caution

Do not use initCommands for runtime environment customization. See how to build custom runtime images.

Subsequent deploys

For applications with existing running versions, Zerops starts new containers matching the count of existing containers.

Zerops executes the same steps as the first deployment for each new container. Your service briefly contains both new and old versions during this process.

Old containers are then removed from the project balancer to stop receiving new requests. The processes inside old containers terminate and Zerops gradually deletes all old containers.

Readiness checks

If your application is not ready to handle requests immediately after starting via the start command, configure a readiness check in your zerops.yaml.

When readiness checks are defined, Zerops:

1. Starts your application
2. Performs readiness check
3. Waits and retries - If check fails, waits 5 seconds and repeats step 2
4. Activates container - If check succeeds, marks container as active

Runtime containers with pending readiness checks do not receive incoming requests - only active containers handle traffic.

If readiness checks fail for 5 minutes, Zerops marks the container as failed, deletes it, creates a new container, and repeats the deployment process.

Readiness check types:

• httpGet - Succeeds when URL returns HTTP 2xx status (5-second timeout, follows 3xx redirects)
• exec.command - Succeeds when command returns status code 0 (5-second timeout)

Read the runtime log to troubleshoot failed readiness checks.

Manual deploy using Zerops CLI

Start deploy-only pipelines using the Zerops CLI. The zcli service deploy command uploads and deploys your application in Zerops. Use this when you have your own build process. For building applications in Zerops, use automatic or manual build processes instead.

Usage:
  zcli service deploy pathToFileOrDir [flags]

Flags:
      --archiveFilePath string   If set, zCLI creates a tar.gz archive with the application code in the required path relative
                                 to the working directory. By default, no archive is created.
      --deployGitFolder          Sets a custom path to the zerops.yaml file relative to the working directory. By default zCLI
                                 looks for zerops.yaml in the working directory.
  -h, --help                     the service deploy command.
      --projectId string         If you have access to more than one project, you must specify the project ID for which the
                                 command is to be executed.
      --serviceId string         If you have access to more than one service, you must specify the service ID for which the
                                 command is to be executed.
      --versionName string       Adds a custom version name. Automatically filled if the VERSIONNAME environment variable exists.
      --workingDir string        Sets a custom working directory. Default working directory is the current directory. (default "./")
      --zeropsYamlPath string    Sets a custom path to the zerops.yaml file relative to the working directory. By default zCLI
                                 looks for zerops.yaml in the working directory.

pathToFileOrDir defines paths to directories and/or files relative to the working directory. The working directory defaults to the current directory and can be changed using the --workingDir flag.

Place zerops.yaml in the working directory.

Info

You can modify the deploy pipeline anytime by updating the zerops.yaml in your working directory.

Manage build and deploys

Cancel running build

When you need to cancel an incorrect running build, use the Zerops GUI. Go to the service detail, open the running processes list, and click Open pipeline detail. Then click Cancel build.

Caution

Build cancellation is only available before the build pipeline finishes. Once the build completes, deployment cannot be cancelled.

Application versions

Zerops keeps the 10 most recent versions of your application in internal storage.

Access the application versions list in Zerops GUI by going to service detail and choosing the Pipelines & CI/CD settings section from the left menu. The active version is highlighted - click the button below to show all archived versions.

Access pipeline details from the additional menu. Pipeline details contain:

• Pipeline configuration (zerops.yaml) used for the selected version
• Build log (if available)
• Prepare runtime log (if available)

You can download the build artifact for selected versions or manually delete inactive versions.

Restore an archived version

Restore archived versions by choosing Activate from the additional menu. Zerops will deploy the selected version and archive the currently active version.

Environment variables restore to their state from the last moment when the selected version was active.