Zerops YAML Configuration

The zerops.yaml file is crucial for defining how Zerops should build and deploy your application. Add the zerops.yaml file to the root of your repository and customize it to suit your application's needs.

---

🙌Quick Links to Runtime-Specific Guides

Node.jsPHPPythonGo.NETRustJavaNginx

Basic Structure

zerops.yaml

zerops:
  - setup: <service_name>
    build: ...
    run: ...

• The top-level element is always zerops.
• setup contains the hostname of your service (must exist in Zerops).
• Multiple services can be defined in a single zerops.yaml (useful for monorepos):

zerops:
  - setup: app
    build: ...
    run: ...

  - setup: api
    build: ...
    run: ...

Each service configuration requires build and run sections. An optional deploy section can be added for readiness checks.

Service Inheritance

extends Optional

The extends key allows you to inherit configuration from another service defined in the same zerops.yaml file. This is useful for creating environment-specific configurations while maintaining a common base.

zerops:
  - setup: base
    build:
      buildCommands:
        - echo "hello"
      deployFiles: ./
    run:
      start: server run

  - setup: prod
    extends: base
    run:
      crontab:
        - command: xyz
          allContainers: false
          timing: "* * * * *"

  - setup: dev
    extends: base
    run:
      crontab:
        - command: different command
          allContainers: false
          timing: "* * * * *"

When using extends:

• The extends value must refer to another service's setup value in the same file
• The child service inherits all configuration from the base service
• Configuration is merged at the section level (build, run, deploy)
• You can override specific sections by redefining them

Tip

Create a base service with common configuration and extend it for environment-specific services to keep your zerops.yaml file DRY (Don't Repeat Yourself).

Build Configuration

base Required

Sets the base technology for the build environment. See available options.

build:
  base: nodejs@latest

You can specify multiple technologies:

build:
  base:
    - nodejs@latest
  prepareCommands:
    - zsc add python@3.9

os Optional

Sets the operating system for the build environment. Options:

• alpine (default)
• ubuntu

Current versions:

• Alpine 3.20
• Ubuntu 24.04

build:
  os: ubuntu

prepareCommands Optional

Customizes the build environment by installing additional dependencies or tools.

build:
  prepareCommands:
    - apt-get update
    - apt-get install -y some-package

buildCommands Required

Defines the commands to build your application.

build:
  buildCommands:
    - npm install
    - npm run build

Running commands in a single shell instance:

buildCommands:
  - |
    npm install
    npm run build

deployFiles Required

Specifies which files or folders to deploy after a successful build.

build:
  deployFiles:
    - dist
    - package.json
    - node_modules

The files/folders will be placed into /var/www folder in runtime, e.g. ./src/assets/fonts would result in /var/www/src/assets/fonts.

Using wildcards:

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

By default, ./src/assets/fonts deploys to /var/www/src/assets/fonts, keeping the full path. Adding ~, like ./src/assets/~fonts, shortens it to /var/www/fonts

.deployignore

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

To ignore a specific file or directory path, start the pattern with a forward slash (/). Without the leading slash, the pattern will match files with that name in any directory.

Tip

For consistency, it's recommended to configure both your .gitignore and .deployignore files with the same patterns.

Examples:

zerops.yaml

zerops:
  - setup: app
    build:
      deployFiles: ./

.deployignore

/src/file.txt

The example above ignores file.txt only in the root src directory.

.deployignore

src/file.txt

This example above ignores file.txt in ANY directory named src, such as:

• /src/file.txt
• /folder2/folder3/src/file.txt
• /src/src/file.txt

Note

.deployignore file also works with zcli service deploy command.

cache Optional

Defines which files or folders to cache for subsequent builds.

build:
  cache: node_modules

For more information, see our detailed guide on build cache, complete with extensive examples.

envVariables Optional

Sets environment variables for the build environment.

build:
  envVariables:
    DB_NAME: db
    DB_HOST: db
    DB_USER: db
    DB_PASS: ${db_password}

Info

The yamlPreprocessor option in your project & service import YAML allows you to generate random secret values, passwords, and public/private key pairs. For more information, see the yamlPreprocessor page.

Runtime Configuration

base Optional

Sets the base technology for the runtime environment. If not specified, the current version is maintained.

run:
  base: nodejs@latest

os Optional

Sets the operating system for the runtime environment. Options and versions are the same as for the build environment.

ports Optional

Specifies the internal ports on which your application will listen.

run:
  ports:
    - port: 8080
      protocol: TCP # Optional
      httpSupport: true # Optional
    - port: 8081
      ...

Available parameters:

port Required

Defines the port number on which your application listens. Must be between 10 and 65435, as ports outside this range are reserved for internal Zerops systems.

protocol Optional

Specifies the network protocol to use:

• Allowed values: TCP (default) or UDP

httpSupport Optional

Indicates whether the port is running a web server:

• Default value: true
• Set to false if a web server isn't running on the port
• Only available with TCP protocol
• Used by Zerops for public access configuration

prepareCommands Optional

Customizes the runtime environment by installing additional dependencies or tools.

addToRunPrepare Optional

Defines files or folders to be copied from the build container to the prepare runtime container.

initCommands Optional

Defines commands to run each time a new runtime container starts or restarts.

run:
  initCommands:
    - rm -rf ./cache

start Required for some runtimes

Defines the start command for your application.

run:
  start: npm start

startCommands Optional

Defines start commands

Unlike start, you can define multiple commands that starts their own processes.

run:
  startCommands:
    # start the application
    - command: npm run start:prod
      name: server
    # start the replication
    
    - command: litestream replicate -config=litestream.yaml
      name: replication
      # restore the database on container init
      initCommands:
        - litestream restore -if-replica-exists -if-db-not-exists -config=litestream.yaml $DB_NAME

See start-commands-example

documentRoot Optional

Customizes the root folder for publicly accessible web server content (available only for webserver runtimes).

siteConfigPath Optional

Sets the custom webserver configuration (available only for webserver runtimes).

envVariables Optional

Defines environment variables for the runtime environment.

    run:
      base: nodejs@20
      envVariables:
        DB_NAME: db
        DB_HOST: db
        DB_USER: db
        DB_PASS: ${db_password}

healthCheck Optional

Defines a health check for your application.

run:
  healthCheck:
    # HTTP GET method example
    httpGet:
      port: 80
      path: /status
      host: my-host.zerops
      scheme: https
    # OR command-based example
    exec:
      command: |
        curl -s http://localhost:8080/status > /tmp/status
        grep -q "OK" /tmp/status

    # Common parameters
    failureTimeout: 60
    disconnectTimeout: 30
    recoveryTimeout: 30
    execPeriod: 10

Available parameters:

httpGet Optional

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

• port Required - Defines the port of the HTTP GET request.
• path Required - Defines the URL path of the HTTP GET request.
• host Optional - The health check is triggered from inside of your runtime container so it uses the localhost (127.0.0.1). If you need to add a host to the request header, specify it in the host attribute.
• scheme Optional - The health check is triggered from inside of your runtime container so no https is required. If your application requires a https request, set scheme: https.

exec Optional

Configures the health check to run a local command.

• command Required - Defines a local command to be run. The command has access to the same environment variables. 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 above.

Common parameters Optional

The following parameters can be used with either httpGet or exec health checks:

• failureTimeout - Time in seconds until container fails after consecutive health check failures (reset by success).
• disconnectTimeout - Time in seconds until container is disconnected and becomes publicly unavailable.
• recoveryTimeout - Time in seconds until container is connected and becomes publicly available.
• execPeriod - Time interval in seconds between health check attempts.

Tip

Health checks continuously monitor your running application, while readiness checks verify if a new deployment is ready to receive traffic. For readiness checks, see the readinessCheck section.

crontab Optional

Defines scheduled commands to run as cron jobs within a service.

run:
  crontab:
    - command: "date >> /var/log/cron.log"
      timing: "0 * * * *"

Setup cron jobs. See examples.

Deploy Configuration

readinessCheck Optional

Defines a readiness check for your application. Requires either httpGet object or exec object.

deploy:
  readinessCheck:
    # HTTP GET method example
    httpGet:
      port: 80
      path: /status
      host: my-host.zerops
      scheme: https

    # Common parameters
    failureTimeout: 60
    retryPeriod: 10

Readiness checks work similarly to health checks but are specifically for deployment. They verify if a new deployment is ready to receive traffic.

Available parameters:

httpGet and exec

The httpGet and exec options work the same way as in health checks. See that section for detailed parameter descriptions.

Common parameters Optional

The following parameters can be used with either httpGet or exec readiness checks:

• failureTimeout - Time in seconds until container is marked as failed.
• retryPeriod - Time interval in seconds between readiness check attempts (equivalent to execPeriod in health checks).

Tip

Unlike health checks which run continuously, readiness checks only run during deployments to determine when your application is ready to accept traffic.

Note

For more detailed information on specific configurations, refer to the runtime-specific guides linked at the beginning of this document.

---