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.

Parameter Availability

Not all parameters are available for every service type. Most parameters work across different runtime services, but some are specific to certain service types (e.g., documentRoot for webserver services, routing for Static services). This documentation covers zerops.yaml configuration for runtime services.

🙌Quick Links to Runtime-Specific Guides

Node.js PHP Python Go .NET Rust Java Deno Bun Elixir Gleam Nginx

Basic Structure

zerops.yaml

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

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 Configuration

setup

Contains the hostname of your service (must exist in Zerops).

setup: app

extends

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:
        - npm run build
      deployFiles: ./dist
    run:
      start: npm start

  - setup: prod
    extends: base
    run:
      envVariables:
        NODE_ENV: production

  - setup: dev
    extends: base
    run:
      envVariables:
        NODE_ENV: development

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

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

Sets the operating system for the build environment. Options:

alpine (default)
ubuntu

Current versions:

Alpine 3.20
Ubuntu 24.04

build:
  os: ubuntu

prepareCommands

Customizes the build environment by installing additional dependencies or tools.

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

buildCommands

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

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

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

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

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

run:
  base: nodejs@latest

os

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

ports

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

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

Specifies the network protocol to use:

Allowed values: TCP (default) or UDP

httpSupport

Indicates whether the port is running a web server:

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

prepareCommands

Customizes the runtime environment by installing additional dependencies or tools.

addToRunPrepare

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

initCommands

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

run:
  initCommands:
    - rm -rf ./cache

start

Defines the start command for your application.

run:
  start: npm start

startCommands

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

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

siteConfigPath

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

envVariables

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}

envReplace

Automatically replaces environment variable placeholders in your static files with their actual values during deployment.

run:
  envReplace:
    delimiter: "%%"
    target:
      - config/jwt/public.pem
      - config/jwt/private.pem
      - ./config/

Available parameters:

delimiter

Characters that wrap your variable names in placeholders (e.g., %% means placeholders look like %%VARIABLE%%).

Type: string or array of strings
Supports multiple delimiters simultaneously

target

Files or directories to process for variable replacement.

Type: string or array of strings
Can be specific files or directories

Warning

Directory targets only process files directly in the specified directory, not subdirectories for performance reasons. To process files in subdirectories, specify each subdirectory explicitly in the target array. For example, ./config/ processes only files in the config directory itself, not files in ./config/jwt/ or other subdirectories.

How it works:

Define placeholders in your files using the specified delimiters
Set environment variables with matching names
During deployment, Zerops finds and replaces placeholders with actual values

Example usage:

run:
  envReplace:
    delimiter: "%%"
    target:
      - ./config/
      - ./templates/
      - ./              # Only processes files in root, not subdirectories

File content before replacement:

# config/jwt/public.pem
%%JWT_PUBLIC_KEY_CONTENT%%

Environment variable:

JWT_PUBLIC_KEY_CONTENT=-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA...
-----END PUBLIC KEY-----

The placeholder gets replaced with the actual JWT public key during deployment.

routing

Configures URL routing, redirects, and HTTP headers (only for Static services).

run:
  routing:
    root: /custom/root
    cors: "'*' always"
    redirects:
      - from: /old-path
        to: /new-path
        status: 301
    headers:
      - for: "/*"
        values:
          X-Frame-Options: "'DENY'"

Available parameters:

root

Sets a custom root directory for the service.

Type: string

cors

Enables CORS headers for cross-origin requests.

Type: string
Sets Access-Control-Allow-Origin, Access-Control-Allow-Methods, Access-Control-Allow-Headers, and Access-Control-Expose-Headers
Special case: "*" is automatically converted to '*'

redirects

Defines URL redirects and rewrites.

Type: array of objects
Each redirect object supports:
- from - Source path to match (supports wildcards with *)
- to - Destination path
- status - HTTP status code (required for absolute URLs)
- preservePath - Preserve path after wildcard match
- preserveQuery - Preserve query parameters

headers

Sets custom HTTP headers for specific paths.

Type: array of objects
Each header object supports:
- for - Path pattern to match
- values - Object with header name/value pairs

Example usage:

run:
  routing:
    cors: "'*' always"
    redirects:
      # Permanent redirect
      - from: /old-page
        to: /new-page
        status: 301
      # Wildcard redirect with path preservation
      - from: /blog/*
        to: /articles/
        preservePath: true
        status: 302
    headers:
      - for: "/*"
        values:
          X-Frame-Options: "'DENY'"
          Content-Security-Policy: '"default-src ''self''"'

healthCheck

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

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

port - Defines the port of the HTTP GET request.
path - Defines the URL path of the HTTP GET request.
host - 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 - 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

Configures the health check to run a local command.

command - 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

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

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

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

Setup cron jobs. See examples.

Deploy Configuration

temporaryShutdown

Controls the container replacement order during deployment.

deploy:
  temporaryShutdown: true

Type: boolean
Default: false

When false (default): New containers are started before old containers are removed, ensuring zero-downtime deployment.

When true: Old containers are removed before new containers are started, causing temporary downtime but using fewer resources during deployment.

readinessCheck

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

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.

Need help? Join our Discord community.

CDN

Base List

Basic Structure​

Service Configuration​

setup Required​

extends Optional​

Build Configuration​

base Required​

os Optional​

prepareCommands Optional​

buildCommands Required​

Running commands in a single shell instance:​

deployFiles Required​

Using wildcards:​

.deployignore​

cache Optional​

envVariables Optional​

Runtime Configuration​

base Optional​

os Optional​

ports Optional​

port Required​

protocol Optional​

httpSupport Optional​

prepareCommands Optional​

addToRunPrepare Optional​

initCommands Optional​

start Required for some runtimes​

startCommands Optional​

documentRoot Optional​

siteConfigPath Optional​

envVariables Optional​

envReplace Optional​

delimiter Required​

target Required​

routing Optional​

root Optional​

cors Optional​

redirects Optional​

headers Optional​

healthCheck Optional​

httpGet Optional​

exec Optional​

Common parameters Optional​

crontab Optional​

Deploy Configuration​

temporaryShutdown Optional​

readinessCheck Optional​

httpGet and exec​

Common parameters Optional​

Basic Structure

Service Configuration

setup

extends

Build Configuration

base

os

prepareCommands

buildCommands

Running commands in a single shell instance:

deployFiles

Using wildcards:

.deployignore

cache

envVariables

Runtime Configuration

base

os

ports

port

protocol

httpSupport

prepareCommands

addToRunPrepare

initCommands

start

startCommands

documentRoot

siteConfigPath

envVariables

envReplace

delimiter

target

routing

root

cors

redirects

headers

healthCheck

httpGet

exec

Common parameters

crontab

Deploy Configuration

temporaryShutdown

readinessCheck

httpGet and exec

Common parameters