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.jsPHPPythonGo.NETRustJavaDenoBunElixirGleamNginx

Basic Structure

zerops.yaml

zerops:
  - setup: app
    # optional
    build: ...
    # optional
    deploy: ...
    # required
    run: ...

Multiple services can be defined in a single zerops.yaml (useful for monorepos):

zerops:
  - setup: app
    # optional
    build: ...
    # optional
    deploy: ...
    # required
    run: ...

  - setup: api
    # optional
    build: ...
    # optional
    deploy: ...
    # required
    run: ...

Each service configuration requires a run section. Optional build and deploy sections can be added to further customize your process.

Service Configuration

setup Required

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

setup: app

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:
        - 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 starts as a full copy of the base service, then its own keys are applied on top
• Merging is recursive, key by key. Redefining run in the child does not replace the whole run section, only the keys you specify inside it. The same applies to nested objects such as healthCheck or readinessCheck
• Maps such as envVariables are merged: the child's keys are added to the base's keys, and a key defined in both takes the child's value. Setting a key to null removes the inherited variable (an empty string "" is a regular value), and envVariables: null drops the whole inherited map
• Lists such as buildCommands, initCommands, deployFiles, ports or startCommands are replaced as a whole, never appended. If you need to change a list, define the full list in the child
• A base service can itself extend another service. Chains are resolved regardless of the order of services in the file. A service cannot extend itself
• extends also accepts a list, for example extends: [base, logging]. The child is then resolved exactly as if logging extended base and the child extended logging: later services in the list override earlier ones, and the child's own keys override all of them

The following example shows how maps and lists behave differently:

zerops:
  - setup: base
    build:
      base: nodejs@22
      buildCommands:
        - npm ci
        - npm run build
      deployFiles: ./dist
    run:
      base: nodejs@22
      start: npm start
      envVariables:
        LOG_LEVEL: info
        NODE_ENV: development

  - setup: prod
    extends: base
    build:
      buildCommands:
        - npm ci
        - npm run build -- --mode=production
    run:
      envVariables:
        NODE_ENV: production
        LOG_LEVEL: null

  - setup: dev
    extends: base
    run:
      envVariables:
        DEBUG: "1"

The resolved prod service is:

setup: prod
build:
  base: nodejs@22                  # inherited
  buildCommands:                   # list replaced as a whole
    - npm ci
    - npm run build -- --mode=production
  deployFiles: ./dist              # inherited
run:
  base: nodejs@22                  # inherited
  start: npm start                 # inherited
  envVariables:                    # map merged key by key, LOG_LEVEL removed by null
    NODE_ENV: production

And dev keeps everything from base and adds DEBUG:

run:
  envVariables:
    LOG_LEVEL: info
    NODE_ENV: development
    DEBUG: "1"

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 Optional

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

Deprecated. The operating system is part of the base value, for example ubuntu/nodejs@22 or alpine/nodejs@22. Use the OS-prefixed form in both build.base and run.base instead of setting os. A bare nodejs@22 defaults to Alpine.

Current versions:

• Alpine Linux
• Ubuntu

build:
  base: ubuntu/nodejs@22

prepareCommands Optional

Customizes the build environment by installing additional dependencies or tools.

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

Note

build.prepareCommands run in the /home/zerops directory.

buildCommands Optional

Defines the commands to build your application.

build:
  buildCommands:
    - npm install
    - npm run build

Note

build.buildCommands run in the /build/source directory.

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.

addToRunPrepare Optional

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

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.

Deploy Configuration Optional

temporaryShutdown Optional

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 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: "60s"
    retryPeriod: "10s"

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 until container is marked as failed. Use a duration string with a unit, for example "60s".
• retryPeriod - Time interval between readiness check attempts, for example "10s" (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.

Runtime Configuration Required

base Optional

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

run:
  base: nodejs@latest

os Optional

Deprecated, same as for the build environment: put the OS into run.base (ubuntu/nodejs@22) instead.

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: 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 Optional

Customizes the runtime environment by installing additional dependencies or tools.

Note

run.prepareCommands run in the /home/zerops directory.

initCommands Optional

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

run:
  initCommands:
    - rm -rf ./cache

Note

run.initCommands run in the /var/www directory.

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

Each entry supports:

• command (required) - the command to run
• name (optional) - distinguishes the process in logs
• workingDir (optional, default /var/www) - the directory the command and its initCommands run in
• user (optional, default zerops) - the system user the command and its initCommands run under. The user has to exist in the runtime container, create it in prepareCommands.
• initCommands (optional) - commands run before this process starts, each time a container starts or restarts

run:
  prepareCommands:
    - sudo adduser --system --group --home /home/git git
  startCommands:
    - command: gitea web
      name: gitea
      user: git

See start-commands-example

documentRoot Optional

Customizes the root folder for publicly accessible web server content. The path is relative to /var/www. Available for the Nginx and PHP services. The Static service ignores it, use routing.root there.

run:
  base: alpine/nginx@latest
  documentRoot: dist

siteConfigPath Optional

Sets the custom webserver configuration for the Nginx, PHP and Static services. The path is relative to /var/www and the file must be part of the deployed files. A .tmpl file is rendered as a template with {{.DocumentRoot}} and {{.Environment.NAME}}, any other file is used verbatim. On the Static service routing takes precedence: when both are set, siteConfigPath is ignored.

run:
  base: alpine/nginx@latest
  siteConfigPath: site_config.tmpl

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}

envReplace Optional

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 Required

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 Required

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.

Info

Not to be confused with the zsc env-replace command, which renders {{.VARIABLE}} Go templates from a source path into a separate target path and can be run from initCommands or manually.

How it works:

1. Define placeholders in your files using the specified delimiters
2. Set environment variables with matching names
3. 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 Optional

Configures the document root, redirects, CORS and HTTP headers of the Static service. Any other service, including the Nginx service, ignores this section without an error.

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

Available parameters:

root Optional

Sets the folder served by the service, relative to /var/www (default /var/www itself). This is the Static service's equivalent of documentRoot.

• Type: string

cors Optional

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, all to the same value
• Special case: "*" is automatically converted to '*'

redirects Optional

Defines URL redirects and rewrites.

• Type: array of objects
• Each redirect object supports:
  • from Required - Source path to match. Without * it matches the exact path, with a trailing * it matches the path prefix (path matching). An absolute URL (https://old-domain.com/*) matches on the request domain.
  • to Required - Destination path or absolute URL
  • status Optional - HTTP status code. Omit it for a masked redirect that serves the target content under the original URL. Required for absolute URLs, and limited to 301 or 302 when from is absolute.
  • preservePath Optional - Append the part of the path after the wildcard to to. Not allowed on masked redirects.
  • preserveQuery Optional - Append the original query string. Not allowed on masked redirects.

headers Optional

Sets custom HTTP headers for specific paths.

• Type: array of objects
• Each header object supports:
  • for Required - Path to match, same rules as from ("/*" for the whole site, "/" matches the homepage only)
  • values Required - Object with header name/value pairs. Values are inserted into add_header verbatim, so include the quotes: X-Frame-Options: "'DENY'"

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 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: "60s"
    disconnectTimeout: "30s"
    recoveryTimeout: "30s"
    execPeriod: "10s"

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 until container fails after consecutive health check failures (reset by success). Use a duration string with a unit, for example "30s".
• disconnectTimeout - Time until container is disconnected and becomes publicly unavailable.
• recoveryTimeout - Time until container is connected and becomes publicly available.
• execPeriod - Time interval 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 * * * *"
      allContainers: false

Setup cron jobs. See examples.

volume Optional

Mounts a Local Storage service's volume into the runtime containers. The mount exists only in the run phase — it is not available in the build or prepare containers, so build and run.prepareCommands cannot access the volume. See how the mount behaves.

run:
  volume:
    hostname: vol         # hostname of the Local Storage service
    mountPath: /srv/data  # optional, defaults to /mnt/{hostname}
    readOnly: false       # optional, defaults to false

Available parameters:

hostname Required

Hostname of the Local Storage service in the same project.

mountPath Optional

Absolute path the volume is mounted to inside the runtime containers. Defaults to /mnt/{hostname}. System directories (/etc, /var, /var/www, /tmp, ...) are rejected; their subdirectories are allowed.

readOnly Optional

Mounts the volume read-only. Defaults to false.

Caution

All containers of a service that mounts a volume are placed on the physical machine holding the volume, together with the containers of every other service mounting it. A service can mount at most one volume. See Mount Local Storage to a service for details.

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.

Editor support (JSON Schema)

Zerops publishes an official JSON Schema ↗ for zerops.yaml:

https://api.app-prg1.zerops.io/api/rest/public/settings/zerops-yml-json-schema.json

With the schema attached, your editor gives you:

• Autocomplete for every key and nested field
• Inline documentation on hover
• Validation — typos, wrong types, and missing required fields are flagged as you type
• Enum suggestions for fields like base or cache

Auto-detection via SchemaStore

The schema is registered with SchemaStore ↗, so most YAML-aware editors apply it automatically — no setup required — when the file is named:

• zerops.yml
• zerops.yaml

This covers VS Code (with the YAML extension by Red Hat ↗), all JetBrains IDEs, and any editor backed by yaml-language-server ↗ (Neovim, Helix, Sublime LSP, …).

Manual attachment

If your file is named differently, add a modeline at the top:

# yaml-language-server: $schema=https://api.app-prg1.zerops.io/api/rest/public/settings/zerops-yml-json-schema.json
zerops:
  - setup: app
    # ...

The same URL works in any editor that lets you map a schema to a file pattern manually (e.g., yaml.schemas in VS Code settings.json, or JetBrains' JSON Schema Mappings panel).