Zerops.yaml Specification

This page provides a comprehensive reference for all available parameters in the zerops.yaml configuration file.

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).

File Structure

zerops:
  - setup: service-name
    extends: base-service  # optional
    build:                 # optional
      ...
    deploy:                # optional
      ...
    run:                   # required
      ...

Top-Level Configuration

setup

string

required

The hostname of your service. Must match an existing service in your Zerops project.

setup: app

extends

string

Inherit configuration from another service defined in the same zerops.yaml file. Useful for environment-specific configurations.

zerops:
  - setup: base
    build:
      buildCommands:
        - npm run build
    run:
      start: npm start

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

How it works:

The extends value must refer to another service’s setup value
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

Build Configuration

The build section defines how your application should be built before deployment.

base

build.base

string | string[]

required

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

build:
  base: nodejs@latest

You can specify multiple technologies:

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

os

build.os

string

default:"alpine"

Sets the operating system for the build environment.Options:

alpine (default)
ubuntu

build:
  os: ubuntu

prepareCommands

build.prepareCommands

string[]

Commands to customize the build environment by installing additional dependencies or tools.

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

buildCommands

build.buildCommands

string[]

Commands to build your application.

build:
  buildCommands:
    - npm install
    - npm run build

Run commands in a single shell instance:

buildCommands:
  - |
    npm install
    npm run build

deployFiles

build.deployFiles

string | string[]

required

Files or folders to deploy after a successful build. Files are placed in /var/www in the runtime container.

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

Using wildcards:The ~ character acts as a wildcard for one or more folders:

# Deploys all file.txt files in any path beginning with /path/ and ending with /to/
deployFiles: ./path/~/to/file.txt

# ./src/assets/fonts -> /var/www/fonts (shortened path)
deployFiles: ./src/assets/~fonts

Using .deployignore:Add a .deployignore file to your project root to exclude files during deployment. Uses the same pattern format as .gitignore.

.deployignore

/src/file.txt        # Ignores file only in root src directory
src/file.txt         # Ignores file in any directory named src

cache

build.cache

string | string[]

Files or folders to cache for subsequent builds.

build:
  cache: node_modules

For detailed information, see the build cache guide.

addToRunPrepare

build.addToRunPrepare

string | string[]

Files or folders to copy from the build container to the prepare runtime container.

envVariables

build.envVariables

object

Environment variables for the build environment.

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

The yamlPreprocessor option in your import YAML allows you to generate random values and keys. See yamlPreprocessor.

Deploy Configuration

The deploy section controls deployment behavior.

temporaryShutdown

deploy.temporaryShutdown

boolean

default:false

Controls the container replacement order during deployment.

deploy:
  temporaryShutdown: true

false (default): New containers start before old containers are removed (zero-downtime)
true: Old containers are removed before new containers start (temporary downtime, fewer resources)

readinessCheck

deploy.readinessCheck

object

Defines a readiness check to verify if a new deployment is ready to receive traffic. Requires either httpGet or exec.

deploy:
  readinessCheck:
    httpGet:
      port: 80
      path: /status
      host: my-host.zerops
      scheme: https
    failureTimeout: 60
    retryPeriod: 10

readinessCheck.httpGet

deploy.readinessCheck.httpGet

object

Configure HTTP GET health check.Parameters:

port (required) - Port number for the HTTP request
path (required) - URL path for the HTTP request
host - Host header for the request (default: localhost)
scheme - HTTP or HTTPS (default: HTTP)

readinessCheck:
  httpGet:
    port: 3000
    path: /health
    scheme: https

readinessCheck.exec

deploy.readinessCheck.exec

object

Configure command-based health check.Parameters:

command (required) - Shell command to execute

readinessCheck:
  exec:
    command: curl -s http://localhost/status | grep OK

readinessCheck.failureTimeout

deploy.readinessCheck.failureTimeout

number

Time in seconds until container is marked as failed.

readinessCheck.retryPeriod

deploy.readinessCheck.retryPeriod

number

Time interval in seconds between readiness check attempts.

Runtime Configuration

The run section defines how your application runs in production.

base

run.base

string

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

run:
  base: nodejs@latest

os

run.os

string

Sets the operating system for the runtime environment. Same options as build.os.

ports

run.ports

array

Internal ports on which your application will listen.

run:
  ports:
    - port: 8080
      protocol: TCP
      httpSupport: true
    - port: 8081
      protocol: UDP

ports[].port

run.ports[].port

number

required

Port number between 10 and 65435.

ports[].protocol

run.ports[].protocol

string

default:"TCP"

Network protocol: TCP or UDP

ports[].httpSupport

run.ports[].httpSupport

boolean

default:false

Set to true if a web server is running on this port. Only available with TCP protocol.

prepareCommands

run.prepareCommands

string[]

Commands to customize the runtime environment.

initCommands

run.initCommands

string[]

Commands to run each time a runtime container starts or restarts.

run:
  initCommands:
    - rm -rf ./cache

start

run.start

string

Start command for your application. Either start or startCommands is required.

run:
  start: npm start

startCommands

run.startCommands

array

Define multiple start commands that run their own processes.

run:
  startCommands:
    - command: npm run start:prod
      name: server
    - command: litestream replicate -config=litestream.yaml
      name: replication
      initCommands:
        - litestream restore -if-replica-exists -config=litestream.yaml

See start-commands-example for more details.

documentRoot

run.documentRoot

string

Root folder for publicly accessible web server content. Available only for webserver runtimes.

run:
  documentRoot: public

siteConfigPath

run.siteConfigPath

string

Path to custom webserver configuration. Available only for webserver runtimes.

envVariables

run.envVariables

object

Environment variables for the runtime environment.

run:
  envVariables:
    DB_NAME: db
    DB_HOST: db
    DB_USER: db
    DB_PASS: ${db_password}
    NODE_ENV: production

envReplace

run.envReplace

object

Automatically replace environment variable placeholders in static files during deployment.

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

envReplace.delimiter

run.envReplace.delimiter

string | string[]

required

Characters that wrap variable names in placeholders (e.g., %% means %%VARIABLE%%).Supports multiple delimiters:

delimiter:
  - "%%"
  - "@@"

envReplace.target

run.envReplace.target

string | string[]

required

Files or directories to process for variable replacement.

Directory targets only process files directly in the specified directory, not subdirectories. To process subdirectories, specify each one explicitly.

Example:File content before:

%%JWT_PUBLIC_KEY_CONTENT%%

Environment variable:

JWT_PUBLIC_KEY_CONTENT=-----BEGIN PUBLIC KEY-----...

The placeholder gets replaced with the actual value during deployment.

routing

run.routing

object

Configure 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'"

routing.root

run.routing.root

string

Custom root directory for the service.

routing.cors

run.routing.cors

string

Enable CORS headers for cross-origin requests.

cors: "'*' always"

Special case: "*" is automatically converted to '*'

routing.redirects

run.routing.redirects

array

Define URL redirects and rewrites.Each redirect object supports:

from (required) - Source path to match (supports wildcards with *)
to (required) - Destination path
status - HTTP status code (required for absolute URLs)
preservePath - Preserve path after wildcard match
preserveQuery - Preserve query parameters

redirects:
  - from: /old-page
    to: /new-page
    status: 301
  - from: /blog/*
    to: /articles/
    preservePath: true
    status: 302

routing.headers

run.routing.headers

array

Set custom HTTP headers for specific paths.Each header object supports:

for (required) - Path pattern to match
values (required) - Object with header name/value pairs

headers:
  - for: "/*"
    values:
      X-Frame-Options: "'DENY'"
      Content-Security-Policy: '"default-src \'self\'"'

healthCheck

run.healthCheck

object

Define a health check for your running application.

run:
  healthCheck:
    httpGet:
      port: 80
      path: /status
    failureTimeout: 60
    disconnectTimeout: 30
    recoveryTimeout: 30
    execPeriod: 10

healthCheck.httpGet

run.healthCheck.httpGet

object

Configure HTTP GET health check.Parameters:

port (required) - Port number
path (required) - URL path
host - Host header
scheme - HTTP or HTTPS

healthCheck:
  httpGet:
    port: 8080
    path: /health
    scheme: https

healthCheck.exec

run.healthCheck.exec

object

Configure command-based health check.Parameters:

command (required) - Shell command

healthCheck:
  exec:
    command: |
      curl -s http://localhost:8080/status > /tmp/status
      grep -q "OK" /tmp/status

healthCheck.failureTimeout

run.healthCheck.failureTimeout

number

Time in seconds until container fails after consecutive health check failures.

healthCheck.disconnectTimeout

run.healthCheck.disconnectTimeout

number

Time in seconds until container is disconnected and becomes publicly unavailable.

healthCheck.recoveryTimeout

run.healthCheck.recoveryTimeout

number

Time in seconds until container is connected and becomes publicly available.

healthCheck.execPeriod

run.healthCheck.execPeriod

number

Time interval in seconds between health check attempts.

crontab

run.crontab

array

Define scheduled commands to run as cron jobs.

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

Each cron job supports:

command (required) - Shell command to execute
timing (required) - Cron format schedule (minute hour day month weekday)
allContainers (required) - Run on all containers (true) or one (false)
workingDir - Working directory (default: /var/www)

See cron examples for more details.

Complete Example

Here’s a comprehensive example showing multiple services with various configurations:

zerops:
  - setup: api
    build:
      base: nodejs@20
      os: alpine
      prepareCommands:
        - corepack enable
      buildCommands:
        - pnpm install --frozen-lockfile
        - pnpm run build
      deployFiles:
        - dist
        - node_modules
        - package.json
      cache:
        - node_modules
        - .pnpm-store
    deploy:
      readinessCheck:
        httpGet:
          port: 3000
          path: /health
        failureTimeout: 60
    run:
      base: nodejs@20
      ports:
        - port: 3000
          httpSupport: true
      start: node dist/index.js
      envVariables:
        NODE_ENV: production
        PORT: "3000"
      healthCheck:
        httpGet:
          port: 3000
          path: /health
        failureTimeout: 60
        execPeriod: 10

Overview

Quick introduction to zerops.yaml

Base Technologies

Available runtime and build technologies

Cron Jobs

Schedule automated tasks

Build Cache

Optimize build times with caching

Need help? Join our Discord community.

Get Started

Core Concepts

Configuration

​File Structure

​Top-Level Configuration

​setup

​extends

​Build Configuration

​base

​os

​prepareCommands

​buildCommands

​deployFiles

​cache

​addToRunPrepare

​envVariables

​Deploy Configuration

​temporaryShutdown

​readinessCheck

​readinessCheck.httpGet

​readinessCheck.exec

​readinessCheck.failureTimeout

​readinessCheck.retryPeriod

​Runtime Configuration

​base

​os

​ports

​ports[].port

​ports[].protocol

​ports[].httpSupport

​prepareCommands

​initCommands

​start

​startCommands

​documentRoot

​siteConfigPath

​envVariables

​envReplace

​envReplace.delimiter

​envReplace.target

​routing

​routing.root

​routing.cors

​routing.redirects

​routing.headers

​healthCheck

​healthCheck.httpGet

​healthCheck.exec

​healthCheck.failureTimeout

​healthCheck.disconnectTimeout

​healthCheck.recoveryTimeout

​healthCheck.execPeriod

​crontab

​Complete Example

​Related Resources

Overview

Base Technologies

Cron Jobs

Build Cache

Build docs developers (and LLMs) love

File Structure

Top-Level Configuration

setup

extends

Build Configuration

base

os

prepareCommands

buildCommands

deployFiles

cache

addToRunPrepare

envVariables

Deploy Configuration

temporaryShutdown

readinessCheck

readinessCheck.httpGet

readinessCheck.exec

readinessCheck.failureTimeout

readinessCheck.retryPeriod

Runtime Configuration

base

os

ports

ports[].port

ports[].protocol

ports[].httpSupport

prepareCommands

initCommands

start

startCommands

documentRoot

siteConfigPath

envVariables

envReplace

envReplace.delimiter

envReplace.target

routing

routing.root

routing.cors

routing.redirects

routing.headers

healthCheck

healthCheck.httpGet

healthCheck.exec

healthCheck.failureTimeout

healthCheck.disconnectTimeout

healthCheck.recoveryTimeout

healthCheck.execPeriod

crontab

Complete Example

Related Resources