# Zerops YAML Configuration


export const languages = [
    { name: "Node.js", link: "/nodejs/how-to/build-pipeline" },
    { name: "PHP", link: "/php/how-to/build-pipeline" },
    { name: "Python", link: "/python/how-to/build-pipeline" },
    { name: "Go", link: "/go/how-to/build-pipeline" },
    { name: ".NET", link: "/dotnet/how-to/build-pipeline" },
    { name: "Rust", link: "/rust/how-to/build-pipeline" },
    { name: "Java", link: "/java/how-to/build-pipeline" },
    { name: "Deno", link: "/deno/how-to/build-pipeline" },
    { name: "Bun", link: "/bun/how-to/build-pipeline" },
    { name: "Elixir", link: "/elixir/how-to/build-pipeline" },
    { name: "Gleam", link: "/gleam/how-to/build-pipeline" },
    { name: "Nginx", link: "/nginx/how-to/build-pipeline" }
]

The `zerops.yaml` file is crucial for defining how Zerops should [build and deploy](/features/pipeline) your application.
Add the `zerops.yaml` file to the **root of your repository** and customize it to suit your application's needs.

:::note 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.
:::

---

## Basic Structure

```yaml title="zerops.yaml"
zerops:
  - setup: app
    # optional
    build: ...
    # optional
    deploy: ...
    # required
    run: ...
```

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

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

```yaml
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.

```yaml
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 *[Optional]*

### base *[Required]*

Sets the base technology for the build environment. [See available options](/zerops-yaml/base-list).

```yaml
build:
  base: nodejs@latest
```

You can specify multiple technologies:

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

### os *[Optional]*

Sets the operating system for the build environment. Options:

- `alpine` (default)
- `ubuntu` (default for ubuntu service)

Current versions:

- Alpine Linux
- Ubuntu

```yaml
build:
  os: ubuntu
```

### prepareCommands *[Optional]*

Customizes the build environment by installing additional dependencies or tools.

```yaml
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.

```yaml
build:
  buildCommands:
    - npm install
    - npm run build
```

:::note
`build.buildCommands` run in the `/build/source` directory.
:::

#### Running commands in a single shell instance:

```yaml
buildCommands:
  - |
    npm install
    npm run build
```

### deployFiles *[Required]*

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

```yaml
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/`.

```yaml
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`](https://git-scm.com/docs/gitignore#_pattern_format).

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:

```yaml title="zerops.yaml"
zerops:
  - setup: app
    build:
      deployFiles: ./
```

```text title=".deployignore"
/src/file.txt
```
The example above ignores `file.txt` only in the root src directory.
```text title=".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`](/references/zcli/commands#deploy) command.
:::

### cache *[Optional]*

Defines which files or folders to cache for subsequent builds.

```yaml
build:
  cache: node_modules
```

For more information, see our detailed [guide on build cache](/features/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.

```yaml
build:
  envVariables:
    DB_NAME: db
    DB_HOST: db
    DB_USER: db
    DB_PASS: 
```

:::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](/references/import-yaml/pre-processor) page.
:::

## Deploy Configuration *[Optional]*

### temporaryShutdown *[Optional]*

Controls the container replacement order during deployment.

```yaml
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.

```yaml
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](#healthcheck-) 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](#healthcheck-). 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.
:::

## Runtime Configuration *[Required]*

### base *[Optional]*

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

```yaml
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.

```yaml
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](/features/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.

```yaml
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.

```yaml
run:
  start: npm start
```

### startCommands *[Optional]*

Defines start commands.

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

```yaml
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](https://github.com/zeropsio/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.

```yaml
    run:
      base: nodejs@20
      envVariables:
        DB_NAME: db
        DB_HOST: db
        DB_USER: db
        DB_PASS: 
```

### envReplace *[Optional]*

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

```yaml
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.
:::

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

```yaml
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 URL routing, redirects, and HTTP headers (only for Static services).

```yaml
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 *[Optional]*
Sets a custom root directory for the service.
- 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`
- 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 ([supports wildcards](/static/overview#wildcard-matching) with `*`)
  - **to** *[Required]* - Destination path
  - **status** *[Optional]* - HTTP status code (required for absolute URLs)
  - **preservePath** *[Optional]* - Preserve path after wildcard match
  - **preserveQuery** *[Optional]* - Preserve query parameters

#### headers *[Optional]*
Sets custom HTTP headers for specific paths.
- Type: `array of objects`
- Each header object supports:
  - **for** *[Required]* - Path pattern to match
  - **values** *[Required]* - Object with header name/value pairs

**Example usage:**

```yaml
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.

```yaml
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](#readinesscheck-).
:::

### crontab *[Optional]*

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

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

Setup cron jobs. See [examples](/zerops-yaml/cron).

:::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](https://discord.gg/zeropsio).*

## Editor support (JSON Schema)

Zerops publishes an official [JSON Schema ↗](https://json-schema.org/) 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 ↗](https://www.schemastore.org/), 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 ↗](https://marketplace.visualstudio.com/items?itemName=redhat.vscode-yaml)), all JetBrains IDEs, and any editor backed by [`yaml-language-server` ↗](https://github.com/redhat-developer/yaml-language-server) (Neovim, Helix, Sublime LSP, …).

### Manual attachment

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

```yaml
# 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).