Build & deploy pipeline

Configure the pipeline

Zerops provides a customizable build and runtime environment for your application. Start by adding a zerops.yml 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.yml in your repository tells Zerops how to build and deploy your application.

Zerops will follow these instruction when the build & deploy pipeline is triggered for the Node.js service named api:

1. Create a standard build environment with the Node.js v.20 preinstalled.
2. Build your app using these commands: npm i, npm run build
3. Create a standard runtime environment with the Node.js v.20 preinstalled.
4. Deploy the built artefact from the ./dist folder to the runtime container
5. Cache the content of the ./node_modules folder for the next build
6. Start your application using the npm start command

Learn more about all zerops.yml parameters for your runtime:

• Node.js
• PHP
• Python
• Go
• .NET
• Rust
• Java

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 repository or GitLab repository.

Github Integration via Zerops GUI

Manually

To start a new build & deploy pipeline manually, use the Zerops CLI. zCLI is the Zerops command-line tool.

The zcli push command uploads your application code, builds and deploys your application in Zerops.

The command triggers the build pipeline defined in zerops.yml. zerops.yml must be in the working directory. The working directory is by default the current directory and can be changed using the --workingDir flag.

zCLI uploads all files and subdirectories of the working directory to Zerops and starts the build pipeline. If the .gitignore file is found, it is interpreted and the defined files and folders will be ignored.

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.yml file relative to the working directory. By default zCLI
                                 looks for zerops.yml in the working directory.

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

Build phase

Zerops starts a temporary build container and performs following actions:

1. Installs the build environment.
2. Downloads your application source code from GitHub ↗, GitLab ↗ or via [Zerops CLI].
3. Optionally customises the build environment.
4. Runs the build commands.
5. Uploads the application artefact to the internal Zerops storage and prepares it for the deploy.
6. Optionally caches the selected files for the next build.

The build container is automatically deleted after the build has finished or failed.

Build hardware resources

Each runtime service have different HW resources for build containers:

• Node.js
• PHP
• Python
• Go
• .NET
• Rust
• Java

The build container is always started with the minimum hardware resources and scales vertically up to the maximum resources.

Info

Hardware resources of the build containers are not charged. The build costs are covered by the standard Zerops project fee.

Build time limit

The time limit for the whole build pipeline is 1 hour. After 1 hour, Zerops terminates the build pipeline and deletes the build container.

Customise the build environment

Each runtime service in Zerops has a default build environment with a major version based on the build.base attribute in zerops.yml. To install additional packages or tools add one or more build.prepareCommands commands to your zerops.yml.

Learn more about what is included in the default build environment:

• Node.js
• PHP
• Python
• Go
• .NET
• Rust
• Java

Deploy phase

Application artefact

When the build phase is finished, the application artefact is stored in the internal Zerops storage and the build container is deleted.

If you triggered the deploy pipeline manually using Zerops CLI, the application artefact is also uploaded to the internal Zerops storage.

Zerops uses the stored artefact to deploy the identical version of your application each time a new container is started:

• when a new application version is deployed
• when the application scales horizontally
• when a runtime container fails and a new container is started automatically

First deploy

When your application is deployed for the first time, Zerops will start one or more runtime containers based on the service auto scaling settings.

Zerops performs following actions for each new container:

1. Installs the runtime environment
2. Downloads the application artefact from the internal storage
3. Optionally runs the init commands
4. Starts your application using the start command
5. Optionally waits until the readiness check succeeds
6. The container is now active and receives incoming requests.

Services with multiple containers are deployed in parallel.

Info

If your application needs to be initialized in each runtime container, add init commands to zerops.yml.

Caution

Do not use the initCommands for customising your runtime environment. See how to customise the runtime environment.

Further deploys

When a previous version of your application is already running, Zerops will start new containers. The count of new containers will be the same as the count of existing containers.

Zerops performs the identical actions for each new container as the first deployment. When all new containers are started your service contains both new and old versions for a short period of time.

The old containers are then removed from the project balancer so they don't receive new requests. The PHP process inside each of the old containers is terminated and all old containers are gradually deleted.

Readiness checks

If your application isn't ready to handle requests right after it is started via the start command, configure a readiness check in your zerops.yml.

If the readiness check is defined, Zerops will:

1. Start your application
2. Perform a readiness check
3. If the readiness check fails, wait 5 seconds and repeat step 2.
4. If the readiness check succeeds, set the container as active.

Application in the runtime container with a pending readiness check won't receive any incoming requests. Only active containers receive incoming requests to your Node.js service.

If the readiness check is still failing after 5 minutes, the specific runtime container is marked as failed and Zerops will delete it, create a new runtime container and perform the deploy.

The httpGet readiness check is successful when the URL returns HTTP status code 2xx. The timeout is 5 seconds. When the URL returns a 3xx HTTP status, the readiness check HTTP client will follow the redirect.

The exec.command readiness check is successful when the command returns status code 0. The timeout is 5 seconds.

Read the runtime log to troubleshoot failed readiness checks.

Customise the runtime environment

Each runtime service in Zerops has a default runtime environment with a major version based on the run.base attribute in zerops.yml. To install additional packages or tools add one or more run.prepareCommands commands to your zerops.yml.

Learn more about what is included in the default runtime environment:

• Node.js
• PHP
• Python
• Go
• .NET
• Rust
• Java

When the first deploy with a defined prepareCommands 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 run.prepareCommands commands in the defined order

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.

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

Manual deploy using Zerops CLI

To start only a deploy pipeline, use the Zerops CLI. zCLI is the Zerops command-line tool.

The zcli service deploy command uploads your application and deploys it in Zerops. Use this tool if you have your own build process. If you want to build your application in Zerops, use an automatic or manual build process.

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.yml file relative to the working directory. By default zCLI
                                 looks for zerops.yml 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.yml file relative to the working directory. By default zCLI
                                 looks for zerops.yml in the working directory.

pathToFileOrDir defines a path to one or more directories and/or files relative to the working directory. The working directory is by default the current directory and can be changed using the
--workingDir flag.

zerops.yml must be placed in the working directory.

Info

You can change the deploy pipeline when you need to. Just simply modify the zerops.yml in your working directory.

Manage build and deploys

Cancel running build

When you know that the running build is not correct and you want to cancel it, you can do it in Zerops GUI. Go to the service detail, open the list of running processes and click on the Open pipeline detail button. Then click on the Cancel build button.

Caution

The build cancellation is available before the build pipeline is finished. When the build is finished, the deployment cannot be cancelled.

Application versions

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

The list of application versions is available in Zerops GUI. Go to the service detail and choose Service dashboard & runtime containers from the left menu. The active version is highlighted, show all archived version by clicking on the button below.

The pipeline detail is accessible from the additional menu. The pipeline detail contains

• The pipeline config (zerops.yml) that was used for the selected version
• The build log (if available)
• The prepare runtime log (if available)

You can download the build artefact of the selected version or delete an inactive version manually.

Restore an archived version

You can restore an archived version by choosing the Activate item from the additional menu. Zerops will deploy the selected version and the active version will be archived.

The environment variables will be restored to the latest moment when the selected version was active.