----------------------------------------

# Alpine > How To > Build Pipeline


Zerops provides a customizable build and runtime environment for your Alpine application.

## Add zerops.yaml to your repository

Start by adding `zerops.yaml` file to the **root of your repository** and modify it to fit your application:

```yaml
zerops:
  # define hostname of your service
  - setup: app
    # ==== how to build your application ====
    build:
      # REQUIRED. Set the base technology for the build environment:
      base: alpine@3.20

      # OPTIONAL. Customize the build environment by installing additional packages
      # or tools to the base build environment.
      prepareCommands:
        - sudo apk add --no-cache something
        - curl something else

      # OPTIONAL. Build your application
      buildCommands:
        - <your build commands>

      # REQUIRED. Select which files / folders to deploy after
      # the build has successfully finished
      deployFiles: app

      # OPTIONAL. Which files / folders you want to cache for the next build.
      # Next builds will be faster when the cache is used.
      cache: some_file

    # ==== how to run your application ====
    run:
      # OPTIONAL. Sets the base technology for the runtime environment:
      base: alpine@3.20

      # OPTIONAL. Sets the internal port(s) your app listens on:
      ports:
        # port number
        - port: 8080

      # OPTIONAL. Customize the runtime Alpine environment by installing additional
      # dependencies to the base Alpine runtime environment.
      prepareCommands:
        - sudo apk add --no-cache something
        - curl something else

      # OPTIONAL. Run one or more commands each time a new runtime container
      # is started or restarted. These commands are triggered before
      # your Alpine application is started.
      initCommands:
       - rm -rf ./cache

      # OPTIONAL. Your Alpine application start command
      start: ./app
```

The top-level element is always `zerops`.

### Setup

The first element `setup` contains the **hostname** of your service. A runtime service with the same hostname must exist in Zerops.
Zerops supports the definition of multiple runtime services in a single `zerops.yaml`. This is useful when you use a monorepo. Just add multiple setup elements in your `zerops.yaml`:

```yaml
zerops:
  # definition for app service
  - setup: app
    # optional
    build: ...
    # optional
    deploy: ...
    # required
    run: ...

  # definition for api service
  - setup: api
    # optional
    build: ...
    # optional
    deploy: ...
    # required
    run: ...
```

Each service configuration contains at least the `run` section. Optional `build` and `deploy` sections can be added to further customize your process.

## Build pipeline configuration

### base

_REQUIRED._ Sets the base technology for the build environment.

Following options are available for Alpine builds:

- `alpine@3.23`, `alpine@latest`
- `alpine@3.22`
- `alpine@3.21`
- `alpine@3.20`
- `alpine@3.19`
- `alpine@3.18`
- `alpine@3.17`

```yaml
zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build:
      # REQUIRED. Sets the base technology for the build environment:
      base: alpine@3.20
      ...
```

<p>
  The base build environment contains {data.alpine.default}, [Zerops command line tool](/references/cli), `git` and `wget`.
</p>

:::info
You can change the base environment when you need to. Just simply modify the `zerops.yaml` in your repository.
:::

If you need to install more technologies to the build environment, set multiple values as a yaml array. For example:

```yaml
zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build:
      # REQUIRED. Sets the base technology for the build environment:
      base:
        - alpine@3.20
      prepareCommands:
        - zsc add nodejs@latest
      ...
```

See the full list of supported [build base environments](/zerops-yaml/base-list#runtime-services).

To customize your build environment use the [prepareCommands](#preparecommands) attribute.

:::note
Modifying the base technology will invalidate your build cache. See our [Build Cache Documentation](/features/build-cache) for more details about cache invalidation.
:::

### prepareCommands

_OPTIONAL._ Customizes the build environment by installing additional dependencies or tools to the base build environment.

The base build environment contains:

- <span>{data.alpine.default}</span>
- [Zerops command line tool](/references/cli)
- `git` and `wget`

To install additional packages or tools add one or more prepare commands:

```yaml
zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build:
      # REQUIRED. Set the base technology for the build environment:
      base: alpine@3.20

      # OPTIONAL. Customize the build environment by installing additional packages
      # or tools to the base build environment.
      prepareCommands:
        - sudo apk add --no-cache something
        - curl something else
      ...
```

When the first build is triggered, Zerops will

1. create a build container
2. download your application code from your repository
3. run the prepare commands in the defined order

The application code is available in `/build/source` before the prepare commands are triggered, so you can use any file from your repository in your prepare commands (e.g. a configuration file). The commands themselves run in the `/home/zerops` directory.

:::note
These commands are skipped when using cached environment. Modifying `prepareCommands` will invalidate your build cache. See our [Build Cache Documentation](/features/build-cache) for details about cache invalidation.
:::

#### Command exit code

If any command fails, it returns an exit code other than 0 and the build is canceled. Read the [build log](/alpine/how-to/logs#build-log) to troubleshoot the error. If the command ends successfully, it returns the exit code 0 and Zerops triggers the following command. When all prepare commands are finished, your custom build environment is ready for the build phase.

#### Single or separated shell instances

You can configure your prepare commands to be run in a single shell instance or multiple shell instances. The format is identical to [build commands](#buildcommands).

### buildCommands

_OPTIONAL._ Defines build commands.

```yaml
zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build:
      # REQUIRED. Set the base technology for the build environment:
      base: alpine@3.20

      # OPTIONAL. Build your application
      buildCommands:
        - <your build commands>
      ...
```

Build commands are optional. Zerops triggers each command in the defined order in a dedicated build container, running from the `/build/source` directory.

Before the build commands are triggered the build container contains:

1. base environment defined by the [base](#base) attribute
2. optional customisation of the base environment defined in the [prepareCommands](#preparecommands) attribute
3. your application code

For detailed information about build commands, refer to the documentation for your specific technology (e.g., [Node.js](/nodejs/how-to/build-pipeline), [Go](/go/how-to/build-pipeline), [Python](/python/how-to/build-pipeline), etc.).

#### Run build commands as a single shell instance

Use following syntax to run all commands in the same environment context. For example, if one command changes the current directory, the next command continues in that directory. When one command creates an environment variable, the next command can access it.

```yaml
buildCommands:
  - |
    cd src
    ./build.sh
```

#### Run build commands as separate shell instances

When the following syntax is used, each command is triggered in a separate environment context. For example, each shell instance starts in the home directory again. When one command creates an environment variable, it won't be available for the next command.

```yaml
buildCommands:
  - cd src
  - ./build.sh
```

#### Command exit code

If any command fails, it returns an exit code other than 0 and the build is canceled. Read the [build log](/alpine/how-to/logs#build-log) to troubleshoot the error.

If the command ends successfully, it returns the exit code 0 and Zerops triggers the following command. When all `buildCommands` are finished, the application build is completed and ready for the deploy phase.

### deployFiles

_REQUIRED._ Selects which files or folders will be deployed after the build has successfully finished. To filter out specific files or folders, use [`.deployignore`](#deployignore) file.

```yaml
# REQUIRED. Select which files / folders to deploy after
# the build has successfully finished
deployFiles:
  - app
```

Determines files or folders produced by your build, which should be deployed to your runtime service containers.

The path starts from the **root directory** of your project (the location of `zerops.yaml`). You must enclose the name in quotes if the folder or the file name contains a space.

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

#### Examples

Deploys a folder, and a file from the project root directory:

```yaml
deployFiles:
  - app
  - file.txt
```

Deploys the whole content of the build container:

```yaml
deployFiles: .
```

Deploys a folder, and a file in a defined path:

```yaml
deployFiles:
  - ./path/to/file.txt
  - ./path/to/dir/
```

#### How to use a wildcard in the path

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

Deploys all folders that are located in any path that begins with `/path/to/`

```yaml
deployFiles: ./path/to/~/
```

Deploys all folders that are located in any path that begins with `/path/` and ends with `/to/`

```yaml
deployFiles: ./path/~/to/
```

:::note Example
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 will be cached for the next build.

```yaml
# OPTIONAL. Which files / folders you want to cache for the next build.
# Next builds will be faster when the cache is used.
cache: file.txt
```

The cache attribute helps optimize build times by preserving specified files between builds.

The cache attribute supports the [~ wildcard character](#how-to-use-a-wildcard-in-the-path).

Learn more about the [build cache system](/features/build-cache) in Zerops.

### envVariables

_OPTIONAL._ Defines the environment variables for the build environment.

Enter one or more env variables in following format:

```yaml
zerops:
  # define hostname of your service
  - setup: app
    # ==== how to build your application ====
    build:
      base: alpine@3.20
        …

      # OPTIONAL. Defines the env variables for the build environment:
      envVariables:
        MODE: production
        DB_NAME: db
        DB_HOST: db
        DB_USER: db
        DB_PASS: ${db_password}
```

Read more about [environment variables](/alpine/how-to/env-variables) in Zerops.

## Runtime configuration

### base

_OPTIONAL._ Sets the base technology for the runtime environment.
If you don't specify the `run.base` attribute, Zerops keeps the current Alpine version for your runtime.

Following options are available for Alpine builds:

- `alpine@3.23`, `alpine@latest`
- `alpine@3.22`
- `alpine@3.21`
- `alpine@3.20`
- `alpine@3.19`
- `alpine@3.18`
- `alpine@3.17`

```yaml
zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build:
      # REQUIRED. Sets the base technology for the build environment:
      base: alpine@3.20
      ...

    # ==== how to run your application ====
    run:
      # OPTIONAL. Sets the base technology for the runtime environment:
        base: alpine@3.20
      ...
```

<p>
  The base runtime environment contains {data.alpine.default}, Zerops command line tool, `git` and `wget`.
</p>

:::info
You can change the base environment when you need to. Just simply modify the `zerops.yaml` in your repository.
:::

If you need to install more technologies to the runtime environment, set multiple values as a yaml array. For example:

```yaml
zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build:
      # REQUIRED. Sets the base technology for the build environment:
      base: alpine@3.20
      ...

    # ==== how to run your application ====
    run:
      # OPTIONAL. Sets the base technology for the runtime environment:
      base:
        - alpine@3.20
      prepareCommands:
        - zsc add nodejs@latest
      ...
```

See the full list of supported [run base environments](/zerops-yaml/base-list).

To customise your build environment use the `prepareCommands` attribute.

### ports

_OPTIONAL._ Specifies one or more internal ports on which your application will listen.

Projects in Zerops represent a group of one or more services. Services can be of different types (runtime services, databases, message brokers, object storage, etc.). All services of the same project share a **dedicated private network**. To connect to a service within the same project, just use the service hostname and its internal port.

For example, to connect to an Alpine service with hostname = "app" and port = 8080 from another service of the same project, simply use `app:8080`. Read more about [how to access an Alpine service](/references/networking/internal-access#basic-service-communication).

Each port has following attributes:

<table className="w-full my-1.5">
  <thead>
    <tr>
      <th className="w-fit"><strong>Parameter</strong></th>
      <th className="w-fit"><strong>Description</strong></th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td className="w-fit">port</td>
      <td className="w-fit">Defines the port number. You can set any port number between <em>10</em> and <em>65435</em>. Ports outside this interval are reserved for internal Zerops systems.</td>
    </tr>
    <tr>
      <td className="w-fit">protocol</td>
      <td className="w-fit"><strong>Optional.</strong> Defines the protocol. Allowed values are <code>TCP</code> or <code>UDP</code>. Default value is <code>TCP</code>.</td>
    </tr>
    <tr>
      <td className="w-fit">httpSupport</td>
      <td className="w-fit"><strong>Optional.</strong> <code>httpSupport = true</code> is the default setting for TCP protocol. Set <code>httpSupport = false</code> if a web server isn't running on the port. Zerops uses this information for the configuration of [public access](/features/access). <code>httpSupport = true</code> is available only in combination with the TCP protocol.</td>
    </tr>
  </tbody>
</table>

### prepareCommands

_OPTIONAL._ Customises the Alpine runtime environment by installing additional dependencies or tools to the runtime base environment.

<p>
  The base Alpine environment contains {data.alpine.default}, [Zerops command line tool](/references/cli) and `git` and `wget`. To install additional packages or tools add one or more prepare commands:
</p>

```yaml
zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build:
      ...

    # ==== how to run your application ====
    run:
      # OPTIONAL. Customise the runtime environment by installing additional packages
      # or tools to the base Alpine runtime environment.
      prepareCommands:
        - sudo apk add --no-cache something
        - curl something else
      ...
```

When the first deploy with a defined prepare attribute is triggered, Zerops will

1. create a prepare runtime container
2. optionally: [copy selected folders or files from your build container](#copy-folders-or-files-from-your-build-container)
3. run the `prepareCommands` commands in the defined order

:::note
`run.prepareCommands` run in the `/home/zerops` directory.
:::

#### Command exit code

If any command fails, it returns an exit code other than 0 and the deploy is canceled. Read the [prepare runtime log](/alpine/how-to/logs#prepare-runtime-log) to troubleshoot the error. If the command ends successfully, it returns the exit code 0 and Zerops triggers the following command. When all `prepareCommands` commands are finished, your custom runtime environment is ready for the deploy phase.

#### Cache of your custom runtime environment

Some packages or tools can take a long time to install. Therefore, Zerops caches your custom runtime environment after the installation of your custom packages or tools is completed. When the second or following deploy is triggered, Zerops will use the custom runtime cache from the previous deploy if following conditions are met:

1. Content of the [build.addToRunPrepare](#copy-folders-or-files-from-your-build-container) and `run.prepareCommands` attributes didn't change from the previous deploy
2. The custom runtime cache wasn't invalidated in the Zerops GUI.

To invalidate the Zerops runtime cache go to your service detail in Zerops GUI, choose **Service dashboard & runtime containers** from the left menu and click on the **Open pipeline detail** button. Then click on the **Clear runtime prepare cache** button.

When the prepare cache is used, Zerops doesn't create a prepare runtime container and executes the deployment of your application directly.

#### Single or separated shell instances

You can configure your prepare commands to be run in a single shell instance or multiple shell instances. The format is identical to [build commands](#buildcommands).

### Copy folders or files from your build container

<p>
  The prepare runtime container contains {data.alpine.default}, [Zerops command line tool](/references/cli) and `git` and `wget`.
</p>

The prepare runtime container does not contain your application code nor the built application. If you need to copy some folders or files from the build container to the runtime container (e.g. a configuration file) use the `addToRunPrepare` attribute in the [build section](#build-pipeline-configuration).

```yaml
zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build:
      ...
      addToRunPrepare: ./runtime-config.yaml

    # ==== how to run your application ====
    run:
      # OPTIONAL. Customise the runtime environment by installing additional packages
      # or tools to the base Alpine runtime environment.
      prepareCommands:
        - sudo apk add --no-cache something
        - curl something else
      ...
```

In the example above Zerops will copy the `runtime-config.yaml` file from your build container **after the build has finished** into the new **prepare runtime** container. The copied files and folders will be available in the `/home/zerops` folder in the new prepare runtime container before the prepare commands are triggered.

### initCommands

_OPTIONAL._ Defines one or more commands to be run each time a new runtime container is started or a container is restarted.

```yaml
zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build: ...

    # ==== how to run your application ====
    run:
      # OPTIONAL. Run one or more commands each time a new runtime container
      # is started or restarted. These commands are triggered before
      # your Alpine application is started.
      initCommands:
        - rm -rf ./cache
```

These commands are triggered in the runtime container before your Alpine application is started via the [start command](#start).

:::note
`run.initCommands` run in the `/var/www` directory.
:::

Use init commands to clean or initialise your application cache or similar operations.

:::caution
The init commands will delay the start of your application each time a new runtime container is started (including the horizontal [scaling](/alpine/how-to/scaling) or when a runtime container is restarted).

Do not use the init commands for customising your runtime environment. Use the [run:prepareCommands](#preparecommands-1) attribute instead.
:::

#### Command exit code

If any of the `initCommands` fails, it returns an exit code other than 0, but deploy is **not** canceled. After all init commands are finished, regardless of the status code, the application is started. Read the [runtime log](/alpine/how-to/logs#runtime-log) to troubleshoot the error.

#### Single or separated shell instances

You can configure your `initCommands` to be run in a single shell instance or multiple shell instances. The format is identical to [build commands](#buildcommands).

### envVariables

_OPTIONAL._ Defines the environment variables for the runtime environment.

Enter one or more env variables in following format:

```yaml
zerops:
  # define hostname of your service
  - setup: app
    # ==== how to run your application ====
    run:
      # OPTIONAL. Defines the env variables for the runtime environment:
      envVariables:
        MODE: production
        DB_NAME: db
        DB_HOST: db
        DB_USER: db
        DB_PASS: ${db_password}
```

Read more about [environment variables](/alpine/how-to/env-variables) in Zerops.

### start

_OPTIONAL._ Defines the start command for your Alpine application.

```yaml
zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build: ...

    # ==== how to run your application ====
    run:
      # OPTIONAL. Your Alpine application start command
      start: ./app
```

### health check

_OPTIONAL._ Defines a health check.

`healthCheck` requires either one `httpGet` object or one `exec` object.

#### httpGet

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

Following attributes are available:

<table className="w-full my-1.5">
  <thead>
    <tr>
      <th className="w-fit whitespace-nowrap">Parameter</th>
      <th className="w-fit whitespace-nowrap">Description</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td className="w-fit whitespace-nowrap font-semibold">port</td>
      <td>Defines the port of the HTTP GET request.
The readiness check will trigger a GET request on <code>{'http://127.0.0.1:{port}/{path}'}</code></td>
    </tr>
    <tr>
      <td className="w-fit whitespace-nowrap font-semibold">path</td>
      <td>Defines the URL path of the HTTP GET request.
The readiness check will trigger a GET request on <code>{'http://127.0.0.1:{port}/{path}'}</code></td>
    </tr>
    <tr>
      <td className="w-fit whitespace-nowrap font-semibold">host</td>
      <td><strong>Optional.</strong> The readiness check is triggered from inside of your runtime container so it always uses the localhost <code>127.0.0.1</code>. If you need to add a <code>host</code> to the request header, specify it in the <code>host</code> attribute.</td>
    </tr>
    <tr>
      <td className="w-fit whitespace-nowrap font-semibold">scheme</td>
      <td><strong>Optional.</strong> The readiness check is triggered from inside of your runtime container so no https is required.
If your application requires a https request, set <code>scheme: https</code></td>
    </tr>
  </tbody>
</table>

**Example:**

```yaml
zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build: ...

    # ==== how to run your application ====
    run:
      # OPTIONAL. Your Alpine application start command
      start: ./app

      # OPTIONAL. Define a health check with a HTTP GET request option.
      # Configures the check on http://127.0.0.1:80/status
      healthCheck:
        httpGet:
          port: 80
          path: /status
```

#### exec

Configures the health check to run a local command.
Following attributes are available:

<table className="w-full my-1.5">
  <thead>
    <tr>
      <th className="w-fit"><strong>Parameter</strong></th>
      <th className="w-fit"><strong>Description</strong></th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td className="w-fit"><strong>command</strong></td>
      <td className="w-fit">
        Defines a local command to be run.

        The command has access to the same [environment variables](/alpine/how-to/create#set-secret-environment-variables) as your Alpine application.

        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 below.
      </td>
    </tr>
  </tbody>
</table>

**Example:**

```yaml
zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build: ...

    # ==== how to run your application ====
    run:
      # REQUIRED. Your Alpine application start command
      start: ./app

      # OPTIONAL. Define a health check with a shell command.
      healthCheck:
        exec:
          command: |
            touch grass
            rm -rf life
            mv /outside/user /home/user
```

### crontab

_OPTIONAL._ Defines cron jobs.

Setup cron jobs in the following format:

```yaml
zerops:
  # define hostname of your service
  - setup: app

    # ==== how to run your application ====
    run:
      crontab:
        # REQUIRED. Sets the command to execute:
        - command: ""
        # REQUIRED. Sets the interval time to execute:
          timing: "0 * * * *"
```

Read more about setting up [cron](/zerops-yaml/cron) in Zerops.

## Deploy configuration

### readiness check

_OPTIONAL._ Defines a readiness check. Read more about how the [readiness check works](/alpine/how-to/deploy-process#readiness-checks) in Zerops.

`readinessCheck` requires either one `httpGet` object or one `exec` object.

#### httpGet

Configures the readiness check to request a local URL using a http GET method.

Following attributes are available:

<table className="w-full my-1.5">
  <thead>
    <tr>
      <th className="w-fit whitespace-nowrap">Parameter</th>
      <th className="w-fit whitespace-nowrap">Description</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td className="w-fit whitespace-nowrap font-semibold">port</td>
      <td>Defines the port of the HTTP GET request.
The readiness check will trigger a GET request on <code>{'http://127.0.0.1:{port}/{path}'}</code></td>
    </tr>
    <tr>
      <td className="w-fit whitespace-nowrap font-semibold">path</td>
      <td>Defines the URL path of the HTTP GET request.
The readiness check will trigger a GET request on <code>{'http://127.0.0.1:{port}/{path}'}</code></td>
    </tr>
    <tr>
      <td className="w-fit whitespace-nowrap font-semibold">host</td>
      <td><strong>Optional.</strong> The readiness check is triggered from inside of your runtime container so it always uses the localhost <code>127.0.0.1</code>. If you need to add a <code>host</code> to the request header, specify it in the <code>host</code> attribute.</td>
    </tr>
    <tr>
      <td className="w-fit whitespace-nowrap font-semibold">scheme</td>
      <td><strong>Optional.</strong> The readiness check is triggered from inside of your runtime container so no https is required.
If your application requires a https request, set <code>scheme: https</code></td>
    </tr>
  </tbody>
</table>

**Example:**

```yaml
zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build: ...

    # ==== how to deploy your application ====
    deploy:
      # OPTIONAL. Define a readiness check with a HTTP GET request option.
      # Configures the check on http://127.0.0.1:80/status
      readinessCheck:
        httpGet:
          port: 80
          path: /status

    # ==== how to run your application ====
    run: ...
```

Read more about how the [readiness check works](/alpine/how-to/deploy-process#readiness-checks) in Zerops.

#### exec

Configures the readiness check to run a local command.
Following attributes are available:

<table className="w-full my-1.5">
  <thead>
    <tr>
      <th className="w-fit"><strong>Parameter</strong></th>
      <th className="w-fit"><strong>Description</strong></th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td className="w-fit"><strong>command</strong></td>
      <td className="w-fit">
        Defines a local command to be run.

        The command has access to the same [environment variables](/alpine/how-to/create#set-secret-environment-variables) as your Alpine application.

        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 below.
      </td>
    </tr>
  </tbody>
</table>

**Example:**

```yaml
zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build: ...

    # ==== how to deploy your application ====
    deploy:
      # OPTIONAL. Define a readiness check with a HTTP GET request option.
      # Configures the check on http://127.0.0.1:80/status
      readinessCheck:
        exec:
          command: |
            touch grass
            rm -rf life
            mv /outside/user /home/user
```

Read more about how the [readiness check works](/alpine/how-to/deploy-process#readiness-checks) in Zerops.

----------------------------------------

# Alpine > How To > Build Process


## Build process overview

Zerops starts a temporary build container and performs the following actions:

1. **Installs the build environment** - Sets up base system and  runtime
2. **Downloads your application source code** - From [GitHub ↗](https://www.github.com), [GitLab ↗](https://www.gitlab.com) or via [Zerops CLI](/references/cli)
3. **Optionally customizes the build environment** - Runs prepare commands if configured
4. **Runs the build commands** - Executes your build process
5. **Uploads the application artifact** - Stores build output to internal Zerops storage
6. **Caches selected files** - Preserves specified files for faster future builds

The build container is automatically deleted after the build has finished or failed.

## Build configuration

Configure your  build process in your `zerops.yaml` file according to the  pipeline guide</VarLink>.

## Build environment

### Default  build environment

The default  build environment contains:

- <span>{data.alpine.default}</span>
- [zCLI](/references/cli), Zerops command line tool
-

### Customize build environment

To install additional packages or tools, add one or more  to your `zerops.yaml`.

:::info
The application code is available in the `/build/source` folder in your build container before the prepare commands are triggered. This allows you to use any file from your application code in your prepare commands (e.g. a configuration file).
:::

### Build hardware resources

All runtime services use the same hardware resources for build containers:

<table className="w-fit my-1.5">
  <thead>
    <tr className="text-center rounded-lg">
      <th className="w-fit"><strong>HW resource</strong></th>
      <th className="w-fit"><strong>Minimum</strong></th>
      <th className="w-fit"><strong>Maximum</strong></th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td className="w-fit font-semibold">CPU cores</td>
      <td className="w-fit">1</td>
      <td className="w-fit">5</td>
    </tr>
    <tr>
      <td className="w-fit font-semibold">RAM</td>
      <td className="w-fit">8 GB</td>
      <td className="w-fit">8 GB</td>
    </tr>
    <tr>
      <td className="w-fit font-semibold">Disk</td>
      <td className="w-fit">1 GB</td>
      <td className="w-fit">100 GB</td>
    </tr>
  </tbody>
</table>

Build containers start with minimum resources and scale vertically up to maximum capacity as needed.

### Build time limit

The time limit for the whole build pipeline is **1 hour**. After 1 hour, Zerops will terminate the build pipeline and delete the build container.

:::info
Build container resources are not charged separately. Limited build time is included in your [project core plan](/company/pricing#project-core-plans), with additional build time available if needed.
:::

## Troubleshooting  builds

:::tip Advanced troubleshooting
For complex build issues that require investigation, you can enable [debug mode](/features/debug-mode) to pause the build process at specific points and inspect the build container state interactively.
:::

### Build and prepare command failures

If any  or  fails (returns non-zero exit code), the build is canceled. Check the  to troubleshoot the error.

### Build cache issues

If you encounter unexpected build behavior or dependency issues, the problem might be related to cached build data. While Zerops maintains the build cache to speed up deployments, sometimes you may need to start fresh.

To invalidate the build cache:

1. Go to your service detail in Zerops GUI
2. Choose **Pipelines & CI/CD Settings** from the left menu
3. Click on the **Invalidate build cache** button

This will force Zerops to run the next build clean, including all prepare commands.

Learn more about [build cache behavior](/features/build-cache).

## More resources

For more details about the build and deploy pipeline, including how to cancel builds and manage application versions, see the [general pipeline documentation](/features/pipeline).

## Next steps

- Understand the
- Learn how to
- Explore

----------------------------------------

# Alpine > How To > Controls



----------------------------------------

# Alpine > How To > Create


Zerops provides a Alpine runtime service with extensive build support. Alpine runtime is highly scalable and customisable to suit both development and production.

## Create Alpine service using Zerops GUI

First, set up a project in Zerops GUI. Then go to the project dashboard page and choose **Add new service** in the left menu in the **Services** block. Then add a new Alpine service:

[Video: /vids/services/golang.webm](/vids/services/golang.webm)

### Choose Alpine version

Following Alpine versions are currently supported:

:::info
You can [change](/alpine/how-to/upgrade) the major version at any time later.
:::

### Set a hostname

Enter a unique service identifier like "app","cache", "gui" etc. Duplicate services with the same name in the same project are forbidden.

#### Limitations:

- maximum 25 characters
- must contain only lowercase ASCII letters (a-z) or numbers (0-9)

:::caution
The hostname is fixed after the service is created. It can't be changed later.
:::

### Set secret environment variables

Add environment variables with sensitive data, such as password, tokens, salts, certificates etc. These will be securely saved inside Zerops and added to your runtime service upon start.

Setting the secret environment variables is optional. You can set them later in Zerops GUI.

Read more about [different types of env variables](/alpine/how-to/env-variables#service-env-variables) in Zerops.

## Create Alpine service using zCLI

zCLI is the Zerops command-line tool. To create a new Alpine service via the command-line, follow these steps:

1. [Install & setup zCLI](/references/cli)
2. [Create a project description file](/alpine/how-to/create#create-a-project-description-file)
3. [Create a project with a Alpine and PostgreSQL service](#full-example)

### Create a project description file

Zerops uses a yaml format to describe the project infrastructure.

#### Basic example:

Create a directory `my-project`. Create an `description.yaml` file inside the `my-project` directory with following content:

```yaml
# basic project data
project:
  # project name
  name: my-project
# array of project services
services:
  - # service name
    hostname: app
    # service type and version number in alpine@{version} format
    type: alpine@3.20
    # defines the minimum number of containers for horizontal autoscaling
    minContainers: 1
    # defines the maximum number of containers for horizontal autoscaling. Max value = 6.
    maxContainers: 6
    # optional: create env variables
    envSecrets:
      S3_ACCESS_KEY_ID: 'P8cX1vVVb'
      S3_ACCESS_SECRET: 'ogFthuiLYki8XoL73opSCQ'
```

The yaml file describes your future project infrastructure. The project will contain one Alpine service with default [auto scaling](/alpine/how-to/scaling) configuration. Hostname will be set to "app", the internal port(s) the service listens on will be defined later in the [zerops.yaml](/alpine/how-to/build-pipeline#ports). Following secret env variables will be configured:

```env
S3_ACCESS_KEY_ID="P8cX1vVVb"
S3_ACCESS_SECRET="ogFthuiLYki8XoL73opSCQ"
```

#### Full example:

Create a directory my-project. Create an description.yaml file inside the my-project directory with following content:

```yaml
# basic project data
project:
  # project name
  name: my-project
  # optional: project description
  description: A project with a Alpine and PostgreSQL database
  # optional: project tags
  tags:
    - DEMO
    - ZEROPS
# array of project services
services:
  - # service name
    hostname: app
    # service type and version number in alpine@{version} format
    type: alpine@3.20
    # optional: vertical auto scaling customization
    verticalAutoscaling:
      cpuMode: DEDICATED
      minCpu: 2
      maxCpu: 5
      minRam: 2
      maxRam: 24
      minDisk: 6
      maxDisk: 50
      startCpuCoreCount: 3
      minFreeRamGB: 0.5
      minFreeRamPercent: 20
    # defines the minimum number of containers for horizontal autoscaling. Max value = 6.
    minContainers: 2
    # defines the maximum number of containers for horizontal autoscaling. Max value = 6.
    maxContainers: 4
    # optional: create secret env variables
    envSecrets:
      S3_ACCESS_KEY_ID: 'P8cX1vVVb'
      S3_ACCESS_SECRET: 'ogFthuiLYki8XoL73opSCQ'
  - # second service hostname
    hostname: db
    # service type and version number in postgresql@{version} format
    type: postgresql@12
    # mode of operation "HA"/"non_HA"
    mode: NON_HA
```

The yaml file describes your future project infrastructure. The project will contain an Alpine service and a [PostgreSQL](/postgresql/overview) service.

Alpine service with "app" hostname, the internal port(s) the service listens on will be defined later in the zerops.yaml. Alpine service will run with a custom vertical and horizontal scaling. Following secret env variables will be configured:

```env
S3_ACCESS_KEY_ID="P8cX1vVVb"
S3_ACCESS_SECRET="ogFthuiLYki8XoL73opSCQ"
```

The hostname of the PostgreSQL service will be set to "db". The [single container](/features/scaling#single-container-mode)(/features/scaling#deployment-modes-databases-and-shared-storage) mode will be chosen and the default auto [scaling configuration](/postgresql/how-to/scale#configure-scaling) will be set.

#### Description of description.yaml parameters

The `project:` section is required. Only one project can be defined.

<table className="w-full my-1.5">
  <thead>
    <tr>
      <th className="w-fit"><strong>Parameter</strong></th>
      <th className="w-fit"><strong>Description</strong></th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td className="w-fit"><strong>hostname</strong></td>
      <td className="w-fit">
        The unique service identifier.

        The hostname of the new database will be set to the `hostname` value.

        <strong>Limitations:</strong>
        <ul>
        <li>duplicate services with the same name in the same project are forbidden</li>
        <li>maximum 25 characters</li>
        <li>must contain only lowercase ASCII letters (a-z) or numbers (0-9)</li>
        </ul>
      </td>
    </tr>
    <tr>
      <td className="w-fit"><strong>type</strong></td>
      <td className="w-fit">
        Specifies the service type and version.

        See what [Alpine service types](/references/import-yaml/type-list#runtime-services) are currently supported.
      </td>
    </tr>
    <tr>
      <td className="w-fit"><strong>verticalAutoscaling</strong></td>
      <td className="w-fit">
        <strong>Optional.</strong> Defines [custom vertical auto scaling parameters](/alpine/how-to/create#set-auto-scaling-configuration).

        All verticalAutoscaling attributes are optional. Not specified attributes will be set to their default values.
      </td>
    </tr>
    <tr>
      <td className="w-fit"><strong>- cpuMode</strong></td>
      <td className="w-fit">
        <strong>Optional.</strong> Accepts `SHARED`, `DEDICATED` values. Default is `SHARED`
      </td>
    </tr>
    <tr>
      <td className="w-fit"><strong>- minCpu/maxCpu</strong></td>
      <td className="w-fit">
        <strong>Optional.</strong> Set the minCpu or maxCpu in CPU cores (integer).
      </td>
    </tr>
    <tr>
      <td className="w-fit"><strong>- minRam/maxRam</strong></td>
      <td className="w-fit">
        <strong>Optional.</strong> Set the minRam or maxRam in GB (float).
      </td>
    </tr>
    <tr>
      <td className="w-fit"><strong>- minDisk/maxDisk</strong></td>
      <td className="w-fit">
        <strong>Optional.</strong> Set the minDisk or maxDisk in GB (float).
      </td>
    </tr>
    <tr>
      <td className="w-fit"><strong>minContainers</strong></td>
      <td className="w-fit">
        <strong>Optional.</strong> Default = 1. Defines the minimum number of containers for [horizontal autoscaling](/alpine/how-to/create#horizontal-auto-scaling).

        <strong>Limitations:</strong>

        Current maximum value = 10.
      </td>
    </tr>
    <tr>
      <td className="w-fit"><strong>maxContainers</strong></td>
      <td className="w-fit">
        Defines the maximum number of containers for [horizontal autoscaling](/alpine/how-to/create#horizontal-auto-scaling).

        <strong>Limitations:</strong>

        Current maximum value = 10.
      </td>
    </tr>
    <tr>
      <td className="w-fit"><strong>envSecrets</strong></td>
      <td className="w-fit">
        <strong>Optional.</strong> Defines one or more secret env variables as a key value map. See env variable [restrictions](/alpine/how-to/env-variables#env-variable-restrictions).
      </td>
    </tr>
  </tbody>
</table>

### Create a project based on the description.yaml

When you have your `description.yaml` ready, use the `zcli project project-import` command to create a new project and the service infrastructure.

```sh
Usage:
  zcli project project-import importYamlPath [flags]

Flags:
  -h, --help                Help for the project import command.
      --org-id string        If you have access to more than one organization, you must specify the org ID for which the
                            project is to be created.
      --working-dir string   Sets a custom working directory. Default working directory is the current directory. (default "./")
```

Zerops will create a project and one or more services based on the `description.yaml` content.

Maximum size of the `description.yaml` file is 100 kB.

You don't specify the project name in the `zcli project project-import` command, because the project name is defined in the `description.yaml`.

If you have access to more than one client, you must specify the client ID for which the project is to be created. The `clientID` is located in the Zerops GUI under the client name on the project dashboard page.

### Add Alpine service to an existing project

#### Example:

Create a directory `my-project` if it doesn't exist. Create an `import.yaml` file inside the `my-project` directory with following content:

```yaml
# basic project data
project:
  # project name
  name: my-project
# array of project services
services:
  - # service name
    hostname: app
    # service type and version number in alpine@{version} format
    type: alpine@3.20
    # defines the minimum number of containers for horizontal autoscaling
    minContainers: 1
    # defines the maximum number of containers for horizontal autoscaling. Max value = 6.
    maxContainers: 6
    # optional: create env variables
    envSecrets:
      S3_ACCESS_KEY_ID: 'P8cX1vVVb'
      S3_ACCESS_SECRET: 'ogFthuiLYki8XoL73opSCQ'
```

The yaml file describes the list of one or more services that you want to add to your existing project. In the example above, one Alpine service version 1 with default [auto scaling](/alpine/how-to/scaling) configuration will be added to your project. Hostname of the new service will be set to `app`. Following secret env variables will be configured:

```env
S3_ACCESS_KEY_ID="P8cX1vVVb"
S3_ACCESS_SECRET="ogFthuiLYki8XoL73opSCQ"
```

The content of the `services:` section of `import.yaml` is identical to the project description file. The `import.yaml` never contains the `project:` section because the project already exists.

When you have your `import.yaml` ready, use the `zcli project service-import` command to add one or more services to your existing Zerops project.

```sh
Usage:
  zcli project service-import importYamlPath [flags]

Flags:
  -h, --help                Help for the project service import command.
  -P, --project-id string   If you have access to more than one project, you must specify the project ID for which the
                           command is to be executed.
```

zCLI commands are interactive, when you press enter after `zcli project service-import importYamlPath`, you will be given a list of your projects to choose from.

Maximum size of the import.yaml file is 100 kB.


----------------------------------------

# Alpine > How To > Customize Runtime


## Build Custom Runtime Images

Zerops allows you to build custom runtime images (CRI) when the default base runtime images don't meet your application's requirements. This is an optional phase in the [build and deploy pipeline](/features/pipeline#runtime-prepare-phase-optional).

Alpine is a versatile base for running anything not explicitly offered as a dedicated Zerops runtime. You can install any packages and tools you need, treating it as a clean OS to customize however you want.

It is also a great option when you need a specific version of a technology (like Go, Node.js, or PHP) that Zerops doesn't support by default—whether it's an older version for legacy projects or a newer release not yet available.

## Configuration

### Default  Runtime Environment

The default  runtime environment contains:

- <span>{data.alpine.default}</span>
- [zCLI](/references/cli)
-

### When You Need a Custom Runtime Image

Since Alpine serves as a general-purpose base, you'll likely want to customize it for your specific use case. Common scenarios include:

:::important
You should not include your application code in the custom runtime image, as your built/packaged code is deployed automatically into fresh containers.
:::

Here are examples of configuring custom runtime images in your `zerops.yml`:

### Basic  Setup

### Using Build Files in Runtime Preparation

For complete configuration details, see the [runtime prepare phase configuration guide](/features/pipeline#configuration).

## Process and Caching

### How Runtime Prepare Works
The runtime prepare process follows the same steps for all runtimes. See [how runtime prepare works](/features/pipeline#how-it-works) for the complete process details.

### Caching Behavior
Zerops caches custom runtime images to optimize deployment times. Learn about [custom runtime image caching](/features/pipeline#custom-runtime-image-caching) including when images are cached and reused.

### Build Management
For information about managing builds and deployments, see [managing builds and deployments](/features/pipeline#manage-builds-and-deployments).

:::warning
Shared storage mounts are not available during the runtime prepare phase.
:::

## Troubleshooting

If your `prepareCommands` fail, check the  for specific error messages.

----------------------------------------

# Alpine > How To > Deploy Process



----------------------------------------

# Alpine > How To > Env Variables



----------------------------------------

# Alpine > How To > Filebrowser



----------------------------------------

# Alpine > How To > Logs



----------------------------------------

# Alpine > How To > Scaling



----------------------------------------

# Alpine > How To > Shared Storage



----------------------------------------

# Alpine > How To > Trigger Pipeline



----------------------------------------

# Alpine > How To > Upgrade



----------------------------------------

# Alpine > Overview


[Alpine Linux ↗](https://alpinelinux.org/) is a lightweight, security-oriented Linux distribution based on musl libc and busybox, known for its small footprint and efficiency.

Alpine services in Zerops provide a minimal base environment for running applications built with technologies that aren't officially supported by Zerops, or for custom setups requiring full control over the runtime environment while keeping resource usage low.

:::tip
Do you have any questions? Check the step-by-step tutorial, browse the documentation and join our **[Discord](https://discord.com/invite/WDvCZ54)** community to get help from our team and other members.
:::

## Feature Highlights

- [Create Alpine service](/alpine/how-to/create) — Start with creating an Alpine service using GUI or zCLI.
- [zerops.yaml](/alpine/how-to/build-pipeline#add-zeropsyaml-to-your-repository) — See a full example of zerops.yaml file to configure your own app.
- [Scaling configuration](/alpine/how-to/scaling) — Set up scaling of your Alpine service so that it runs smoothly while using only necessary resources.

{" "}

- [Customize build environment](/alpine/how-to/build-process#customize-build-environment)
- [Customize runtime environment](/alpine/how-to/customize-runtime)

## When in doubt, reach out

Don't know how to start or got stuck during the process? You might not be the first one, visit the FAQ section to find out.

In case you haven't found an answer (and also if you have), we and our community are looking forward to hearing from you on Discord.

Have you built something that others might find useful? Don't hesitate to share your knowledge!

- [FAQ](/alpine/faq) — Most common questions in one place.
- [Discord](https://discord.com/invite/WDvCZ54) — Join our core team and Zerops community on Discord. Ask questions and share your tips with other members.

## Popular Guides

- [zCLI](/references/cli) — Get even more out of Zerops with the zCLI command line tool.
- [Zerops VPN](/references/networking/vpn) — Connect to your services easily with Zerops VPN.


----------------------------------------

# Bun > How To > Build Pipeline


Zerops provides a customizable build and runtime environment for your Bun application.

## Add zerops.yaml to your repository

Start by adding `zerops.yaml` file to the **root of your repository** and modify it to fit your application:

```yaml
zerops:
  # define hostname of your service
  - setup: app
    # ==== how to build your application ====
    build:
      # REQUIRED. Set the base technology for the build environment:
      base: bun@latest

      # OPTIONAL. Set the operating system for the build environment.
      # os: ubuntu

      # OPTIONAL. Customise the build environment by installing additional packages
      # or tools to the base build environment.
      # prepareCommands:
      #   - sudo apt-get something
      #   - curl something else

      # OPTIONAL. Build your application
      buildCommands:
        - bun i
        - bun run build

      # REQUIRED. Select which files / folders to deploy after
      # the build has successfully finished
      deployFiles:
        - dist
        - package.json
        - node_modules

      # OPTIONAL. Which files / folders you want to cache for the next build.
      # Next builds will be faster when the cache is used.
      cache: node_modules

    # ==== how to run your application ====
    run:
      # OPTIONAL. Sets the base technology for the runtime environment:
      base: bun@latest

      # OPTIONAL. Sets the internal port(s) your app listens on:
      ports:
        # port number
        - port: 3000

      # OPTIONAL. Customise the runtime Bun environment by installing additional
      # dependencies to the base Bun runtime environment.
      # prepareCommands:
      #   - sudo apt-get something
      #   - curl something else

      # OPTIONAL. Run one or more commands each time a new runtime container
      # is started or restarted. These commands are triggered before
      # your Bun application is started.
      # initCommands:
      #  - rm -rf ./cache

      # REQUIRED. Your Bun application start command
      start: bun start
```

The top-level element is always `zerops`.

### Setup

The first element `setup` contains the **hostname** of your service. A runtime service with the same hostname must exist in Zerops.
Zerops supports the definition of multiple runtime services in a single `zerops.yaml`. This is useful when you use a monorepo. Just add multiple setup elements in your `zerops.yaml`:

```yaml
zerops:
  # definition for app service
  - setup: app
    # optional
    build: ...
    # optional
    deploy: ...
    # required
    run: ...

  # definition for api service
  - setup: api
    # optional
    build: ...
    # optional
    deploy: ...
    # required
    run: ...
```

Each service configuration contains at least the `run` section. Optional `build` and `deploy` sections can be added to further customize your process.

## Build pipeline configuration

### base

_REQUIRED._ Sets the base technology for the build environment.

Following options are available for Bun builds:

- `bun@1.3.9`, `bun@1.3`, `bun@latest`
- `bun@1.2.2`, `bun@1.2`
- `bun@nightly`
- `bun@canary`
- `bun@1.1.34`, `bun@1.1(Ubuntu only)`

```yaml
zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build:
      # REQUIRED. Sets the base technology for the build environment:
      base: bun@latest
      ...
```

<p>
  The base build environment contains {data.alpine.default}, the selected
  major version of Bun,
  [Zerops command line tool](/references/cli), `npm`,
  `yarn`, `git` and `npx` tools.
</p>

:::info
You can change the base environment when you need to. Just simply modify the `zerops.yaml` in your repository.
:::

If you need to install more technologies to the build environment, set multiple values as a yaml array. For example:

```yaml
zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build:
      # REQUIRED. Sets the base technology for the build environment:
      base:
        - bun@latest
      prepareCommands:
        - zsc add go@latest
      ...
```

See the full list of supported [build base environments](/zerops-yaml/base-list#runtime-services).

To customise your build environment use the [prepareCommands](build-pipeline#preparecommands) attribute.

:::note
Modifying the base technology will invalidate your build cache. See our [Build Cache Documentation](/features/build-cache) for more details about cache invalidation.
:::

### os

_OPTIONAL._ Sets the operating system for the build environment.

Following options are available:

- `alpine`
- `ubuntu`

Default value is `alpine`.

We are currently using following os version:

- <span>{data.alpine.default}</span>
- <span>{data.ubuntu.default}</span>

:::caution
The os version is fixed and cannot be customised.
:::

:::note
Changing the OS setting will invalidate your build cache. See our [Build Cache Documentation](/features/build-cache) for details about cache behavior.
:::

### prepareCommands

_OPTIONAL._ Customises the build environment by installing additional dependencies or tools to the base build environment.

The base build environment contains:

- <span>{data.alpine.default}</span>
- selected version of Bun defined in the [base](build-pipeline#base) attribute
- [Zerops command line tool](/references/cli)
- `npm`, `yarn`, `git` and `npx` tools

To install additional packages or tools add one or more prepare commands:

```yaml
zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build:
      # REQUIRED. Set the base technology for the build environment:
      base: bun@latest

      # OPTIONAL. Customise the build environment by installing additional packages
      # or tools to the base build environment.
      prepareCommands:
        - sudo apt-get something
        - curl something else
      ...
```

When the first build is triggered, Zerops will

1. create a build container
2. download your application code from your repository
3. run the prepare commands in the defined order

The application code is available in `/build/source` before the prepare commands are triggered, so you can use any file from your repository in your prepare commands (e.g. a configuration file). The commands themselves run in the `/home/zerops` directory.

:::note
These commands are skipped when using cached environment. Modifying `prepareCommands` will invalidate your build cache. See our [Build Cache Documentation](/features/build-cache) for details about cache invalidation.
:::

#### Command exit code

If any command fails, it returns an exit code other than 0 and the build is canceled. Read the [build log](logs#build-log) to troubleshoot the error. If the command ends successfully, it returns the exit code 0 and Zerops triggers the following command. When all prepare commands are finished, your custom build environment is ready for the build phase.

#### Single or separated shell instances

You can configure your prepare commands to be run in a single shell instance or multiple shell instances. The format is identical to [build commands](#buildcommands).

### buildCommands

_OPTIONAL._ Defines build commands.

```yaml
zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build:
      # REQUIRED. Set the base technology for the build environment:
      base: bun@latest

      # OPTIONAL. Build your application
      buildCommands:
        - bun i
        - bun run build
      ...
```

Build commands are optional. Zerops triggers each command in the defined order in a dedicated build container, running from the `/build/source` directory.

Before the build commands are triggered the build container contains:

1. base environment defined by the [base](build-pipeline#base) attribute
2. optional customisation of the base environment defined in the [prepareCommands](build-pipeline#preparecommands) attribute
3. your application code

#### Run build commands as a single shell instance

Use following syntax to run all commands in the same environment context. For example, if one command changes the current directory, the next command continues in that directory. When one command creates an environment variable, the next command can access it.

```yaml
buildCommands:
  - |
    bun i
    bun run build
```

#### Run build commands as a separate shell instances

When the following syntax is used, each command is triggered in a separate environment context. For example, each shell instance starts in the home directory again. When one command creates an environment variable, it won't be available for the next command.

```yaml
buildCommands:
  - bun i
  - bun run build
```

#### Command exit code

If any command fails, it returns an exit code other than 0 and the build is canceled. Read the [build log](logs#build-log) to troubleshoot the error. If the error log doesn't contain any specific error message, try to run your build with the --verbose option.

```yaml
buildCommands:
  - bun i --verbose
  - bun run build
```

If the command ends successfully, it returns the exit code 0 and Zerops triggers the following command. When all `buildCommands` are finished, the application build is completed and ready for the deploy phase.

### deployFiles

_REQUIRED._ Selects which files or folders will be deployed after the build has successfully finished. To filter out specific files or folders, use [`.deployignore`](#deployignore) file.

```yaml
# REQUIRED. Select which files / folders to deploy after
# the build has successfully finished
deployFiles:
  - dist
  - package.json
  - node_modules
```

Determines files or folders produced by your build, which should be deployed to your runtime service containers.

The path starts from the **root directory** of your project (the location of `zerops.yaml`). You must enclose the name in quotes if the folder or the file name contains a space.

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

#### Examples

Deploys a folder, and a file from the project root directory:

```yaml
deployFiles:
  - dist
  - package.json
```

Deploys the whole content of the build container:

```yaml
deployFiles: .
```

Deploys a folder, and a file in a defined path:

```yaml
deployFiles:
  - ./path/to/file.txt
  - ./path/to/dir/
```

#### How to use a wildcard in the path

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

Deploys all folders that are located in any path that begins with `/path/to/`

```yaml
deployFiles: ./path/to/~/
```

Deploys all folders that are located in any path that begins with `/path/` and ends with `/to/`

```yaml
deployFiles: ./path/~/to/
```

:::note Example
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 will be cached for the next build.

```yaml
# OPTIONAL. Which files / folders you want to cache for the next build.
# Next builds will be faster when the cache is used.
cache: file.txt
```

The cache attribute helps optimize build times by preserving specified files between builds.

The cache attribute supports the [~ wildcard character](#how-to-use-a-wildcard-in-the-path).

Learn more about the [build cache system](/features/build-cache) in Zerops.

### envVariables

_OPTIONAL._ Defines the environment variables for the build environment.

Enter one or more env variables in following format:

```yaml
zerops:
  # define hostname of your service
  - setup: app
    # ==== how to build your application ====
    build:
      base: bun@latest
        …

      # OPTIONAL. Defines the env variables for the build environment:
      envVariables:
        NODE_ENV: production
        DB_NAME: db
        DB_HOST: db
        DB_USER: db
        DB_PASS: ${db_password}
```

Read more about [environment variables](env-variables) in Zerops.

## Runtime configuration

### base

_OPTIONAL._ Sets the base technology for the runtime environment.
If you don't specify the `run.base` attribute, Zerops keeps the current Bun version for your runtime.

Following options are available for Bun runtimes:

- `bun@1.3.9`, `bun@1.3`, `bun@latest`
- `bun@1.2.2`, `bun@1.2`
- `bun@nightly`
- `bun@canary`
- `bun@1.1.34`, `bun@1.1(Ubuntu only)`

```yaml
zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build:
      # REQUIRED. Sets the base technology for the build environment:
      base: bun@latest
      ...

    # ==== how to run your application ====
    run:
      # OPTIONAL. Sets the base technology for the runtime environment:
        base: bun@latest
      ...
```

<p>
  The base runtime environment contains {data.alpine.default}, the
  selected major version of Bun, Zerops command line tool, `npm`, `yarn`, `git` and `npx` tools.
</p>

:::info
You can change the base environment when you need to. Just simply modify the `zerops.yaml` in your repository.
:::

If you need to install more technologies to the runtime environment, set multiple values as a yaml array. For example:

```yaml
zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build:
      # REQUIRED. Sets the base technology for the build environment:
      base: bun@latest
      ...

    # ==== how to run your application ====
    run:
      # OPTIONAL. Sets the base technology for the runtime environment:
      base:
        - bun@latest
      prepareCommands:
        - zsc add go@latest
      ...
```

See the full list of supported [run base environments](/zerops-yaml/base-list).

To customise your build environment use the `prepareCommands` attribute.

### os

_OPTIONAL._ Sets the operating system for the runtime environment.

Following options are available:

- `alpine`
- `ubuntu`

Default value is `alpine`.

We are currently using following os version:

- <span>{data.alpine.default}</span>
- <span>{data.ubuntu.default}</span>

:::caution
The os version is fixed and cannot be customised.
:::

### ports

_OPTIONAL._ Specifies one or more internal ports on which your application will listen.

Projects in Zerops represent a group of one or more services. Services can be of different types (runtime services, databases, message brokers, object storage, etc.). All services of the same project share a **dedicated private network**. To connect to a service within the same project, just use the service hostname and its internal port.

For example, to connect to a Bun service with hostname = "app" and port = 3000 from another service of the same project, simply use `app:3000`. Read more about [how to access a Bun service](/features/access).

Each port has following attributes:

| parameter   | description                                                                                                                                                                                                                                                                                                            |
| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| port        | Defines the port number. You can set any port number between _10_ and _65435_. Ports outside this interval are reserved for internal Zerops systems.                                                                                                                                                                   |
| protocol    | **Optional.** Defines the protocol. Allowed values are `TCP` or `UDP`. Default value is `TCP`.                                                                                                                                                                                                                         |
| httpSupport | **Optional.** `httpSupport = true` is the default setting for TCP protocol. Set `httpSupport = false` if a web server isn't running on the port. Zerops uses this information for the configuration of [public access](/features/access). `httpSupport = true` is available only in combination with the TCP protocol. |
| httpSupport | **Optional.** `httpSupport = true` is the default setting for TCP protocol. Set `httpSupport = false` if a web server isn't running on the port. Zerops uses this information for the configuration of [public access](/features/access). `httpSupport = true` is available only in combination with the TCP protocol. |

### prepareCommands

_OPTIONAL._ Customises the Bun runtime environment by installing additional dependencies or tools to the runtime base environment.

<p>
  The base Bun environment contains {data.alpine.default} the selected
  major version of Bun, [Zerops command line tool](/references/cli) and `npm`, `yarn`, `git` and `npx` tools. To install
  additional packages or tools add one or more prepare commands:
</p>

```yaml
zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build:
      ...

    # ==== how to run your application ====
    run:
      # OPTIONAL. Customise the runtime environment by installing additional packages
      # or tools to the base Bun runtime environment.
      prepareCommands:
        - sudo apt-get something
        - curl something else
      ...
```

When the first deploy with a defined prepare attribute is triggered, Zerops will

1. create a prepare runtime container
2. optionally: [copy selected folders or files from your build container](build-pipeline#copy-folders-or-files-from-your-build-container)
3. run the `prepareCommands` commands in the defined order

:::note
`run.prepareCommands` run in the `/home/zerops` directory.
:::

#### Command exit code

If any command fails, it returns an exit code other than 0 and the deploy is canceled. Read the [prepare runtime log](logs#prepare-runtime-log) to troubleshoot the error. If the command ends successfully, it returns the exit code 0 and Zerops triggers the following command. When all `prepareCommands` commands are finished, your custom runtime environment is ready for the deploy phase.

#### Cache of your custom runtime environment

Some packages or tools can take a long time to install. Therefore, Zerops caches your custom runtime environment after the installation of your custom packages or tools is completed. When the second or following deploy is triggered, Zerops will use the custom runtime cache from the previous deploy if following conditions are met:

1. Content of the [build.addToRunPrepare](#copy-folders-or-files-from-your-build-container) and `run.prepareCommands` attributes didn't change from the previous deploy
2. The custom runtime cache wasn't invalidated in the Zerops GUI.

To invalidate the custom runtime cache go to `yyy`

When the custom runtime cache is used, Zerops doesn't create a prepare runtime container and executes the deployment of your application directly.

#### Single or separated shell instances

You can configure your prepare commands to be run in a single shell instance or multiple shell instances. The format is identical to [build commands](#buildcommands).

### Copy folders or files from your build container

<p>
  The prepare runtime container contains {data.alpine.default}, the selected major version of Bun, [Zerops command line tool](/references/cli) and `npm`,
  `yarn`, `git` and `npx` tools.
</p>

The prepare runtime container does not contain your application code nor the built application. If you need to copy some folders or files from the build container to the runtime container (e.g. a configuration file) use the `addToRunPrepare` attribute in the [build section](#build-pipeline-configuration).

```yaml
zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build:
      ...
      addToRunPrepare: ./runtime-config.yaml

    # ==== how to run your application ====
    run:
      # OPTIONAL. Customise the runtime environment by installing additional packages
      # or tools to the base Bun runtime environment.
      prepareCommands:
        - sudo apt-get something
        - curl something else
      ...
```

In the example above Zerops will copy the `runtime-config.yaml` file from your build container **after the build has finished** into the new **prepare runtime** container. The copied files and folders will be available in the `/home/zerops` folder in the new prepare runtime container before the prepare commands are triggered.

### initCommands

_OPTIONAL._ Defines one or more commands to be run each time a new runtime container is started or a container is restarted.

```yaml
zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build: ...

    # ==== how to run your application ====
    run:
      # OPTIONAL. Run one or more commands each time a new runtime container
      # is started or restarted. These commands are triggered before
      # your Bun application is started.
      initCommands:
        - rm -rf ./cache
```

These commands are triggered in the runtime container before your Bun application is started via the [start command](build-pipeline#start).

:::note
`run.initCommands` run in the `/var/www` directory.
:::

Use init commands to clean or initialise your application cache or similar operations.

:::caution
The init commands will delay the start of your application each time a new runtime container is started (including the [horizontal scaling](scaling) or when a runtime container is restarted).

Do not use the init commands for customising your runtime environment. Use the [run:prepareCommands](build-pipeline#preparecommands-1) attribute instead.
:::

#### Command exit code

If any of the `initCommands` fails, it returns an exit code other than 0, but deploy is **not** canceled. After all init commands are finished, regardless of the status code, the application is started. Read the [runtime log](logs#runtime-log) to troubleshoot the error.

#### Single or separated shell instances

You can configure your `initCommands` to be run in a single shell instance or multiple shell instances. The format is identical to [build commands](#buildcommands).

### envVariables

_OPTIONAL._ Defines the environment variables for the runtime environment.

Enter one or more env variables in following format:

```yaml
zerops:
  # define hostname of your service
  - setup: app
    # ==== how to run your application ====
    run:
      # OPTIONAL. Defines the env variables for the runtime environment:
      envVariables:
        NODE_ENV: production
        DB_NAME: db
        DB_HOST: db
        DB_USER: db
        DB_PASS: ${db_password}
```

Read more about [environment variables](env-variables) in Zerops.

### start

_REQUIRED._ Defines the start command for your Bun application.

```yaml
zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build: ...

    # ==== how to run your application ====
    run:
      # REQUIRED. Your Bun application start command
      start: bun start
```

We recommend starting your Bun application using `bun start`.

### health check

_OPTIONAL._ Defines a health check.

`healthCheck` requires either one `httpGet` object or one `exec` object.

#### httpGet

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

Following attributes are available:

<table className="w-full my-1.5">
  <thead>
    <tr>
      <th className="w-fit whitespace-nowrap">Parameter</th>
      <th className="w-fit whitespace-nowrap">Description</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td className="w-fit whitespace-nowrap font-semibold">port</td>
      <td>Defines the port of the HTTP GET request.
The readiness check will trigger a GET request on <code>{'http://127.0.0.1:{port}/{path}'}</code></td>
    </tr>
    <tr>
      <td className="w-fit whitespace-nowrap font-semibold">path</td>
      <td>Defines the URL path of the HTTP GET request.
The readiness check will trigger a GET request on <code>{'http://127.0.0.1:{port}/{path}'}</code></td>
    </tr>
    <tr>
      <td className="w-fit whitespace-nowrap font-semibold">host</td>
      <td><strong>Optional.</strong> The readiness check is triggered from inside of your runtime container so it always uses the localhost <code>127.0.0.1</code>. If you need to add a <code>host</code> to the request header, specify it in the <code>host</code> attribute.</td>
    </tr>
    <tr>
      <td className="w-fit whitespace-nowrap font-semibold">scheme</td>
      <td><strong>Optional.</strong> The readiness check is triggered from inside of your runtime container so no https is required.
If your application requires a https request, set <code>scheme: https</code></td>
    </tr>
  </tbody>
</table>

**Example:**

```yaml
zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build: ...

    # ==== how to run your application ====
    run:
      # REQUIRED. Your Bun application start command
      start: bun start

      # OPTIONAL. Define a health check with a HTTP GET request option.
      # Configures the check on http://127.0.0.1:80/status
      healthCheck:
        httpGet:
          port: 80
          path: /status
```

#### exec

Configures the health check to run a local command.
Following attributes are available:

| Parameter   | Description                                                                                                                                                                                                                                                                                                                     |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **command** | Defines a local command to be run.
The command has access to the same [environment variables](create#set-secret-environment-variables) as your Bun application.
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 below. |

**Example:**

```yaml
zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build: ...

    # ==== how to run your application ====
    run:
      # REQUIRED. Your Bun application start command
      start: bun start

      # OPTIONAL. Define a health check with a shell command.
      healthCheck:
        exec:
          command: |
            touch grass
            rm -rf life
            mv /outside/user /home/user
```

### crontab

_OPTIONAL._ Defines cron jobs.

Setup cron jobs in the following format:

```yaml
zerops:
  # define hostname of your service
  - setup: app

    # ==== how to run your application ====
    run:
      crontab:
        # REQUIRED. Sets the command to execute:
        - command: ""
        # REQUIRED. Sets the interval time to execute:
          timing: "0 * * * *"
```

Read more about setting up [cron](/zerops-yaml/cron) in Zerops.

## Deploy configuration

### readiness check

_OPTIONAL._ Defines a readiness check. Read more about how the [readiness check works](deploy-process#readiness-checks) in Zerops.

`readinessCheck` requires either one `httpGet` object or one `exec` object.

#### httpGet

Configures the readiness check to request a local URL using a http GET method.

Following attributes are available:

<table className="w-full my-1.5">
  <thead>
    <tr>
      <th className="w-fit whitespace-nowrap">Parameter</th>
      <th className="w-fit whitespace-nowrap">Description</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td className="w-fit whitespace-nowrap font-semibold">port</td>
      <td>Defines the port of the HTTP GET request.
The readiness check will trigger a GET request on <code>{'http://127.0.0.1:{port}/{path}'}</code></td>
    </tr>
    <tr>
      <td className="w-fit whitespace-nowrap font-semibold">path</td>
      <td>Defines the URL path of the HTTP GET request.
The readiness check will trigger a GET request on <code>{'http://127.0.0.1:{port}/{path}'}</code></td>
    </tr>
    <tr>
      <td className="w-fit whitespace-nowrap font-semibold">host</td>
      <td><strong>Optional.</strong> The readiness check is triggered from inside of your runtime container so it always uses the localhost <code>127.0.0.1</code>. If you need to add a <code>host</code> to the request header, specify it in the <code>host</code> attribute.</td>
    </tr>
    <tr>
      <td className="w-fit whitespace-nowrap font-semibold">scheme</td>
      <td><strong>Optional.</strong> The readiness check is triggered from inside of your runtime container so no https is required.
If your application requires a https request, set <code>scheme: https</code></td>
    </tr>
  </tbody>
</table>

**Example:**

```yaml
zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build: ...

    # ==== how to deploy your application ====
    deploy:
      # OPTIONAL. Define a readiness check with a HTTP GET request option.
      # Configures the check on http://127.0.0.1:80/status
      readinessCheck:
        httpGet:
          port: 80
          path: /status

    # ==== how to run your application ====
    run: ...
```

Read more about how the [readiness check works](deploy-process#readiness-checks) in Zerops.

#### exec

Configures the readiness check to run a local command.
Following attributes are available:

| Parameter   | Description                                                                                                                                                                                                                                                                                                                     |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **command** | Defines a local command to be run.
The command has access to the same [environment variables](create#set-secret-environment-variables) as your Bun application.
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 below. |

**Example:**

```yaml
zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build: ...

    # ==== how to deploy your application ====
    deploy:
      # OPTIONAL. Define a readiness check with a HTTP GET request option.
      # Configures the check on http://127.0.0.1:80/status
      readinessCheck:
        exec:
          command: |
            touch grass
            rm -rf life
            mv /outside/user /home/user
```

Read more about how the [readiness check works](deploy-process#readiness-checks) in Zerops.


----------------------------------------

# Bun > How To > Build Process



----------------------------------------

# Bun > How To > Controls



----------------------------------------

# Bun > How To > Create


Zerops provides a powerful Bun runtime service with extensive build support. The Bun runtime is highly scalable and customizable to suit your development and production needs. With just a few clicks or commands, you can have a production-ready Bun environment up and running in no time.

## Create a Bun service using Zerops GUI

First, set up a project in the Zerops GUI. Then go to the project dashboard page and choose **Add new service** in the left menu under the **Services** section. From there, you can add a new Bun service:

[Video: /vids/services/bun.webm](/vids/services/bun.webm)

### Choose a Bun version

Zerops supports the following Bun versions:

:::info
You can easily [upgrade](upgrade) the major version at any time later.
:::

### Set a hostname

Enter a unique service identifier like "app", "cache", "gui", etc. Duplicate services with the same name within the same project are not allowed.

#### Limitations:

- Maximum 25 characters
- Must contain only lowercase ASCII letters (a-z) or numbers (0-9)

:::caution
The hostname is fixed after the service is created and cannot be changed later.
:::

### Set secret environment variables

Add environment variables with sensitive data, such as passwords, tokens, salts, certificates, etc. These will be securely saved inside Zerops and added to your runtime service upon start.

Setting secret environment variables is optional. You can always set them later in the Zerops GUI.

Read more about the [different types of environment variables](env-variables#service-env-variables) in Zerops.

## Create a Bun service using zCLI

zCLI is the Zerops command-line tool. To create a new Bun service via the command line, follow these steps:

1. [Install & setup zCLI](/references/cli)
2. [Create a project description file](create#create-a-project-description-file)
3. [Create a project with a Bun and PostgreSQL service](#full-example)

### Create a project description file

Zerops uses a YAML format to describe the project infrastructure.

#### Basic example:

Create a directory called `my-project`. Inside the `my-project` directory, create a `description.yaml` file with the following content:
```yaml
# basic project data
project:
  # project name
  name: my-project
# array of project services
services:
  - # service name
    hostname: app
    # service type and version number in Bun@{version} format
    type: bun@latest
    # defines the minimum number of containers for horizontal autoscaling
    minContainers: 1
    # defines the maximum number of containers for horizontal autoscaling. Max value = 6.
    maxContainers: 6
    # optional: create env variables
    envSecrets:
      S3_ACCESS_KEY_ID: 'P8cX1vVVb'
      S3_ACCESS_SECRET: 'ogFthuiLYki8XoL73opSCQ'
```

The yaml file describes your future project infrastructure. The project will contain one Bun service with default [auto scaling](scaling) configuration. Hostname will be set to "app", the internal port(s) the service listens on will be defined later in the [zerops.yaml](build-pipeline#ports). Following secret env variables will be configured:

```env
S3_ACCESS_KEY_ID="P8cX1vVVb"
S3_ACCESS_SECRET="ogFthuiLYki8XoL73opSCQ"
```

#### Full example:

Create a directory my-project. Create an description.yaml file inside the my-project directory with following content:

```yaml
# basic project data
project:
  # project name
  name: my-project
  # optional: project description
  description: A project with a Bun and PostgreSQL database
  # optional: project tags
  tags:
    - DEMO
    - ZEROPS
# array of project services
services:
  - # service name
    hostname: app
    # service type and version number in Bun@{version} format
    type: bun@latest
    # optional: vertical auto scaling customization
    verticalAutoscaling:
      cpuMode: DEDICATED
      minCpu: 2
      maxCpu: 5
      minRam: 2
      maxRam: 24
      minDisk: 6
      maxDisk: 50
      startCpuCoreCount: 3
      minFreeRamGB: 0.5
      minFreeRamPercent: 20
    # defines the minimum number of containers for horizontal autoscaling. Max value = 6.
    minContainers: 2
    # defines the maximum number of containers for horizontal autoscaling. Max value = 6.
    maxContainers: 4
    # optional: create env variables
    envSecrets:
      S3_ACCESS_KEY_ID: 'P8cX1vVVb'
      S3_ACCESS_SECRET: 'ogFthuiLYki8XoL73opSCQ'
  - # second service hostname
    hostname: db
    # service type and version number in postgresql@{version} format
    type: postgresql@12
    # mode of operation "HA"/"non_HA"
    mode: NON_HA
```

The yaml file describes your future project infrastructure. The project will contain a Bun service and a [PostgreSQL](/postgresql/overview) service.

Bun service with "app" hostname, the internal port(s) the service listens on will be defined later in the [zerops.yaml](build-pipeline#ports). Bun service will run with custom vertical and horizontal scaling. Following secret env variables will be configured:

```env
S3_ACCESS_KEY_ID="P8cX1vVVb"
S3_ACCESS_SECRET="ogFthuiLYki8XoL73opSCQ"
```

The hostname of the PostgreSQL service will be set to "db". The [single container](/features/scaling#single-container-mode)(/features/scaling#deployment-modes-databases-and-shared-storage) mode will be chosen and the default auto [scaling configuration](/postgresql/how-to/scale#configure-scaling) will be set.

#### Description of description.yaml parameters

The `project:` section is required. Only one project can be defined.

| Parameter       | Description                                                                                                                     | Limitations             |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------- | ----------------------- |
| **name**        | The name of the new project. Duplicates are allowed.                                                                            |                         |
| **description** | **Optional.** Description of the new project.                                                                                   | Maximum 255 characters. |
| **tags**        | **Optional.** One or more string tags. Tags do not have a functional meaning, they only provide better orientation in projects. |
| **tags**        | **Optional.** One or more string tags. Tags do not have a functional meaning, they only provide better orientation in projects. |

At least one service in `services:` section is required. You can create a project with multiple services. The example above contains Bun and PostgreSQL services but you can create a `description.yaml` with your own combination of [services](/features/infrastructure).

<table className="w-full my-1.5">
  <thead>
    <tr>
      <th className="w-fit">Parameter</th>
      <th className="w-fit">Description</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td className="w-fit">
        <b>hostname</b>
      </td>
      <td className="w-fit">
        The unique service identifier.
        <ul>
        <li>duplicate services with the same name in the same project are forbidden</li>
        <li>maximum 25 characters</li>
        <li>must contain only lowercase ASCII letters (a-z) or numbers (0-9)</li>
        </ul>
      </td>
    </tr>
    <tr>
      <td className="w-fit">
        <b>type</b>
      </td>
      <td className="w-fit">
        Specifies the service type and version.

        See what [Bun service types](/references/import-yaml/type-list#runtime-services) are currently supported.
      </td>
    </tr>
    <tr>
      <td className="w-fit">
        <b>verticalAutoscaling</b>
      </td>
      <td className="w-fit">
        <b>Optional.</b> Defines [custom vertical auto scaling parameters](/bun/how-to/scaling#configure-scaling).

        All verticalAutoscaling attributes are optional. Not specified attributes will be set to their default values.
      </td>
    </tr>
    <tr>
      <td className="w-fit">
        <b> - cpuMode</b>
      </td>
      <td className="w-fit">
        <b>Optional.</b> Accepts `SHARED`, `DEDICATED` values. Default is `SHARED`
      </td>
    </tr>
    <tr>
      <td className="w-fit">
        <b> - minCpu/maxCpu</b>
      </td>
      <td className="w-fit">
        <b>Optional.</b> Set the minCpu or maxCpu in CPU cores (integer).
      </td>
    </tr>
    <tr>
      <td className="w-fit">
        <b> - minRam/maxRam</b>
      </td>
      <td className="w-fit">
        <b>Optional.</b> Set the minRam or maxRam in GB (float).
      </td>
    </tr>
    <tr>
      <td className="w-fit">
        <b> - minDisk/maxDisk</b>
      </td>
      <td className="w-fit">
        <b>Optional.</b> Set the minDisk or maxDisk in GB (float).
      </td>
    </tr>
    <tr>
      <td className="w-fit">
        <b>minContainers</b>
      </td>
      <td className="w-fit">
        <b>Optional.</b> Default = 1. Defines the minimum number of containers
        for [horizontal autoscaling](/bun/how-to/scaling#configure-scaling).

        <b>Limitations:</b>

        Current maximum value = 10.
      </td>
    </tr>
    <tr>
      <td className="w-fit">
        <b>maxContainers</b>
      </td>
      <td className="w-fit">
        Defines the maximum number of containers for [horizontal autoscaling](/bun/how-to/scaling#configure-scaling).

        <b>Limitations:</b>

        Current maximum value = 10.
      </td>
    </tr>
    <tr>
      <td className="w-fit">
        <b>envSecrets</b>
      </td>
      <td className="w-fit">
        <b>Optional.</b> Defines one or more secret env variables as a key value
        map. See env variable [restrictions](env-variables#env-variable-restrictions).
      </td>
    </tr>
  </tbody>
</table>

### Create a project based on the description.yaml

When you have your `description.yaml` ready, use the `zcli project project-import` command to create a new project and the service infrastructure.

```sh
Usage:
  zcli project project-import importYamlPath [flags]

Flags:
  -h, --help                Help for the project import command.
      --org-id string        If you have access to more than one organization, you must specify the org ID for which the
                            project is to be created.
      --working-dir string   Sets a custom working directory. Default working directory is the current directory. (default "./")
```

Zerops will create a project and one or more services based on the `description.yaml` content.

Maximum size of the `description.yaml` file is 100 kB.

You don't specify the project name in the `zcli project project-import` command, because the project name is defined in the `description.yaml`.

If you have access to more than one client, you must specify the client ID for which the project is to be created. The `clientID` is located in the Zerops GUI under the client name on the project dashboard page.

### Add Bun service to an existing project

#### Example:

Create a directory `my-project` if it doesn't exist. Create an `import.yaml` file inside the `my-project` directory with following content:

```yaml
# basic project data
project:
  # project name
  name: my-project
# array of project services
services:
  - # service name
    hostname: app
    # service type and version number in Bun@{version} format
    type: bun@latest
    # defines the minimum number of containers for horizontal autoscaling
    minContainers: 1
    # defines the maximum number of containers for horizontal autoscaling. Max value = 6.
    maxContainers: 6
    # optional: create env variables
    envSecrets:
      S3_ACCESS_KEY_ID: 'P8cX1vVVb'
      S3_ACCESS_SECRET: 'ogFthuiLYki8XoL73opSCQ'
```

The yaml file describes the list of one or more services that you want to add to your existing project. In the example above, one Bun service with default [auto scaling](scaling) configuration will be added to your project. Hostname of the new service will be set to `app`. Following secret env variables will be configured:

```env
S3_ACCESS_KEY_ID="P8cX1vVVb"
S3_ACCESS_SECRET="ogFthuiLYki8XoL73opSCQ"
```

The content of the `services:` section of `import.yaml` is identical to the project description file. The `import.yaml` never contains the `project:` section because the project already exists.

When you have your `import.yaml` ready, use the `zcli project service-import` command to add one or more services to your existing Zerops project.

```sh
Usage:
  zcli project service-import importYamlPath [flags]

Flags:
  -h, --help                Help for the project service import command.
  -P, --project-id string   If you have access to more than one project, you must specify the project ID for which the
                           command is to be executed.
```

zCLI commands are interactive, when you press enter after `zcli project service-import importYamlPath`, you will be given a list of your projects to choose from.

Maximum size of the import.yaml file is 100 kB.

----------------------------------------

# Bun > How To > Customize Runtime



----------------------------------------

# Bun > How To > Deploy Process



----------------------------------------

# Bun > How To > Env Variables



----------------------------------------

# Bun > How To > Filebrowser



----------------------------------------

# Bun > How To > Logs



----------------------------------------

# Bun > How To > Scaling



----------------------------------------

# Bun > How To > Shared Storage



----------------------------------------

# Bun > How To > Trigger Pipeline



----------------------------------------

# Bun > How To > Upgrade



----------------------------------------

# Bun > Overview


[Bun ↗](https:/bun.org/en) is an asynchronous event-driven JavaScript runtime, which is designed to build scalable network applications.

As said, there is no need for coding yet, we have created a [Github repository ↗](https://github.com/zeropsio/recipe-bun), a **_recipe_**, containing the most simple Bun web application. The repo will be used as a source from which the app will be built.

### 🚀 Feel free to deploy the recipe yourself

This is the most bare-bones example of Bun app running in Zerops — as few libraries as possible,
  just a simple endpoint with connect, read and write to a Zerops PostgreSQL database.

  [Deploy "bun" recipe on Zerops](https://app.zerops.io/recipe/?lf=bun)

1. Log in/sign up to [Zerops GUI ↗](https://app.zerops.io)

2. In the **Projects** box click on **Import a project** and paste in the following YAML config ([source ↗](https://github.com/zeropsio/recipe-bun/blob/main/zerops-project-import.yaml)):

```yaml
project:
  name: recipe-bun
  tags:
    - zerops-recipe

services:
  - hostname: api
    type: bun@1.1
    enableSubdomainAccess: true
    buildFromGit: https://github.com/zeropsio/recipe-bun

  - hostname: db
    type: postgresql@16
    mode: NON_HA
    priority: 1
```

3. Click on **Import project** and wait until all pipelines have finished.

**That's it, your application is now up and running! :star: Let's check it works:**

1. A _subdomain_ should have been enabled and visible in the project's **IP addressed & Public Routing Overview** box. Its format should look similar to this `https://api-806-3000.prg1.zerops.app`.
2. Click or the `subdomain` URL to open it in a browser and you should see

```
{"message":"This is a simple, basic Bun application running in Zerops.io,\n          each request adds an entry to the PostgreSQL database and returns a count.\n          See the source repository (https://github.com/zeropsio/recipe-bun) for more information.","newEntry":"dfd1e873-bfc8-4f36-af07-e32561820b93","count":"1"}
```

:::tip
Do you have any questions? Check the step-by-step tutorial, browse the documentation and join our **[Discord](https://discord.com/invite/WDvCZ54)** community to get help from our team and other members.
:::

## How to start

It doesn't matter whether it's your first curious introduction to Zerops, you have already mastered the basics and are looking for a tiny detail or inspiration. Below, choose a section that fits your needs:

- [Care for details?](/bun/how-to/create) — Dive in all Zerops has to offer for your Bun application.
- [Bun recipes](https://github.com/zeropsio?q=Bun&type=all&language=&sort=) — Get inspired by already existing repositories, ready to be imported to Zerops.

## Feature Highlights

- [Create Bun service](/bun/how-to/create) — Start with creating a Bun service using GUI or zCLI.
- [Zerops.yaml](/bun/how-to/build-pipeline#add-zeropsyaml-to-your-repository) — See a full example of zerops.yaml file to create your own app.
- [Scaling configuration](/bun/how-to/scaling) — Set up scaling of your Bun application so that it runs smoothly while using only necessary resources.

{" "}

- [Customize build environment](/bun/how-to/build-process#customize-build-environment)
- [Customize runtime environment](/bun/how-to/customize-runtime)

## When in doubt, reach out

Don't know how to start or got stuck during the process? You might not be the first one, visit the FAQ section to find out.

In case you haven't found an answer (and also if you have), we and our community are looking forward to hearing from you on Discord.

Have you build something that others might find useful? Don't hesitate to share your knowledge!

- [Discord](https://discord.com/invite/WDvCZ54) — Join our core team and Zerops community on Discord. Ask questions and share your tips with other members.

## Popular Guides

- [zCLI](/references/cli) — Get even more out of Zerops with the zCLI command line tool.
- [Zerops VPN](/references/networking/vpn) — Connect to your services easily with Zerops VPN.


----------------------------------------

# Clickhouse > Overview


Zerops provides a fully managed [ClickHouse](https://clickhouse.com/) columnar database optimized for blazing-fast analytical queries on massive datasets, making it ideal for data warehousing and real-time analytics applications.

## Supported Versions

Currently supported ClickHouse version:

Import configuration version:

- `clickhouse@25.3`

## Service Configuration

Our ClickHouse implementation features optimized default settings designed for analytical workloads and data warehousing use cases.

### Resource Allocation

Zerops automatically allocates resources to your ClickHouse service based on demand within the limits defined in your [automatic scaling configuration](/features/scaling).

## High Availability and Deployment Modes

:::important
Deployment mode is selected during service creation and cannot be changed later.
:::

### High-Availability (HA) Setup

The recommended solution for production workloads and mission-critical analytics:

* **3 data nodes** with automatic monitoring, repairs, and replication factor of 3
* **Default cluster name:** `zerops` (currently 1 shard with 3 replicas)

#### Replication Configuration

The `Replicated` database engine handles replication automatically, but there are specific requirements you need to follow:

**For Database Operations**
Use this configuration when creating/managing databases:

```sql
CREATE DATABASE uk ON CLUSTER '{cluster}'
ENGINE = Replicated('/clickhouse/databases/{uuid}', '{shard}', '{replica}');
```

**For Table Operations**
Use `ENGINE = ReplicatedMergeTree` when creating tables (without the `ON CLUSTER '{cluster}'` clause):

```sql
CREATE TABLE uk.uk_price_paid
(
    price     UInt32,
    date      Date,
    postcode1 LowCardinality(String),
    postcode2 LowCardinality(String),
    type      Enum8('terraced' = 1, 'semi-detached' = 2, 'detached' = 3, 'flat' = 4, 'other' = 0),
    is_new    UInt8,
    duration  Enum8('freehold' = 1, 'leasehold' = 2, 'unknown' = 0),
    addr1     String,
    addr2     String,
    street    LowCardinality(String),
    locality  LowCardinality(String),
    town      LowCardinality(String),
    district  LowCardinality(String),
    county    LowCardinality(String)
) ENGINE = ReplicatedMergeTree ORDER BY (postcode1, postcode2, addr1, addr2);
```

For more details see:
- https://clickhouse.com/docs/engines/database-engines/replicated
- https://clickhouse.com/docs/engines/table-engines/mergetree-family/replication
- https://clickhouse.com/docs/sql-reference/distributed-ddl

You can use other `Replicated*` engines from the MergeTree family. Replication is only supported for tables in the MergeTree family:

* `ReplicatedMergeTree`
* `ReplicatedSummingMergeTree`
* `ReplicatedReplacingMergeTree`
* `ReplicatedAggregatingMergeTree`
* `ReplicatedCollapsingMergeTree`
* `ReplicatedVersionedCollapsingMergeTree`
* `ReplicatedGraphiteMergeTree`

User management (users, grants, etc.) is replicated by Keeper by default. The `ON CLUSTER '{cluster}'` clause is not needed when creating/deleting users or changing grants.

The default `<service-hostname>` database follows these practices. If you don't follow these recommendations, it is possible you will face issues in case of fail and repair scenario.

### Single Container Installation

Suitable for development and testing environments:

* Consists of 1 ClickHouse node
* Lower resource requirements
* No automatic replication

:::warning
Use for development purposes or non-critical data only. **Make sure to have backups enabled** if using in production, as you can lose your data due to container volatility.
:::

## Network Access & Protocols

Zerops automatically configures secure authentication for your ClickHouse service.

### Default Database
Zerops creates a default database with the same name as your service hostname (`<service-hostname>`) during service creation.

### Default Users

#### `zerops` User
* Created automatically upon service creation
* Has privileges for the default database
* Password available as environment variable `password`

#### `super` User
* Administrative user for cluster management
* Can create new databases, users, and manage permissions
* Password available as environment variable `superUserPassword`

### Access Methods

Services within the same project can access ClickHouse directly using:
```
<service-hostname>:<port>
```

For HA cluster setups, you can also access specific data nodes:
```
node-stable-<1..3>.db.<service-hostname>.zerops:<port>
```

For external access, use `zcli` VPN to connect using the same connection strings.

ClickHouse offers multiple interfaces for different use cases:

#### Native TCP Protocol
**Port:** `9000` (Environment variable: `port` or `portNative`)

Optimal for high-performance applications and ClickHouse-native clients.

More about it in [official ClickHouse docs](https://clickhouse.com/docs/interfaces/tcp).

#### HTTP/HTTPS Interface
**Port:** `8123` (Environment variable: `portHttp`)

Ideal for web applications and REST API integrations.

It is also possible to setup HTTPS domain access or enable subdomain for access from outside the project. Then you can access the database using following URL:
- `https://clickhouse.my-awesome-domain.tld`
- JDBC connection string example (use `ssl=true&sslmode=NONE` options):
`jdbc:clickhouse:https://clickhouse.my-awesome-domain.tld:443/?ssl=true&sslmode=NONE`

More about it in [official ClickHouse docs](https://clickhouse.com/docs/interfaces/http).

#### MySQL Protocol
**Port:** `9004` (Environment variable: `portMysql`)

Enables connectivity from MySQL-compatible tools and applications.

More about it in [official ClickHouse docs](https://clickhouse.com/docs/interfaces/mysql).

#### PostgreSQL Protocol
**Port:** `9005` (Environment variable: `portPostgresql`)

Allows integration with PostgreSQL-compatible clients and ORMs.

More about it in [official ClickHouse docs](https://clickhouse.com/docs/interfaces/postgresql).

## Backup and Recovery

Zerops provides comprehensive backup functionality using ClickHouse's native backup capabilities.

### Backup Process

* Backups are performed using ClickHouse SQL command `BACKUP ALL ...` with `super` user permissions
* All databases are backed up (excluding system databases)
* Backup files are stored as `tar.gz` archives
* Contains the complete folder structure produced by the SQL backup command

### Restore Options

#### Option 1: Custom S3 Bucket Restore

1. Download backup from Zerops GUI or via API
2. Extract the tar.gz archive and upload to your S3 bucket
3. Restore using ClickHouse SQL commands:

```sql
-- Restore specific table
RESTORE TABLE mydb.mytable AS mydb.mytable2
FROM S3('https://storage-prg1.zerops.io/mybucket/path/to/dir/with/untarred/backup',
        'my-access-key-id', 'my-secret-key');

-- Restore all data
RESTORE ALL FROM S3('https://storage-prg1.zerops.io/mybucket/path/to/backup',
                   'my-access-key-id', 'my-secret-key');

-- see https://clickhouse.com/docs/operations/backup#configuring-backuprestore-to-use-an-s3-endpoint
```

#### Option 2: Support-Assisted Restore

Contact Zerops support on Discord, and we'll place the backup on the container's filesystem for restoration using the `File` driver (see [ClickHouse documentation](https://clickhouse.com/docs/operations/backup) for further info).

:::note
A simple GUI/API action for backup restoration is on our roadmap for future releases.
:::

## Troubleshooting

### Common Issues

#### Connection Problems
* Verify you're using the correct port for your chosen protocol
* Check that your service is running and healthy in the Zerops dashboard
* For HA clusters, try connecting to specific nodes if the main endpoint fails
* Ensure authentication credentials are correct

#### Replication Issues
* Verify you're using `ON CLUSTER '{cluster}'` for database operations
* Confirm tables use `ReplicatedMergeTree` engines

## Learn More

- [Official ClickHouse Documentation](https://clickhouse.com/docs) - Comprehensive guide to ClickHouse features and SQL syntax
- [ClickHouse Replication Guide](https://clickhouse.com/docs/engines/table-engines/mergetree-family/replication) - Detailed replication concepts
- [Distributed DDL Reference](https://clickhouse.com/docs/sql-reference/distributed-ddl) - Cluster operations documentation

## Support

For advanced configurations or custom requirements:
- Join our [Discord community](https://discord.gg/zerops)
- Contact support via [email](mailto:support@zerops.io)

----------------------------------------

# Company > About


## Our Story

Zerops, originally founded in 2018, began as an internal project at [vshosting.eu](https://vshosting.eu), one of the largest providers of managed hosting solutions in Central Europe. In June 2024, after a period when the project had been shut down following corporate restructuring, Zerops was re-launched as an independent startup. Now headed by the original development team and backed by strong partners, Zerops continues its mission with renewed focus and independence.

## Technology & Infrastructure

Zerops runs on bare metal, with the platform built from the ground up using Golang and [Incus](https://linuxcontainers.org/incus/) containerization. Our servers are currently located in Prague, Czech Republic, leveraging vshosting's state-of-the-art datacenter facilities.

## Financial Backing & Partners

Zerops is financially backed by established venture capital firms:
- [Presto Ventures](https://www.prestoventures.com/) - A leading Central European venture capital firm
- [Gi21 Capital](https://gi21capital.com/) - A technology-focused investment firm

Our primary infrastructure partner is [vshosting.eu](https://vshosting.eu), which itself is part of [Contabo](https://contabo.com/en/), owned by global investment firm [KKR](https://www.kkr.com/). This strategic partnership provides Zerops with enterprise-grade infrastructure stability.

## Looking Ahead

We're committed to continually improving the Zerops platform with a focus on:

- **Multiregional Deployment**: Beginning with built-in CDN capabilities, followed by the ability to run entire projects in different regions
- **Enhanced Performance**: Ongoing optimization of our container orchestration and resource management
- **Developer Experience**: Continuous improvement of our UI, CLI, and API interfaces

## Connect With Us

- [Discord](https://discord.com/invite/WDvCZ54)
- [X.com](https://x.com/zeropsio)
- [LinkedIn](https://www.linkedin.com/company/zerops)
- [Contact Us](mailto:team@zerops.io)

----------------------------------------

# Company > Branding


# Zerops Brand Assets

Here you can find and download our official logos and badges in various formats. Please follow our brand guidelines when using these assets.

## Download Assets

Below you'll find our official assets available in various formats. Click the download buttons to get the assets in your preferred format.

## Brand Guidelines

When using Zerops brand assets, please:

- Don't modify the logos or badges in any way
- Maintain adequate spacing around the assets
- Use the provided color versions (light/dark) as appropriate
- Don't use the Zerops logo or badges in a way that suggests partnership or endorsement without permission
- Don't use the assets as your own branding or as part of your logo


----------------------------------------

# Company > Payment


Zerops provides a transparent credit-based payment system that makes managing your account finances straightforward. You can easily add funds to your account through manual or automatic top-ups, track all your transactions, and download invoices for your records.

This page explains how to manage your account balance, set up payment preferences, and access your complete billing history to help you maintain uninterrupted service while keeping your finances organized.

## Manual Top-up

Manual top-ups give you direct control over your account funding. To add credits to your account immediately:

1. Navigate to **Credit & Spend Overview** in the Organization section of the main menu
2. Click on **Top up credit** and fill in the [billing information](#billing-information)
3. Enter your desired top-up amount (minimum $10 VAT excl.)
3. Complete payment using your saved or new payment method

## Automatic Top-ups

Automatic top-up ensures your projects continue running without interruption by replenishing your credits when they run low.

:::note Prerequisites
Automatic top-ups are available once you have made at least one manual top-up, saved a payment method, and provided your [billing information](#billing-information). The saved card is charged off-session, so a valid payment method must stay on file.
:::

To turn them on, navigate to **Credit & Spend Overview** in the Organization section of the main menu, open the automatic top-up settings, and configure the three values described below.

### How Automatic Top-ups Work

When enabled, Zerops periodically checks your balance and tops it up by a fixed amount whenever your credit drops below a threshold you choose, up to a limit you set for each calendar month.
Zerops initiates an automatic payment when:

- Your combined balance (credit + promo credit) drops **below your threshold**
- You have automatic top-ups enabled
- The top-up wouldn't exceed your **calendar-month limit**

:::note Important notes
- Each top-up charges the **fixed amount** you configured, regardless of how fast you're spending
- Your balance is checked periodically (every few minutes), so a top-up can take a few minutes to appear after you drop below the threshold
- The final automatic top-up of the month is reduced so the month's total lands exactly on your calendar-month limit; after the limit is reached, automatic top-ups pause until the next calendar month
- To avoid repeatedly hitting your payment method (which can get a card flagged or blocked by the payment processor), top-ups are spaced out: after a **successful** top-up Zerops waits **1 hour** before the next one, and after a **failed** top-up it waits **1 day** before trying again
- If a charge fails, Zerops notifies you so you can check the validity and available funds of your saved card. After **3 failed attempts in a row**, automatic top-up is turned off and you're notified by email; re-enable it once your payment method is working again
- Auto top-up limits don't affect manual payments — add any amount manually regardless of automatic settings
:::

### Configuration Options

#### Threshold
When your combined balance (credit + promo credit) drops below this value, an automatic top-up is triggered.

#### Top-up Amount
The fixed amount charged to your saved card on each automatic top-up.

- Minimum: $10 (matches the minimum manual payment)
- Maximum: $10,000 per top-up

#### Calendar-Month Limit
The maximum total that can be automatically charged within a single calendar month (UTC). This safeguards against unexpected costs: once the limit is reached, automatic top-ups pause until the next calendar month.

- Must be at least the top-up amount (so at least one top-up can go through each month)

#### Real-World Example

**Scenario:** Application with ~$50 weekly operating costs and an initial manual top-up of $100

**Your Settings:**
- Threshold = $50
- Top-up amount = $200
- Calendar-month limit = $500

**Expected behavior:**
- When your balance falls below $50, Zerops charges $200 to bring it back up
- Each top-up is exactly $200, no matter how fast you're spending, until you approach the calendar-month limit
- After two top-ups ($400), a full $200 would exceed the $500 limit, so the next top-up is reduced to $100, bringing the month's total to exactly $500
- Automatic top-ups then pause until the limit resets at the start of the next calendar month (UTC)

## Billing Information

You are required to enter billing details for all transactions (manual and automatic top-ups), with one exception:

- EU-based users who are not VAT payers with transactions under $350

You can save your billing details by navigating to **Invoices & Billing Settings** in the Organization section of the main menu.

## Invoices

Zerops provides easy access to all invoices generated for manual and automatic top-ups within your organization.

To view and manage your invoices navigate to **Invoices & Billing Settings** in the Organization section of the main menu.

## Export Credit Consumption Records

Zerops allows you to download monthly reports of your credit consumption history for analysis and record-keeping.

1. Navigate to **Credit & Spend Overview** in the Organization section
2. Find the **Export Credit Consumption Records** section
3. Click on any month button to download that period's report

Reports are available for the past 12 months in TXT format and include:
- Client information and reporting period
- Starting and ending balances
- Itemized resource charges by project and service
- Credit transactions (top-ups, refunds, promotional credits)
- Clear distinction between common (paid) and promotional credits

----------------------------------------

# Company > Pricing


Zerops provides a straightforward pricing structure based on your project type and resource usage.

The total cost of deploying an application includes your project's **core package cost** + the **cost of the resources** of the services inside a project. Additional charges may apply for optional features such as dedicated IPv4, extra egress, object storage, extra backup space and extra build time.

:::note Fair Billing Model
Resources are allocated per service and billed by the minute, though credit is deducted hourly based on actual usage. You're only charged for what you use, calculated down to the minute.
:::

Need to add credits to your account? Visit our [Top-up & Billing page](/company/payment) for instructions.

## Project Core Plans

Zerops offers two core types to match different needs and budgets. For detailed information on both core types, visit our [Project & Services Structure](/features/infrastructure) page.

### Lightweight Core - Free
Best for development, testing, and smaller workloads with limited redundancy.

**Included resources:**
- **Build Time**: 15 hours per month
- **Backup Storage**: 5 GB
- **Egress Traffic**: 100 GB per month

### Serious Core - $10 / 30 days
Optimized for production workloads with high availability and comprehensive failover protection.

**Included resources:**
- **Build Time**: 150 hours per month
- **Backup Storage**: 25 GB
- **Egress Traffic**: 3 TB per month

:::note Storage Limits
All projects have a technical maximum backup storage limit of **1 TiB**. Usage beyond the free tier allocation (5GB or 25GB) is billed according to the [overage costs](#overage-costs) below.
:::

## Resource Pricing

Services in Zerops require computing resources that are billed separately from your project core. These resources are allocated per service and billed by the minute based on actual usage, with credits deducted hourly.

<table className="w-full my-1.5">
  <thead>
    <tr>
      <th className="w-fit whitespace-nowrap"><strong>Resource</strong></th>
      <th className="w-fit whitespace-nowrap"><strong>Price</strong></th>
      <th className="w-fit"><strong>Description</strong></th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td className="w-fit whitespace-nowrap"><strong>Shared CPU</strong></td>
      <td className="w-fit whitespace-nowrap"><strong>$0.60</strong> per CPU / 30 days</td>
      <td className="w-fit">Economical option for most workloads with good performance</td>
    </tr>
    <tr>
      <td className="w-fit whitespace-nowrap"><strong>Dedicated CPU</strong></td>
      <td className="w-fit whitespace-nowrap"><strong>$6.00</strong> per CPU / 30 days</td>
      <td className="w-fit">Reserved CPU cores for predictable performance</td>
    </tr>
    <tr>
      <td className="w-fit whitespace-nowrap"><strong>RAM</strong></td>
      <td className="w-fit whitespace-nowrap"><strong>$0.75</strong> per 0.25 GB / 30 days</td>
      <td className="w-fit">Memory allocated to your services</td>
    </tr>
    <tr>
      <td className="w-fit whitespace-nowrap"><strong>Disk Space</strong></td>
      <td className="w-fit whitespace-nowrap"><strong>$0.05</strong> per 0.5 GB / 30 days</td>
      <td className="w-fit">Storage space for your applications and data</td>
    </tr>
  </tbody>
</table>

:::note Daily Spending Control
You can set a daily spending limit in the GUI for your project to keep an eye on costs and avoid unexpected charges. This provides an alternative to configuring automatic resource scaling ranges while keeping your services running optimally.

Reaching the limit does not stop your project - your services keep running. When a project reaches its daily spending limit, Zerops sends you a warning notification (e-mail) so you can decide whether to raise the limit. The limit resets at midnight (UTC).
:::

## Additional Services

Enhance your deployment with these optional services to meet specific requirements for networking, storage, and data transfer.

<table className="w-full my-1.5">
  <thead>
    <tr>
      <th className="w-fit whitespace-nowrap"><strong>Service</strong></th>
      <th className="w-fit whitespace-nowrap"><strong>Price</strong></th>
      <th className="w-fit"><strong>Description</strong></th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td className="w-fit whitespace-nowrap"><strong>Dedicated IPv4</strong></td>
      <td className="w-fit whitespace-nowrap"><strong>$3.00</strong> per 30 days</td>
      <td className="w-fit">Exclusive IPv4 address for your project (instead of shared)</td>
    </tr>
    <tr>
      <td className="w-fit whitespace-nowrap"><strong>Object Storage</strong></td>
      <td className="w-fit whitespace-nowrap"><strong>$0.01</strong> per GB / 30 days</td>
      <td className="w-fit">Scalable storage for files, backups, and static assets</td>
    </tr>
  </tbody>
</table>

## Overage Costs

When you exceed the resources included in your project core plan, the following charges apply:

<table className="w-full my-1.5">
  <thead>
    <tr>
      <th className="w-fit whitespace-nowrap"><strong>Item</strong></th>
      <th className="w-fit whitespace-nowrap"><strong>Price</strong></th>
      <th className="w-fit"><strong>Description</strong></th>
    </tr>
  </thead>
  <tbody>
      <tr>
        <td className="w-fit whitespace-nowrap"><strong>Extra Egress</strong></td>
        <td className="w-fit whitespace-nowrap"><strong>$0.02</strong> per GB</td>
        <td className="w-fit">Data transfer out of your project beyond plan limits</td>
      </tr>
    <tr>
      <td className="w-fit whitespace-nowrap"><strong>Extra Backup Space</strong></td>
      <td className="w-fit whitespace-nowrap"><strong>$0.50</strong> per 5 GB</td>
      <td className="w-fit">Additional storage for automatic, encrypted backups</td>
    </tr>
    <tr>
      <td className="w-fit whitespace-nowrap"><strong>Extra Build Time</strong></td>
      <td className="w-fit whitespace-nowrap"><strong>$0.50</strong> per 15 hours</td>
      <td className="w-fit">Additional time for building and deploying applications</td>
    </tr>
  </tbody>
</table>

## Pricing Calculator

Use our pricing calculator to estimate your monthly costs based on your specific needs:


----------------------------------------

# Deno > How To > Build Pipeline


Zerops provides a customizable build and runtime environment for your Deno application.

## Add zerops.yaml to your repository

Start by adding `zerops.yaml` file to the **root of your repository** and modify it to fit your application:

```yaml
zerops:
  # define hostname of your service
  - setup: app
    # ==== how to build your application ====
    build:
      # REQUIRED. Set the base technology for the build environment:
      base: deno@latest

      # OPTIONAL. Set the operating system for the build environment.
      # os: ubuntu

      # OPTIONAL. Customise the build environment by installing additional packages
      # or tools to the base build environment.
      # prepareCommands:
      #   - sudo apt-get something
      #   - curl something else

      # OPTIONAL. Build your application
      buildCommands:
        - deno task build

      # REQUIRED. Select which files / folders to deploy after
      # the build has successfully finished
      deployFiles:
        - dist
        - deno.jsonc

      # OPTIONAL. Which files / folders you want to cache for the next build.
      # Next builds will be faster when the cache is used.
      # cache: directory

    # ==== how to run your application ====
    run:
      # OPTIONAL. Sets the base technology for the runtime environment:
      base: deno@latest

      # OPTIONAL. Sets the internal port(s) your app listens on:
      ports:
        # port number
        - port: 3000

      # OPTIONAL. Customise the runtime Deno environment by installing additional
      # dependencies to the base Deno runtime environment.
      # prepareCommands:
      #   - sudo apt-get something
      #   - curl something else

      # OPTIONAL. Run one or more commands each time a new runtime container
      # is started or restarted. These commands are triggered before
      # your Deno application is started.
      # initCommands:
      #  - rm -rf ./cache

      # REQUIRED. Your Deno application start command
      start: deno task start
```

The top-level element is always `zerops`.

### Setup

The first element `setup` contains the **hostname** of your service. A runtime service with the same hostname must exist in Zerops.
Zerops supports the definition of multiple runtime services in a single `zerops.yaml`. This is useful when you use a monorepo. Just add multiple setup elements in your `zerops.yaml`:

```yaml
zerops:
  # definition for app service
  - setup: app
    # optional
    build: ...
    # optional
    deploy: ...
    # required
    run: ...

  # definition for api service
  - setup: api
    # optional
    build: ...
    # optional
    deploy: ...
    # required
    run: ...
```

Each service configuration contains at least the `run` section. Optional `build` and `deploy` sections can be added to further customize your process.

## Build pipeline configuration

### base

_REQUIRED._ Sets the base technology for the build environment.

Following options are available for Deno builds:

- `deno@2.0.0`, `deno@2`, `deno@latest`
- `deno@1.45.5`, `deno@1`

```yaml
zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build:
      # REQUIRED. Sets the base technology for the build environment:
      base: deno@latest
      ...
```

<p>
  The base build environment contains {data.alpine.default}, the selected
  major version of Deno, [Zerops command line tool](/references/cli), `npm`, `yarn`, `git` and `npx` tools.
</p>

:::info
You can change the base environment when you need to. Just simply modify the `zerops.yaml` in your repository.
:::

If you need to install more technologies to the build environment, set multiple values as a yaml array. For example:

```yaml
zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build:
      # REQUIRED. Sets the base technology for the build environment:
      base:
        - deno@latest
      prepareCommands:
        - zsc add go@latest
      ...
```

See the full list of supported [build base environments](/zerops-yaml/base-list#runtime-services).

To customise your build environment use the [prepareCommands](#preparecommands) attribute.

:::note
Modifying the base technology will invalidate your build cache. See our [Build Cache Documentation](/features/build-cache) for more details about cache invalidation.
:::

### os

_OPTIONAL._ Sets the operating system for the build environment.

Following options are available:

- `alpine`
- `ubuntu`

Default value is `alpine`.

We are currently using following os version:

- <span>{data.alpine.default}</span>
- <span>{data.ubuntu.default}</span>

:::caution
The os version is fixed and cannot be customised.
:::

:::note
Changing the OS setting will invalidate your build cache. See our [Build Cache Documentation](/features/build-cache) for details about cache behavior.
:::

### prepareCommands

_OPTIONAL._ Customises the build environment by installing additional dependencies or tools to the base build environment.

The base build environment contains:

- <span>{data.alpine.default}</span>
- selected version of Deno defined in the [base](#base) attribute
- [Zerops command line tool](/references/cli)
- `npm`, `yarn`, `git` and `npx` tools

To install additional packages or tools add one or more prepare commands:

```yaml
zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build:
      # REQUIRED. Set the base technology for the build environment:
      base: deno@latest

      # OPTIONAL. Customise the build environment by installing additional packages
      # or tools to the base build environment.
      prepareCommands:
        - sudo apt-get something
        - curl something else
      ...
```

When the first build is triggered, Zerops will

1. create a build container
2. download your application code from your repository
3. run the prepare commands in the defined order

The application code is available in `/build/source` before the prepare commands are triggered, so you can use any file from your repository in your prepare commands (e.g. a configuration file). The commands themselves run in the `/home/zerops` directory.

:::note
These commands are skipped when using cached environment. Modifying `prepareCommands` will invalidate your build cache. See our [Build Cache Documentation](/features/build-cache) for details about cache invalidation.
:::

#### Command exit code

If any command fails, it returns an exit code other than 0 and the build is canceled. Read the [build log](/deno/how-to/logs#build-log) to troubleshoot the error. If the command ends successfully, it returns the exit code 0 and Zerops triggers the following command. When all prepare commands are finished, your custom build environment is ready for the build phase.

#### Single or separated shell instances

You can configure your prepare commands to be run in a single shell instance or multiple shell instances. The format is identical to [build commands](#buildcommands).

### buildCommands

_OPTIONAL._ Defines build commands.

```yaml
zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build:
      # REQUIRED. Set the base technology for the build environment:
      base: deno@latest

      # OPTIONAL. Build your application
      buildCommands:
        - deno task build
      ...
```

Build commands are optional. Zerops triggers each command in the defined order in a dedicated build container, running from the `/build/source` directory.

Before the build commands are triggered the build container contains:

1. base environment defined by the [base](#base) attribute
2. optional customisation of the base environment defined in the [prepareCommands](#preparecommands) attribute
3. your application code

#### Run build commands as a single shell instance

Use following syntax to run all commands in the same environment context. For example, if one command changes the current directory, the next command continues in that directory. When one command creates an environment variable, the next command can access it.

```yaml
buildCommands:
  - |
    deno test
    deno task build
```

#### Run build commands as a separate shell instances

When the following syntax is used, each command is triggered in a separate environment context. For example, each shell instance starts in the home directory again. When one command creates an environment variable, it won't be available for the next command.

```yaml
buildCommands:
  - deno task build
```

#### Command exit code

If any command fails, it returns an exit code other than 0 and the build is canceled. Read the [build log](/deno/how-to/logs#build-log) to troubleshoot the error. If the error log doesn't contain any specific error message, try to run your build with the --verbose option.

```yaml
buildCommands:
  - npm i --verbose
  - npm run build
```

If the command ends successfully, it returns the exit code 0 and Zerops triggers the following command. When all `buildCommands` are finished, the application build is completed and ready for the deploy phase.

### deployFiles

_REQUIRED._ Selects which files or folders will be deployed after the build has successfully finished. To filter out specific files or folders, use [`.deployignore`](#deployignore) file.

```yaml
# REQUIRED. Select which files / folders to deploy after
# the build has successfully finished
deployFiles:
  - dist
  - package.json
  - node_modules
```

Determines files or folders produced by your build, which should be deployed to your runtime service containers.

The path starts from the **root directory** of your project (the location of `zerops.yaml`). You must enclose the name in quotes if the folder or the file name contains a space.

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

#### Examples

Deploys a folder, and a file from the project root directory:

```yaml
deployFiles:
  - dist
  - package.json
```

Deploys the whole content of the build container:

```yaml
deployFiles: .
```

Deploys a folder, and a file in a defined path:

```yaml
deployFiles:
  - ./path/to/file.txt
  - ./path/to/dir/
```

#### How to use a wildcard in the path

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

Deploys all folders that are located in any path that begins with `/path/to/`

```yaml
deployFiles: ./path/to/~/
```

Deploys all folders that are located in any path that begins with `/path/` and ends with `/to/`

```yaml
deployFiles: ./path/~/to/
```

:::note Example
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 will be cached for the next build.

```yaml
# OPTIONAL. Which files / folders you want to cache for the next build.
# Next builds will be faster when the cache is used.
cache: file.txt
```

The cache attribute helps optimize build times by preserving specified files between builds.

The cache attribute supports the [~ wildcard character](#how-to-use-a-wildcard-in-the-path).

Learn more about the [build cache system](/features/build-cache) in Zerops.

### envVariables

_OPTIONAL._ Defines the environment variables for the build environment.

Enter one or more env variables in following format:

```yaml
zerops:
  # define hostname of your service
  - setup: app
    # ==== how to build your application ====
    build:
      base: deno@latest
        …

      # OPTIONAL. Defines the env variables for the build environment:
      envVariables:
        NODE_ENV: production
        DB_NAME: db
        DB_HOST: db
        DB_USER: db
        DB_PASS: ${db_password}
```

Read more about [environment variables](/deno/how-to/env-variables) in Zerops.

## Runtime configuration

### base

_OPTIONAL._ Sets the base technology for the runtime environment.
If you don't specify the `run.base` attribute, Zerops keeps the current Deno version for your runtime.

Following options are available for Deno builds:

- `2.0`
- `1.45`

```yaml
zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build:
      # REQUIRED. Sets the base technology for the build environment:
      base: deno@latest
      ...

    # ==== how to run your application ====
    run:
      # OPTIONAL. Sets the base technology for the runtime environment:
        base: deno@latest
      ...
```

<p>
  The base runtime environment contains {data.alpine.default}, the
  selected major version of Deno, Zerops command line tool, `npm`, `yarn`, `git` and `npx` tools.
</p>

:::info
You can change the base environment when you need to. Just simply modify the `zerops.yaml` in your repository.
:::

If you need to install more technologies to the runtime environment, set multiple values as a yaml array. For example:

```yaml
zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build:
      # REQUIRED. Sets the base technology for the build environment:
      base: deno@latest
      ...

    # ==== how to run your application ====
    run:
      # OPTIONAL. Sets the base technology for the runtime environment:
      base:
        - deno@latest
      prepareCommands:
        - zsc add go@latest
      ...
```

See the full list of supported [run base environments](/zerops-yaml/base-list).

To customise your build environment use the `prepareCommands` attribute.

### os

_OPTIONAL._ Sets the operating system for the runtime environment.

Following options are available:

- `alpine`
- `ubuntu`

Default value is `alpine`.

We are currently using following os version:

- <span>{data.alpine.default}</span>
- <span>{data.ubuntu.default}</span>

:::caution
The os version is fixed and cannot be customised.
:::

### ports

_OPTIONAL._ Specifies one or more internal ports on which your application will listen.

Projects in Zerops represent a group of one or more services. Services can be of different types (runtime services, databases, message brokers, object storage, etc.). All services of the same project share a **dedicated private network**. To connect to a service within the same project, just use the service hostname and its internal port.

For example, to connect to a Deno service with hostname = "app" and port = 3000 from another service of the same project, simply use `app:3000`. Read more about [how to access a Deno service](/references/networking/internal-access#basic-service-communication).

Each port has following attributes:

| parameter   | description                                                                                                                                                                                                                                                                                                            |
| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| port        | Defines the port number. You can set any port number between _10_ and _65435_. Ports outside this interval are reserved for internal Zerops systems.                                                                                                                                                                   |
| protocol    | **Optional.** Defines the protocol. Allowed values are `TCP` or `UDP`. Default value is `TCP`.                                                                                                                                                                                                                         |
| httpSupport | **Optional.** `httpSupport = true` is the default setting for TCP protocol. Set `httpSupport = false` if a web server isn't running on the port. Zerops uses this information for the configuration of [public access](/features/access). `httpSupport = true` is available only in combination with the TCP protocol. |
| httpSupport | **Optional.** `httpSupport = true` is the default setting for TCP protocol. Set `httpSupport = false` if a web server isn't running on the port. Zerops uses this information for the configuration of [public access](/features/access). `httpSupport = true` is available only in combination with the TCP protocol. |

### prepareCommands

_OPTIONAL._ Customises the Deno runtime environment by installing additional dependencies or tools to the runtime base environment.

<p>
  The base Deno environment contains {data.alpine.default} the selected
  major version of Deno, [Zerops command line tool](/references/cli) and `npm`, `yarn`, `git` and `npx` tools. To install
  additional packages or tools add one or more prepare commands:
</p>

```yaml
zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build:
      ...

    # ==== how to run your application ====
    run:
      # OPTIONAL. Customise the runtime environment by installing additional packages
      # or tools to the base Deno runtime environment.
      prepareCommands:
        - sudo apt-get something
        - curl something else
      ...
```

When the first deploy with a defined prepare attribute is triggered, Zerops will

1. create a prepare runtime container
2. optionally: [copy selected folders or files from your build container](#copy-folders-or-files-from-your-build-container)
3. run the `prepareCommands` commands in the defined order

:::note
`run.prepareCommands` run in the `/home/zerops` directory.
:::

#### Command exit code

If any command fails, it returns an exit code other than 0 and the deploy is canceled. Read the [prepare runtime log](/deno/how-to/logs#prepare-runtime-log) to troubleshoot the error. If the command ends successfully, it returns the exit code 0 and Zerops triggers the following command. When all `prepareCommands` commands are finished, your custom runtime environment is ready for the deploy phase.

#### Cache of your custom runtime environment

Some packages or tools can take a long time to install. Therefore, Zerops caches your custom runtime environment after the installation of your custom packages or tools is completed. When the second or following deploy is triggered, Zerops will use the custom runtime cache from the previous deploy if following conditions are met:

1. Content of the [build.addToRunPrepare](#copy-folders-or-files-from-your-build-container) and `run.prepareCommands` attributes didn't change from the previous deploy
2. The custom runtime cache wasn't invalidated in the Zerops GUI.

To invalidate the custom runtime cache go to `yyy`

When the custom runtime cache is used, Zerops doesn't create a prepare runtime container and executes the deployment of your application directly.

#### Single or separated shell instances

You can configure your prepare commands to be run in a single shell instance or multiple shell instances. The format is identical to [build commands](#buildcommands).

### Copy folders or files from your build container

<p>
  The prepare runtime container contains {data.alpine.default}, the
  selected major version of Deno, [Zerops command line tool](/references/cli) and `npm`, `yarn`, `git` and `npx` tools.
</p>

The prepare runtime container does not contain your application code nor the built application. If you need to copy some folders or files from the build container to the runtime container (e.g. a configuration file) use the `addToRunPrepare` attribute in the [build section](#build-pipeline-configuration).

```yaml
zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build:
      ...
      addToRunPrepare: ./runtime-config.yaml

    # ==== how to run your application ====
    run:
      # OPTIONAL. Customise the runtime environment by installing additional packages
      # or tools to the base Deno runtime environment.
      prepareCommands:
        - sudo apt-get something
        - curl something else
      ...
```

In the example above Zerops will copy the `runtime-config.yaml` file from your build container **after the build has finished** into the new **prepare runtime** container. The copied files and folders will be available in the `/home/zerops` folder in the new prepare runtime container before the prepare commands are triggered.

### initCommands

_OPTIONAL._ Defines one or more commands to be run each time a new runtime container is started or a container is restarted.

```yaml
zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build: ...

    # ==== how to run your application ====
    run:
      # OPTIONAL. Run one or more commands each time a new runtime container
      # is started or restarted. These commands are triggered before
      # your Deno application is started.
      initCommands:
        - rm -rf ./cache
```

These commands are triggered in the runtime container before your Deno application is started via the [start command](#start).

:::note
`run.initCommands` run in the `/var/www` directory.
:::

Use init commands to clean or initialise your application cache or similar operations.

:::caution
The init commands will delay the start of your application each time a new runtime container is started (including the horizontal [scaling](/deno/how-to/scaling) or when a runtime container is restarted).

Do not use the init commands for customising your runtime environment. Use the [run:prepareCommands](#preparecommands-1) attribute instead.
:::

#### Command exit code

If any of the `initCommands` fails, it returns an exit code other than 0, but deploy is **not** canceled. After all init commands are finished, regardless of the status code, the application is started. Read the [runtime log](/deno/how-to/logs#runtime-log) to troubleshoot the error.

#### Single or separated shell instances

You can configure your `initCommands` to be run in a single shell instance or multiple shell instances. The format is identical to [build commands](#buildcommands).

### envVariables

_OPTIONAL._ Defines the environment variables for the runtime environment.

Enter one or more env variables in following format:

```yaml
zerops:
  # define hostname of your service
  - setup: app
    # ==== how to run your application ====
    run:
      # OPTIONAL. Defines the env variables for the runtime environment:
      envVariables:
        NODE_ENV: production
        DB_NAME: db
        DB_HOST: db
        DB_USER: db
        DB_PASS: ${db_password}
```

Read more about [environment variables](/deno/how-to/env-variables) in Zerops.

### start

_REQUIRED._ Defines the start command for your Deno application.

```yaml
zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build: ...

    # ==== how to run your application ====
    run:
      # REQUIRED. Your Deno application start command
      start: deno task start
```

We recommend starting your Deno application using `deno task start`.

### health check

_OPTIONAL._ Defines a health check.

`healthCheck` requires either one `httpGet` object or one `exec` object.

#### httpGet

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

Following attributes are available:

<table className="w-full my-1.5">
  <thead>
    <tr>
      <th className="w-fit whitespace-nowrap">Parameter</th>
      <th className="w-fit whitespace-nowrap">Description</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td className="w-fit whitespace-nowrap font-semibold">port</td>
      <td>Defines the port of the HTTP GET request.
The readiness check will trigger a GET request on <code>{'http://127.0.0.1:{port}/{path}'}</code></td>
    </tr>
    <tr>
      <td className="w-fit whitespace-nowrap font-semibold">path</td>
      <td>Defines the URL path of the HTTP GET request.
The readiness check will trigger a GET request on <code>{'http://127.0.0.1:{port}/{path}'}</code></td>
    </tr>
    <tr>
      <td className="w-fit whitespace-nowrap font-semibold">host</td>
      <td><strong>Optional.</strong> The readiness check is triggered from inside of your runtime container so it always uses the localhost <code>127.0.0.1</code>. If you need to add a <code>host</code> to the request header, specify it in the <code>host</code> attribute.</td>
    </tr>
    <tr>
      <td className="w-fit whitespace-nowrap font-semibold">scheme</td>
      <td><strong>Optional.</strong> The readiness check is triggered from inside of your runtime container so no https is required.
If your application requires a https request, set <code>scheme: https</code></td>
    </tr>
  </tbody>
</table>

**Example:**

```yaml
zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build: ...

    # ==== how to run your application ====
    run:
      # REQUIRED. Your Deno application start command
      start: deno task start

      # OPTIONAL. Define a health check with a HTTP GET request option.
      # Configures the check on http://127.0.0.1:80/status
      healthCheck:
        httpGet:
          port: 80
          path: /status
```

#### exec

Configures the health check to run a local command.
Following attributes are available:

| Parameter   | Description                                                                                                                                                                                                                                                                                                                     |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **command** | Defines a local command to be run.
The command has access to the same [environment variables](/deno/how-to/create#set-secret-environment-variables) as your Deno application.
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 below. |

**Example:**

```yaml
zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build: ...

    # ==== how to run your application ====
    run:
      # REQUIRED. Your Deno application start command
      start: deno task start

      # OPTIONAL. Define a health check with a shell command.
      healthCheck:
        exec:
          command: |
            touch grass
            rm -rf life
            mv /outside/user /home/user
```

### crontab

_OPTIONAL._ Defines cron jobs.

Setup cron jobs in the following format:

```yaml
zerops:
  # define hostname of your service
  - setup: app

    # ==== how to run your application ====
    run:
      crontab:
        # REQUIRED. Sets the command to execute:
        - command: ""
        # REQUIRED. Sets the interval time to execute:
          timing: "0 * * * *"
```

Read more about setting up [cron](/zerops-yaml/cron) in Zerops.

## Deploy configuration

### readiness check

_OPTIONAL._ Defines a readiness check. Read more about how the [readiness check works](/deno/how-to/deploy-process#readiness-checks) in Zerops.

`readinessCheck` requires either one `httpGet` object or one `exec` object.

#### httpGet

Configures the readiness check to request a local URL using a http GET method.

Following attributes are available:

<table className="w-full my-1.5">
  <thead>
    <tr>
      <th className="w-fit whitespace-nowrap">Parameter</th>
      <th className="w-fit whitespace-nowrap">Description</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td className="w-fit whitespace-nowrap font-semibold">port</td>
      <td>Defines the port of the HTTP GET request.
The readiness check will trigger a GET request on <code>{'http://127.0.0.1:{port}/{path}'}</code></td>
    </tr>
    <tr>
      <td className="w-fit whitespace-nowrap font-semibold">path</td>
      <td>Defines the URL path of the HTTP GET request.
The readiness check will trigger a GET request on <code>{'http://127.0.0.1:{port}/{path}'}</code></td>
    </tr>
    <tr>
      <td className="w-fit whitespace-nowrap font-semibold">host</td>
      <td><strong>Optional.</strong> The readiness check is triggered from inside of your runtime container so it always uses the localhost <code>127.0.0.1</code>. If you need to add a <code>host</code> to the request header, specify it in the <code>host</code> attribute.</td>
    </tr>
    <tr>
      <td className="w-fit whitespace-nowrap font-semibold">scheme</td>
      <td><strong>Optional.</strong> The readiness check is triggered from inside of your runtime container so no https is required.
If your application requires a https request, set <code>scheme: https</code></td>
    </tr>
  </tbody>
</table>

**Example:**

```yaml
zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build: ...

    # ==== how to deploy your application ====
    deploy:
      # OPTIONAL. Define a readiness check with a HTTP GET request option.
      # Configures the check on http://127.0.0.1:80/status
      readinessCheck:
        httpGet:
          port: 80
          path: /status

    # ==== how to run your application ====
    run: ...
```

Read more about how the [readiness check works](/deno/how-to/deploy-process#readiness-checks) in Zerops.

#### exec

Configures the readiness check to run a local command.
Following attributes are available:

| Parameter   | Description                                                                                                                                                                                                                                                                                                                     |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **command** | Defines a local command to be run.
The command has access to the same [environment variables](/deno/how-to/create#set-secret-environment-variables) as your Deno application.
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 below. |

**Example:**

```yaml
zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build: ...

    # ==== how to deploy your application ====
    deploy:
      # OPTIONAL. Define a readiness check with a HTTP GET request option.
      # Configures the check on http://127.0.0.1:80/status
      readinessCheck:
        exec:
          command: |
            touch grass
            rm -rf life
            mv /outside/user /home/user
```

Read more about how the [readiness check works](/deno/how-to/deploy-process#readiness-checks) in Zerops.


----------------------------------------

# Deno > How To > Build Process


## Build process overview

Zerops starts a temporary build container and performs the following actions:

1. **Installs the build environment** - Sets up base system and Deno runtime
2. **Downloads your application source code** - From [GitHub ↗](https://www.github.com), [GitLab ↗](https://www.gitlab.com) or via [Zerops CLI](/references/cli)
3. **Optionally customizes the build environment** - Runs prepare commands if configured
4. **Runs the build commands** - Executes your build process
5. **Uploads the application artifact** - Stores build output to internal Zerops storage
6. **Caches selected files** - Preserves specified files for faster future builds

The build container is automatically deleted after the build has finished or failed.

## Build configuration

Configure your Deno build process in your `zerops.yaml` file according to the [full build & deploy Deno pipeline guide](/deno/how-to/build-pipeline).

## Build environment

### Default Deno build environment

The default Deno build environment contains:

- <span>{data.ubuntu.default}</span>
- Selected version of Deno defined in `zerops.yaml` [build.base](/deno/how-to/build-pipeline#base) parameter
- [zCLI](/references/cli), Zerops command line tool
- Deno and Git

### Customize build environment

To install additional packages or tools, add one or more [build.prepareCommands](/deno/how-to/build-pipeline#preparecommands) to your `zerops.yaml`.

:::info
The application code is available in the `/build/source` folder in your build container before the prepare commands are triggered. This allows you to use any file from your application code in your prepare commands (e.g. a configuration file).
:::

### Build hardware resources

All runtime services use the same hardware resources for build containers:

<table className="w-fit my-1.5">
  <thead>
    <tr className="text-center rounded-lg">
      <th className="w-fit"><strong>HW resource</strong></th>
      <th className="w-fit"><strong>Minimum</strong></th>
      <th className="w-fit"><strong>Maximum</strong></th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td className="w-fit font-semibold">CPU cores</td>
      <td className="w-fit">1</td>
      <td className="w-fit">5</td>
    </tr>
    <tr>
      <td className="w-fit font-semibold">RAM</td>
      <td className="w-fit">8 GB</td>
      <td className="w-fit">8 GB</td>
    </tr>
    <tr>
      <td className="w-fit font-semibold">Disk</td>
      <td className="w-fit">1 GB</td>
      <td className="w-fit">100 GB</td>
    </tr>
  </tbody>
</table>

Build containers start with minimum resources and scale vertically up to maximum capacity as needed.

:::info
Build container resources are not charged separately. Limited build time is included in your [project core plan](/company/pricing#project-core-plans), with additional build time available if needed.
:::

### Build time limit

The time limit for the whole build pipeline is **1 hour**. After 1 hour, Zerops will terminate the build pipeline and delete the build container.

## Troubleshooting Deno builds

### Build command failures

If any [build command](/deno/how-to/build-pipeline#buildcommands) fails (returns non-zero exit code), the build is canceled. Check the [build log](/deno/how-to/logs#build-log) to troubleshoot the error.

For Deno, if the error log doesn't contain specific error messages, try running your build with verbose output:

```yaml
buildCommands:
  - deno cache main.ts
  - deno compile --allow-net --allow-read main.ts
```

### Prepare command failures

If any [prepare command](/deno/how-to/build-pipeline#preparecommands) fails, check the [build log](/deno/how-to/logs#build-log) for specific error messages. Common issues include:

- Missing permissions in Deno commands (add --allow-net, --allow-read, etc.)
- Ubuntu package installation failures (use sudo apt-get update first)
- Deno cache directory permissions

### Build cache issues

If you encounter unexpected build behavior or dependency issues, the problem might be related to [cached build data](/features/build-cache). While Zerops maintains the build cache to speed up deployments, sometimes you may need to start fresh.

To invalidate the build cache:

1. Go to your service detail in Zerops GUI
2. Choose **Pipelines & CI/CD Settings** from the left menu
3. Click on the **Invalidate build cache** button

This will force Zerops to run the next build clean, including all prepare commands. Learn more about [build cache behavior](/features/build-cache).

:::tip Advanced troubleshooting
For complex build issues that require investigation, you can enable [debug mode](/features/debug-mode) to pause the build process at specific points and inspect the build container state interactively.
:::

## More resources

For more details about the build and deploy pipeline, including how to cancel builds and manage application versions, see the [general pipeline documentation](/features/pipeline).

## Next steps

- Understand the [deployment process](/deno/how-to/deploy-process)
- Learn how to [customize the runtime environment](/deno/how-to/customize-runtime)
- Explore [build and runtime logs](/deno/how-to/logs)

----------------------------------------

# Deno > How To > Controls



----------------------------------------

# Deno > How To > Create


Zerops provides a powerful Deno runtime service with extensive build support. The Deno runtime is highly scalable and customizable to suit your development and production needs. With just a few clicks or commands, you can have a production-ready Deno environment up and running in no time.

## Create a Deno service using Zerops GUI

First, set up a project in the Zerops GUI. Then go to the project dashboard page and choose **Add new service** in the left menu under the **Services** section. From there, you can add a new Deno service:

[Video: /vids/services/deno.webm](/vids/services/deno.webm)

### Choose a Deno version

Zerops supports the following Deno versions:

:::info
You can easily [upgrade](/deno/how-to/upgrade) the major version at any time later.
:::

### Set a hostname

Enter a unique service identifier like "app", "cache", "gui", etc. Duplicate services with the same name within the same project are not allowed.

#### Limitations:

- Maximum 25 characters
- Must contain only lowercase ASCII letters (a-z) or numbers (0-9)

:::caution
The hostname is fixed after the service is created and cannot be changed later.
:::

### Set secret environment variables

Add environment variables with sensitive data, such as passwords, tokens, salts, certificates, etc. These will be securely saved inside Zerops and added to your runtime service upon start.

Setting secret environment variables is optional. You can always set them later in the Zerops GUI.

Read more about the [different types of environment variables](/deno/how-to/env-variables#service-env-variables) in Zerops.

## Create a Deno service using zCLI

zCLI is the Zerops command-line tool. To create a new Deno service via the command line, follow these steps:

1. [Install & setup zCLI](/references/cli)
2. [Create a project description file](/deno/how-to/create#create-a-project-description-file)
3. [Create a project with a Deno and PostgreSQL service](#full-example)

### Create a project description file

Zerops uses a YAML format to describe the project infrastructure.

#### Basic example:

Create a directory called `my-project`. Inside the `my-project` directory, create a `description.yaml` file with the following content:
```yaml
# basic project data
project:
  # project name
  name: my-project
# array of project services
services:
  - # service name
    hostname: app
    # service type and version number in deno@{version} format
    type: deno@latest
    # defines the minimum number of containers for horizontal autoscaling
    minContainers: 1
    # defines the maximum number of containers for horizontal autoscaling. Max value = 6.
    maxContainers: 6
    # optional: create env variables
    envSecrets:
      S3_ACCESS_KEY_ID: 'P8cX1vVVb'
      S3_ACCESS_SECRET: 'ogFthuiLYki8XoL73opSCQ'
```

The yaml file describes your future project infrastructure. The project will contain one Deno version 20 service with default [auto scaling](/deno/how-to/scaling) configuration. Hostname will be set to "app", the internal port(s) the service listens on will be defined later in the [zerops.yaml](/deno/how-to/build-pipeline#ports). Following secret env variables will be configured:

```env
S3_ACCESS_KEY_ID="P8cX1vVVb"
S3_ACCESS_SECRET="ogFthuiLYki8XoL73opSCQ"
```

#### Full example:

Create a directory my-project. Create an description.yaml file inside the my-project directory with following content:

```yaml
# basic project data
project:
  # project name
  name: my-project
  # optional: project description
  description: A project with a Deno and PostgreSQL database
  # optional: project tags
  tags:
    - DEMO
    - ZEROPS
# array of project services
services:
  - # service name
    hostname: app
    # service type and version number in deno@{version} format
    type: deno@latest
    # optional: vertical auto scaling customization
    verticalAutoscaling:
      cpuMode: DEDICATED
      minCpu: 2
      maxCpu: 5
      minRam: 2
      maxRam: 24
      minDisk: 6
      maxDisk: 50
      startCpuCoreCount: 3
      minFreeRamGB: 0.5
      minFreeRamPercent: 20
    # defines the minimum number of containers for horizontal autoscaling. Max value = 6.
    minContainers: 2
    # defines the maximum number of containers for horizontal autoscaling. Max value = 6.
    maxContainers: 4
    # optional: create env variables
    envSecrets:
      S3_ACCESS_KEY_ID: 'P8cX1vVVb'
      S3_ACCESS_SECRET: 'ogFthuiLYki8XoL73opSCQ'
  - # second service hostname
    hostname: db
    # service type and version number in postgresql@{version} format
    type: postgresql@12
    # mode of operation "HA"/"non_HA"
    mode: NON_HA
```

The yaml file describes your future project infrastructure. The project will contain a Deno service and a [PostgreSQL](/postgresql/overview) service.

Deno service with "app" hostname, the internal port(s) the service listens on will be defined later in the [zerops.yaml](/deno/how-to/build-pipeline#ports). Deno service will run on version 20 with a custom vertical and horizontal scaling. Following secret env variables will be configured:

```env
S3_ACCESS_KEY_ID="P8cX1vVVb"
S3_ACCESS_SECRET="ogFthuiLYki8XoL73opSCQ"
```

The hostname of the PostgreSQL service will be set to "db". The [single container](/features/scaling#single-container-mode)(/features/scaling#deployment-modes-databases-and-shared-storage) mode will be chosen and the default auto [scaling configuration](/postgresql/how-to/scale#configure-scaling) will be set.

#### Description of description.yaml parameters

The `project:` section is required. Only one project can be defined.

| Parameter       | Description                                                                                                                     | Limitations             |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------- | ----------------------- |
| **name**        | The name of the new project. Duplicates are allowed.                                                                            |                         |
| **description** | **Optional.** Description of the new project.                                                                                   | Maximum 255 characters. |
| **tags**        | **Optional.** One or more string tags. Tags do not have a functional meaning, they only provide better orientation in projects. |
| **tags**        | **Optional.** One or more string tags. Tags do not have a functional meaning, they only provide better orientation in projects. |

At least one service in `services:` section is required. You can create a project with multiple services. The example above contains Deno and PostgreSQL services but you can create a `description.yaml` with your own combination of [services](/features/infrastructure).

<table className="w-full my-1.5">
  <thead>
    <tr>
      <th className="w-fit">Parameter</th>
      <th className="w-fit">Description</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td className="w-fit">
        <b>hostname</b>
      </td>
      <td className="w-fit">
        The unique service identifier.
        <ul>
        <li>duplicate services with the same name in the same project are forbidden</li>
        <li>maximum 25 characters</li>
        <li>must contain only lowercase ASCII letters (a-z) or numbers (0-9)</li>
        </ul>
      </td>
    </tr>
    <tr>
      <td className="w-fit">
        <b>type</b>
      </td>
      <td className="w-fit">
        Specifies the service type and version.

        See what [Deno service types](/references/import-yaml/type-list#runtime-services) are currently supported.
      </td>
    </tr>
    <tr>
      <td className="w-fit">
        <b>verticalAutoscaling</b>
      </td>
      <td className="w-fit">
        <b>Optional.</b> Defines [custom vertical auto scaling parameters](/deno/how-to/create#set-auto-scaling-configuration).

        All verticalAutoscaling attributes are optional. Not specified
        attributes will be set to their default values.
      </td>
    </tr>
    <tr>
      <td className="w-fit">
        <b> - cpuMode</b>
      </td>
      <td className="w-fit">
        <b>Optional.</b> Accepts `SHARED`, `DEDICATED` values. Default is `SHARED`
      </td>
    </tr>
    <tr>
      <td className="w-fit">
        <b> - minCpu/maxCpu</b>
      </td>
      <td className="w-fit">
        <b>Optional.</b> Set the minCpu or maxCpu in CPU cores (integer).
      </td>
    </tr>
    <tr>
      <td className="w-fit">
        <b> - minRam/maxRam</b>
      </td>
      <td className="w-fit">
        <b>Optional.</b> Set the minRam or maxRam in GB (float).
      </td>
    </tr>
    <tr>
      <td className="w-fit">
        <b> - minDisk/maxDisk</b>
      </td>
      <td className="w-fit">
        <b>Optional.</b> Set the minDisk or maxDisk in GB (float).
      </td>
    </tr>
    <tr>
      <td className="w-fit">
        <b>minContainers</b>
      </td>
      <td className="w-fit">
        <b>Optional.</b> Default = 1. Defines the minimum number of containers
        for [horizontal autoscaling](/deno/how-to/create#horizontal-auto-scaling).

        <b>Limitations:</b>

        Current maximum value = 10.
      </td>
    </tr>
    <tr>
      <td className="w-fit">
        <b>maxContainers</b>
      </td>
      <td className="w-fit">
        Defines the maximum number of containers for [horizontal autoscaling](/deno/how-to/create#horizontal-auto-scaling).

        <b>Limitations:</b>

        Current maximum value = 10.
      </td>
    </tr>
    <tr>
      <td className="w-fit">
        <b>envSecrets</b>
      </td>
      <td className="w-fit">
        <b>Optional.</b> Defines one or more secret env variables as a key value
        map. See env variable [restrictions](/deno/how-to/env-variables#env-variable-restrictions).
      </td>
    </tr>
  </tbody>
</table>

### Create a project based on the description.yaml

When you have your `description.yaml` ready, use the `zcli project project-import` command to create a new project and the service infrastructure.

```sh
Usage:
  zcli project project-import importYamlPath [flags]

Flags:
  -h, --help                Help for the project import command.
      --org-id string        If you have access to more than one organization, you must specify the org ID for which the
                            project is to be created.
      --working-dir string   Sets a custom working directory. Default working directory is the current directory. (default "./")
```

Zerops will create a project and one or more services based on the `description.yaml` content.

Maximum size of the `description.yaml` file is 100 kB.

You don't specify the project name in the `zcli project project-import` command, because the project name is defined in the `description.yaml`.

If you have access to more than one client, you must specify the client ID for which the project is to be created. The `clientID` is located in the Zerops GUI under the client name on the project dashboard page.

### Add Deno service to an existing project

#### Example:

Create a directory `my-project` if it doesn't exist. Create an `import.yaml` file inside the `my-project` directory with following content:

```yaml
# basic project data
project:
  # project name
  name: my-project
# array of project services
services:
  - # service name
    hostname: app
    # service type and version number in deno@{version} format
    type: deno@latest
    # defines the minimum number of containers for horizontal autoscaling
    minContainers: 1
    # defines the maximum number of containers for horizontal autoscaling. Max value = 6.
    maxContainers: 6
    # optional: create env variables
    envSecrets:
      S3_ACCESS_KEY_ID: 'P8cX1vVVb'
      S3_ACCESS_SECRET: 'ogFthuiLYki8XoL73opSCQ'
```

The yaml file describes the list of one or more services that you want to add to your existing project. In the example above, one Deno service version 20 with default [auto scaling](/deno/how-to/scaling) configuration will be added to your project. Hostname of the new service will be set to `app`. Following secret env variables will be configured:

```env
S3_ACCESS_KEY_ID="P8cX1vVVb"
S3_ACCESS_SECRET="ogFthuiLYki8XoL73opSCQ"
```

The content of the `services:` section of `import.yaml` is identical to the project description file. The `import.yaml` never contains the `project:` section because the project already exists.

When you have your `import.yaml` ready, use the `zcli project service-import` command to add one or more services to your existing Zerops project.

```sh
Usage:
  zcli project service-import importYamlPath [flags]

Flags:
  -h, --help                Help for the project service import command.
  -P, --project-id string   If you have access to more than one project, you must specify the project ID for which the
                           command is to be executed.
```

zCLI commands are interactive, when you press enter after `zcli project service-import importYamlPath`, you will be given a list of your projects to choose from.

Maximum size of the import.yaml file is 100 kB.


----------------------------------------

# Deno > How To > Customize Runtime


## Build Custom Runtime Images

Zerops allows you to build custom runtime images (CRI) when the default base runtime images don't meet your Deno application's requirements. This is an optional phase in the [build and deploy pipeline](/features/pipeline#runtime-prepare-phase-optional).

:::important
You should not include your application code in the custom runtime image, as your built/packaged code is deployed automatically into fresh containers.
:::

## Configuration

### Default Deno Runtime Environment

The default Deno runtime environment contains:

- <span>{data.ubuntu.default}</span>
- Selected version of Deno when the runtime service was created
- [zCLI](/references/cli)
- Deno and Git

### When You Need a Custom Runtime Image

If your Deno application needs more than what's included in the default environment, you'll need to build a custom runtime image. Common scenarios include:

- **System packages for processing**: When your app processes images, videos, or files (requiring packages like `sudo apt-get install -y imagemagick`)
- **Global Deno tools**: When you need CLI tools or utilities available system-wide
- **Native dependencies**: When your Deno modules require system libraries that aren't in the default environment

Here are Deno-specific examples of configuring custom runtime images in your `zerops.yml`:

### Basic Deno Setup

### Using Build Files in Runtime Preparation

```yaml
build:
  addToRunPrepare:
    - deno.json
    - import_map.json
run:
  prepareCommands:
    - sudo apt-get update
    - sudo apt-get install -y imagemagick
    - deno cache deps.ts
```

For complete configuration details, see the [runtime prepare phase configuration guide](/features/pipeline#configuration).

## Process and Caching

### How Runtime Prepare Works
The runtime prepare process follows the same steps for all runtimes. See [how runtime prepare works](/features/pipeline#how-it-works) for the complete process details.

### Caching Behavior
Zerops caches custom runtime images to optimize deployment times. Learn about [custom runtime image caching](/features/pipeline#custom-runtime-image-caching) including when images are cached and reused.

### Build Management
For information about managing builds and deployments, see [managing builds and deployments](/features/pipeline#manage-builds-and-deployments).

:::warning
Shared storage mounts are not available during the runtime prepare phase.
:::

## Troubleshooting

If your `prepareCommands` fail, check the [prepare runtime log](/deno/how-to/logs#prepare-runtime-log) for specific error messages.

----------------------------------------

# Deno > How To > Deploy Process



----------------------------------------

# Deno > How To > Env Variables



----------------------------------------

# Deno > How To > Filebrowser



----------------------------------------

# Deno > How To > Logs



----------------------------------------

# Deno > How To > Scaling



----------------------------------------

# Deno > How To > Shared Storage



----------------------------------------

# Deno > How To > Trigger Pipeline



----------------------------------------

# Deno > How To > Upgrade



----------------------------------------

# Deno > Overview


[Deno ↗](https://deno.org/en) is an asynchronous event-driven JavaScript runtime, which is designed to build scalable network applications.

:::tip
Have you got any additional question? Join our **[Discord](https://discord.com/invite/WDvCZ54)** community to get help from our team and other members.
:::

As said, there is no need for coding yet, we have created a [Github repository ↗](https://github.com/zeropsio/recipe-deno), a **_recipe_**, containing the most simple Deno web application. The repo will be used as a source from which the app will be built.

### 🚀 No Fuss, Just Deploy with Speed!

This is the most bare-bones example of Deno app running in Zerops — as few libraries as possible,
  just a simple endpoint with connect, read and write to a Zerops PostgreSQL database.

  [Deploy "deno" recipe on Zerops](https://app.zerops.io/recipe/?lf=deno)

1. Log in/sign up to [Zerops GUI ↗](https://app.zerops.io)

2. In the **Projects** box click on **Import a project** and paste in the following YAML config ([source ↗](https://github.com/zeropsio/recipe-deno/blob/main/zerops-project-import.yaml)):

```yaml
project:
  name: recipe-deno
  tags:
    - zerops-recipe

services:
  - hostname: api
    type: deno@1
    buildFromGit: https://github.com/zeropsio/recipe-deno
    enableSubdomainAccess: true

  - hostname: db
    type: postgresql@16
    mode: NON_HA
    priority: 1
```

3. Click on **Import project** and wait until all pipelines have finished.

**That's it, your application is now up and running! :star: Let's check it works:**

1. A _subdomain_ should have been enabled and visible in the project's **IP addressed & Public Routing Overview** box. Its format should look similar to this `https://api-7f6-8000.prg1.zerops.app`.
2. Click or the `subdomain` URL to open it in a browser and you should see

```
{"message":"This is a simple, basic Deno / Oak application running in Zerops.io,\n      each request adds an entry to the PostgreSQL database and returns a count.\n      See the source repository (https://github.com/zeropsio/recipe-deno) for more information.","newEntry":"274b0cc1-5b6d-4351-b8ec-53cf82bd9d0f","count":1}
```

:::tip
Do you have any questions? Check the step-by-step tutorial, browse the documentation and join our **[Discord](https://discord.com/invite/WDvCZ54)** community to get help from our team and other members.
:::

## How to start

It doesn't matter whether it's your first curious introduction to Zerops, you have already mastered the basics and are looking for a tiny detail or inspiration. Below, choose a section that fits your needs:

- [Care for details?](/deno/how-to/create) — Dive in all Zerops has to offer for your Deno application.
- [Deno recipes](https://github.com/zeropsio?q=deno&type=all&language=&sort=) — Get inspired by already existing repositories, ready to be imported to Zerops.

## Feature Highlights

- [Create Deno service](/deno/how-to/create) — Start with creating a Deno service using GUI or zCLI.
- [Zerops.yaml](/deno/how-to/build-pipeline#add-zeropsyaml-to-your-repository) — See a full example of zerops.yaml file to create your own app.
- [Scaling configuration](/deno/how-to/scaling) — Set up scaling of your Deno application so that it runs smoothly while using only necessary resources.

{" "}

- [Customize build environment](/deno/how-to/build-process#customize-build-environment)
- [Customize runtime environment](/deno/how-to/customize-runtime)

## When in doubt, reach out

Don't know how to start or got stuck during the process? You might not be the first one, visit the FAQ section to find out.

In case you haven't found an answer (and also if you have), we and our community are looking forward to hearing from you on Discord.

Have you build something that others might find useful? Don't hesitate to share your knowledge!

- [Discord](https://discord.com/invite/WDvCZ54) — Join our core team and Zerops community on Discord. Ask questions and share your tips with other members.

## Popular Guides

- [zCLI](/references/cli) — Get even more out of Zerops with the zCLI command line tool.
- [Zerops VPN](/references/networking/vpn) — Connect to your services easily with Zerops VPN.


----------------------------------------

# Docker > Overview


Zerops provides Docker support through dedicated Virtual Machine (VM) environments, ensuring maximum compatibility and isolation while maintaining integration with the broader Zerops ecosystem. This guide explains how to effectively use Docker services in Zerops, including best practices and important considerations.

## Why VMs

While Zerops primarily uses native Linux containers for optimal performance, this VM-based approach allows you to run virtually any Docker container while maintaining Zerops' robust infrastructure management.

You can learn more about [differences](/features/container-vs-vm) between Containers and Virtual Machines in Zerops.

Before using Docker services, consider these important aspects:

### Virtual Machine Environment

Docker services in Zerops operate in a full VM environment, which has several implications:

- **Slower Boot Times**: VMs require more time to initialize due to full kernel boot
- **Higher Resource Usage**: VMs include additional system overhead compared to native containers
- **Scaling Limitations**:
    - Vertical scaling requires VM restart
    - Resources must be set as fixed values (no min-max ranges)
    - Zerops automatically restarts the VM when resource values are changed in UI
- **Storage Management**: Disk space can only be increased, not decreased without recreation
- **Build Phase Limitations**: Build phase runs in containers, not in the VM environment

### Advantages

Despite these limitations, Docker services offer some benefits:

- **Broad Compatibility**: Run almost any Docker container with minimal modification
- **Familiar Environment**: Standard Docker runtime environment

## Configuration Guide

### Supported Version

Currently supported Docker versions:

### Basic Structure

Docker services in Zerops are configured through the `zerops.yaml` file. Here's a typical configuration pattern:

```yaml title="zerops.yaml"
zerops:
  - setup: app
    run:
      base: docker@latest
      prepareCommands:
        - docker image pull <your-image>:<version>  # Always use specific version tags
      start: docker run --network=host <your-image>:<version>
      ports:
        - port: <port-number>
          httpSupport: true
```

:::important
Always use specific version tags (like `1.0.0`) instead of `:latest`. Zerops caches the `prepareCommands` output, which means a new `:latest` image won't be automatically pulled on subsequent deployments unless the cache is manually cleared or the commands change.
:::

Refer to the [Docker recipe repository](https://github.com/zeropsio/recipe-docker) for an example configuration.

:::note
We are actively working on improving the speed of image caching after `run.prepareCommands` and reducing the startup time of runtime VMs. These improvements will be released in future updates.
:::

### Network Configuration

Docker services require the `--network=host` flag for proper integration with Zerops:

- **Direct Port Management**: Ports are managed through `zerops.yaml`
- **Simplified Configuration**: Avoids double port exposure in Docker and Zerops
- **Native Performance**: Direct access to host networking

### Docker Compose Support

For projects using Docker Compose, additional configuration is required:

1. **File Deployment**:
   ```yaml title="zerops.yaml"
   build:
     # base cannot be docker — build phase runs in containers, not VMs
     deployFiles: ./docker-compose.yaml
     addToRunPrepare: ./docker-compose.yaml
   ```

2. **Network Mode**:
   ```yaml title="docker-compose.yaml"
   services:
     your-service:
       image: your-image:1.0.0
       network_mode: host
   ```

3. **Start Command**:
   ```yaml title="zerops.yaml"
   run:
     start: docker compose up --force-recreate
   ```

### Environment Variables

When using Docker services, there's an additional layer to consider since environment variables defined in Zerops must be explicitly passed to your Docker containers.

#### 1. Defining Variables in Zerops

Define your environment variables in the `run.envVariables` section of your `zerops.yaml` (example uses [referenced](/features/env-variables#referencing-variables) variables):

```yaml title="zerops.yaml"
zerops:
  - setup: app
    run:
      base: docker@latest
      envVariables:
        DB_HOST: ${db_hostname}
        DB_PORT: ${db_port}
```

#### 2. Passing Variables to Docker Containers

For single containers, pass variables using the `-e` flag:

```yaml title="zerops.yaml"
run:
  base: docker@latest
  prepareCommands:
    - docker image pull my-application:1.0.0  # Use specific version tags, not :latest
  start: docker run -e DB_HOST -e DB_PORT --network=host my-application:1.0.0
```

:::important
Always use specific version tags (like `1.0.0`) instead of `:latest`. Zerops caches the `prepareCommands` output, which means a new `:latest` image won't be automatically pulled on subsequent deployments unless the cache is manually cleared or the commands change.
:::

For Docker Compose setups, pass environment variables in your `docker-compose.yaml`:

```yaml title="docker-compose.yaml"
services:
  api:
    image: my-application:1.0.0
    network_mode: host
    environment:
      - DB_HOST
      - DB_PORT
```

## Implementation Examples

### Single Container

```yaml title="zerops.yaml"
zerops:
  - setup: app
    run:
      base: docker@latest
      prepareCommands:
        - docker image pull crccheck/hello-world:1.0.0  # Always use specific version tags
      start: docker run --network=host crccheck/hello-world:1.0.0
      ports:
        - port: 8000
          httpSupport: true
```

:::important
Always use specific version tags (like `1.0.0`) instead of `:latest`. Zerops caches the `prepareCommands` output, which means a new `:latest` image won't be automatically pulled on subsequent deployments unless the cache is manually cleared or the commands change.
:::

### Single Service with Docker Compose

```yaml title="zerops.yaml"
zerops:
  - setup: api
    build:
      # base cannot be docker — build phase runs in containers, not VMs
      deployFiles: ./docker-compose.yaml
      addToRunPrepare: ./docker-compose.yaml
    run:
      base: docker@latest
      prepareCommands:
        - docker compose pull api
      start: docker compose up api --force-recreate
      ports:
        - port: 8000
          httpSupport: true
```

```yaml title="docker-compose.yaml (excerpt)"
services:
  api:
    image: your-image:1.0.0
    network_mode: host
    # other configuration...
```

### Multiple Services with Docker Compose

```yaml title="zerops.yaml"
zerops:
  - setup: apps
    build:
      # base cannot be docker — build phase runs in containers, not VMs
      deployFiles: ./docker-compose.yaml
      addToRunPrepare: ./docker-compose.yaml
    run:
      base: docker@latest
      prepareCommands:
        - docker compose pull
      start: docker compose up --force-recreate
      ports:
        - port: 8000
          httpSupport: true
```

```yaml title="docker-compose.yaml (excerpt)"
services:
  web:
    image: web-image:1.0.0
    network_mode: host
    # other configuration...

  api:
    image: api-image:1.0.0
    network_mode: host
    # other configuration...
```

## Best Practices

#### Image Management
- **Always use specific version tags** instead of `:latest` - This prevents caching issues as Zerops caches `prepareCommands` output

#### Resource Planning
- Account for VM overhead in resource allocation
- Plan for longer initialization times
- Consider the impact on scaling operations

#### Migration Consideration
- Evaluate if your workload could run on native containers
- Consider gradual migration for complex applications
- Balance development effort against operational benefits

## Limitations and Workarounds

### Build Phase

Since the build phase runs in containers rather than VMs:

- Use `run.prepareCommands` for Docker-specific build steps
- Consider external CI/CD for complex Docker builds
- Leverage pre-built images when possible

### Scaling Operations

Docker services in Zerops have specific scaling characteristics that differ from native containers:

#### Vertical Scaling
- Resources must be defined with **fixed** values instead of min-max ranges
- CPU, RAM, and disk are specified as single values:
  ```yaml
  verticalAutoscaling:
    cpu: 3
    ram: 2
    disk: 20
  ```
- Any change to these values through the UI triggers an automatic VM restart
- Plan your resource allocation carefully to minimize scaling operations

#### Horizontal Scaling
- Still supports multiple containers through `minContainers` and `maxContainers`
- Consider breaking large services into smaller components
- Implement proper health checks for reliable scaling
- Use horizontal scaling when possible to avoid VM restarts

----------------------------------------

# Dotnet > How To > Build Pipeline


Zerops provides a customizable build and runtime environment for your .NET application.

## Add zerops.yaml to your repository

Start by adding `zerops.yaml` file to the **root of your repository** and modify it to fit your application:

```yaml
zerops:
  # define hostname of your service
  - setup: app
    # ==== how to build your application ====
    build:
      # REQUIRED. Set the base technology for the build environment:
      base: dotnet@6

      # OPTIONAL. Set the operating system for the build environment.
      # os: ubuntu

      # OPTIONAL. Customize the build environment by installing additional packages
      # or tools to the base build environment.
      # prepareCommands:
      #   - sudo apt-get something
      #   - curl something else

      # OPTIONAL. Build your application
      buildCommands:
        - npm i
        - npm run build

      # REQUIRED. Select which files / folders to deploy after
      # the build has successfully finished
      deployFiles:
        - dist
        - package.json
        - node_modules

      # OPTIONAL. Which files / folders you want to cache for the next build.
      # Next builds will be faster when the cache is used.
      cache: node_modules

    # ==== how to run your application ====
    run:
      # OPTIONAL. Sets the base technology for the runtime environment:
      base: dotnet@latest

      # OPTIONAL. Sets the internal port(s) your app listens on:
      ports:
        # port number
        - port: 5000

      # OPTIONAL. Customize the runtime .NET environment by installing additional
      # dependencies to the base .NET runtime environment.
      # prepareCommands:
      #   - sudo apt-get something
      #   - curl something else

      # OPTIONAL. Run one or more commands each time a new runtime container
      # is started or restarted. These commands are triggered before
      # your .NET application is started.
      # initCommands:
      #  - rm -rf ./cache

      # REQUIRED. Your .NET application start command
      start: npm start
```

The top-level element is always `zerops`.

### Setup

The first element `setup` contains the **hostname** of your service. A runtime service with the same hostname must exist in Zerops.
Zerops supports the definition of multiple runtime services in a single `zerops.yaml`. This is useful when you use a monorepo. Just add multiple setup elements in your `zerops.yaml`:

```yaml
zerops:
  # definition for app service
  - setup: app
    # optional
    build: ...
    # optional
    deploy: ...
    # required
    run: ...

  # definition for api service
  - setup: api
    # optional
    build: ...
    # optional
    deploy: ...
    # required
    run: ...
```

Each service configuration contains at least the `run` section. Optional `build` and `deploy` sections can be added to further customize your process.

## Build pipeline configuration

### base

_REQUIRED._ Sets the base technology for the build environment.

Following options are available for .NET builds:

- `dotnet@10`, `dotnet@latest`
- `dotnet@9`
- `dotnet@8`
- `dotnet@7`
- `dotnet@6`

```yaml
zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build:
      # REQUIRED. Sets the base technology for the build environment:
      base: dotnet@6
      ...
```

<p>
  The base build environment contains {data.alpine.default}, the selected
  major version of .NET, [Zerops command line tool](/references/cli), `ASP .NET` and `git`.
</p>

:::info
You can change the base environment when you need to. Just simply modify the `zerops.yaml` in your repository.
:::

If you need to install more technologies to the build environment, set multiple values as a yaml array. For example:

```yaml
zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build:
      # REQUIRED. Sets the base technology for the build environment:
      base:
        - dotnet@6
      prepareCommands:
        - zsc add go@latest
      ...
```

See the full list of supported [build base environments](/zerops-yaml/base-list#runtime-services).

To customize your build environment use the [prepareCommands](#preparecommands) attribute.

:::note
Modifying the base technology will invalidate your build cache. See our [Build Cache Documentation](/features/build-cache) for more details about cache invalidation.
:::

### os

_OPTIONAL._ Sets the operating system for the build environment.

Following options are available:

- `alpine`
- `ubuntu`

Default value is `alpine`.

We are currently using following os version:

- <span>{data.alpine.default}</span>
- <span>{data.ubuntu.default}</span>

:::caution
The os version is fixed and cannot be customized.
:::

:::note
Changing the OS setting will invalidate your build cache. See our [Build Cache Documentation](/features/build-cache) for details about cache behavior.
:::

### prepareCommands

_OPTIONAL._ Customizes the build environment by installing additional dependencies or tools to the base build environment.

The base build environment contains:

- <span>{data.alpine.default}</span>
- selected version of .NET defined in the [base](#base) attribute
- [Zerops command line tool](/references/cli)
- `ASP .NET` and `git`

To install additional packages or tools add one or more prepare commands:

```yaml
zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build:
      # REQUIRED. Set the base technology for the build environment:
      base: dotnet@6

      # OPTIONAL. Customize the build environment by installing additional packages
      # or tools to the base build environment.
      prepareCommands:
        - sudo apt-get something
        - curl something else
      ...
```

When the first build is triggered, Zerops will

1. create a build container
2. download your application code from your repository
3. run the prepare commands in the defined order

The application code is available in `/build/source` before the prepare commands are triggered, so you can use any file from your repository in your prepare commands (e.g. a configuration file). The commands themselves run in the `/home/zerops` directory.

:::note
These commands are skipped when using cached environment. Modifying `prepareCommands` will invalidate your build cache. See our [Build Cache Documentation](/features/build-cache) for details about cache invalidation.
:::

#### Command exit code

If any command fails, it returns an exit code other than 0 and the build is canceled. Read the [build log](/dotnet/how-to/logs#build-log) to troubleshoot the error. If the command ends successfully, it returns the exit code 0 and Zerops triggers the following command. When all prepare commands are finished, your custom build environment is ready for the build phase.

#### Single or separated shell instances

You can configure your prepare commands to be run in a single shell instance or multiple shell instances. The format is identical to [build commands](#buildcommands).

### buildCommands

_OPTIONAL._ Defines build commands.

```yaml
zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build:
      # REQUIRED. Set the base technology for the build environment:
      base: dotnet@6

      # OPTIONAL. Build your application
      buildCommands:
        - dotnet build -o app
      ...
```

Build commands are optional. Zerops triggers each command in the defined order in a dedicated build container, running from the `/build/source` directory.

Before the build commands are triggered the build container contains:

1. base environment defined by the [base](#base) attribute
2. optional customisation of the base environment defined in the [prepareCommands](#preparecommands) attribute
3. your application code

#### Run build commands as a single shell instance

Use following syntax to run all commands in the same environment context. For example, if one command changes the current directory, the next command continues in that directory. When one command creates an environment variable, the next command can access it.

```yaml
buildCommands:
  - |
    sudo apt-get -y install dotnet-runtime-6.0 aspnetcore-runtime-6.0 dotnet-sdk-6.0 # already installed for .NET service
    dotnet build -o app
```

#### Run build commands as a separate shell instances

When the following syntax is used, each command is triggered in a separate environment context. For example, each shell instance starts in the home directory again. When one command creates an environment variable, it won't be available for the next command.

```yaml
buildCommands:
  - sudo apt-get -y install dotnet-runtime-6.0 aspnetcore-runtime-6.0 dotnet-sdk-6.0 # already installed for .NET service
  - dotnet build -o app
```

#### Command exit code

If any command fails, it returns an exit code other than 0 and the build is canceled. Read the [build log](/dotnet/how-to/logs#build-log) to troubleshoot the error. If the error log doesn't contain any specific error message, try to run your build with the `--verbosity <LEVEL>` option.

```yaml
buildCommands:
  - dotnet build --verbosity detailed
```

If the command ends successfully, it returns the exit code 0 and Zerops triggers the following command. When all `buildCommands` are finished, the application build is completed and ready for the deploy phase.

### deployFiles

_REQUIRED._ Selects which files or folders will be deployed after the build has successfully finished. To filter out specific files or folders, use [`.deployignore`](#deployignore) file.

```yaml
# REQUIRED. Select which files / folders to deploy after
# the build has successfully finished
deployFiles:
  - app
```

Determines files or folders produced by your build, which should be deployed to your runtime service containers.

The path starts from the **root directory** of your project (the location of `zerops.yaml`). You must enclose the name in quotes if the folder or the file name contains a space.

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

#### Examples

Deploys a folder, and a file from the project root directory:

```yaml
deployFiles:
  - app
  - file.txt
```

Deploys the whole content of the build container:

```yaml
deployFiles: .
```

Deploys a folder, and a file in a defined path:

```yaml
deployFiles:
  - ./path/to/file.txt
  - ./path/to/dir/
```

#### How to use a wildcard in the path

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

Deploys all folders that are located in any path that begins with `/path/to/`

```yaml
deployFiles: ./path/to/~/
```

Deploys all folders that are located in any path that begins with `/path/` and ends with `/to/`

```yaml
deployFiles: ./path/~/to/
```

:::note Example
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 will be cached for the next build.

```yaml
# OPTIONAL. Which files / folders you want to cache for the next build.
# Next builds will be faster when the cache is used.
cache: file.txt
```

The cache attribute helps optimize build times by preserving specified files between builds.

The cache attribute supports the [~ wildcard character](#how-to-use-a-wildcard-in-the-path).

Learn more about the [build cache system](/features/build-cache) in Zerops.

### envVariables

_OPTIONAL._ Defines the environment variables for the build environment.

Enter one or more env variables in following format:

```yaml
zerops:
  # define hostname of your service
  - setup: app
    # ==== how to build your application ====
    build:
      base: dotnet@6
        …

      # OPTIONAL. Defines the env variables for the build environment:
      envVariables:
        DOTNET_ENV: production
        DB_NAME: db
        DB_HOST: db
        DB_USER: db
        DB_PASS: ${db_password}
```

Read more about [environment variables](/dotnet/how-to/env-variables) in Zerops.

## Runtime configuration

### base

_OPTIONAL._ Sets the base technology for the runtime environment.
If you don't specify the `run.base` attribute, Zerops keeps the current .NET version for your runtime.

Following options are available for .NET builds:

- `dotnet@10`, `dotnet@latest`
- `dotnet@9`
- `dotnet@8`
- `dotnet@7`
- `dotnet@6`

```yaml
zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build:
      # REQUIRED. Sets the base technology for the build environment:
      base: dotnet@6
      ...

    # ==== how to run your application ====
    run:
      # OPTIONAL. Sets the base technology for the runtime environment:
        base: dotnet@6
      ...
```

<p>
  The base runtime environment contains {data.alpine.default}, the
  selected major version of .NET, [Zerops command line tool](/references/cli) and `ASP .NET` and `git`.
</p>

:::info
You can change the base environment when you need to. Just simply modify the `zerops.yaml` in your repository.
:::

If you need to install more technologies to the runtime environment, set multiple values as a yaml array. For example:

```yaml
zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build:
      # REQUIRED. Sets the base technology for the build environment:
      base: dotnet@6
      ...

    # ==== how to run your application ====
    run:
      # OPTIONAL. Sets the base technology for the runtime environment:
      base:
        - dotnet@6
      prepareCommands:
        - zsc add go@latest
      ...
```

See the full list of supported [run base environments](/zerops-yaml/base-list).

To customise your build environment use the `prepareCommands` attribute.

### os

_OPTIONAL._ Sets the operating system for the runtime environment.

Following options are available:

- `alpine`
- `ubuntu`

Default value is `alpine`.

We are currently using following os version:

- <span>{data.alpine.default}</span>
- <span>{data.ubuntu.default}</span>

:::caution
The os version is fixed and cannot be customised.
:::

### ports

_OPTIONAL._ Specifies one or more internal ports on which your application will listen.

Projects in Zerops represent a group of one or more services. Services can be of different types (runtime services, databases, message brokers, object storage, etc.). All services of the same project share a **dedicated private network**. To connect to a service within the same project, just use the service hostname and its internal port.

For example, to connect to a .NET service with hostname = "app" and port = 5000 from another service of the same project, simply use `app:5000`. Read more about [how to access a .NET service](/references/networking/internal-access#basic-service-communication).

Each port has following attributes:

<table className="w-full my-1.5">
  <thead>
    <tr>
      <th className="w-fit"><strong>Parameter</strong></th>
      <th className="w-fit"><strong>Description</strong></th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td className="w-fit">port</td>
      <td className="w-fit">Defines the port number. You can set any port number between <em>10</em> and <em>65435</em>. Ports outside this interval are reserved for internal Zerops systems.</td>
    </tr>
    <tr>
      <td className="w-fit">protocol</td>
      <td className="w-fit"><strong>Optional.</strong> Defines the protocol. Allowed values are <code>TCP</code> or <code>UDP</code>. Default value is <code>TCP</code>.</td>
    </tr>
    <tr>
      <td className="w-fit">httpSupport</td>
      <td className="w-fit"><strong>Optional.</strong> <code>httpSupport = true</code> is the default setting for TCP protocol. Set <code>httpSupport = false</code> if a web server isn't running on the port. Zerops uses this information for the configuration of [public access](/features/access). <code>httpSupport = true</code> is available only in combination with the TCP protocol.</td>
    </tr>
  </tbody>
</table>

### prepareCommands

_OPTIONAL._ Customises the .NET runtime environment by installing additional dependencies or tools to the runtime base environment.

<p>
  The base .NET environment contains {data.alpine.default}, the selected
  major version of .NET, [Zerops command line tool](/references/cli) and `ASP .NET` and `git`. To install additional packages
  or tools add one or more prepare commands:
</p>

```yaml
zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build:
      ...

    # ==== how to run your application ====
    run:
      # OPTIONAL. Customise the runtime environment by installing additional packages
      # or tools to the base .NET runtime environment.
      prepareCommands:
        - sudo apt-get something
        - curl something else
      ...
```

When the first deploy with a defined prepare attribute is triggered, Zerops will

1. create a prepare runtime container
2. optionally: [copy selected folders or files from your build container](#copy-folders-or-files-from-your-build-container)
3. run the `prepareCommands` commands in the defined order

:::note
`run.prepareCommands` run in the `/home/zerops` directory.
:::

#### Command exit code

If any command fails, it returns an exit code other than 0 and the deploy is canceled. Read the [prepare runtime log](/dotnet/how-to/logs#prepare-runtime-log) to troubleshoot the error. If the command ends successfully, it returns the exit code 0 and Zerops triggers the following command. When all `prepareCommands` commands are finished, your custom runtime environment is ready for the deploy phase.

#### Cache of your custom runtime environment

Some packages or tools can take a long time to install. Therefore, Zerops caches your custom runtime environment after the installation of your custom packages or tools is completed. When the second or following deploy is triggered, Zerops will use the custom runtime cache from the previous deploy if following conditions are met:

1. Content of the [build.addToRunPrepare](#copy-folders-or-files-from-your-build-container) and `run.prepareCommands` attributes didn't change from the previous deploy
2. The custom runtime cache wasn't invalidated in the Zerops GUI.

To invalidate the Zerops runtime cache go to your service detail in Zerops GUI, choose **Service dashboard & runtime containers** from the left menu and click on the **Open pipeline detail** button. Then click on the **Clear runtime prepare cache** button.

When the prepare cache is used, Zerops doesn't create a prepare runtime container and executes the deployment of your application directly.

#### Single or separated shell instances

You can configure your prepare commands to be run in a single shell instance or multiple shell instances. The format is identical to [build commands](#buildcommands).

### Copy folders or files from your build container

<p>
  The prepare runtime container contains {data.alpine.default}, the
  selected major version of .NET,
  [Zerops command line tool](/references/cli) and
  `ASP .NET` and `git`.
</p>

The prepare runtime container does not contain your application code nor the built application. If you need to copy some folders or files from the build container to the runtime container (e.g. a configuration file) use the `addToRunPrepare` attribute in the [build section](#build-pipeline-configuration).

```yaml
zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build:
      ...
      addToRunPrepare: ./runtime-config.yaml

    # ==== how to run your application ====
    run:
      # OPTIONAL. Customise the runtime environment by installing additional packages
      # or tools to the base .NET runtime environment.
      prepareCommands:
        - sudo apt-get something
        - curl something else
      ...
```

In the example above Zerops will copy the `runtime-config.yaml` file from your build container **after the build has finished** into the new **prepare runtime** container. The copied files and folders will be available in the `/home/zerops` folder in the new prepare runtime container before the prepare commands are triggered.

### initCommands

_OPTIONAL._ Defines one or more commands to be run each time a new runtime container is started or a container is restarted.

```yaml
zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build: ...

    # ==== how to run your application ====
    run:
      # OPTIONAL. Run one or more commands each time a new runtime container
      # is started or restarted. These commands are triggered before
      # your .NET application is started.
      initCommands:
        - rm -rf ./cache
```

These commands are triggered in the runtime container before your .NET application is started via the [start command](#start).

:::note
`run.initCommands` run in the `/var/www` directory.
:::

Use init commands to clean or initialise your application cache or similar operations.

:::caution
The init commands will delay the start of your application each time a new runtime container is started (including the horizontal [scaling](/dotnet/how-to/scaling) or when a runtime container is restarted).

Do not use the init commands for customising your runtime environment. Use the [run:prepareCommands](#preparecommands-1) attribute instead.
:::

#### Command exit code

If any of the `initCommands` fails, it returns an exit code other than 0, but deploy is **not** canceled. After all init commands are finished, regardless of the status code, the application is started. Read the [runtime log](/dotnet/how-to/logs#runtime-log) to troubleshoot the error.

#### Single or separated shell instances

You can configure your `initCommands` to be run in a single shell instance or multiple shell instances. The format is identical to [build commands](#buildcommands).

### envVariables

_OPTIONAL._ Defines the environment variables for the runtime environment.

Enter one or more env variables in following format:

```yaml
zerops:
  # define hostname of your service
  - setup: app
    # ==== how to run your application ====
    run:
      # OPTIONAL. Defines the env variables for the runtime environment:
      envVariables:
        DOTNET_ENV: production
        DB_NAME: db
        DB_HOST: db
        DB_USER: db
        DB_PASS: ${db_password}
```

Read more about [environment variables](/dotnet/how-to/env-variables) in Zerops.

### start

_REQUIRED._ Defines the start command for your .NET application.

```yaml
zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build: ...

    # ==== how to run your application ====
    run:
      # REQUIRED. Your .NET application start command
      start: cd app && dotnet dnet.dll
```

### health check

_OPTIONAL._ Defines a health check.

`healthCheck` requires either one `httpGet` object or one `exec` object.

#### httpGet

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

Following attributes are available:

<table className="w-full my-1.5">
  <thead>
    <tr>
      <th className="w-fit whitespace-nowrap">Parameter</th>
      <th className="w-fit whitespace-nowrap">Description</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td className="w-fit whitespace-nowrap font-semibold">port</td>
      <td>Defines the port of the HTTP GET request.
The readiness check will trigger a GET request on <code>{'http://127.0.0.1:{port}/{path}'}</code></td>
    </tr>
    <tr>
      <td className="w-fit whitespace-nowrap font-semibold">path</td>
      <td>Defines the URL path of the HTTP GET request.
The readiness check will trigger a GET request on <code>{'http://127.0.0.1:{port}/{path}'}</code></td>
    </tr>
    <tr>
      <td className="w-fit whitespace-nowrap font-semibold">host</td>
      <td><strong>Optional.</strong> The readiness check is triggered from inside of your runtime container so it always uses the localhost <code>127.0.0.1</code>. If you need to add a <code>host</code> to the request header, specify it in the <code>host</code> attribute.</td>
    </tr>
    <tr>
      <td className="w-fit whitespace-nowrap font-semibold">scheme</td>
      <td><strong>Optional.</strong> The readiness check is triggered from inside of your runtime container so no https is required.
If your application requires a https request, set <code>scheme: https</code></td>
    </tr>
  </tbody>
</table>

**Example:**

```yaml
zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build: ...

    # ==== how to run your application ====
    run:
      # REQUIRED. Your .NET application start command
      start: cd app && dotnet dnet.dll

      # OPTIONAL. Define a health check with a HTTP GET request option.
      # Configures the check on http://127.0.0.1:80/status
      healthCheck:
        httpGet:
          port: 80
          path: /status
```

#### exec

Configures the health check to run a local command.
Following attributes are available:

<table className="w-full my-1.5">
  <thead>
    <tr>
      <th className="w-fit"><strong>Parameter</strong></th>
      <th className="w-fit"><strong>Description</strong></th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td className="w-fit"><strong>command</strong></td>
      <td className="w-fit">
        Defines a local command to be run.

        The command has access to the same [environment variables](/dotnet/how-to/create#set-secret-environment-variables) as your .NET application.

        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 below.
      </td>
    </tr>
  </tbody>
</table>

**Example:**

```yaml
zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build: ...

    # ==== how to run your application ====
    run:
      # REQUIRED. Your .NET application start command
      start: cd app && dotnet dnet.dll

      # OPTIONAL. Define a health check with a shell command.
      healthCheck:
        exec:
          command: |
            touch grass
            rm -rf life
            mv /outside/user /home/user
```

### crontab

_OPTIONAL._ Defines cron jobs.

Setup cron jobs in the following format:

```yaml
zerops:
  # define hostname of your service
  - setup: app

    # ==== how to run your application ====
    run:
      crontab:
        # REQUIRED. Sets the command to execute:
        - command: ""
        # REQUIRED. Sets the interval time to execute:
          timing: "0 * * * *"
```

Read more about setting up [cron](/zerops-yaml/cron) in Zerops.

## Deploy configuration

### readiness check

_OPTIONAL._ Defines a readiness check. Read more about how the [readiness check works](/dotnet/how-to/deploy-process#readiness-checks) in Zerops.

`readinessCheck` requires either one `httpGet` object or one `exec` object.

#### httpGet

Configures the readiness check to request a local URL using a http GET method.

Following attributes are available:

<table className="w-full my-1.5">
  <thead>
    <tr>
      <th className="w-fit whitespace-nowrap">Parameter</th>
      <th className="w-fit whitespace-nowrap">Description</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td className="w-fit whitespace-nowrap font-semibold">port</td>
      <td>Defines the port of the HTTP GET request.
The readiness check will trigger a GET request on <code>{'http://127.0.0.1:{port}/{path}'}</code></td>
    </tr>
    <tr>
      <td className="w-fit whitespace-nowrap font-semibold">path</td>
      <td>Defines the URL path of the HTTP GET request.
The readiness check will trigger a GET request on <code>{'http://127.0.0.1:{port}/{path}'}</code></td>
    </tr>
    <tr>
      <td className="w-fit whitespace-nowrap font-semibold">host</td>
      <td><strong>Optional.</strong> The readiness check is triggered from inside of your runtime container so it always uses the localhost <code>127.0.0.1</code>. If you need to add a <code>host</code> to the request header, specify it in the <code>host</code> attribute.</td>
    </tr>
    <tr>
      <td className="w-fit whitespace-nowrap font-semibold">scheme</td>
      <td><strong>Optional.</strong> The readiness check is triggered from inside of your runtime container so no https is required.
If your application requires a https request, set <code>scheme: https</code></td>
    </tr>
  </tbody>
</table>

**Example:**

```yaml
zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build: ...

    # ==== how to deploy your application ====
    deploy:
      # OPTIONAL. Define a readiness check with a HTTP GET request option.
      # Configures the check on http://127.0.0.1:80/status
      readinessCheck:
        httpGet:
          port: 80
          path: /status

    # ==== how to run your application ====
    run: ...
```

Read more about how the [readiness check works](/dotnet/how-to/deploy-process#readiness-checks) in Zerops.

#### exec

Configures the readiness check to run a local command.
Following attributes are available:

<table className="w-full my-1.5">
  <thead>
    <tr>
      <th className="w-fit"><strong>Parameter</strong></th>
      <th className="w-fit"><strong>Description</strong></th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td className="w-fit"><strong>command</strong></td>
      <td className="w-fit">
        Defines a local command to be run.

        The command has access to the same [environment variables](/dotnet/how-to/create#set-secret-environment-variables) as your .NET application.

        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 below.
      </td>
    </tr>
  </tbody>
</table>

**Example:**

```yaml
zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build: ...

    # ==== how to deploy your application ====
    deploy:
      # OPTIONAL. Define a readiness check with a HTTP GET request option.
      # Configures the check on http://127.0.0.1:80/status
      readinessCheck:
        exec:
          command: |
            touch grass
            rm -rf life
            mv /outside/user /home/user
```

Read more about how the [readiness check works](/dotnet/how-to/deploy-process#readiness-checks) in Zerops.


----------------------------------------

# Dotnet > How To > Build Process



----------------------------------------

# Dotnet > How To > Controls



----------------------------------------

# Dotnet > How To > Create


Zerops provides a .NET runtime service with extensive build support. .NET runtime is highly scalable and customisable to suit both development and production.

## Create .NET service using Zerops GUI

First, set up a project in Zerops GUI. Then go to the project dashboard page and choose **Add new service** in the left menu in the **Services** block. Then add a new .NET service:

[Video: /vids/services/dotnet.webm](/vids/services/dotnet.webm)

### Choose .NET version

Following .NET versions are currently supported:

:::info
You can [change](/dotnet/how-to/upgrade) the major version at any time later.
:::

### Set a hostname

Enter a unique service identifier like "app","cache", "gui" etc. Duplicate services with the same name in the same project are forbidden.

#### Limitations:

- maximum 25 characters
- must contain only lowercase ASCII letters (a-z) or numbers (0-9)

:::caution
The hostname is fixed after the service is created. It can't be changed later.
:::

### Set secret environment variables

Add environment variables with sensitive data, such as password, tokens, salts, certificates etc. These will be securely saved inside Zerops and added to your runtime service upon start.

Setting the secret environment variables is optional. You can set them later in Zerops GUI.

Read more about [different types of env variables](/dotnet/how-to/env-variables#service-env-variables) in Zerops.

## Create .NET service using zCLI

zCLI is the Zerops command-line tool. To create a new .NET service via the command-line, follow these steps:

1. [Install & setup zCLI](/references/cli)
2. [Create a project description file](/dotnet/how-to/create#create-a-project-description-file)
3. [Create a project with a .NET and PostgreSQL service](#full-example)

### Create a project description file

Zerops uses a yaml format to describe the project infrastructure.

#### Basic example:

Create a directory `my-project`. Create an `description.yaml` file inside the `my-project` directory with following content:

```yaml
# basic project data
project:
  # project name
  name: my-project
# array of project services
services:
  - # service name
    hostname: app
    # service type and version number in dotnet@6 format
    type: dotnet@6
    # defines the minimum number of containers for horizontal autoscaling
    minContainers: 1
    # defines the maximum number of containers for horizontal autoscaling. Max value = 6.
    maxContainers: 6
    # optional: create env variables
    envSecrets:
      S3_ACCESS_KEY_ID: 'P8cX1vVVb'
      S3_ACCESS_SECRET: 'ogFthuiLYki8XoL73opSCQ'
```

The yaml file describes your future project infrastructure. The project will contain one .NET version 6 service with default [auto scaling](/dotnet/how-to/scaling) configuration. Hostname will be set to "app", the internal port(s) the service listens on will be defined later in the [zerops.yaml](/dotnet/how-to/build-pipeline#ports). Following secret env variables will be configured:

```env
S3_ACCESS_KEY_ID="P8cX1vVVb"
S3_ACCESS_SECRET="ogFthuiLYki8XoL73opSCQ"
```

#### Full example:

Create a directory my-project. Create an description.yaml file inside the my-project directory with following content:

```yaml
# basic project data
project:
  # project name
  name: my-project
  # optional: project description
  description: A project with a .NET and PostgreSQL database
  # optional: project tags
  tags:
    - DEMO
    - ZEROPS
# array of project services
services:
  - # service name
    hostname: app
    # service type and version number in dotnet@6 format
    type: dotnet@6
    # optional: vertical auto scaling customization
    verticalAutoscaling:
      cpuMode: DEDICATED
      minCpu: 2
      maxCpu: 5
      minRam: 2
      maxRam: 24
      minDisk: 6
      maxDisk: 50
      startCpuCoreCount: 3
      minFreeRamGB: 0.5
      minFreeRamPercent: 20
    # defines the minimum number of containers for horizontal autoscaling. Max value = 6.
    minContainers: 2
    # defines the maximum number of containers for horizontal autoscaling. Max value = 6.
    maxContainers: 4
    # optional: create secret env variables
    envSecrets:
      S3_ACCESS_KEY_ID: 'P8cX1vVVb'
      S3_ACCESS_SECRET: 'ogFthuiLYki8XoL73opSCQ'
  - # second service hostname
    hostname: db
    # service type and version number in postgresql@{version} format
    type: postgresql@12
    # mode of operation "HA"/"non_HA"
    mode: NON_HA
```

The yaml file describes your future project infrastructure. The project will contain a .NET service and a [PostgreSQL](/postgresql/overview) service.

.NET service with "app" hostname, the internal port(s) the service listens on will be defined later in the [zerops.yaml](/dotnet/how-to/build-pipeline#ports). .NET service will run on version 6 with a custom vertical and horizontal scaling. Following secret env variables will be configured:

```env
S3_ACCESS_KEY_ID="P8cX1vVVb"
S3_ACCESS_SECRET="ogFthuiLYki8XoL73opSCQ"
```

The hostname of the PostgreSQL service will be set to "db". The [single container](/features/scaling#single-container-mode)(/features/scaling#deployment-modes-databases-and-shared-storage) mode will be chosen and the default auto [scaling configuration](/postgresql/how-to/scale#configure-scaling) will be set.

#### Description of description.yaml parameters

The `project:` section is required. Only one project can be defined.

<table className="w-full my-1.5">
  <thead>
    <tr>
      <th className="w-fit"><strong>Parameter</strong></th>
      <th className="w-fit"><strong>Description</strong></th>
      <th className="w-fit"><strong>Limitations</strong></th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td className="w-fit"><strong>name</strong></td>
      <td className="w-fit">The name of the new project. Duplicates are allowed.</td>
      <td className="w-fit"></td>
    </tr>
    <tr>
      <td className="w-fit"><strong>description</strong></td>
      <td className="w-fit"><strong>Optional.</strong> Description of the new project.</td>
      <td className="w-fit">Maximum 255 characters.</td>
    </tr>
    <tr>
      <td className="w-fit"><strong>tags</strong></td>
      <td className="w-fit"><strong>Optional.</strong> One or more string tags. Tags do not have a functional meaning, they only provide better orientation in projects.</td>
      <td className="w-fit"></td>
    </tr>
  </tbody>
</table>

At least one service in `services:` section is required. You can create a project with multiple services. The example above contains .NET and PostgreSQL services but you can create a `description.yaml` with your own combination of [services](/features/infrastructure).

<table className="w-full my-1.5">
  <thead>
    <tr>
      <th className="w-fit"><strong>Parameter</strong></th>
      <th className="w-fit"><strong>Description</strong></th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td className="w-fit"><strong>hostname</strong></td>
      <td className="w-fit">
        The unique service identifier.

        The hostname of the new database will be set to the `hostname` value.

        <strong>Limitations:</strong>
        <ul>
        <li>duplicate services with the same name in the same project are forbidden</li>
        <li>maximum 25 characters</li>
        <li>must contain only lowercase ASCII letters (a-z) or numbers (0-9)</li>
        </ul>
      </td>
    </tr>
    <tr>
      <td className="w-fit"><strong>type</strong></td>
      <td className="w-fit">
        Specifies the service type and version.

        See what [.NET service types](/references/import-yaml/type-list#runtime-services) are currently supported.
      </td>
    </tr>
    <tr>
      <td className="w-fit"><strong>verticalAutoscaling</strong></td>
      <td className="w-fit">
        <strong>Optional.</strong> Defines [custom vertical auto scaling parameters](/dotnet/how-to/create#set-auto-scaling-configuration).

        All verticalAutoscaling attributes are optional. Not specified attributes will be set to their default values.
      </td>
    </tr>
    <tr>
      <td className="w-fit"><strong>- cpuMode</strong></td>
      <td className="w-fit">
        <strong>Optional.</strong> Accepts `SHARED`, `DEDICATED` values. Default is `SHARED`
      </td>
    </tr>
    <tr>
      <td className="w-fit"><strong>- minCpu/maxCpu</strong></td>
      <td className="w-fit">
        <strong>Optional.</strong> Set the minCpu or maxCpu in CPU cores (integer).
      </td>
    </tr>
    <tr>
      <td className="w-fit"><strong>- minRam/maxRam</strong></td>
      <td className="w-fit">
        <strong>Optional.</strong> Set the minRam or maxRam in GB (float).
      </td>
    </tr>
    <tr>
      <td className="w-fit"><strong>- minDisk/maxDisk</strong></td>
      <td className="w-fit">
        <strong>Optional.</strong> Set the minDisk or maxDisk in GB (float).
      </td>
    </tr>
    <tr>
      <td className="w-fit"><strong>minContainers</strong></td>
      <td className="w-fit">
        <strong>Optional.</strong> Default = 1. Defines the minimum number of containers for [horizontal autoscaling](/dotnet/how-to/create#horizontal-auto-scaling).

        <strong>Limitations:</strong>

        Current maximum value = 10.
      </td>
    </tr>
    <tr>
      <td className="w-fit"><strong>maxContainers</strong></td>
      <td className="w-fit">
        Defines the maximum number of containers for [horizontal autoscaling](/dotnet/how-to/create#horizontal-auto-scaling).

        <strong>Limitations:</strong>

        Current maximum value = 10.
      </td>
    </tr>
    <tr>
      <td className="w-fit"><strong>envSecrets</strong></td>
      <td className="w-fit">
        <strong>Optional.</strong> Defines one or more secret env variables as a key value map. See env variable [restrictions](/dotnet/how-to/env-variables#env-variable-restrictions).
      </td>
    </tr>
  </tbody>
</table>

### Create a project based on the description.yaml

When you have your `description.yaml` ready, use the `zcli project project-import` command to create a new project and the service infrastructure.

```sh
Usage:
  zcli project project-import importYamlPath [flags]

Flags:
  -h, --help                Help for the project import command.
      --org-id string        If you have access to more than one organization, you must specify the org ID for which the
                            project is to be created.
      --working-dir string   Sets a custom working directory. Default working directory is the current directory. (default "./")
```

Zerops will create a project and one or more services based on the `description.yaml` content.

Maximum size of the `description.yaml` file is 100 kB.

You don't specify the project name in the `zcli project project-import` command, because the project name is defined in the `description.yaml`.

If you have access to more than one client, you must specify the client ID for which the project is to be created. The `clientID` is located in the Zerops GUI under the client name on the project dashboard page.

### Add .NET service to an existing project

#### Example:

Create a directory `my-project` if it doesn't exist. Create an `import.yaml` file inside the `my-project` directory with following content:

```yaml
# basic project data
project:
  # project name
  name: my-project
# array of project services
services:
  - # service name
    hostname: app
    # service type and version number in dotnet@6 format
    type: dotnet@6
    # defines the minimum number of containers for horizontal autoscaling
    minContainers: 1
    # defines the maximum number of containers for horizontal autoscaling. Max value = 6.
    maxContainers: 6
    # optional: create env variables
    envSecrets:
      S3_ACCESS_KEY_ID: 'P8cX1vVVb'
      S3_ACCESS_SECRET: 'ogFthuiLYki8XoL73opSCQ'
```

The yaml file describes the list of one or more services that you want to add to your existing project. In the example above, one .NET service version 6 with default [auto scaling](/dotnet/how-to/scaling) configuration will be added to your project. Hostname of the new service will be set to `app`. Following secret env variables will be configured:

```env
S3_ACCESS_KEY_ID="P8cX1vVVb"
S3_ACCESS_SECRET="ogFthuiLYki8XoL73opSCQ"
```

The content of the `services:` section of `import.yaml` is identical to the project description file. The `import.yaml` never contains the `project:` section because the project already exists.

When you have your `import.yaml` ready, use the `zcli project service-import` command to add one or more services to your existing Zerops project.

```sh
Usage:
  zcli project service-import importYamlPath [flags]

Flags:
  -h, --help                Help for the project service import command.
  -P, --project-id string   If you have access to more than one project, you must specify the project ID for which the
                           command is to be executed.
```

zCLI commands are interactive, when you press enter after `zcli project service-import importYamlPath`, you will be given a list of your projects to choose from.

Maximum size of the import.yaml file is 100 kB.


----------------------------------------

# Dotnet > How To > Customize Runtime



----------------------------------------

# Dotnet > How To > Deploy Process



----------------------------------------

# Dotnet > How To > Env Variables



----------------------------------------

# Dotnet > How To > Filebrowser



----------------------------------------

# Dotnet > How To > Logs



----------------------------------------

# Dotnet > How To > Scaling



----------------------------------------

# Dotnet > How To > Shared Storage



----------------------------------------

# Dotnet > How To > Trigger Pipeline



----------------------------------------

# Dotnet > How To > Upgrade



----------------------------------------

# Dotnet > Overview


[.NET ↗](https://dotnet.microsoft.com/en-us/) is the free, open-source, cross-platform framework for building modern apps and powerful cloud services..

As said, there is no need for coding yet, we have created a [Github repository ↗](https://github.com/zeropsio/recipe-dotnet-hello-world), a **_recipe_**, containing the most simple .NET web application. The repo will be used as a source from which the app will be built.

### 🚀 Feel free to deploy the recipe yourself

This is the most bare-bones example of .NET running in Zerops — as few libraries as possible,
  just a simple endpoint with connect, read and write to a Zerops PostgreSQL database.

  [Deploy "dotnet" recipe on Zerops](https://app.zerops.io/recipe/?lf=dotnet)

1. Log in/sign up to [Zerops GUI ↗](https://app.zerops.io)
2. In the **Projects** box click on **Import a project** and paste in the following YAML config ([source ↗](https://github.com/zeropsio/recipe-dotnet-hello-world/blob/main/import-project/description.yaml)):

```yaml
project:
  name: my-first-project
services:
  - hostname: helloworld
    type: dotnet@latest
    minContainers: 1
    maxContainers: 3
    buildFromGit: https://github.com/zeropsio/recipe-dotnet-hello-world@main
    enableSubdomainAccess: true
```

3. Click on **Import project** and wait until all pipelines have finished.

**That's it, your application is now up and running! :star: Let's check it works:**

1. A _subdomain_ should have been enabled and visible in the project's **IP addressed & Public Routing Overview** box. Its format should look similar to this `https://helloworld-24-8080.prg1.zerops.app`.
2. Click or the `subdomain` URL to open it in a browser and you should see

```
Hello, World!
```

:::tip
Do you have any questions? Check the step-by-step tutorial, browse the documentation and join our **[Discord](https://discord.com/invite/WDvCZ54)** community to get help from our team and other members.
:::

## How to start

- [Care for details?](/dotnet/how-to/create) — Dive in all Zerops has to offer for your .NET application.

## Feature Highlights

- [Create .NET service](/dotnet/how-to/create) — Start with creating a .NET service using GUI or zCLI.
- [zerops.yaml](/dotnet/how-to/build-pipeline#add-zeropsyaml-to-your-repository) — See a full example of zerops.yaml file to create your own app.
- [Scaling configuration](/dotnet/how-to/scaling) — Set up scaling of your .NET application so that it runs smoothly while using only necessary resources.

{" "}

- [Customize build environment](/dotnet/how-to/build-process#customize-build-environment)
- [Customize runtime environment](/dotnet/how-to/customize-runtime)

## When in doubt, reach out

Don't know how to start or got stuck during the process? You might not be the first one, visit the FAQ section to find out.

In case you haven't found an answer (and also if you have), we and our community are looking forward to hearing from you on Discord.

Have you build something that others might find useful? Don't hesitate to share your knowledge!

- [FAQ](/dotnet/faq) — Most common questions in one place.
- [Discord](https://discord.com/invite/WDvCZ54) — Join our core team and Zerops community on Discord. Ask questions and share your tips with other members.

## Popular Guides

- [zCLI](/references/cli) — Get even more out of Zerops with the zCLI command line tool.
- [Zerops VPN](/references/networking/vpn) — Connect to your services easily with Zerops VPN.


----------------------------------------

# Elasticsearch > Overview


Deploy [Elasticsearch](https://www.elastic.co/elasticsearch/) instances in Zerops with flexible scaling options, from standalone nodes to highly available clusters.

## Supported Versions

Currently supported Elasticsearch versions:

Import configuration version:

- `elasticsearch@9.2`
- `elasticsearch@8.16`

## Connection Details

- **Port**: 9200
- **Protocol**: HTTP only
- **Internal Access**: `http://{hostname}:9200`
- **Basic auth security**
    - **User**: `elastic`
    - **Password**: randomly generated during service creation, find under **Access Details** in service detail

#### Example
```sh
curl -u elastic:generatedpassword http://elasticsearch:9200
```

## Configuration Options

### Plugin Management

You can configure Elasticsearch plugins using a comma-separated list in your environment secrets:

```yaml
envSecrets:
  PLUGINS: "analysis-icu,ingest-attachment"
```

**Plugin Configuration Details:**
- Defines plugins to install at service startup
- **Format**: `plugin1,plugin2,...`
- Service automatically installs specified plugins during initialization
- Removing a plugin from this list triggers uninstallation on service restart

### JVM Heap Allocation

Control the JVM heap size as a percentage of container memory:

```yaml
envSecrets:
  HEAP_PERCENT: "75"
```

**Heap Configuration Details:**
- Value represents the percentage of container memory allocated to JVM heap
- **Default**: 50% of available container memory
- **Valid range**: 1-100
- To increase available memory, adjust the service's RAM allocation in scaling configuration

:::note Requires Restart
Changes to HEAP_PERCENT require a service restart to take effect.
:::

## Backup

Elasticsearch backups are created using `elasticdump`:

- **Format**: `.gz` (per index/component dump)
- **Tooling**: `elasticdump`
- **Compression**: Gzip compressed JSON data

For backup configuration, scheduling, retention policies, and management options, see the [Zerops Backups](/features/backup) documentation.

### Restoring Backups

To restore an Elasticsearch backup:

1. **Download** the backup file (`.gz`) from the Zerops UI
2. **Extract** the compressed files to access the JSON data
3. **Prepare** your target environment (clean existing indices or use a new instance)
4. **Restore** using either:
   - **elasticdump tool**: Use the same tool that created the backup for restoration via Zerops VPN or during deployment
   - **Elasticsearch API**: Import the data through REST API [calls](https://www.elastic.co/docs/deploy-manage/tools/snapshot-and-restore/restore-snapshot)

For assistance with the restoration process, contact Zerops support.

## Example Configuration

```yaml
services:
  - hostname: elasticsearch
    type: elasticsearch@8.16
    mode: HA
    envSecrets:
      PLUGINS: "analysis-icu,ingest-attachment"
      HEAP_PERCENT: "75"
```

## Related Resources

- [Elasticsearch Official Documentation](https://www.elastic.co/guide/index.html)
- [Available Elasticsearch Plugins](https://www.elastic.co/guide/en/elasticsearch/plugins/current/index.html)

----------------------------------------

# Elixir > How To > Build Pipeline


Zerops provides a customizable build and runtime environment for your Elixir application.

## Add zerops.yaml to your repository

Start by adding `zerops.yaml` file to the **root of your repository** and modify it to fit your application:

```yaml
zerops:
  # define hostname of your service
  - setup: app
    # ==== how to build your application ====
    build:
      # REQUIRED. Set the base technology for the build environment:
      base: elixir@latest

      # OPTIONAL. Set the operating system for the build environment.
      # os: ubuntu

      # OPTIONAL. Customise the build environment by installing additional packages
      # or tools to the base build environment.
      # prepareCommands:
      #   - sudo apt-get something
      #   - curl something else

      # OPTIONAL. Build your application
      buildCommands:
        - mix deps.get --only prod
        - mix compile
        - mix release

      # REQUIRED. Select which files / folders to deploy after
      # the build has successfully finished
      deployFiles: _build/prod/rel/app/

      # OPTIONAL. Which files / folders you want to cache for the next build.
      # Next builds will be faster when the cache is used.
      cache: node_modules

    # ==== how to run your application ====
    run:
      # OPTIONAL. Sets the base technology for the runtime environment:
      base: elixir@latest

      # OPTIONAL. Sets the internal port(s) your app listens on:
      ports:
        # port number
        - port: 3000

      # OPTIONAL. Customise the runtime Elixir environment by installing additional
      # dependencies to the base Elixir runtime environment.
      # prepareCommands:
      #   - sudo apt-get something
      #   - curl something else

      # OPTIONAL. Run one or more commands each time a new runtime container
      # is started or restarted. These commands are triggered before
      # your Elixir application is started.
      # initCommands:
      #  - rm -rf ./cache

      # REQUIRED. Your Elixir application start command
      start: npm start
```

The top-level element is always `zerops`.

### Setup

The first element `setup` contains the **hostname** of your service. A runtime service with the same hostname must exist in Zerops.
Zerops supports the definition of multiple runtime services in a single `zerops.yaml`. This is useful when you use a monorepo. Just add multiple setup elements in your `zerops.yaml`:

```yaml
zerops:
  # definition for app service
  - setup: app
    # optional
    build: ...
    # optional
    deploy: ...
    # required
    run: ...

  # definition for api service
  - setup: api
    # optional
    build: ...
    # optional
    deploy: ...
    # required
    run: ...
```

Each service configuration contains at least the `run` section. Optional `build` and `deploy` sections can be added to further customize your process.

## Build pipeline configuration

### base

_REQUIRED._ Sets the base technology for the build environment.

Following options are available for Elixir builds:

- `1.16`

```yaml
zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build:
      # REQUIRED. Sets the base technology for the build environment:
      base: elixir@latest
      ...
```

<p>
  The base build environment contains {data.alpine.default}, the selected
  major version of Elixir, [Zerops command line tool](/references/cli), `npm`, `yarn`, `git` and `npx` tools.
</p>

:::info
You can change the base environment when you need to. Just simply modify the `zerops.yaml` in your repository.
:::

If you need to install more technologies to the build environment, set multiple values as a yaml array. For example:

```yaml
zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build:
      # REQUIRED. Sets the base technology for the build environment:
      base:
        - elixir@latest
      prepareCommands:
        - zsc add go@latest
      ...
```

See the full list of supported [build base environments](/zerops-yaml/base-list#runtime-services).

To customise your build environment use the [prepareCommands](#preparecommands) attribute.

:::note
Modifying the base technology will invalidate your build cache. See our [Build Cache Documentation](/features/build-cache) for more details about cache invalidation.
:::

### os

_OPTIONAL._ Sets the operating system for the build environment.

Following options are available:

- `alpine`
- `ubuntu`

Default value is `alpine`.

We are currently using following os version:

- <span>{data.alpine.default}</span>
- <span>{data.ubuntu.default}</span>

:::caution
The os version is fixed and cannot be customised.
:::

:::note
Changing the OS setting will invalidate your build cache. See our [Build Cache Documentation](/features/build-cache) for details about cache behavior.
:::

### prepareCommands

_OPTIONAL._ Customises the build environment by installing additional dependencies or tools to the base build environment.

The base build environment contains:

- <span>{data.alpine.default}</span>
- selected version of Elixir defined in the [base](#base) attribute
- [Zerops command line tool](/references/cli)
- `npm`, `yarn`, `git` and `npx` tools

To install additional packages or tools add one or more prepare commands:

```yaml
zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build:
      # REQUIRED. Set the base technology for the build environment:
      base: elixir@latest

      # OPTIONAL. Customise the build environment by installing additional packages
      # or tools to the base build environment.
      prepareCommands:
        - sudo apt-get something
        - curl something else
      ...
```

When the first build is triggered, Zerops will

1. create a build container
2. download your application code from your repository
3. run the prepare commands in the defined order

The application code is available in `/build/source` before the prepare commands are triggered, so you can use any file from your repository in your prepare commands (e.g. a configuration file). The commands themselves run in the `/home/zerops` directory.

:::note
These commands are skipped when using cached environment. Modifying `prepareCommands` will invalidate your build cache. See our [Build Cache Documentation](/features/build-cache) for details about cache invalidation.
:::

#### Command exit code

If any command fails, it returns an exit code other than 0 and the build is canceled. Read the [build log](/elixir/how-to/logs#build-log) to troubleshoot the error. If the command ends successfully, it returns the exit code 0 and Zerops triggers the following command. When all prepare commands are finished, your custom build environment is ready for the build phase.

#### Single or separated shell instances

You can configure your prepare commands to be run in a single shell instance or multiple shell instances. The format is identical to [build commands](#buildcommands).

### buildCommands

_OPTIONAL._ Defines build commands.

```yaml
zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build:
      # REQUIRED. Set the base technology for the build environment:
      base: elixir@latest

      # OPTIONAL. Build your application
      buildCommands:
        - npm i
        - npm run build
      ...
```

Build commands are optional. Zerops triggers each command in the defined order in a dedicated build container, running from the `/build/source` directory.

Before the build commands are triggered the build container contains:

1. base environment defined by the [base](#base) attribute
2. optional customisation of the base environment defined in the [prepareCommands](#preparecommands) attribute
3. your application code

#### Run build commands as a single shell instance

Use following syntax to run all commands in the same environment context. For example, if one command changes the current directory, the next command continues in that directory. When one command creates an environment variable, the next command can access it.

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

#### Run build commands as a separate shell instances

When the following syntax is used, each command is triggered in a separate environment context. For example, each shell instance starts in the home directory again. When one command creates an environment variable, it won't be available for the next command.

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

#### Command exit code

If any command fails, it returns an exit code other than 0 and the build is canceled. Read the [build log](/elixir/how-to/logs#build-log) to troubleshoot the error. If the error log doesn't contain any specific error message, try to run your build with the --verbose option.

```yaml
buildCommands:
  - npm i --verbose
  - npm run build
```

If the command ends successfully, it returns the exit code 0 and Zerops triggers the following command. When all `buildCommands` are finished, the application build is completed and ready for the deploy phase.

### deployFiles

_REQUIRED._ Selects which files or folders will be deployed after the build has successfully finished. To filter out specific files or folders, use [`.deployignore`](#deployignore) file.

```yaml
# REQUIRED. Select which files / folders to deploy after
# the build has successfully finished
deployFiles:
  - dist
  - package.json
  - node_modules
```

Determines files or folders produced by your build, which should be deployed to your runtime service containers.

The path starts from the **root directory** of your project (the location of `zerops.yaml`). You must enclose the name in quotes if the folder or the file name contains a space.

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

#### Examples

Deploys a folder, and a file from the project root directory:

```yaml
deployFiles:
  - dist
  - package.json
```

Deploys the whole content of the build container:

```yaml
deployFiles: .
```

Deploys a folder, and a file in a defined path:

```yaml
deployFiles:
  - ./path/to/file.txt
  - ./path/to/dir/
```

#### How to use a wildcard in the path

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

Deploys all folders that are located in any path that begins with `/path/to/`

```yaml
deployFiles: ./path/to/~/
```

Deploys all folders that are located in any path that begins with `/path/` and ends with `/to/`

```yaml
deployFiles: ./path/~/to/
```

:::note Example
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 will be cached for the next build.

```yaml
# OPTIONAL. Which files / folders you want to cache for the next build.
# Next builds will be faster when the cache is used.
cache: file.txt
```

The cache attribute helps optimize build times by preserving specified files between builds.

The cache attribute supports the [~ wildcard character](#how-to-use-a-wildcard-in-the-path).

Learn more about the [build cache system](/features/build-cache) in Zerops.

### envVariables

_OPTIONAL._ Defines the environment variables for the build environment.

Enter one or more env variables in following format:

```yaml
zerops:
  # define hostname of your service
  - setup: app
    # ==== how to build your application ====
    build:
      base: elixir@latest
        …

      # OPTIONAL. Defines the env variables for the build environment:
      envVariables:
        NODE_ENV: production
        DB_NAME: db
        DB_HOST: db
        DB_USER: db
        DB_PASS: ${db_password}
```

Read more about [environment variables](/elixir/how-to/env-variables) in Zerops.

## Runtime configuration

### base

_OPTIONAL._ Sets the base technology for the runtime environment.
If you don't specify the `run.base` attribute, Zerops keeps the current Elixir version for your runtime.

Following options are available for Elixir builds:

- `1.16`

```yaml
zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build:
      # REQUIRED. Sets the base technology for the build environment:
      base: elixir@latest
      ...

    # ==== how to run your application ====
    run:
      # OPTIONAL. Sets the base technology for the runtime environment:
        base: elixir@latest
      ...
```

<p>
  The base runtime environment contains {data.alpine.default}, the
  selected major version of Elixir, Zerops command line tool, `npm`, `yarn`, `git` and `npx` tools.
</p>

:::info
You can change the base environment when you need to. Just simply modify the `zerops.yaml` in your repository.
:::

If you need to install more technologies to the runtime environment, set multiple values as a yaml array. For example:

```yaml
zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build:
      # REQUIRED. Sets the base technology for the build environment:
      base: elixir@latest
      ...

    # ==== how to run your application ====
    run:
      # OPTIONAL. Sets the base technology for the runtime environment:
      base:
        - elixir@latest
      prepareCommands:
        - zsc add go@latest
      ...
```

See the full list of supported [run base environments](/zerops-yaml/base-list).

To customise your build environment use the `prepareCommands` attribute.

### os

_OPTIONAL._ Sets the operating system for the runtime environment.

Following options are available:

- `alpine`
- `ubuntu`

Default value is `alpine`.

We are currently using following os version:

- <span>{data.alpine.default}</span>
- <span>{data.ubuntu.default}</span>

:::caution
The os version is fixed and cannot be customised.
:::

### ports

_OPTIONAL._ Specifies one or more internal ports on which your application will listen.

Projects in Zerops represent a group of one or more services. Services can be of different types (runtime services, databases, message brokers, object storage, etc.). All services of the same project share a **dedicated private network**. To connect to a service within the same project, just use the service hostname and its internal port.

For example, to connect to a Elixir service with hostname = "app" and port = 3000 from another service of the same project, simply use `app:3000`. Read more about [how to access a Elixir service](/references/networking/internal-access#basic-service-communication).

Each port has following attributes:

| parameter   | description                                                                                                                                                                                                                                                                                                            |
| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| port        | Defines the port number. You can set any port number between _10_ and _65435_. Ports outside this interval are reserved for internal Zerops systems.                                                                                                                                                                   |
| protocol    | **Optional.** Defines the protocol. Allowed values are `TCP` or `UDP`. Default value is `TCP`.                                                                                                                                                                                                                         |
| httpSupport | **Optional.** `httpSupport = true` is the default setting for TCP protocol. Set `httpSupport = false` if a web server isn't running on the port. Zerops uses this information for the configuration of [public access](/features/access). `httpSupport = true` is available only in combination with the TCP protocol. |
| httpSupport | **Optional.** `httpSupport = true` is the default setting for TCP protocol. Set `httpSupport = false` if a web server isn't running on the port. Zerops uses this information for the configuration of [public access](/features/access). `httpSupport = true` is available only in combination with the TCP protocol. |

### prepareCommands

_OPTIONAL._ Customises the Elixir runtime environment by installing additional dependencies or tools to the runtime base environment.

<p>
  The base Elixir environment contains {data.alpine.default} the selected
  major version of Elixir, [Zerops command line tool](/references/cli) and `npm`, `yarn`, `git` and `npx` tools. To install
  additional packages or tools add one or more prepare commands:
</p>

```yaml
zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build:
      ...

    # ==== how to run your application ====
    run:
      # OPTIONAL. Customise the runtime environment by installing additional packages
      # or tools to the base Elixir runtime environment.
      prepareCommands:
        - sudo apt-get something
        - curl something else
      ...
```

When the first deploy with a defined prepare attribute is triggered, Zerops will

1. create a prepare runtime container
2. optionally: [copy selected folders or files from your build container](#copy-folders-or-files-from-your-build-container)
3. run the `prepareCommands` commands in the defined order

:::note
`run.prepareCommands` run in the `/home/zerops` directory.
:::

#### Command exit code

If any command fails, it returns an exit code other than 0 and the deploy is canceled. Read the [prepare runtime log](/elixir/how-to/logs#prepare-runtime-log) to troubleshoot the error. If the command ends successfully, it returns the exit code 0 and Zerops triggers the following command. When all `prepareCommands` commands are finished, your custom runtime environment is ready for the deploy phase.

#### Cache of your custom runtime environment

Some packages or tools can take a long time to install. Therefore, Zerops caches your custom runtime environment after the installation of your custom packages or tools is completed. When the second or following deploy is triggered, Zerops will use the custom runtime cache from the previous deploy if following conditions are met:

1. Content of the [build.addToRunPrepare](#copy-folders-or-files-from-your-build-container) and `run.prepareCommands` attributes didn't change from the previous deploy
2. The custom runtime cache wasn't invalidated in the Zerops GUI.

To invalidate the custom runtime cache go to `yyy`

When the custom runtime cache is used, Zerops doesn't create a prepare runtime container and executes the deployment of your application directly.

#### Single or separated shell instances

You can configure your prepare commands to be run in a single shell instance or multiple shell instances. The format is identical to [build commands](#buildcommands).

### Copy folders or files from your build container

<p>
  The prepare runtime container contains {data.alpine.default}, the
  selected major version of Elixir, [Zerops command line tool](/references/cli) and `npm`, `yarn`, `git` and `npx` tools.
</p>

The prepare runtime container does not contain your application code nor the built application. If you need to copy some folders or files from the build container to the runtime container (e.g. a configuration file) use the `addToRunPrepare` attribute in the [build section](#build-pipeline-configuration).

```yaml
zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build:
      ...
      addToRunPrepare: ./runtime-config.yaml

    # ==== how to run your application ====
    run:
      # OPTIONAL. Customise the runtime environment by installing additional packages
      # or tools to the base Elixir runtime environment.
      prepareCommands:
        - sudo apt-get something
        - curl something else
      ...
```

In the example above Zerops will copy the `runtime-config.yaml` file from your build container **after the build has finished** into the new **prepare runtime** container. The copied files and folders will be available in the `/home/zerops` folder in the new prepare runtime container before the prepare commands are triggered.

### initCommands

_OPTIONAL._ Defines one or more commands to be run each time a new runtime container is started or a container is restarted.

```yaml
zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build: ...

    # ==== how to run your application ====
    run:
      # OPTIONAL. Run one or more commands each time a new runtime container
      # is started or restarted. These commands are triggered before
      # your Elixir application is started.
      initCommands:
        - rm -rf ./cache
```

These commands are triggered in the runtime container before your Elixir application is started via the [start command](#start).

:::note
`run.initCommands` run in the `/var/www` directory.
:::

Use init commands to clean or initialise your application cache or similar operations.

:::caution
The init commands will delay the start of your application each time a new runtime container is started (including the horizontal [scaling](/elixir/how-to/scaling) or when a runtime container is restarted).

Do not use the init commands for customising your runtime environment. Use the [run:prepareCommands](#preparecommands-1) attribute instead.
:::

#### Command exit code

If any of the `initCommands` fails, it returns an exit code other than 0, but deploy is **not** canceled. After all init commands are finished, regardless of the status code, the application is started. Read the [runtime log](/elixir/how-to/logs#runtime-log) to troubleshoot the error.

#### Single or separated shell instances

You can configure your `initCommands` to be run in a single shell instance or multiple shell instances. The format is identical to [build commands](#buildcommands).

### envVariables

_OPTIONAL._ Defines the environment variables for the runtime environment.

Enter one or more env variables in following format:

```yaml
zerops:
  # define hostname of your service
  - setup: app
    # ==== how to run your application ====
    run:
      # OPTIONAL. Defines the env variables for the runtime environment:
      envVariables:
        NODE_ENV: production
        DB_NAME: db
        DB_HOST: db
        DB_USER: db
        DB_PASS: ${db_password}
```

Read more about [environment variables](/elixir/how-to/env-variables) in Zerops.

### start

_REQUIRED._ Defines the start command for your Elixir application.

```yaml
zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build: ...

    # ==== how to run your application ====
    run:
      # REQUIRED. Your Elixir application start command
      start: npm start
```

We recommend starting your Elixir application using `npm start`.

### health check

_OPTIONAL._ Defines a health check.

`healthCheck` requires either one `httpGet` object or one `exec` object.

#### httpGet

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

Following attributes are available:

<table className="w-full my-1.5">
  <thead>
    <tr>
      <th className="w-fit whitespace-nowrap">Parameter</th>
      <th className="w-fit whitespace-nowrap">Description</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td className="w-fit whitespace-nowrap font-semibold">port</td>
      <td>Defines the port of the HTTP GET request.
The readiness check will trigger a GET request on <code>{'http://127.0.0.1:{port}/{path}'}</code></td>
    </tr>
    <tr>
      <td className="w-fit whitespace-nowrap font-semibold">path</td>
      <td>Defines the URL path of the HTTP GET request.
The readiness check will trigger a GET request on <code>{'http://127.0.0.1:{port}/{path}'}</code></td>
    </tr>
    <tr>
      <td className="w-fit whitespace-nowrap font-semibold">host</td>
      <td><strong>Optional.</strong> The readiness check is triggered from inside of your runtime container so it always uses the localhost <code>127.0.0.1</code>. If you need to add a <code>host</code> to the request header, specify it in the <code>host</code> attribute.</td>
    </tr>
    <tr>
      <td className="w-fit whitespace-nowrap font-semibold">scheme</td>
      <td><strong>Optional.</strong> The readiness check is triggered from inside of your runtime container so no https is required.
If your application requires a https request, set <code>scheme: https</code></td>
    </tr>
  </tbody>
</table>

**Example:**

```yaml
zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build: ...

    # ==== how to run your application ====
    run:
      # REQUIRED. Your Elixir application start command
      start: npm start

      # OPTIONAL. Define a health check with a HTTP GET request option.
      # Configures the check on http://127.0.0.1:80/status
      healthCheck:
        httpGet:
          port: 80
          path: /status
```

#### exec

Configures the health check to run a local command.
Following attributes are available:

| Parameter   | Description                                                                                                                                                                                                                                                                                                                     |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **command** | Defines a local command to be run.
The command has access to the same [environment variables](/elixir/how-to/create#set-secret-environment-variables) as your Elixir application.
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 below. |

**Example:**

```yaml
zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build: ...

    # ==== how to run your application ====
    run:
      # REQUIRED. Your Elixir application start command
      start: npm start

      # OPTIONAL. Define a health check with a shell command.
      healthCheck:
        exec:
          command: |
            touch grass
            rm -rf life
            mv /outside/user /home/user
```

### crontab

_OPTIONAL._ Defines cron jobs.

Setup cron jobs in the following format:

```yaml
zerops:
  # define hostname of your service
  - setup: app

    # ==== how to run your application ====
    run:
      crontab:
        # REQUIRED. Sets the command to execute:
        - command: ""
        # REQUIRED. Sets the interval time to execute:
          timing: "0 * * * *"
```

Read more about setting up [cron](/zerops-yaml/cron) in Zerops.

## Deploy configuration

### readiness check

_OPTIONAL._ Defines a readiness check. Read more about how the [readiness check works](/elixir/how-to/deploy-process#readiness-checks) in Zerops.

`readinessCheck` requires either one `httpGet` object or one `exec` object.

#### httpGet

Configures the readiness check to request a local URL using a http GET method.

Following attributes are available:

<table className="w-full my-1.5">
  <thead>
    <tr>
      <th className="w-fit whitespace-nowrap">Parameter</th>
      <th className="w-fit whitespace-nowrap">Description</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td className="w-fit whitespace-nowrap font-semibold">port</td>
      <td>Defines the port of the HTTP GET request.
The readiness check will trigger a GET request on <code>{'http://127.0.0.1:{port}/{path}'}</code></td>
    </tr>
    <tr>
      <td className="w-fit whitespace-nowrap font-semibold">path</td>
      <td>Defines the URL path of the HTTP GET request.
The readiness check will trigger a GET request on <code>{'http://127.0.0.1:{port}/{path}'}</code></td>
    </tr>
    <tr>
      <td className="w-fit whitespace-nowrap font-semibold">host</td>
      <td><strong>Optional.</strong> The readiness check is triggered from inside of your runtime container so it always uses the localhost <code>127.0.0.1</code>. If you need to add a <code>host</code> to the request header, specify it in the <code>host</code> attribute.</td>
    </tr>
    <tr>
      <td className="w-fit whitespace-nowrap font-semibold">scheme</td>
      <td><strong>Optional.</strong> The readiness check is triggered from inside of your runtime container so no https is required.
If your application requires a https request, set <code>scheme: https</code></td>
    </tr>
  </tbody>
</table>

**Example:**

```yaml
zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build: ...

    # ==== how to deploy your application ====
    deploy:
      # OPTIONAL. Define a readiness check with a HTTP GET request option.
      # Configures the check on http://127.0.0.1:80/status
      readinessCheck:
        httpGet:
          port: 80
          path: /status

    # ==== how to run your application ====
    run: ...
```

Read more about how the [readiness check works](/elixir/how-to/deploy-process#readiness-checks) in Zerops.

#### exec

Configures the readiness check to run a local command.
Following attributes are available:

| Parameter   | Description                                                                                                                                                                                                                                                                                                                     |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **command** | Defines a local command to be run.
The command has access to the same [environment variables](/elixir/how-to/create#set-secret-environment-variables) as your Elixir application.
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 below. |

**Example:**

```yaml
zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build: ...

    # ==== how to deploy your application ====
    deploy:
      # OPTIONAL. Define a readiness check with a HTTP GET request option.
      # Configures the check on http://127.0.0.1:80/status
      readinessCheck:
        exec:
          command: |
            touch grass
            rm -rf life
            mv /outside/user /home/user
```

Read more about how the [readiness check works](/elixir/how-to/deploy-process#readiness-checks) in Zerops.


----------------------------------------

# Elixir > How To > Build Process



----------------------------------------

# Elixir > How To > Controls



----------------------------------------

# Elixir > How To > Create


Zerops provides a powerful Elixir runtime service with extensive build support. The Elixir runtime is highly scalable and customizable to suit your development and production needs. With just a few clicks or commands, you can have a production-ready Elixir environment up and running in no time.

## Create a Elixir service using Zerops GUI

First, set up a project in the Zerops GUI. Then go to the project dashboard page and choose **Add new service** in the left menu under the **Services** section. From there, you can add a new Elixir service:

[Video: /vids/services/elixir.webm](/vids/services/elixir.webm)

### Choose a Elixir version

Zerops supports the following Elixir versions:

:::info
You can easily [upgrade](/elixir/how-to/upgrade) the major version at any time later.
:::

### Set a hostname

Enter a unique service identifier like "app", "cache", "gui", etc. Duplicate services with the same name within the same project are not allowed.

#### Limitations:

- Maximum 25 characters
- Must contain only lowercase ASCII letters (a-z) or numbers (0-9)

:::caution
The hostname is fixed after the service is created and cannot be changed later.
:::

### Set secret environment variables

Add environment variables with sensitive data, such as passwords, tokens, salts, certificates, etc. These will be securely saved inside Zerops and added to your runtime service upon start.

Setting secret environment variables is optional. You can always set them later in the Zerops GUI.

Read more about the [different types of environment variables](/elixir/how-to/env-variables#service-env-variables) in Zerops.

## Create a Elixir service using zCLI

zCLI is the Zerops command-line tool. To create a new Elixir service via the command line, follow these steps:

1. [Install & setup zCLI](/references/cli)
2. [Create a project description file](/elixir/how-to/create#create-a-project-description-file)
3. [Create a project with a Elixir and PostgreSQL service](#full-example)

### Create a project description file

Zerops uses a YAML format to describe the project infrastructure.

#### Basic example:

Create a directory called `my-project`. Inside the `my-project` directory, create a `description.yaml` file with the following content:
```yaml
# basic project data
project:
  # project name
  name: my-project
# array of project services
services:
  - # service name
    hostname: app
    # service type and version number in elixir@{version} format
    type: elixir@latest
    # defines the minimum number of containers for horizontal autoscaling
    minContainers: 1
    # defines the maximum number of containers for horizontal autoscaling. Max value = 6.
    maxContainers: 6
    # optional: create env variables
    envSecrets:
      S3_ACCESS_KEY_ID: 'P8cX1vVVb'
      S3_ACCESS_SECRET: 'ogFthuiLYki8XoL73opSCQ'
```

The yaml file describes your future project infrastructure. The project will contain one Elixir version 20 service with default [auto scaling](/elixir/how-to/scaling) configuration. Hostname will be set to "app", the internal port(s) the service listens on will be defined later in the [zerops.yaml](/elixir/how-to/build-pipeline#ports). Following secret env variables will be configured:

```env
S3_ACCESS_KEY_ID="P8cX1vVVb"
S3_ACCESS_SECRET="ogFthuiLYki8XoL73opSCQ"
```

#### Full example:

Create a directory my-project. Create an description.yaml file inside the my-project directory with following content:

```yaml
# basic project data
project:
  # project name
  name: my-project
  # optional: project description
  description: A project with a Elixir and PostgreSQL database
  # optional: project tags
  tags:
    - DEMO
    - ZEROPS
# array of project services
services:
  - # service name
    hostname: app
    # service type and version number in elixir@{version} format
    type: elixir@latest
    # optional: vertical auto scaling customization
    verticalAutoscaling:
      cpuMode: DEDICATED
      minCpu: 2
      maxCpu: 5
      minRam: 2
      maxRam: 24
      minDisk: 6
      maxDisk: 50
      startCpuCoreCount: 3
      minFreeRamGB: 0.5
      minFreeRamPercent: 20
    # defines the minimum number of containers for horizontal autoscaling. Max value = 6.
    minContainers: 2
    # defines the maximum number of containers for horizontal autoscaling. Max value = 6.
    maxContainers: 4
    # optional: create env variables
    envSecrets:
      S3_ACCESS_KEY_ID: 'P8cX1vVVb'
      S3_ACCESS_SECRET: 'ogFthuiLYki8XoL73opSCQ'
  - # second service hostname
    hostname: db
    # service type and version number in postgresql@{version} format
    type: postgresql@12
    # mode of operation "HA"/"non_HA"
    mode: NON_HA
```

The yaml file describes your future project infrastructure. The project will contain a Elixir service and a [PostgreSQL](/postgresql/overview) service.

Elixir service with "app" hostname, the internal port(s) the service listens on will be defined later in the [zerops.yaml](/elixir/how-to/build-pipeline#ports). Elixir service will run on version 20 with a custom vertical and horizontal scaling. Following secret env variables will be configured:

```env
S3_ACCESS_KEY_ID="P8cX1vVVb"
S3_ACCESS_SECRET="ogFthuiLYki8XoL73opSCQ"
```

The hostname of the PostgreSQL service will be set to "db". The [single container](/features/scaling#single-container-mode)(/features/scaling#deployment-modes-databases-and-shared-storage) mode will be chosen and the default auto [scaling configuration](/postgresql/how-to/scale#configure-scaling) will be set.

#### Description of description.yaml parameters

The `project:` section is required. Only one project can be defined.

| Parameter       | Description                                                                                                                     | Limitations             |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------- | ----------------------- |
| **name**        | The name of the new project. Duplicates are allowed.                                                                            |                         |
| **description** | **Optional.** Description of the new project.                                                                                   | Maximum 255 characters. |
| **tags**        | **Optional.** One or more string tags. Tags do not have a functional meaning, they only provide better orientation in projects. |
| **tags**        | **Optional.** One or more string tags. Tags do not have a functional meaning, they only provide better orientation in projects. |

At least one service in `services:` section is required. You can create a project with multiple services. The example above contains Elixir and PostgreSQL services but you can create a `description.yaml` with your own combination of [services](/features/infrastructure).

<table className="w-full my-1.5">
  <thead>
    <tr>
      <th className="w-fit">Parameter</th>
      <th className="w-fit">Description</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td className="w-fit">
        <b>hostname</b>
      </td>
      <td className="w-fit">
        The unique service identifier.
        <ul>
        <li>duplicate services with the same name in the same project are forbidden</li>
        <li>maximum 25 characters</li>
        <li>must contain only lowercase ASCII letters (a-z) or numbers (0-9)</li>
        </ul>
      </td>
    </tr>
    <tr>
      <td className="w-fit">
        <b>type</b>
      </td>
      <td className="w-fit">
        Specifies the service type and version.

        See what [Elixir service types](/references/import-yaml/type-list#runtime-services) are currently supported.
      </td>
    </tr>
    <tr>
      <td className="w-fit">
        <b>verticalAutoscaling</b>
      </td>
      <td className="w-fit">
        <b>Optional.</b> Defines [custom vertical auto scaling parameters](/elixir/how-to/create#set-auto-scaling-configuration).

        All verticalAutoscaling attributes are optional. Not specified
        attributes will be set to their default values.
      </td>
    </tr>
    <tr>
      <td className="w-fit">
        <b> - cpuMode</b>
      </td>
      <td className="w-fit">
        <b>Optional.</b> Accepts `SHARED`, `DEDICATED` values. Default is `SHARED`
      </td>
    </tr>
    <tr>
      <td className="w-fit">
        <b> - minCpu/maxCpu</b>
      </td>
      <td className="w-fit">
        <b>Optional.</b> Set the minCpu or maxCpu in CPU cores (integer).
      </td>
    </tr>
    <tr>
      <td className="w-fit">
        <b> - minRam/maxRam</b>
      </td>
      <td className="w-fit">
        <b>Optional.</b> Set the minRam or maxRam in GB (float).
      </td>
    </tr>
    <tr>
      <td className="w-fit">
        <b> - minDisk/maxDisk</b>
      </td>
      <td className="w-fit">
        <b>Optional.</b> Set the minDisk or maxDisk in GB (float).
      </td>
    </tr>
    <tr>
      <td className="w-fit">
        <b>minContainers</b>
      </td>
      <td className="w-fit">
        <b>Optional.</b> Default = 1. Defines the minimum number of containers
        for [horizontal autoscaling](/elixir/how-to/create#horizontal-auto-scaling).

        <b>Limitations:</b>

        Current maximum value = 10.
      </td>
    </tr>
    <tr>
      <td className="w-fit">
        <b>maxContainers</b>
      </td>
      <td className="w-fit">
        Defines the maximum number of containers for [horizontal autoscaling](/elixir/how-to/create#horizontal-auto-scaling).

        <b>Limitations:</b>

        Current maximum value = 10.
      </td>
    </tr>
    <tr>
      <td className="w-fit">
        <b>envSecrets</b>
      </td>
      <td className="w-fit">
        <b>Optional.</b> Defines one or more secret env variables as a key value
        map. See env variable [restrictions](/elixir/how-to/env-variables#env-variable-restrictions).
      </td>
    </tr>
  </tbody>
</table>

### Create a project based on the description.yaml

When you have your `description.yaml` ready, use the `zcli project project-import` command to create a new project and the service infrastructure.

```sh
Usage:
  zcli project project-import importYamlPath [flags]

Flags:
  -h, --help                Help for the project import command.
      --org-id string        If you have access to more than one organization, you must specify the org ID for which the
                            project is to be created.
      --working-dir string   Sets a custom working directory. Default working directory is the current directory. (default "./")
```

Zerops will create a project and one or more services based on the `description.yaml` content.

Maximum size of the `description.yaml` file is 100 kB.

You don't specify the project name in the `zcli project project-import` command, because the project name is defined in the `description.yaml`.

If you have access to more than one client, you must specify the client ID for which the project is to be created. The `clientID` is located in the Zerops GUI under the client name on the project dashboard page.

### Add Elixir service to an existing project

#### Example:

Create a directory `my-project` if it doesn't exist. Create an `import.yaml` file inside the `my-project` directory with following content:

```yaml
# basic project data
project:
  # project name
  name: my-project
# array of project services
services:
  - # service name
    hostname: app
    # service type and version number in elixir@{version} format
    type: elixir@latest
    # defines the minimum number of containers for horizontal autoscaling
    minContainers: 1
    # defines the maximum number of containers for horizontal autoscaling. Max value = 6.
    maxContainers: 6
    # optional: create env variables
    envSecrets:
      S3_ACCESS_KEY_ID: 'P8cX1vVVb'
      S3_ACCESS_SECRET: 'ogFthuiLYki8XoL73opSCQ'
```

The yaml file describes the list of one or more services that you want to add to your existing project. In the example above, one Elixir service version 20 with default [auto scaling](/elixir/how-to/scaling) configuration will be added to your project. Hostname of the new service will be set to `app`. Following secret env variables will be configured:

```env
S3_ACCESS_KEY_ID="P8cX1vVVb"
S3_ACCESS_SECRET="ogFthuiLYki8XoL73opSCQ"
```

The content of the `services:` section of `import.yaml` is identical to the project description file. The `import.yaml` never contains the `project:` section because the project already exists.

When you have your `import.yaml` ready, use the `zcli project service-import` command to add one or more services to your existing Zerops project.

```sh
Usage:
  zcli project service-import importYamlPath [flags]

Flags:
  -h, --help                Help for the project service import command.
  -P, --project-id string   If you have access to more than one project, you must specify the project ID for which the
                           command is to be executed.
```

zCLI commands are interactive, when you press enter after `zcli project service-import importYamlPath`, you will be given a list of your projects to choose from.

Maximum size of the import.yaml file is 100 kB.


----------------------------------------

# Elixir > How To > Customize Runtime



----------------------------------------

# Elixir > How To > Deploy Process



----------------------------------------

# Elixir > How To > Env Variables



----------------------------------------

# Elixir > How To > Filebrowser



----------------------------------------

# Elixir > How To > Logs



----------------------------------------

# Elixir > How To > Scaling



----------------------------------------

# Elixir > How To > Shared Storage



----------------------------------------

# Elixir > How To > Trigger Pipeline



----------------------------------------

# Elixir > How To > Upgrade



----------------------------------------

# Elixir > Overview


[Elixir ↗](https://elixir.org/en) is an asynchronous event-driven JavaScript runtime, which is designed to build scalable network applications.

As said, there is no need for coding yet, we have created a [Github repository ↗](https://github.com/zeropsio/recipe-elixir), a **_recipe_**, containing the most simple Elixir web application. The repo will be used as a source from which the app will be built.

### 🚀 Feel free to deploy the recipe yourself

This is the most bare-bones example of Elixir app running in Zerops — as few libraries as possible,
  just a simple endpoint with connect, read and write to a Zerops PostgreSQL database.

  [Deploy "elixir" recipe on Zerops](https://app.zerops.io/recipe/?lf=elixir)

1. Log in/sign up to [Zerops GUI ↗](https://app.zerops.io)

2. In the **Projects** box click on **Import a project** and paste in the following YAML config ([source ↗](https://github.com/zeropsio/recipe-elixir/blob/main/zerops-project-import.yaml)):

```yaml
project:
  name: recipe-elixir
  tags:
    - zerops-recipe

services:
  - hostname: api
    type: elixir@1.16
    enableSubdomainAccess: true
    buildFromGit: https://github.com/zeropsio/recipe-elixir

  - hostname: db
    type: postgresql@16
    mode: NON_HA
    priority: 1
```

3. Click on **Import project** and wait until all pipelines have finished.

**That's it, your application is now up and running! :star: Let's check it works:**

1. A _subdomain_ should have been enabled and visible in the project's **IP addressed & Public Routing Overview** box. Its format should look similar to this `https://api-808-4000.prg1.zerops.app`.
2. Click or the `subdomain` URL to open it in a browser and you should see

```
{"message":"This is a simple Elixir application running in Zerops.io, each request adds an entry to the PostgreSQL database and returns a count. See the source repository (https://github.com/zeropsio/recipe-elixir) for more information.","newEntry":"e64be640-d6c2-4be8-93ac-d1e40e56fa06","count":1}
```

:::tip
Do you have any questions? Check the step-by-step tutorial, browse the documentation and join our **[Discord](https://discord.com/invite/WDvCZ54)** community to get help from our team and other members.
:::

## How to start

It doesn't matter whether it's your first curious introduction to Zerops, you have already mastered the basics and are looking for a tiny detail or inspiration. Below, choose a section that fits your needs:

- [Care for details?](/elixir/how-to/create) — Dive in all Zerops has to offer for your Elixir application.
- [Elixir recipes](https://github.com/zeropsio?q=elixir&type=all&language=&sort=) — Get inspired by already existing repositories, ready to be imported to Zerops.

## Feature Highlights

- [Create Elixir service](/elixir/how-to/create) — Start with creating a Elixir service using GUI or zCLI.
- [Zerops.yaml](/elixir/how-to/build-pipeline#add-zeropsyaml-to-your-repository) — See a full example of zerops.yaml file to create your own app.
- [Scaling configuration](/elixir/how-to/scaling) — Set up scaling of your Elixir application so that it runs smoothly while using only necessary resources.

{" "}

- [Customize build environment](/elixir/how-to/build-process#customize-build-environment)
- [Customize runtime environment](/elixir/how-to/customize-runtime)

## When in doubt, reach out

Don't know how to start or got stuck during the process? You might not be the first one, visit the FAQ section to find out.

In case you haven't found an answer (and also if you have), we and our community are looking forward to hearing from you on Discord.

Have you build something that others might find useful? Don't hesitate to share your knowledge!

- [FAQ](/elixir/faq) — Most common questions in one place.
- [Discord](https://discord.com/invite/WDvCZ54) — Join our core team and Zerops community on Discord. Ask questions and share your tips with other members.

## Popular Guides

- [zCLI](/references/cli) — Get even more out of Zerops with the zCLI command line tool.
- [Zerops VPN](/references/networking/vpn) — Connect to your services easily with Zerops VPN.


----------------------------------------

# Features > Access


Zerops provides multiple ways to access your services, whether you need internal communication between services, secure access from your development machine, or public access from the internet.

:::note
By default, your services are not publicly accessible until you configure external access. Internal communication between services within the same project works automatically.
:::

## How Zerops Networking Works

Every Zerops project includes a **shared networking infrastructure** that handles all access methods:

**Private Project Network:**
- All services within a project share a dedicated private network
- Services communicate directly using hostnames and internal ports
- Traffic stays isolated within your project

**Public Access Infrastructure:**
- **Core (L3) Balancer** manages IP addresses and direct port access
- **L7 HTTP Balancer** handles domain routing and SSL termination
  - Can be extensively configured for advanced routing, performance optimization, and custom behaviors
  - See the [L7 Balancer Configuration Guide](/references/networking/l7-balancer-config) for detailed options
- Both are shared across all services in your project

**Secure External Access:**
- **Built-in VPN** provides secure tunnel access to your project's private network
- Useful for development, debugging, and administration

## Internal Access

:::tip Complete Internal Access Setup
See the [Internal access reference guide](/references/networking/internal-access).
:::

Services within the same project can communicate directly using hostnames and internal ports. No additional configuration required.

**Example:** Connect to your `api` service on port 3000:
```
http://api:3000
```

**Key points:**
- Use service hostname as the address
- Use HTTP (not HTTPS) for internal communication
- Access internal ports defined in your service configuration
- Communication is automatically isolated from other projects

### Environment Variables

Zerops automatically creates environment variables to help with internal connections between services.

## VPN Access
:::tip Complete VPN Setup
See the [VPN reference guide](/references/networking/vpn).
:::

Connect securely to your project's internal network from your local machine:

```bash
# Connect to your project
zcli vpn up <project-id>

# Access services using internal hostnames
curl http://api:3000/health

# Disconnect when done
zcli vpn down
```

## Public Access

:::tip Complete Public Access Setup
See the [Public access reference guide](/references/networking/public-access).
:::

Make your services accessible from the internet using one of three methods:

### Zerops Subdomain
**Best for:** Development and testing

- Quick setup with automatic `.zerops.app` subdomains
- Each service gets its own unique subdomain
- Automatic SSL certificate management
- Shared infrastructure (has limitations for production use)

### Custom Domain
**Best for:** Production deployments

- Use your own domain names
- Better performance with dedicated balancer
- Full control over SSL and routing
- Requires DNS configuration

### Direct Port Access
**Best for:** Non-HTTP protocols and specialized use cases

- Direct access to specific ports on your services
- Supports any protocol (TCP/UDP)
- Optional firewall configuration
- Uses your project's IP addresses

## Next Steps

- **Internal access setup:** [Internal Access Reference Guide](/references/networking/internal-access)
- **Public access configuration:** [Public Access Reference Guide](/references/networking/public-access)
- **VPN setup and troubleshooting:** [VPN Reference Guide](/references/networking/vpn)
- **Advanced routing and SSL:** [L7 Balancer Configuration Guide](/references/networking/l7-balancer-config)

----------------------------------------

# Features > Backup


Zerops provides an automated, secure backup system for supported services. This guide covers how to configure, manage, and restore your backups.

## Supported Services

Zerops provides automated backup functionality for the following services. For specific backup format details and restore instructions, visit each service's documentation: [MariaDB](/mariadb/how-to/backup), [PostgreSQL](/postgresql/how-to/manage#backups), [Qdrant](/qdrant/overview), [Elasticsearch](/elasticsearch/overview), [NATS](/nats/overview), [Meilisearch](/meilisearch/overview), and [Shared Storage](/shared-storage/how-to/manage#backups).

## Managing Backups in the UI

By default, your data is backed up automatically **every day** between 00:00:00 UTC and 01:00:00 UTC, unless you update your settings.

To manage backups, go to the service detail and choose **Backups List & Configuration** in the left menu.

From this section, you can:
- Create a one-time backup
- Change the frequency/disable of automatic backups
- Configure retention policies and limits

### Backup Frequency Options

Available schedules:
- **No backups**: Disable automatic backups (not recommended)
- **Once a day**: Daily backups at a specified time
- **Once a week**: Weekly backups on a specific day and time
- **Once a month**: Monthly backups on a specific day and time
- **Custom CRON**: Define a custom schedule using CRON syntax

For the Custom CRON option, you can use the following syntax:

<table className="w-full">
  <thead>
    <tr>
      <th className="whitespace-nowrap w-fit">Field name</th>
      <th className="w-full">Allowed values</th>
    </tr>
  </thead>
  <tbody>
    <tr className="text-left">
      <td className="w-fit">Minute</td>
      <td className="w-fit">0-59</td>
    </tr>
    <tr className="text-left">
      <td className="w-fit">Hour</td>
      <td className="w-fit">0-23</td>
    </tr>
    <tr className="text-left">
      <td className="w-fit">Day</td>
      <td className="w-fit">1-31</td>
    </tr>
    <tr className="text-left">
      <td className="w-fit">Month</td>
      <td className="w-fit">1-12</td>
    </tr>
    <tr className="text-left">
      <td className="w-fit">Week Day</td>
      <td className="w-fit">0–7; both 0 and 7 represent Sunday</td>
    </tr>
  </tbody>
</table>

Examples:
- `0 2 * * *` - Every day at 2:00 AM
- `0 4 * * 0` - Every Sunday at 4:00 AM
- `0 0 1 * *` - First day of every month at midnight
- `0 */6 * * *` - Every 6 hours

### Backup Tagging

Zerops uses tags to categorize and manage backups:

**Time-Based Tags** (assigned automatically):
- `daily`: Every automatic backup
- `weekly`: First backup of each week (Monday UTC)
- `monthly`: First backup of each month (1st UTC)

**User Tags** (custom labels you create):
- Used for organization and identification (e.g., `v2.1-release`, `before-migration`, `monthly-snapshot`)
- Add when creating manual backups - up to 24 characters (letters, numbers, `:-_`)

**Protected Tags** (configured in retention policy):
- Backups with these tag names are exempt from automatic deletion, regardless of storage limits
- Define in the backup retention configuration section of the UI and add when creating manual backups

:::important
Manual backups don't get automatic time-based tags. Always add a protected tag to preserve critical manual backups.
:::

### View and Manage Backup Files

In this section, you can:
- Create manual backups
- View all backups with their timestamps and sizes
- Download backups
- Delete backups

:::note
When creating manual backups via the UI, you'll see immediate feedback. If the backup takes longer than 10 seconds, the process continues in the background. You can verify completion by refreshing the backup list or checking service logs.
:::

## Storage and Limits

### Project Storage Quotas

Each Zerops project has a **technical maximum backup storage limit of 1 TiB**:
- Only full backups are stored
- If a backup would exceed the storage limit, it will not be stored
- This quota is shared across all service backups within the project

### Billing
- **Lightweight Project Core**: 5 GB backup storage and 100 GB egress included
- **Serious Project Core**: 25 GB backup storage and 3 TB egress included

When you exceed your plan's free limits, **additional charges apply** according to our [pricing](/company/pricing#overage-costs).

### Retention Policy and Configuration

Zerops manages which backups are kept using a retention policy that you can customize through the UI:

**Default Time-Based Retention** (minimums):
- At least 7 daily backups
- At least 4 weekly backups
- At least 3 monthly backups

**Default Resource Limits** (maximums):
- Max 50 total backups per service
- Storage limited to your project's 1 TiB technical maximum (with billing for usage beyond free tier)

**Customization Options:**
You can modify these defaults in the backup retention configuration interface:
- **Set Protected Tags**: Define tag names that prevent automatic deletion of backups
- **Configure Maximum Limits**: Adjust total number of backups and storage size limits per service
- **Customize Minimum Retention**: Change how many daily, weekly, and monthly backups to keep
- **Set Type-Specific Limits**: Control maximum backups for each type (0 means unlimited, subject to total limits)

:::important
Backups with [protected tags](#backup-tagging) and the minimum required time-based backups will always be kept, even if they exceed the limits above. This ensures your critical recovery points are preserved.
:::

If you need more storage space, contact our support team.

### When Deleting Services or Projects

Deleted services/projects have their backups kept for a 7-day grace period before final removal.

## Command Line Interface

You can also manage backups using the Zerops CLI (zCLI):

```bash
# Create a backup
zcli backup create myServiceName

# Create a backup with tags (including protection)
zcli backup create myServiceName --tags pre-deploy,protected
```

Check `zcli backup --help` for current commands.

:::note
zCLI currently focuses on creation; listing/deletion/tag management is primarily via UI.
:::

## Restoring Backups

Restoration involves downloading backups and using service-specific methods. Zerops facilitates the backup creation and download; the restore action uses service-specific tools and APIs.

1. **Download**: Find the backup in the UI (by date/tag) and download it
2. **Prepare**: Set up your target environment (clean existing data or use a new instance)
3. **Restore**: Use service-specific tools via Zerops VPN, run the restore during deployment, or use the service API if available. For service-specific restore instructions, see each service's documentation linked in the [Supported Services](#supported-services) section above.

:::info Continuous Improvement
We're working on enhancing the restore experience, potentially including more automated options in the future.
:::

For assistance with restoration, contact Zerops support.

## High Availability (HA)

For multi-node HA services:
- **Automatic Backups**: Run on a randomly selected healthy node
- **Manual Backups**: Typically run on the primary/designated node (check logs)
- **Cluster State**: Other nodes stay operational

## Security

Backups are protected with end-to-end encryption:

- **Unique Encryption**: Each project gets its own encryption key (X25519)
- **Secure Process**: Data is encrypted immediately as backups are created
- **Zero-Trust**: Even Zerops staff cannot access your raw backup data
- **Isolated Storage**: Backups are stored separately from your regular data
- **Secure Download**: Backups are only decrypted when you download them

:::important
When a project is deleted, the encryption key is permanently destroyed after 7 days, making the backup data unrecoverable.
:::

## Best Practices

1. **Create backups before major changes**:
   - Always create a manual backup with a protected tag before database migrations, deployments, or large data operations
   - Use descriptive tags like `pre-migration` or `pre-release-v2`

2. **Manage storage efficiently**:
   - Regularly check usage in the Project Overview & Service Backup tabs to monitor free tier usage and stay within the 1 TiB technical limit
   - Remove unnecessary backups, especially those with [protected tags](#backup-tagging)
   - Adjust [retention policies](#retention-policy-and-configuration) based on your recovery needs
   - Regularly review and clean up old backups to optimize storage usage and minimize overage costs

3. **Test your restore process** periodically in a non-production environment to ensure you can recover when needed

## Troubleshooting

### Storage Quota Issues
**Cause**: High backup frequency, long retention periods, or many protected tags can lead to exceeding free tier limits or approaching technical maximums.

**Solutions**:
1. **Review & Prune**: Delete unnecessary manual backups or remove protected status from older backups
2. **Adjust Retention Policy**: Reduce minimum retention counts if your recovery requirements allow
3. **Optimize Schedule**: Reduce backup frequency if daily backups aren't essential
4. **Monitor Costs**: Check usage against your free tier (5GB/25GB) to avoid unexpected overage charges
5. **Contact Support**: If you need assistance managing storage

### Backup Failures
**Cause**: Service health issues, resource exhaustion, or platform problems.

**Solutions**:
1. **Check Service Logs**: Look for error messages around the scheduled backup time
2. **Verify Service Health**: Ensure the service is running properly with adequate resources
3. **Check Platform Status**: Visit status.zerops.io for any ongoing incidents
4. **Contact Support**: If issues persist, reach out with service name, failure time, and relevant logs

----------------------------------------

# Features > Build Cache


> Zerops implements a sophisticated two-layer caching strategy that optimizes build times while maintaining complete control over the build environment. This documentation explores the architecture, configuration patterns, and practical implementation of the build cache system.

## Architecture Overview

The build cache operates through two distinct layers:

1. **Base Layer**: Comprises the OS, installed dependencies, and prepare commands
2. **Build Layer**: Contains the state after executing build commands

The layers work together to create an efficient and predictable build environment, though they are currently coupled in their cache invalidation behavior (invalidating one layer affects the other).

### Cache Implementation

The caching mechanism is implemented through an efficient file movement strategy. This approach ensures near-instantaneous cache operations through simple directory relocation within the container, implementing the following characteristics:

- Files are moved between `/build/source` and `/build/cache` using container-level rename operations
- No packaging, compression, or network transfer is involved
- Cache preservation is achieved through simple directory relocation within the container
- Files maintain their original state and permissions throughout the process

:::note
See detailed [build process lifecycle](#build-process-lifecycle).
:::

## Configuration Guide

### Essential zerops.yaml Fields

The following fields in `zerops.yaml` affect build cache behavior:

**Direct Cache Configuration**:
- `build.cache`: Explicitly defines what should be cached through paths or patterns

**Cache Invalidation Triggers**:
These parameters trigger cache invalidation when modified:
- `build.os`: Base operating system selection
- `build.base`: Pre-installed software stacks and runtimes
- `build.prepareCommands`: System preparation and dependency installation
- `build.cache`: Changes to cache configuration

**Build Artifact Generation**:
- `build.buildCommands`: Generates the build artifact that will be deployed.

## Cache Configuration Patterns

### Pattern 1: System-Wide Cache Control
```yaml
build:
  cache: true   # Cache everything
  # OR
  cache: false  # Intended to disable all caching
```

The boolean values provide system-wide cache control:

`cache: true`:
- Preserves the entire build container state
- Maintains system-level package installations
- Ideal for globally installed packages (Python/PHP packages, Go modules)

`cache: false`:
- Intended to disable all caching
- Currently, due to layer coupling, only files within `/build/source` are not cached
- Everything outside `/build/source` remains cached (see [Common Pitfalls: Layer Coupling](#current-pitfalls))

### Pattern 2: Path-Specific Caching
```yaml
# Single path
build:
  cache: node_modules

# Multiple paths
build:
  cache:
    - node_modules
    - package-lock.json
    - .build
```

Execution flow:
1. Source code extraction to `/build/source`
2. Build command execution
3. Specified path preservation in `/build/cache`
4. Cached content restoration (no-clobber mode - source files take precedence)

:::tip
Ideal for non-versioned dependencies in your working directory (e.g., `node_modules`, `vendor`, `.venv`).
:::

## Path Pattern Reference

Zerops supports [Go's filepath.Match](https://pkg.go.dev/path/filepath#Match) syntax. Consider this example structure:

```
├── node_modules/
├── package.json
├── package-lock.json
└── subdir/
    ├── file1.txt
    ├── file2.txt
    └── file3.md
```

Pattern examples and matches:
```yaml
build:
  cache:
    - "subdir/*.txt"      # Matches: subdir/file1.txt, subdir/file2.txt
    - "package*"          # Matches: package.json, package-lock.json
    - "node_modules"      # Matches: entire node_modules directory recursively
```

:::note
All patterns resolve relative to `/build/source`. Path variations like `./node_modules`, `node_modules`, and `node_modules/` are treated identically.
:::

## Build Process Lifecycle

1. **Initialization Phase**
   - Build container startup
   - Builder process launch
   - Source code loading into `/build/source`

2. **Cache Restoration Phase**
   - Cached file movement to `/build/source` (no-clobber mode)
   - Source file precedence handling
   - Conflict logging (no build interruption)
   - Cache directory cleanup

3. **Build Execution Phase**
   - Build command processing
   - Artifact packaging (`build.deployFiles`)

4. **Cache Preservation Phase**
   - Specific cache files movement outside `/build/source`
   - `/build/source` directory cleanup
   - Container termination

## Cache Invalidation Reference

The build cache invalidates under these conditions:

1. **Manual Triggers**
   - API call: `DELETE /service-stack/{id}/build-cache`
   - GUI: Manual cache clear action

2. **Version Management**
   - Backup app version activation via `PUT /app-version/{id}/deploy`

3. **Configuration Changes**
   Any modifications to:
   ```yaml
   build.os
   build.base
   build.prepareCommands
   build.cache
   ```

### Current Pitfalls

The current implementation has some important characteristics:

1. **Layer Coupling**
   ```yaml
   build:
     base: go@1
     prepareCommands:
       - sudo apk update
       - sudo apk add sqlite
     buildCommands:
       - go build -o app main.go
     cache: false
   ```
   Even with `cache: false`, Go modules outside `/build/source` remain cached.

2. **Cascade Invalidation**
   ```yaml
   build:
     base: node@22
     prepareCommands:
       - sudo apk update
       - sudo apk add sqlite vim  # Adding 'vim' invalidates everything
     buildCommands:
       - npm install
       - npm build
     cache:
       - node_modules
   ```
   Modifying `prepareCommands` invalidates both layers, including cached `node_modules`.

## Real-World Implementation Examples

### Node.js Project with TypeScript
```yaml
build:
  base: node@22
  buildCommands:
    - npm ci
    - npm run build
  cache:
    - node_modules
    - .next
    - .turbo
    - package-lock.json
```

### Go Project with Multiple Dependencies
```yaml
build:
  base: go@1
  prepareCommands:
    - sudo apk add build-base
  buildCommands:
    - go mod download
    - go build -o bin/app cmd/main.go
  cache: true  # Caches entire Go modules directory
```

### PHP/Laravel Project
```yaml
build:
  base: php@8.3
  buildCommands:
    - composer install --no-dev
    - php artisan optimize
  cache:
    - vendor
    - composer.lock
```

## Debugging and Monitoring

* **Build Logs**
   - Cache operations are detailed in build logs
   - File conflicts during restoration are logged
   - Cache preservation status is visible

## Implementation Best Practices

### Cache Strategy Optimization

1. **Layer Management**
   - Maintain stable `prepareCommands` to prevent cache invalidation
   - Group related prepare commands logically

2. **Performance Optimization**:
   - Cache package manager lock files alongside dependency directories
   - Use system-wide caching (`cache: true`) for languages with global package managers

3. **Performance Tuning**
   - Leverage system-wide caching for complex builds
   - Monitor build logs for cache operations and potential conflicts
   - Use explicit patterns for precise control
   - Don't over-optimize – the system handles large caches efficiently

## Future Development

Planned system enhancements include:
- Layer independence implementation
- Granular cache control mechanisms
- Enhanced layer management capabilities
- Improved cache invalidation patterns


----------------------------------------

# Features > Cdn


Zerops CDN is a global content delivery network that brings your static content closer to your users, resulting in faster load times and improved user experience. Built on Nginx and Cloudflare geo-steering technology, our CDN automatically routes users to the nearest server location based on their DNS request.

## Key Benefits

- **Global Reach**: Serve content from strategic locations across the world
- **Reduced Latency**: Content is delivered from the server closest to your users
- **Simple Integration**: No complex configuration required

## Global CDN Infrastructure

Zerops CDN operates across **6 strategic regions** to ensure your content is always delivered from a location close to your users:

<table className="w-full my-1.5 whitespace-nowrap">
  <thead>
    <tr>
      <th className="w-fit" colspan="2">Region</th>
      <th className="w-fit">Location</th>
      <th className="w-fit">Coverage Area</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td className="w-fit font-semibold" rowspan="2">EU</td>
      <td className="w-fit font-semibold">CZ</td>
      <td className="w-fit">Prague, Czech Republic</td>
      <td className="w-full" rowspan="2">Primary European coverage + failover for all regions</td>
    </tr>
    <tr>
      <td className="w-fit font-semibold">DE</td>
      <td className="w-fit">Falkenstein, Germany</td>
    </tr>
    <tr>
      <td className="w-fit font-semibold" colspan="2">UK</td>
      <td className="w-fit">London, United Kingdom</td>
      <td className="w-full">UK and surrounding areas</td>
    </tr>
    <tr>
      <td className="w-fit font-semibold" colspan="2">AU</td>
      <td className="w-fit">Sydney, Australia</td>
      <td className="w-full">Australia and Oceania</td>
    </tr>
    <tr>
      <td className="w-fit font-semibold" colspan="2">SG</td>
      <td className="w-fit">Singapore, Singapore</td>
      <td className="w-full">Southeast Asia</td>
    </tr>
    <tr>
      <td className="w-fit font-semibold" colspan="2">CA</td>
      <td className="w-fit">Beauharnois, Canada</td>
      <td className="w-full">North America</td>
    </tr>
   </tbody>
</table>

### Geo-Steering Technology
Zerops CDN's geo-steering technology automatically routes users to the server location closest to them. Here's how it works:

* **Automatic routing**: Users are directed to the optimal CDN node based on their geographic location
* **Quick failover**: The DNS TTL is set to just 30 seconds, allowing fast recovery if a node fails
* **Redundancy**: If any node becomes unavailable, Cloudflare automatically redirects traffic to the next closest node
* **Reliable backup**: The EU region serves as the ultimate fallback - if all other nodes go down, EU will always be served in DNS

## CDN Modes and Implementation

Zerops CDN currently supports two distinct usage modes (with a third mode coming soon), each designed for specific content delivery needs.

### Object Storage Mode

Perfect for efficiently delivering media files, documents, and other static assets stored in Zerops [Object Storage](/object-storage/overview) to users across different geographical regions.

**Setup process:**
1. Create an Object Storage service or select an existing one
2. Enable the CDN option for this service
3. Set appropriate public read access policies for objects you want to serve via CDN

**Accessing content:**
```txt
https://storage.cdn.zerops.app/your-bucket/path/to/file
```

:::tip
Access the storage CDN URL via the `storageCdnUrl` **project** environment variable `${storageCdnUrl}/your-bucket/path/to/file`.
:::

### Static Mode

Ideal for caching and delivering static website assets like HTML, CSS, JavaScript, and images served from your custom domains.

**Setup process:**
1. Configure domain access for your service through the L7 HTTP Balancer section
2. Access domain settings via the **three dots menu** or **gear icon** next to your domain entry
3. In the "Project Domain Access Modification" dialog, enable the **"Enable CDN for static files"** toggle
4. Optionally enable "Automatically install SSL Certificates" if not already configured

**Accessing content:**
```txt
https://static.cdn.zerops.app/your-domain.com/path/to/file
```

:::tip
Access the static CDN URL via the `staticCdnUrl` **project** environment variable `${staticCdnUrl}/your-domain.com/path/to/file`.
:::

:::warning Wildcard Domains Not Supported
Static CDN cannot be activated for wildcard domains (e.g., *.example.com). You must use specific domain names.
:::

### API Mode *(Coming Soon)*

Designed for caching API responses to reduce load on your backend services and deliver faster responses to clients.

**Environment variable:** Once available, you'll be able to access the API CDN URL via the `apiCdnUrl` **project** environment variable.

:::warning
API Mode is currently under development and will be available in a future release.
:::

### HTML Implementation Examples

Here's how to integrate CDN URLs in your HTML code:

```html
<!-- Compare: Direct Object Storage vs. CDN-accelerated Storage -->
<!-- Direct from Object Storage -->

<!-- Via CDN for faster global delivery -->

<!-- Using environment variables in templates -->

<!-- Compare: Direct Domain vs. CDN-accelerated Domain -->
<!-- Direct from your domain -->
<script src="/static/js/main.js"></script>

<!-- Via CDN for faster global delivery -->
<script src="https://static.cdn.zerops.app/your-domain.com/static/js/main.js"></script>
```

### Testing Specific CDN Nodes

For testing or debugging purposes, you can bypass the automatic geo-steering and access a specific CDN node directly:

```
https://{region}-{mode}.cdn.zerops.app/path/to/content
```

Available region prefixes: `cz`, `de`, `au`, `sg`, `uk`, and `ca`

**Examples:**
- Test Australia node: `https://au-storage.cdn.zerops.app/my-bucket/test.jpg`
- Test UK node: `https://uk-static.cdn.zerops.app/my-domain.com/index.html`

## Managing CDN Content

### Cache Lifecycle

Content served through Zerops CDN follows this lifecycle:

1. **First Request**: When a user requests content not yet in the CDN cache, the request goes to the origin server (your Zerops service), and the response is cached at the CDN node
2. **Subsequent Requests**: Further requests for the same content are served directly from the CDN cache, reducing latency and origin server load
3. **Cache Expiration**: By default, content remains cached for 30 days unless explicitly purged
4. **Automatic Management**: When CDN storage reaches capacity, the least recently used content is automatically removed

:::note Important Cache Behavior
Zerops CDN implements a fixed 30-day TTL policy. Currently, HTTP caching headers such as `Cache-Control`, `Expires`, `Pragma`, etc. do not influence CDN caching behavior. To refresh content sooner than the 30-day period, use the [purge API](#api-reference).

Your `Cache-Control` headers will still affect browser caching behavior.
:::

### When to Purge Cache

You should consider purging cached content when:

- **Content Updates**: You've updated content but kept the same URL (e.g., updated images, CSS files)
- **Deployment Rollouts**: You've deployed a new version of your application
- **Emergency Removal**: You need to immediately remove content that was accidentally made public
- **Testing Changes**: You want to ensure users see the latest version during testing

### Purging Cached Content

Zerops provides multiple ways to manage and purge cached content before its normal expiration:

- **Command Line**: Use the `zsc cdn purge` [command](/references/zsc#cdn) available in all Zerops containers:
  ```sh
  # Purge all content for a domain
  zsc cdn purge example.com
  # Purge all content (wildcard)
  zsc cdn purge example.com "/*"
  # Purge specific file
  zsc cdn purge example.com "/path/to/my-file$"
  ```

  :::important
    - This command must be executed in any container within the project that has the CDN-enabled domain active
    - Currently only works for [Static Mode](#static-mode) CDN
  :::

- **API Endpoints**: For programmatic control, use the [API endpoints](#api-reference). Here are ready-to-use curl examples for quickly purging content in your scripts:

  ```sh
  # Static mode: Purge all content for a domain
  curl --location --request PUT "https://api.app-prg1.zerops.io/api/rest/public/project/$PROJECT_ID/purge-cdn/static/$DOMAIN/*" \
  --header "Authorization: Bearer $USER_OR_ACCESS_TOKEN"
  ```

  ```sh
  # Storage mode: Purge all content for object storage
  curl --location --request PUT "https://api.app-prg1.zerops.io/api/rest/public/service-stack/$OBJECT_STORAGE_SERVICE_ID/purge-cdn/*" \
  --header "Authorization: Bearer $USER_OR_ACCESS_TOKEN"
  ```

#### Purge Pattern Examples

<table className="w-full my-1.5 whitespace-nowrap">
  <thead>
    <tr>
      <th className="w-fit">Pattern</th>
      <th className="w-fit">Description</th>
      <th className="w-fit">Example</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td className="w-fit font-semibold">`/*`</td>
      <td className="w-fit">Purges all content</td>
      <td className="w-full">Useful after major updates</td>
    </tr>
    <tr>
      <td className="w-fit font-semibold">`/images/*`</td>
      <td className="w-fit">Purges all content in a directory</td>
      <td className="w-full">Clear all cached images</td>
    </tr>
    <tr>
      <td className="w-fit font-semibold">`/css/main.css$`</td>
      <td className="w-fit">Purges a specific file</td>
      <td className="w-full">Update a single CSS file</td>
    </tr>
    <tr>
      <td className="w-fit font-semibold">`/2023*`</td>
      <td className="w-fit">Purges content starting with pattern</td>
      <td className="w-full">Clear content with date prefix</td>
    </tr>
   </tbody>
</table>

:::warning Pattern Rules
- Wildcards (`*`) must be at the end of the pattern
- Specific files must include `$` at the end
- Nested wildcards (e.g., `/dir/*.jpg`) are not supported
:::

## API Reference

Zerops provides a comprehensive set of API endpoints to manage your CDN configuration and content. For complete information about base URLs, authorization, and general API usage, please refer to our [API specification](/references/api).

The endpoint links below will take you to the Swagger documentation with detailed request/response schemas and examples:

### CDN Management API

- **[Enable CDN for Storage ↗](https://api.app-prg1.zerops.io/api/rest/public/swagger/#/PublicServiceStack/EnableStorageCdn)** `PUT /api/rest/public/service-stack/{id}/cdn`
- **[Disable CDN for Storage ↗](https://api.app-prg1.zerops.io/api/rest/public/swagger/#/PublicServiceStack/DisableStorageCdn)** `DELETE /api/rest/public/service-stack/{id}/cdn`
- **[Create Object Storage with CDN ↗](https://api.app-prg1.zerops.io/api/rest/public/swagger/#/PublicServiceStackObjectStorage/CreateObjectStorageV1)** `POST /api/rest/public/service-stack/object_storage_v1`
- **[Create Domain Routing with CDN ↗](https://api.app-prg1.zerops.io/api/rest/public/swagger/#/PublicPublicHttpRouting/CreatePublicHttpRouting)** `POST /api/public/public-http-routing`
- **[Update Domain Routing with CDN ↗](https://api.app-prg1.zerops.io/api/rest/public/swagger/#/PublicPublicHttpRouting/UpdatePublicHttpRouting)** `PUT /api/public/public-http-routing/{id}`

### Cache Purge API

- **[Purge Storage Mode Cache ↗](https://api.app-prg1.zerops.io/api/rest/public/swagger/#/PublicServiceStack/PurgeStorageCdn)** `PUT /api/rest/public/service-stack/{id}/purge-cdn/{path}`
- **[Purge Static Mode Cache ↗](https://api.app-prg1.zerops.io/api/rest/public/swagger/#/PublicProject/PurgeStaticCdn)** `PUT /api/rest/public/project/{id}/purge-cdn/static/{domain}/{path}`
- **Purge Api Mode Cache *(Coming soon)***

## Troubleshooting

Having issues with your CDN? Here are solutions to the most common problems:

#### Content Not Updated After Changes
* **Issue:** You've updated content, but users still see the old version.
* **Possible Cause:** The CDN cache is continuing to serve the previously cached version.
* **Solution:**
    - Use the [purge API](#api-reference) with the specific content path
    - For immediate changes, use versioned file names (e.g., `style.v2.css` instead of just `style.css`)

#### Content Not Being Cached
* **Issue:** Your content isn't being cached by the CDN.
* **Possible Cause:** Missing public read permissions on objects.
* **Solution:**
    - For object storage: Check bucket and object access policies
    - Verify the object is accessible directly before attempting CDN access

:::note
Remember that only publicly accessible objects will be cached by the CDN. Private objects will always be fetched directly from the origin.
:::

#### Environment Variables Not Available
* **Issue:** You can't access the new CDN-related project level environment variables in your containers.
* **Possible Cause:** When new environment variables are created, existing services need to be restarted to access them. Services created before the CDN feature release require special handling.
* **Solution:**
    - For services created after CDN release: Restart the service to apply the new environment variables
    - For services created before CDN release: Add and then remove a dummy environment variable in the project settings adn restart the service

#### Unexpected 404 Errors
* **Issue:** Users receive 404 errors when accessing content via CDN.
* **Possible Cause:** Incorrect CDN URL formatting or missing content at origin.
* **Solution:**
    - Double-check your [URL structure](#) (pay attention to domain names and paths)
    - Verify content exists at the origin before attempting CDN access
    - Test accessing the content directly from origin first

**Correct URL patterns:**
- Object Storage: `https://storage.cdn.zerops.app/your-bucket/path/to/file`
- Static Mode: `https://static.cdn.zerops.app/your-domain.com/path/to/file`

---

*Need help implementing CDN in your project? Join our [Discord community](https://discord.gg/zeropsio) where our team and other Zerops users can assist you!*

----------------------------------------

# Features > Coding Agents


Zerops was built on the idea of **environment parity** — giving developers the full development lifecycle, from remote development to highly available production, with the observability and developer tools for maximum flexibility, and sensible defaults so the configs stay reasonable. Turns out that's **exactly what coding agents need** to produce and iterate on production-ready applications.

<div className="w-full flex justify-center my-4">
  <iframe
    width="560"
    height="315"
    src="https://www.youtube.com/embed/spdmTicsIgg?si=laZjTGhiytJRkqoJ"
    title="YouTube video player"
    frameBorder="0"
    allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share"
    referrerPolicy="strict-origin-when-cross-origin"
    allowFullScreen
    className="w-full max-w-[560px] aspect-video rounded-xl"
  />
</div>

## What is it

An **[MCP server](/zcp/overview)** for your agents — with an optional remote cloud development environment container to run them in — that makes use of the flexibility and processes Zerops provides. There's no "Zerops system prompt" hogging your context window. The MCP server is a thin layer that makes **your agent a Zerops platform power user** — when needed — so it understands:

- how networking, scaling, debugging, build & deployment, environment variables, and service provisioning work on the platform
- the development loop: start a dev server → implement → deploy to stage → verify

The depth of the platform underneath is what gives the agent room to actually work. A single agent can scaffold and iterate on projects with multiple runtimes (`app`, `api`, `worker`) backed by multiple [managed services](/features/infrastructure) (object storage `storage`, Postgres `db`, Elasticsearch `search`, NATS `broker`, Valkey `cache`) — just as easily as it can work on a simple Next.js presentational website.

A **[recipe ecosystem](https://app.zerops.io/recipes)** covering the most popular frameworks — pre-prepared for the whole lifecycle — gives the agent a baseline to start from, or a guide for setting up any stack on Zerops.

```text
  ┌─ ZCP MCP ────┐    ┌─ recipes for any stack ────────────────────────────────┐
  │              │    │                                                        │
  │  Claude Code │    │                                                        │
  │     Codex    │    │   Bun, Deno, Node.js, Go, Java, Python, Rust, Gleam    │
  │  Gemini CLI  ├───►│                                                        │
  │   opencode   │    │ Ruby, PHP, .NET, Laravel, Next.js, Nuxt, Astro, Svelte │
  │              │    │                                                        │
  └───────┬──────┘    │   React, Vue, Angular, Solid, Qwik, Analog, Nest.js    │
          │           │                                                        │
          │           │                                                        │
          │           └────────────────────────────────────────────────────────┘
          │
          │    zcp with agent has root ssh access to runtime services,
          │      runs dev server on dev, deploys to stage, verifies
          │
          ├───────────────────────────────────────────────────────────────┐
          │                                                               │
┌─ complex project ────────────────────────────────────────┐    ┌─ simple project ───┐
│         │                                                │    │         │          │
│         ▼                                                │    │         ▼          │
│  ┌────────────┐                                          │    │    ┌──────────┐    │
│  │    zcp     │                                          │    │    │   zcp    │    │
│  │   Ubuntu   │                                          │    │    │  Ubuntu  │    │
│  └────────────┘                                          │    │    └──────────┘    │
│                                                          │    │                    │
│  ┌────────────┐      ┌────────────┐      ┌────────────┐  │    │    ┌──────────┐    │
│  │   appdev   │      │   apidev   │      │ workerdev  │  │    │    │  appdev  │    │
│  │    Bun     │      │   Golang   │      │   Python   │  │    │    │ Node.js  │    │
│  └────────────┘      └────────────┘      └────────────┘  │    │    └──────────┘    │
│                                                          │    │                    │
│  ┌────────────┐      ┌────────────┐      ┌────────────┐  │    │    ┌──────────┐    │
│  │  appstage  │      │  apistage  │      │workerstage │  │    │    │ appstage │    │
│  │    Bun     │      │   Golang   │      │   Python   │  │    │    │ Node.js  │    │
│  └────────────┘      └────────────┘      └────────────┘  │    │    └──────────┘    │
│                                                          │    └────────────────────┘
│  ┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐  │
│  │   db   │ │ search │ │ broker │ │ cache  │ │storage │  │
│  │Postgres│ │Elastic │ │  NATS  │ │ Valkey │ │   S3   │  │
│  └────────┘ └────────┘ └────────┘ └────────┘ └────────┘  │
└──────────────────────────────────────────────────────────┘

```

:::tip[Platform-first, not agent-first]

Most coding-agent platforms went agent-first, then bolted on infrastructure — where it runs, how it reaches the database, how its output becomes production-ready, which third-party services to wire up. **Zerops went platform-first.** The complete development lifecycle existed before coding agents did; we taught them to operate it — **not just how to call APIs, but how to ship software the way a senior developer would.**

:::

## Main features

### Your agent, your subscription

ZCP supports multiple coding agents including Claude Code (Anthropic), Codex (OpenAI), Antigravity, and Grok Build. The container is a regular Ubuntu — install your own CLI tools, drop in your `.claude` / `.cursor` configs, attach your IDE over SSH. **Zerops doesn't resell tokens or proxy your model calls** — sign in with your own Anthropic / OpenAI / Google subscription and the agent talks to its provider directly.

### An ordinary Zerops project underneath

The agent operates inside a normal Zerops project — same shape as production. Managed databases (PostgreSQL, MariaDB, ClickHouse), key-value stores (KeyDB, Valkey), search (Elasticsearch, Meilisearch, Typesense), vector store (Qdrant), message queues (NATS, Kafka), object and shared storage, managed Nginx — all on a private network, addressable by hostname. The same pipeline that deploys here can deploy to a separate HA production project with no `zcp` service attached. Not a sandbox the work outgrows.

### Human ↔ agent handover

The agent and the human share the same workspace — same filesystem, same SSH key, same Cloud IDE in the browser, same remote-dev attach from your local IDE. Take over mid-session, set something up before the agent runs, debug in the same container the agent just left. Nothing reaches production until you merge the PR — the agent opens it, you gate it.

### Recipes for any stack

Runtimes for Bun, Deno, Node.js, Go, Python, Rust, Java, .NET, PHP, Elixir, Gleam — with curated recipes for the framework on top: Next.js, Nuxt, Astro, Svelte, React, Vue, Angular, Solid, Qwik, Analog, NestJS, Laravel, and more. Pick a recipe, select the **AI Agent** environment, and the project comes up with a working dev runtime, a stage runtime, the right managed services wired in, and a coding agent briefed on the Zerops surface.

## How it works in practice

The agent reaches your project's private network one of two ways:

- **Remote** — a `zcp` service deployed into the project runs the agent. You attach to it with your agent's IDE extension or terminal, with any IDE that supports remote development (Cursor, Windsurf, VS Code Remote), or by running [`zcli vpn up`](/references/networking/vpn) and ssh-ing into `zcp` to drive the rest of the project from a shell.
- **Local** — install the `zcp` MCP on your machine and run `zcli vpn up` to join the network. From there your IDE, agent, and shell can ssh directly into any container.

Either way, the agent reaches [managed services by hostname](/references/networking/internal-access) (`db:5432`, `cache:6379`), deploys through the [Zerops pipeline](/features/pipeline), and reads logs and events the same way you would.

**Remote (zcp service)**

```text
                      https://my-app.com
                               │
                               ▼
┌────────────────────────────────────────────────────────────┐
│        Zerops development project (private network)        │
│ ┌─────────────────┐  ┌──────────┐  ┌──────────┐            │
│ │ project ctrl    │  │  stats   │  │  logger  │            │
│ │ + L3 balancer   │  │          │  │          │            │
│ │ + firewall      │  │          │  │          │            │
│ └────────┬────────┘  └──────────┘  └──────────┘            │
│          │                                                 │
│ ┌────────┴────────┐                                        │
│ │   L7 balancer   │                                        │
│ │     (Nginx)     │                    control plane       │
│ └────────┬────────┘               ssh into other services  │
│          │                        dev runtime fs mounted   │
│          ├─────────────────┬─────────────────┐             │
│   ┌──────┴──────┐  ┌───────┴───────┐  ┌──────┴──────┐      │
│   │ appdev:3000 │  │ appstage:3000 │  │ zcp service │      │
│   │ dev runtime │  │ stage runtime │  │ agent + MCP │      │
│   └──────┬──────┘  └───────┬───────┘  └──────┬──────┘      │
│          │                 │                 │             │
│          └─────────────────┼─────────────────┘             │
│                            │                               │
│             ┌──────────────┴────────────┐                  │
│             │                           │                  │
│      ┌──────┴──────┐             ┌──────┴──────┐           │
│      │ db:5432     │             │ cache:6379  │           │
│      │ Postgres    │             │ Valkey      │           │
│      └─────────────┘             └─────────────┘           │
│                                                            │
└────────────────────────────────────────────────────────────┘
```

**Local (zcli vpn up)**

```text
                      https://my-app.com
                               │
                               ▼
┌────────────────────────────────────────────────────────────┐
│        Zerops development project (private network)        │
│ ┌─────────────────┐  ┌──────────┐  ┌──────────┐            │
│ │ project ctrl    │  │  stats   │  │  logger  │            │
│ │ + L3 balancer   │  │          │  │          │            │
│ │ + firewall      │  │          │  │          │            │
│ └────────┬────────┘  └──────────┘  └──────────┘            │
│          │                                                 │
│ ┌────────┴────────┐                                        │
│ │   L7 balancer   │                                        │
│ │     (Nginx)     │                                        │
│ └────────┬────────┘                                        │
│          │                                                 │
│          ├─────────────────┐                               │
│   ┌──────┴──────┐  ┌───────┴───────┐                       │
│   │ appdev:3000 │  │ appstage:3000 │                       │
│   │ dev runtime │  │ stage runtime │                       │
│   └──────┬──────┘  └───────┬───────┘                       │
│          │                 │                               │
│          └────────┬────────┘                               │
│                   │                                        │
│             ┌─────┴─────────────────────┐                  │
│             │                           │                  │
│      ┌──────┴──────┐             ┌──────┴──────┐           │
│      │ db:5432     │             │ cache:6379  │           │
│      │ Postgres    │             │ Valkey      │           │
│      └─────────────┘             └─────────────┘           │
│                                                            │
└──────────────────────────────▲─────────────────────────────┘
                               │
                               │ VPN tunnel
                               │
              ┌────────────────┴────────────────┐
              │ IDE / terminal                  │
              │ + agent                         │
              │ + zcp MCP                       │
              │                                 │
              │ $ curl zerops.io/zcp/install.sh │
              │ $ zcp init                      │
              │ $ zcli vpn up                   │
              └─────────────────────────────────┘
```

The agent runs through two workflows. **Bootstrap** settles which services and runtime targets the app needs. **Develop** is the short work loop — edit code on `appdev`, deploy to `appstage`, check it's reachable, verify behavior against `db:5432` and `cache:6379`, fix from evidence. A session ends with a URL you can open, or a specific blocker — failure category, attempts, what's still needed. Same hostnames, same managed services, same pipeline as production — just at smaller scale. See [Workflows in depth](/zcp/reference/agent-workflow) for both.

```text
    zcp (local or remote)
             │
             ▼
    edit code on appdev   ◀────────────────────────┐
       └ dev server, hot reload                    │
             │                                     │
             ▼                                     │
    deploy to appstage                             │
             │                                     │
             ▼                                     │
    check reachability                             │
             │                                     │
             ▼                                     │
    verify behavior   ─── fail ─────┐              │
             │                      │              │
             │ pass                 ▼              │
             ▼               read logs / events    │
    URL (proof)             fix from evidence ─────┘
```

Once the loop produces verified work, the agent doesn't push to production. It hands off — through whichever path your team uses: a tag push, a protected-branch merge, a manual `zcli` release, a pull request, or a CI job. **A human gates the release**, and the production deploy runs into a [separate production project](/zcp/security/production-policy) that has no `zcp` service at all.

```text
      Dev project                 GitHub                  Prod project

┌─────────────────────┐       ┌──────────────┐       ┌─────────────────────┐
│  appdev             │       │              │       │   app    (HA)       │
│  appstage           │       │  Pull        │       │                     │
│                     │ push  │  Request     │ CI/CD │   db     (HA)       │
│  db, cache          │ ────▶ │              │ ────▶ │                     │
│                     │       │  + human     │       │   cache  (HA)       │
│  zcp service        │       │    review    │       │                     │
│                     │       │              │       │   (no zcp service)  │
└─────────────────────┘       └──────────────┘       └─────────────────────┘
```

## Where does this fit in the agent landscape

With the model clear, here's where ZCP sits among adjacent tools. People say "agent infrastructure," "infra for Claude agents," "agent hosting," or "agent sandboxes" to mean different things — usually one of the categories below.

#### PaaS MCPs

_AWS MCP servers · Railway MCP · Fly.io MCP · Render MCP_

Most major PaaS providers have shipped an MCP — provision services, deploy code, list resources, read operational state. Great for "let my agent ship to my Railway account." These are *deploy and operate* surfaces, driven from outside the platform — and they reflect what's underneath: platforms optimized for day-one deploy that tuck the infrastructure behind a wall. Log and metric read tools landed across the category in 2025 (and AWS only just hit GA), but the **in-network, in-container** surface an agent needs to actually *develop* — hit Postgres from inside the network, follow a build live, drive the dev loop before it ships anything — is still on the other side of the wall.

#### Cloud VPS MCPs

_Hetzner Cloud MCP · DigitalOcean MCP · Linode MCP · raw SSH/server MCPs_

"Let your agent manage your Hetzner VPS." Two shapes cluster here: vendor-API MCPs (DigitalOcean ships an official one) that provision services from outside the box, and community-built SSH MCPs (Hetzner, Linode, Vultr) that give the agent shell access — provision it, SSH in, install Docker and Postgres and nginx, set up systemd units, point a domain at it. Maximum control, lowest cost, full Linux to play with. The same reason senior developers reach for managed platforms applies here: even if you *can* harden SSH, write nginx configs, tune `pg_hba.conf`, rotate TLS, set firewall rules, run fail2ban, and stay on top of CVEs across kernel, OpenSSL, Docker, Postgres, and nginx — you usually don't want to. Each layer is its own domain with its own gotchas, each is a security surface that drifts the moment you stop tending it, and every project becomes a snowflake. Hand that work to an agent and you also hand it the blast radius: misconfigured firewall, debug endpoint left open, port 5432 exposed to the internet, keys never rotated. ZCP is the inverse trade-off — the **guardrails** of a managed platform. Private networking, TLS, isolated services, safe defaults, managed backups, no exposed ports unless you opt in — all built in. The agent operates through [project-scoped MCP tools](/zcp/reference/mcp-operations) instead of `sudo` on a fresh Ubuntu box, so the mistakes that matter on a VPS aren't reachable from where it sits.

#### Cloud dev environments with AI

_GitHub Codespaces + Copilot Coding Agent · Ona (ex-Gitpod) · Coder_

A managed Linux container in the cloud with your editor and an AI assistant attached. Solves "where the agent runs" so state survives between sessions and machine setup stops being a question. The category itself is repositioning toward **governed agent runtimes** — Copilot Coding Agent (the productized successor to Workspace), Coder Agents, and Ona (Gitpod's rebrand after it shut down the SaaS in late 2025) all point the same way. The `zcp` service is the closest thing in this category — managed Linux container, Cloud IDE, your agent of choice — except it lives *inside* a Zerops project, addressing the project's runtimes, database, and cache by hostname, with deploys and logs as primitives the agent can call.

#### Bundled agent platforms

_Replit Agent · Lovable · Bolt.new · v0 · Devin_

The agent, the workspace, the stack, and (often) the hosting target are fused into one closed product. Fast for prototypes. Decisions are made for you. Switching agents usually means switching platforms, and production-grade primitives — a real dev/stage/prod release flow, private networking, observability — are **uneven** across this category: v0, Bolt, and Devin have moved upmarket with deploy/auth/DB primitives, others have not. **ZCP doesn't bundle**: the agent and model stay yours on your own subscription, and the platform underneath is normal Zerops with the full stack of managed services, networking, deploys, and observability.

#### Local coding agents

_Cursor · Windsurf · Zed · Claude Code · Codex · Antigravity · Grok Build · Aider · Cline_

The agent runs on your machine, edits your local checkout, runs local commands. Excellent at code changes. **MCP** is now native across these tools, so external reach — databases, networking, deploy targets, runtime logs — comes through plugins instead of bare hands. The agent still lives on your laptop, though: anything off-machine has to be reached, not *inhabited*. Install the ZCP MCP locally and run `zcli vpn up`, and any of these agents can now reach a real Zerops project alongside your local code: services addressed by hostname, deploys, logs, events.

#### Code-execution sandboxes

_E2B · Modal · Daytona · CodeSandbox SDK_

Mostly ephemeral Linux environments that AI *applications* spin up — often per request — to execute generated code safely (E2B, Modal). The right primitive when you're building a product that needs a model to run untrusted code and hand back the output. Some have pivoted toward **stateful, resumable agent workspaces** — Daytona now explicitly markets "every agent a computer," and CodeSandbox SDK's hibernation/resume sits between ephemeral and persistent. Still a different shape from ZCP; they show up here because the names cluster nearby.

#### Agent SDKs and frameworks

_Cloudflare Agents · Vercel AI SDK · Mastra · Claude Agent SDK_

Libraries for building and shipping agents to *your* users — tool calling, memory, orchestration, model providers, sometimes hosting. They're how somebody would build a product like ZCP, not where a coding agent runs against a project. Same disambiguation — adjacent on the shelf, different shape.

## Where to start

- [Quickstart](/zcp/quickstart) — AI Agent recipe, bundled coding agent, and a real product change in about five minutes.
- [ZCP MCP overview](/zcp/overview) — What the `zcp` MCP gives the agent, where it runs, and how a run ends in proof or a blocker.
- [Remote or local setup](/zcp/setup/choose-workspace) — Choose where the `zcp` MCP runs — inside Zerops with bundled tools, or beside your local editor.
- [Build and ship](/zcp/workflows/build-with-zcp) — Runtime layout, development, delivery, packaging, and production release.


----------------------------------------

# Features > Container Vs Vm


Ever wondered why container technologies like Docker took over the development world so quickly? Let's break down the real differences between traditional VMs and containers - and why you might want to use one over the other.

## Key Distinctions

**Containers** are like lightweight packages that contain just your app and what it needs to run, sharing resources with your main system.

**Virtual Machines** are like having a whole computer inside your computer. Complete with its own operating system, memory, and everything else.

### Why Developers Love Containers

#### They're Fast
- Start up in seconds (not minutes)
- Take up way less space
- You can run many more of them on the same hardware

#### They're Consistent
- Works on your machine? Will work on everyone's machine
- No more "but it works locally" problems
- Same environment from development to production

#### They're Simple
- Easy to share with your team
- Quick to update and modify
- Less configuration headaches

### When VMs Still Make Sense

Sometimes you actually want a full computer-within-a-computer:

- You need to run a completely different operating system
- You're dealing with legacy applications that need specific system configurations
- You require maximum isolation for security reasons

### Real-World Comparison

Think of it like this:
- **Containers** are like apartments in a well-managed building (shared infrastructure, efficient, but with some limitations)
- **VMs** are like having your own house (complete control, but with more overhead)

## Containers and VMs in Zerops

### Why Zerops Uses Both

At Zerops, we use **containers** as our primary runtime environment - they're fast, efficient, and perfect for most modern development workflows. We've optimized our container infrastructure to handle nearly every type of application you might need to run.

However, we also provide **VMs** when you need them, particularly for Docker-based workloads where the additional isolation is essential. Docker containers are a special case - in Zerops, they actually need to run inside VMs for proper security and isolation. While it's technically possible to run Docker in containers using privileged mode, this creates security vulnerabilities.

### When to Use What

<div className="grid grid-cols-1 md:grid-cols-2 gap-1 mt-1">
  <div className="flex-1">
  <h4 className="flex items-center gap-1 mb-0">
    Go with Containers when:
  </h4>
  <ul className="list-none p-0 m-0 flex flex-col gap-0.5">
      <li className="flex items-center gap-0.5">
        <div className="w-0.5 min-w-0.5 shrink-0 aspect-square rounded-full bg-gray-400 flex items-center justify-center scale-75" />
        <span>Building modern web applications</span>
      </li>
      <li className="flex items-center gap-0.5">
        <div className="w-0.5 min-w-0.5 shrink-0 aspect-square rounded-full bg-gray-400 flex items-center justify-center scale-75" />
        <span>Working with microservices</span>
      </li>
      <li className="flex items-center gap-0.5">
        <div className="w-0.5 min-w-0.5 shrink-0 aspect-square rounded-full bg-gray-400 flex items-center justify-center scale-75" />
        <span>Need quick deployment and vertical scaling</span>
      </li>
      <li className="flex items-center gap-0.5">
        <div className="w-0.5 min-w-0.5 shrink-0 aspect-square rounded-full bg-gray-400 flex items-center justify-center scale-75" />
        <span>Want efficient resource usage</span>
      </li>
  </ul>
  </div>
  <div className="flex-1">
  <h4 className="flex items-center gap-1 mb-0">
    Consider VMs when:
  </h4>
  <ul className="list-none p-0 m-0 flex flex-col gap-0.5">
      <li className="flex items-center gap-0.5">
        <div className="w-0.5 min-w-0.5 shrink-0 aspect-square rounded-full bg-gray-400 flex items-center justify-center scale-75" />
        <span>Running legacy applications</span>
      </li>
      <li className="flex items-center gap-0.5">
        <div className="w-0.5 min-w-0.5 shrink-0 aspect-square rounded-full bg-gray-400 flex items-center justify-center scale-75" />
        <span>Need complete OS isolation</span>
      </li>
      <li className="flex items-center gap-0.5">
        <div className="w-0.5 min-w-0.5 shrink-0 aspect-square rounded-full bg-gray-400 flex items-center justify-center scale-75" />
        <span>Require specific hardware access</span>
      </li>
      <li className="flex items-center gap-0.5">
        <div className="w-0.5 min-w-0.5 shrink-0 aspect-square rounded-full bg-gray-400 flex items-center justify-center scale-75" />
        <span>Need to run Docker containers</span>
      </li>
  </ul>
  </div>
</div>

### Resource Allocation

Both containers and VMs in Zerops can have guaranteed resources:
- Specific CPU cores
- Dedicated memory
- Controlled disk space

The difference isn't in resource guarantee capabilities, but rather in how these resources are managed and isolated.

## The Bottom Line

For most modern development work, containers are the way to go. They're faster, more efficient, and easier to work with. VMs still have their place, but unless you have a specific reason to use them, containers will usually make your life easier.

*Remember: The goal is to spend less time managing infrastructure and more time building great applications. Choose the tool that lets you do that most effectively.*

:::tip Pro Tip
Not sure which to choose? Start with containers. You can always switch to VMs if you discover you need them for specific use cases.
:::

----------------------------------------

# Features > Debug Mode


This document describes the debug mode configuration capabilities for service stacks in Zerops, allowing developers to pause execution at specific points during build and runtime processes for debugging purposes.

## Overview

Debug mode introduces control over two distinct phases of deployment:

- **Build phase** - When the `buildCommands` are executed
- **Runtime prepare phase** - When the `prepareCommands` are executed

For each phase, you can choose when to pause the execution:
- **Disable** - No pausing, execution proceeds normally
- **Before first command** - Execution stops before running any commands
- **After last command** - Execution stops after all commands complete
- **On command fail** - Execution stops when a command fails

Each phase can be configured with its own debug settings without affecting the other phase.

:::warning Important
The entire build process, including any time spent in debug mode, has a maximum duration of 60 minutes. After this time limit is reached, the build process is automatically cancelled.
:::

## Configuration

The debug mode configuration can be found in your service detail under the **Pipelines & CI/CD settings**.

## Debug Control

When execution is paused in debug mode, you have several commands available to control the debugging process. Each command serves a specific purpose and affects the deployment process differently.

### Debug Pause Points

There are three key points where execution can pause during deployment:
- ➠ **Disable** - Do not pause
- ↪ **Before First Command** - Paused before any commands run
- ✖ **On Command Failure** - Paused when a command fails
- ✔ **After Last Command** - Paused after all commands complete

### Available Commands

#### Continuing Execution
To proceed with the normal deployment process, use:
```bash
zsc debug continue
```

<table className="w-full my-1.5 whitespace-nowrap">
  <thead>
    <tr>
      <th className="">Pause Point</th>
      <th className="w-full">Behavior</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td className="w-fit">↪ <i>Before First Command</i></td>
      <td className="w-fit">Begins running commands for the current phase until next possible pause point</td>
    </tr>
    <tr>
      <td className="w-fit">✖ <i>On Command Failure</i></td>
      <td className="w-fit">Skips the failed command and continues deployment</td>
    </tr>
    <tr>
      <td className="w-fit">✔ <i>After Last Command</i></td>
      <td className="w-fit">Moves to the next phase (from build to runtime prepare) or completes deployment</td>
    </tr>
  </tbody>
</table>

#### Marking Success
To force a successful deployment status, use:
```bash
zsc debug success
```

<table className="w-full my-1.5 whitespace-nowrap">
  <thead>
    <tr>
      <th className="">Pause Point</th>
      <th className="w-full">Behavior</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td className="w-fit">↪ <i>Before First Command</i></td>
      <td className="w-fit">Ends current phase without running any commands</td>
    </tr>
    <tr>
      <td className="w-fit">✖ <i>On Command Failure</i></td>
      <td className="w-fit">Ignores the failure and ends current phase with success</td>
    </tr>
    <tr>
      <td className="w-fit">✔ <i>After Last Command</i></td>
      <td className="w-fit">Concludes current phase with a successful status</td>
    </tr>
  </tbody>
</table>

:::note
Requires valid `deployFiles` to work properly (fails otherwise).
:::

#### Forcing Failure
To terminate the deployment with a failure status, use:
```bash
zsc debug fail
```

<table className="w-full my-1.5 whitespace-nowrap">
  <thead>
    <tr>
      <th className="">Pause Point</th>
      <th className="w-full">Behavior</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td className="w-fit">↪ <i>Before First Command</i></td>
      <td className="w-fit">Marks current phase as failed without running commands</td>
    </tr>
    <tr>
      <td className="w-fit">✖ <i>On Command Failure</i></td>
      <td className="w-fit">Ends deployment with original error</td>
    </tr>
    <tr>
      <td className="w-fit">✔ <i>After Last Command</i></td>
      <td className="w-fit">Overwrites successful execution with failed status and ends deployment</td>
    </tr>
  </tbody>
</table>

Each phase can be configured independently to pause at any of the points described above, giving you precise control over your debugging workflow. The 60-minute timeout ensures deployments don't remain blocked indefinitely.

## Usage Examples

### Example 1: Debugging Build Failures

<table className="w-full my-1.5 whitespace-nowrap">
  <tbody>
    <tr>
      <td className="w-fit"><b>Build phase</b></td>
      <td className="w-fit">✖ <i>On Command Failure</i></td>
    </tr>
    <tr>
      <td className="w-fit"><b>Prepare runtime phase</b></td>
      <td className="w-fit">➠ <i>Disable</i></td>
    </tr>
  </tbody>
</table>

This configuration allows you to:
1. Inspect the container state after a failure
2. Make necessary adjustments
3. Use `zsc debug continue` to resume or `zsc debug fail` to abort

### Example 2: Validating Runtime Setup

<table className="w-full my-1.5 whitespace-nowrap">
  <tbody>
    <tr>
      <td className="w-fit"><b>Build phase</b></td>
      <td className="w-fit">➠ <i>Disable</i></td>
    </tr>
    <tr>
      <td className="w-fit"><b>Prepare runtime phase</b></td>
      <td className="w-fit">✔ <i>After Last Command</i></td>
    </tr>
  </tbody>
</table>

## Best Practices

#### Targeted Debugging
- Enable debug mode only for the specific phase you need to investigate
- This minimizes disruption to the deployment process
- Helps maintain clear debugging sessions

#### Clean Up
- Always remember to disable debug mode after completing your debugging session
- Set both phases to **Disable**
- Prevents unexpected pauses in future deployments

#### Production Consideration
- Be cautious when using debug mode in production environments
- Paused executions can block deployments
- Consider using separate development services for extended debugging sessions

#### Timeout Awareness
- Be mindful of the 60-minute maximum debug pause time (plan debugging sessions accordingly)

## Technical Considerations

- Debug mode settings persist until explicitly changed
- Build phase and runtime prepare phase operate independently
- Debug commands are only available when execution is paused
- Success signals require valid `deployFiles` to proceed

----------------------------------------

# Features > Env Variables


Zerops manages environment variables at two scopes: service level and project level. These variables are handled automatically without requiring `.env` files.

**On this page:** [Service Variables](#service-variables) · [Project Variables](#project-variables) · [Referencing Variables](#referencing-variables) · [Variable Isolation](#environment-variable-isolation) · [Restrictions](#variable-restrictions) · [Examples](#environment-variable-examples)

## Service Variables

Variables that are specific to individual [services](/features/infrastructure#services).

### User-Defined Variables

You can define service-level variables in two ways:

#### 1. Build & Runtime Variables

These variables are defined with `envVariables` attribute in the [build](/zerops-yaml/specification#envvariables-) or [run](/zerops-yaml/specification#envvariables--1) section of your `zerops.yaml` file and are accessible within their respective containers.

```yaml title="zerops.yaml"
...
  build:
    envVariables:
      DB_NAME: db
      DB_HOST: 127.0.0.1
      DB_USER: db
      DB_PASS: password
    ...
  run:
    envVariables:
      DB_NAME: db
      DB_HOST: 127.0.0.1
      DB_USER: db
      DB_PASS: password
```

See how to [reference variables](#referencing-variables) between services and between build and runtime environments. All variables must follow the [naming restrictions](#variable-restrictions).

:::note
Your application must be redeployed when updating environmental variables in `zerops.yaml`.
:::

#### 2. Secret Variables

For storing sensitive data you don't want in your source repository. They can be updated without redeployment (though services need to be reloaded).

Secret variables can be managed through:

##### GUI Interface

Navigate to service details and find **Environment variables** in the menu. You can:
- Add individual variables using the "Add secret variable" button
- Edit individual variables through the menu that appears on hover
- Use the bulk editor for managing multiple variables in .env format

##### Import Configuration

Create secret variables for a service with `envSecrets` attribute. See the complete [import.yaml structure](/references/import).

```yaml title="import.yaml"
services:
  ...
  envSecrets:
    S3_ACCESS_KEY_ID: 'your-secret-s3-key'
    S3_ACCESS_SECRET: 'your-s3-access-secret'
```

### System-Generated Variables

Zerops automatically generates variables based on service type.

These variables cannot be deleted and are always listed at the bottom of the environment variables page. Some are read-only (like `hostname`), while others can be edited (like `PATH`).

These variables can also be [referenced](#referencing-variables).

## Project Variables

Variables that apply across all services within a [project](/features/infrastructure#projects). These provide a way to share common configuration across services.

They work similarly to service secret variables but at project scope - they're managed through the GUI and can be updated without redeployment (though services need to be reloaded).

:::important
Project variables are **automatically inherited** by all services in the project — both in build and runtime environments. You do not need to [reference](#referencing-variables) them in your `zerops.yaml`.
:::

### User-Defined Variables

You can set project-wide variables through:

#### GUI Interface

Access **Project environment variables** in your project detail to:
- Add individual variables one by one
- Edit individual variables
- Use the bulk editor with .env format

#### Import Configuration

Create project variables with `envVariables` attribute. See the complete [import.yaml structure](/references/import).

```yaml title="import.yaml"
project:
  ...
  envVariables:
    LOG_LEVEL: info
    API_VERSION: v1
```

These variables will be automatically available in all services without any additional configuration.

### System-Generated Variables

Zerops automatically generates project-level variables that are also automatically available in all services.

### Overriding Project Variables

If you need a different value for a specific service, you can override a project variable by defining a service-level variable with the same key. See [Variable Precedence](#variable-precedence) for details on how conflicts are resolved.

```yaml title="zerops.yaml"
run:
  envVariables:
    LOG_LEVEL: debug  # Overrides the project-level LOG_LEVEL for this service only
```

## Environment Variable Isolation

A security feature that controls the **visibility** of environment variables across services within a project. This affects how [referencing variables](#referencing-variables) across services works.

By default, Zerops isolates environment variables between services to enhance security and prevent unintended access to sensitive information. This isolation can be configured at both project and service levels.

### Isolation Modes

Zerops supports two isolation modes:

<table className="w-full my-1.5">
  <thead>
    <tr>
      <th className="w-fit">Mode</th>
      <th className="w-fit">Description</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td className="w-fit whitespace-nowrap"><code>service</code></td>
      <td className="w-full"><strong>Default mode.</strong> Variables are isolated to their respective services. Services can only access their own variables and must explicitly reference variables from other services.</td>
    </tr>
    <tr>
      <td className="w-fit whitespace-nowrap"><code>none</code></td>
      <td className="w-full"><i>Legacy mode.</i> All variables from all services are automatically shared and accessible via prefixing.</td>
    </tr>
  </tbody>
</table>

### Configuring Isolation

#### Project-Level Isolation

Zerops automatically creates the `envIsolation` project variable with the default value `service`. You only need to modify this if you want to disable isolation:

```yaml title="import.yaml"
project:
  envIsolation: none  # Disables isolation, sharing all variables
```

This can also be set through the Project Environment Variables section in the GUI.

#### Service-Level Override

Individual services can override the project-level isolation setting:

```yaml title="import.yaml"
services:
  - hostname: db
    envIsolation: none  # This service's variables will be visible to all services
```

:::tip
You might set a database service to `envIsolation: none` to expose its connection details to other services, without having to manually reference them, while keeping the rest of your services isolated.
:::

:::note
In import YAML, `envIsolation` can also be nested under `envVariables`/`envSecrets`. (If both are present, the nested version takes precedence).
:::

### Accessing Variables Across Services

#### With Isolation Enabled (`service` mode)

When isolation is enabled, you must explicitly create reference variables to access variables from other services:

```yaml title="zerops.yaml"
# In the 'app' service:
run:
  envVariables:
    # Create a local reference to the 'password' variable from the 'db' service
    DB_PASSWORD: ${db_password}
```

This approach gives you complete control over which variables are shared between services.

#### With Isolation Disabled (`none` mode)

When isolation is disabled, variables are automatically available across all services with the service name prefix:

```yaml
# In any service, you can directly access:
${db_password}  # Accesses the 'password' variable from the 'db' service
```

### Best Practices for Variable Isolation

1. **Use Default Isolation**: Keep the default `service` isolation for enhanced security.
2. **Explicit References**: Create explicit references only for variables that need to be shared.
3. **Naming Conventions**: Use clear naming patterns for reference variables (e.g. `DB_PASSWORD` for a reference to `db_password`).
4. **Service-Level Exceptions**: Use service-level isolation overrides sparingly and only for services that need to expose their variables widely.

## Referencing Variables

You can reference other variables using the `${variable_name}` syntax. This is used to reference **service-level variables**, not project variables (which are already automatically inherited).

### Within Same Service

```yaml
envVariables:
  id: 42069
  hostname: app
  name: ${id}-${hostname}  # Results in: 42069-app
```

### Across Services

How this works depends on your [environment variable isolation](#environment-variable-isolation) setting:

**With Isolation Enabled** (`service` mode - default)

Create an explicit reference in the destination service:

```yaml
# In the 'app' service
envVariables:
  # Creating a reference to the 'connectionString' from 'dbtest' service
  dbConnection: ${dbtest_connectionString}
```

**With Isolation Disabled** (`none` mode)

Variables from other services are automatically injected into the container and available using the service prefix format `servicename_variablename`:

```yaml
# In any container, you can directly access variables from other services:
# ${dbtest_connectionString}
```

### Between Build and Runtime Environments

Build and runtime are two distinct environments in Zerops. Each environment can have its own set of variables, and you can use the same variable names in both environments since they are separate. Due to this separation, variables defined in one are not automatically accessible in the other.

To share variables between environments, you need to use specific prefixes:
- Use `RUNTIME_` prefix to access runtime variables during build
- Use `BUILD_` prefix to access build variables during runtime

```yaml title="zerops.yaml"
build:
  envVariables:
    API_KEY: ${RUNTIME_API_KEY}  # Using runtime variable during build
run:
  envVariables:
    API_KEY: "12345-abcde"       # Referenced in build with RUNTIME_ prefix
```

### Project Variables — No Reference Needed

[Project variables](#project-variables) are **automatically available** in all services. Do not use the `${...}` syntax to reference them:

```yaml
# ❌ Wrong - this shadows the project variable
envVariables:
  PROJECT_NAME: ${PROJECT_NAME}

# ✅ Correct - just use the project variable directly in your app
# It's already available without any configuration
```

If a project variable is named `LOG_LEVEL`, your application can read it directly — you don't need to add anything to your `zerops.yaml`.

## Variable Restrictions

All environment variables must follow these restrictions:

### Key
- Alphanumeric characters only (use `_` to separate words)
- Must be unique within their scope
- Case-sensitive

### Value
- ASCII characters only
- No EOL characters

## Variable Management

### Variable Precedence

When the same environment variable key exists in multiple places, Zerops follows these precedence rules:

1. Service-level variables take precedence over project variables
2. Within service-level:
   - Build/runtime variables override secret variables
   - Build and runtime containers are separate environments

## Environment Variable Examples

### Variable Isolation Example

Consider a project with three services: `api`, `db`, and `cache`:

```yaml title="Project structure"
project:
  name: my-project
services:
  - hostname: api
    envSecrets:
      # Creating explicit references to needed variables
      DB_CONNECTION: ${db_user}:${db_password}@${db_hostname}:${db_port}
      CACHE_URL: ${cache_hostname}:${cache_port}
  - hostname: db
    envSecrets:
      password: secureDbPassword
      user: dbuser
      port: 5432
  - hostname: cache
    envSecrets:
      password: cacheServerPass
      port: 6379
```

With this setup:
- The `api` service can only access the specific `db` and `cache` variables it explicitly references
- The `db` service cannot see any variables from `api` or `cache`
- The `cache` service cannot see any variables from `api` or `db`

If we changed the project's `envIsolation` to `none`, all services would be able to see all variables from all other services (prefixed with the service name).

*Need help? Join our [Discord community](https://discord.gg/zeropsio).*

----------------------------------------

# Features > Infrastructure


Zerops organizes your infrastructure into three hierarchical levels: **projects**, **services**, and **containers**. This structure provides secure networking, resource isolation, and scalable application deployment.

## Projects

A project is the top-level entity in Zerops, functioning as a private network where services can communicate internally and share environment variables. Each project provides essential infrastructure including load balancing, routing, and container orchestration.

### Key Project Features

- **Private Networking**: All services within a project share a secure network
- **Environment Variables**: Services can access shared environment variables
- **IPv6/IPv4 Addressing**: Each project receives an IPv6 address, with optional IPv4 addressing
- **Integrated Security**: Built-in firewall and SSL certificate management

:::tip Project Organization
Consider your project strategy carefully. Create separate projects for different environments (dev/staging/prod) or consolidate related applications in a single project to optimize resources and simplify networking.
:::

### Project Core Options

When you create a project, it requires a functioning **core** that includes logger and statistics services, HTTP routing with automatic SSL certificate management, and IP routing with integrated firewall.

Zerops offers two core types to match different needs and budgets:

#### Lightweight Core

Single-container solution perfect for development projects and smaller production workloads. Includes project controller, L3 balancer, firewall, logger, statistics, and HTTP handling in one efficient package.

:::tip Ideal For
Development environments, low-traffic applications, personal projects, budget-conscious teams.
:::

#### Serious Core

Enterprise-grade infrastructure with separated core services across multiple containers for true redundancy and high availability.

:::tip Ideal For
Production applications, high-traffic websites, mission-critical business applications, teams requiring maximum uptime.
:::

#### Features Comparison

<table className="w-full">
  <thead>
    <tr>
      <th className="w-fit"></th>
      <th className="w-fit"><strong>Lightweight Core</strong></th>
      <th className="w-fit"><strong>Serious Core</strong></th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td className="w-fit font-semibold">Infrastructure</td>
      <td className="w-fit">Single container (limited redundancy)</td>
      <td className="w-fit">Multi-container (highly available)</td>
    </tr>
    <tr>
      <td className="w-fit font-semibold">SSL Termination</td>
      <td className="w-fit"></td>
      <td className="w-fit"></td>
    </tr>
    <tr>
      <td className="w-fit font-semibold">Automatic Certificate Generation</td>
      <td className="w-fit"></td>
      <td className="w-fit"></td>
    </tr>
    <tr>
      <td className="w-fit font-semibold">Proxy / Load Balancer</td>
      <td className="w-fit"></td>
      <td className="w-fit"></td>
    </tr>
    <tr>
      <td className="w-fit font-semibold">IPv6 Address</td>
      <td className="w-fit"></td>
      <td className="w-fit"></td>
    </tr>
    <tr>
      <td className="w-fit font-semibold">Build Time</td>
      <td className="w-fit">15 hours</td>
      <td className="w-fit">150 hours</td>
    </tr>
    <tr>
      <td className="w-fit font-semibold">Backup Space</td>
      <td className="w-fit">5 GB</td>
      <td className="w-fit">25 GB</td>
    </tr>
    <tr>
      <td className="w-fit font-semibold">Egress</td>
      <td className="w-fit">100 GB</td>
      <td className="w-fit">3 TB</td>
    </tr>
    <tr>
      <td className="w-fit font-semibold">Failover Protection</td>
      <td className="w-fit">Limited</td>
      <td className="w-fit">Comprehensive</td>
    </tr>
  </tbody>
</table>

For detailed pricing information on both core types, visit our [pricing page](/company/pricing#project-core-plans).

#### Project Core Upgrade

You can upgrade from Lightweight Core to Serious Core for enhanced reliability and increased resources.

:::warning Important
The core upgrade is a **partially destructive process** that will temporarily disrupt your project's operations. Plan upgrades during maintenance windows.
:::

**What happens during upgrade:**
- All project logs and statistics will be lost (forwarded logs/statistics are not affected)
- Services will be network-unavailable during the process (avg. 35 seconds but can take longer)
- $10 project core fee will be charged upon upgrade
- Free project resources will reset to Serious Core limits
- Project IP addresses remain unchanged

:::important
If you encounter issues, **contact support immediately** and try running the process again.
:::

## Services

Services encapsulate your containers and provide specific functionality within a project. A project can contain unlimited services, each with its own purpose.

**Service types include:**
- Runtimes, Linux Containers & Docker
- Databases, Search Engines & Messages Brokers
- Storages
- *System services (needed for fully functioning project core)*

**Management options:**
- **Fully managed**: Zerops handles scaling, routing, and repairs automatically (Databases and Storages)
- **Partially managed**: You maintain control over certain management aspects (Runtimes)

Services within a project communicate via internal hostnames and can share environment variables for seamless integration.

## Containers

Containers are the most granular level of the Zerops architecture. Each service consists of one or more containers that work together to deliver functionality.

**Container deployment:**
- Single containers for simple applications
- Multiple containers for High Availability (HA) mode (e.g. fully managed MariaDB service in HA mode uses 3 containers for the database cluster and 2 for proxies)

**Container capabilities:**
- Use predefined images or custom configurations
- Can be exposed publicly via Zerops subdomains, custom domains, or public ports
- Operate within service resource constraints with automatic scaling

----------------------------------------

# Features > Local Remote Development


Zerops development is network-first. Keep your editor on your laptop, work fully inside Zerops, or use a native editor over SSH — in each case you join the same project-private network with the same hostnames, credentials, managed services, and deploy pipeline that staging and production use. What changes between environments is policy: credentials, resources, access rules, data, and release authority — not the platform underneath.

## How development on Zerops works

Every project ships with a private network. Services reach each other by hostname (`db:5432`, `api:3000`, `redis:6379`), with credentials injected as environment variables.

The development question is how you get onto that network. Three paths give you the same project-private reach, with different filesystem, tooling, and credential boundaries.

- **Local + VPN.** Your laptop joins the private network via WireGuard. Editor, toolchain, and processes stay where they are. A hosted workspace is not required.
- **Cloud IDE.** A Linux workspace in the project, accessed through VS Code Server in the dashboard. Zero local setup.
- **Native IDE over SSH.** SSH from your local VS Code, JetBrains Gateway, Cursor, or plain `ssh` into a workspace or directly into a runtime service container.

Switch paths without reprovisioning the project. A teammate on Local + VPN and another in the Cloud IDE are hitting the same `db:5432`.

```text
   Laptop + editor          Browser tab          Laptop + native IDE
          │                      │                        │
     zcli vpn up          VS Code Server             zcli vpn up
     (WireGuard)          on the project             + ssh apidev
          │                      │                        │
          └──────────────────────┴────────────────────────┘
                                 │
                                 ▼
         ┌─────────── project private network ───────────┐
         │                                               │
         │     api:3000      db:5432      cache:6379     │
         │                                               │
         └───────────────────────────────────────────────┘
```

## Local + VPN

**Best for:** keeping your existing editor, dotfiles, and toolchain — and offloading just the dependencies that are painful to run locally.

```bash
zcli vpn up <project-id>

psql "postgresql://app:secret@db:5432/myapp"
redis-cli -h cache -p 6379
ssh apidev
```

Your laptop can reach project services by hostname: Postgres, Valkey, S3-compatible storage, runtime containers, and any other service in the project. You can keep your normal dev loop and point it at `db:5432` instead of a local mock or Docker Compose dependency.

You do not need a hosted workspace, `zcli push`, or a new editor for this path.

**Source control.** Use git on your laptop the way you always have. Commits, pushes, SSH agent against GitHub, your existing credentials — nothing about Zerops sits between you and the remote.

:::info Complete VPN setup
See the [VPN reference guide](/references/networking/vpn).
:::

## Cloud IDE in Zerops

**Best for:** zero local setup, working from a machine that isn't yours, or wanting a pristine environment that doesn't touch your laptop.

A hosted workspace is a normal Zerops service in the project. It gives you a project-contained Linux environment with private-network access, optional Browser VS Code, `zcli`, git tooling, database CLIs, and shell utilities.

The workspace can also mount runtime service files, so you can inspect or edit code that runs in another container without moving it to your laptop:

```bash
ls /var/www/apidev
ls /var/www/frontenddev
vim /var/www/apidev/src/server.ts
```

The dev server in the runtime container hot-reloads, the database is the same `db:5432`, and staging deploys still go through the Zerops deploy pipeline.

The Cloud IDE itself is configurable. Two access methods:

- **VPN Only.** The IDE is reachable through `zcli vpn up`, no public exposure. Most secure.
- **Public Access.** The IDE is reachable on a `.zerops.app` subdomain, gated by an auto-generated password.

**Source control.** The hosted workspace isn't on your laptop, so your local SSH keys don't follow it. Two patterns work:

- **GitHub via `gh`.** The GitHub CLI is preinstalled. Run `gh auth login` once and `gh` handles HTTPS auth, PR creation, and review flows from the container.
- **Token in env vars.** Save a fine-grained personal access token to the workspace service's secret environment variables; `git` reads it through a credential helper.

Either pattern keeps your token in the workspace service, not in your project's source.

## Native IDE over SSH

**Best for:** native editor UX without carrying the toolchain or databases on your laptop.

Once `zcli vpn up` is connected, every container on the project's private network is reachable from your laptop over SSH. Any editor that speaks Remote SSH can use it: VS Code Remote SSH, JetBrains Gateway, Cursor, Zed, or plain `vim`.

```bash
ssh apidev               # any runtime service in the project
ssh frontenddev
```

In this path, a hosted workspace is convenient but not required. You can connect straight to `apidev`, edit the source there, and run the dev server in the same container. A hosted workspace is only a convenience layer when you want shared tools, runtime file mounts, or Cloud IDE.

**Source control.** SSH agent forwarding works the same way it does to any other machine. Add your local SSH key to your agent (`ssh-add`), and `git push` from inside `apidev` or the workspace service uses your laptop's GitHub key over the forwarded agent socket — no token storage required.

```ssh-config
# Local ~/.ssh/config
Host apidev.zerops
    HostName apidev
    ForwardAgent yes
```

:::info SSH access details
See the [SSH reference guide](/references/networking/ssh).
:::

## Picking a path

|                       | Local + VPN        | Cloud IDE                  | Native IDE over SSH               |
| --------------------- | ------------------ | -------------------------- | --------------------------------- |
| Editor runs           | Local              | Browser                    | Local                             |
| Toolchain             | Local              | Hosted workspace           | Hosted workspace or service container |
| Network entry         | WireGuard VPN      | Browser into the project   | WireGuard VPN, then SSH           |
| Hosted workspace required | No              | Yes                        | No (convenience)                  |
| Git auth              | Local credentials  | `gh` or token in env       | SSH agent forwarding              |
| Best for              | Keeping your setup | Disposable environments    | Native UX, lighter laptop         |
| Best for              | Keeping your setup | Disposable environments    | Native UX, lighter laptop         |

## Why this is not just a cloud IDE

If you've used GitHub Codespaces or Gitpod, Cloud IDE looks similar: a Linux container in the cloud, accessed from a browser or local IDE. Two structural differences matter.

**You don't have to be in the editor.** Codespaces and Gitpod are editor-first. Zerops is network-first. Cloud IDE is one way to reach the project's private network; `zcli vpn up` lets you skip the editor environment entirely and consume the project's managed services from your existing local setup. The hosted workspace itself is just another Zerops service — SSH in, install packages, run processes, configure it however you want.

**Your dev environment runs the same platform as production.** On a CDE, your dev container is one platform and the deployment target is another — making "works on my machine" a fact of life. On Zerops, dev Postgres, queue, cache, or object storage is the same managed service type the app meets later in stage and prod, on the same private network, with the same `zerops.yaml`. Policy differs across environments; the platform underneath doesn't.

## Where to start

- [VPN reference](/references/networking/vpn) — Connect your laptop to a Zerops project-private network.
- [SSH reference](/references/networking/ssh) — Use a native editor or shell over SSH.
- [Build & deploy pipeline](/features/pipeline) — Build and deploy from the same project model.
- [Infrastructure for Coding Agents](/features/coding-agents) — The sibling feature: agents working on Zerops projects through the same access model.


----------------------------------------

# Features > Pipeline


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: "Elixir", link: "/elixir/how-to/build-pipeline" },
    { name: "Deno", link: "/deno/how-to/build-pipeline" },
    { name: "Bun", link: "/bun/how-to/build-pipeline" },
    { name: "Gleam", link: "/gleam/how-to/build-pipeline" },
    { name: "Nginx", link: "/nginx/how-to/build-pipeline" }
]

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

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

## Configure the pipeline

Zerops provides a customizable build and runtime environment for your application. Start by adding a [zerops.yaml](/zerops-yaml/specification) file to the **root of your repository** and modify it to fit your application.

Here is a basic example for a Node.js application:

```yaml
zerops:
  - setup: api
    build:
      base: nodejs@20
      buildCommands:
        - npm i
        - npm run build
      deployFiles: ./dist
      cache: node_modules
    run:
      base: nodejs@20
      start: npm start
```

The zerops.yaml in your repository tells Zerops how to build and deploy your application. When the build & deploy pipeline triggers for the Node.js service named `api`, Zerops will:

1. Create a build environment with Node.js v.20 preinstalled
2. Run build commands: `npm i`, `npm run build`
3. Create a runtime environment with Node.js v.20 preinstalled
4. Deploy the built artifact from the `./dist` folder to runtime containers
5. Cache the `./node_modules` folder for faster subsequent builds
6. Start your application using `npm start`

Learn more about `zerops.yaml` parameters for your runtime:

## Trigger the pipeline

### Continuous deployment

Set up automatic builds triggered by Git events. You can establish continuous deployment in two ways:

* **New Service:** Create a new runtime service and connect it to your GitHub or GitLab repository during the service creation process.
* **Existing Services:** Go to the service detail and choose **Pipelines & CI/CD settings** from the left menu. Click **Connect with a GitHub repository** or **Connect with a GitLab repository** to link your repository.

Once connected, Zerops will automatically build and deploy your application with each push to the selected branch or when you create a new tag.

### On-demand deployment

Trigger builds and deployments manually when needed using either the CLI or GUI.

#### Using Zerops CLI

- **Build and deploy:** `zcli service push` - Uploads code and triggers the full pipeline
- **Deploy only:** `zcli service deploy` - Skips build, deploys pre-built artifacts

See [CLI commands documentation](/references/zcli/commands#service-operations) for all parameters.

#### Using Zerops GUI

In **Pipelines & CI/CD settings** section of your service detail:

- **Re-deploy last pipeline** - With optional secret env variable updates
- **Trigger new pipeline** - From git repo or with custom configuration

#### Using Import YAML

Add `buildFromGit: <repo-url>` to your service configuration for one-time build during import. See [Import YAML documentation](/references/import#service-basic-configuration).

## Build phase

Zerops starts a temporary build container and executes these steps:

1. **Install build environment** - Sets up the runtime and tools
2. **Download source code** - From [GitHub ↗](https://www.github.com), [GitLab ↗](https://www.gitlab.com) or via [Zerops CLI](/references/cli)
3. **Customize environment** - Runs optional preparation commands
4. **Execute build commands** - Compiles and packages your application
5. **Upload artifacts** - Stores build output in internal Zerops storage
6. **Cache files** - Optionally [caches](/features/build-cache) selected files for faster future builds

Zerops automatically deletes the build container after the build finishes or fails.

### Build hardware resources

All runtime services use the same hardware resources for build containers:

<table className="w-fit my-1.5">
  <thead>
    <tr className="text-center rounded-lg">
      <th className="w-fit"><strong>HW resource</strong></th>
      <th className="w-fit"><strong>Minimum</strong></th>
      <th className="w-fit"><strong>Maximum</strong></th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td className="w-fit font-semibold">CPU cores</td>
      <td className="w-fit">1</td>
      <td className="w-fit">5</td>
    </tr>
    <tr>
      <td className="w-fit font-semibold">RAM</td>
      <td className="w-fit">8 GB</td>
      <td className="w-fit">8 GB</td>
    </tr>
    <tr>
      <td className="w-fit font-semibold">Disk</td>
      <td className="w-fit">1 GB</td>
      <td className="w-fit">100 GB</td>
    </tr>
  </tbody>
</table>

Build containers start with minimum resources and scale vertically up to maximum capacity as needed.

:::info
Build container resources are not charged. Build costs are covered by the standard Zerops [project fee](https://zerops.io/#pricing).
:::

### Build time limit

The entire build pipeline has a **1 hour** time limit. After 1 hour, Zerops terminates the build pipeline and deletes the build container.

### Customize the build environment

All runtime services start with a default build environment based on the [build.base](/zerops-yaml/specification#base-) attribute in `zerops.yaml`. Install additional packages or tools by adding [build.prepareCommands](/zerops-yaml/specification#preparecommands-) to your configuration.

Learn more about customizing build environments:

## Runtime prepare phase (optional)

When your application requires additional system packages, libraries, or tools in the runtime environment, Zerops allows you to build a custom runtime image. This optional phase occurs after the build phase and before deployment.

### When to use custom runtime images

Build custom runtime images when you need:
- System packages or libraries for runtime operations (e.g., `sudo apk add imagemagick` for image processing)
- Library dependencies for interpreted languages or dynamically linked binaries
- System-level tools or utilities your application requires
- Customized base operating system or additional software layers

### Configuration

Configure custom runtime images in your `zerops.yml` file using these fields:

#### `run.os` + `run.base`

Specify the operating system and base packages for your custom runtime image:

```yaml
run:
  os: alpine # or ubuntu
  base: nodejs@20 # specify your runtime and version
```

#### `run.prepareCommands`

Define commands that customize your runtime image. These commands run inside a fresh base container:

```yaml
run:
  prepareCommands:
    - sudo apk add --no-cache imagemagick
    - sudo apt-get update && apt-get install -y some-package  # for Ubuntu
```

:::note
`run.prepareCommands` run in the `/home/zerops` directory.
:::

Zerops creates the custom runtime image from this container after all commands complete successfully.

#### `build.addToRunPrepare`

Copy specific files from the build phase to the runtime prepare phase. This is useful when you need source files during runtime preparation:

```yaml
build:
  addToRunPrepare:
    - package.json
    - requirements.txt
    - config/runtime-setup.sh
```

These files are packed immediately after `build.buildCommands` finish and become available during the runtime prepare phase.

### How it works

When you trigger the first deploy with defined [run.prepareCommands](/zerops-yaml/specification#preparecommands--1), Zerops:

1. **Creates prepare container** - Based on `run.os` and `run.base`
2. **Copies build files** - Files specified in [build.addToRunPrepare](/zerops-yaml/specification#addtorunprepare-) (if any)
3. **Runs prepare commands** - Executes [run.prepareCommands](/zerops-yaml/specification#preparecommands--1) in order
4. **Creates runtime image** - Builds custom runtime image from the prepared container
5. **Uses for deployment** - Deploys your application using this custom runtime image

### Custom runtime image caching

Zerops caches custom runtime images to optimize deployment times. The runtime prepare phase is skipped and cached images are reused when:

- It is not the first deployment of your service
- None of these `zerops.yaml` fields changed since the last deployment:
  - `run.os` or `run.base`
  - `run.prepareCommands`
  - `build.addToRunPrepare`
- File contents specified in `build.addToRunPrepare` remain unchanged
- The custom runtime image cache hasn't been manually invalidated

#### Manual cache invalidation

To invalidate the custom runtime image cache, go to your service detail in the Zerops GUI, choose **Pipelines & CI/CD settings** section from the left menu, and click on the button under **Pipeline #**. Then click on the **Clear runtime prepare image** button.

Learn more about building custom runtime images:

:::warning
Do not include your application code in the custom runtime image, as your built application code is deployed automatically into fresh containers.

Shared storage mounts are also not available during the runtime prepare phase.
:::

## Deploy phase

### Application artifacts

After the [build phase](#build-phase) completes, Zerops stores the application artifact in internal storage and deletes the build container.

For [manual deployments](#manual-deploy-using-zerops-cli) using Zerops CLI, the application artifact is also uploaded to internal storage.

Zerops uses the stored artifact to deploy identical versions of your application whenever a new container starts:

- During new application version deployments
- When applications [scale horizontally](/features/scaling#horizontal-scaling-runtime-services-linux-containers-and-docker)
- When runtime containers fail and new containers start automatically

### First deploy

For initial deployments, Zerops starts one or more runtime containers based on your service [auto scaling settings](/features/scaling).

Zerops executes these steps for each new container:

1. **Install runtime environment** - Sets up the runtime (or uses a custom runtime image if configured)
2. **Download application artifact** - Retrieves build output from internal storage
3. **Run initialization** - Executes optional [init commands](/zerops-yaml/specification#initcommands-)
4. **Start application** - Launches your app using the [start command](/zerops-yaml/specification#startcommands-)
5. **Check readiness** - Waits for [readiness check](/zerops-yaml/specification#readinesscheck-) to succeed (if configured)
6. **Activate container** - Container becomes active and receives incoming requests

Services with multiple containers deploy in parallel.

:::info
If your application needs initialization in each runtime container, add [init commands](/zerops-yaml/specification#initcommands-) to `zerops.yaml`.
:::

:::caution
Do not use `initCommands` for runtime environment customization. See [how to build custom runtime images](#runtime-prepare-phase-optional).
:::

### Subsequent deploys

For applications with existing running versions, Zerops starts new containers matching the count of existing containers.

Zerops executes the same steps as the first deployment for each new container. Your service briefly contains both new and old versions during this process.

Old containers are then removed from the project balancer to stop receiving new requests. The processes inside old containers terminate and Zerops gradually deletes all old containers.

### Readiness checks

If your application is not ready to handle requests immediately after starting via the [start command](/zerops-yaml/specification#startcommands-), configure a [readiness check](/zerops-yaml/specification#readinesscheck-) in your `zerops.yaml`.

When readiness checks are defined, Zerops:

1. **Starts your application**
2. **Performs readiness check**
3. **Waits and retries** - If check fails, waits 5 seconds and repeats step 2
4. **Activates container** - If check succeeds, marks container as active

Runtime containers with pending readiness checks do not receive incoming requests - only active containers handle traffic.

If readiness checks fail for 5 minutes, Zerops marks the container as failed, deletes it, creates a new container, and repeats the deployment process.

**Readiness check types:**

- `httpGet` - Succeeds when URL returns HTTP `2xx` status (5-second timeout, follows `3xx` redirects)
- `exec.command` - Succeeds when command returns status code 0 (5-second timeout)

Read the [runtime log](/nodejs/how-to/logs#runtime-log) to troubleshoot failed readiness checks.

## Manual deploy using Zerops CLI

Start deploy-only pipelines using the [Zerops CLI](/references/cli). The [`zcli service deploy`](/references/zcli/commands#deploy) command uploads and deploys your application in Zerops. Use this when you have your own build process. For building applications in Zerops, use [continuous](#continuous-deployment) or [on-demand](#on-demand-deployment) deployment instead.

```sh
Usage:
  zcli service deploy pathToFileOrDir [flags]

Flags:
      --archive-file-path string   If set, zCLI creates a tar.gz archive with the application code in the required path relative
                                 to the working directory. By default, no archive is created.
      --deploy-git-folder          If set, the .git folder is also uploaded with the deploy. By default, the .git folder
                                 is ignored.
  -h, --help                     the service deploy command.
      --project-id string         If you have access to more than one project, you must specify the project ID for which the
                                 command is to be executed.
      --service-id string         If you have access to more than one service, you must specify the service ID for which the
                                 command is to be executed.
      --version-name string       Adds a custom version name. Automatically filled if the VERSIONNAME environment variable exists.
      --working-dir string        Sets a custom working directory. Default working directory is the current directory. (default "./")
      --zerops-yaml-path string    Sets a custom path to the zerops.yaml file relative to the working directory. By default zCLI
                                 looks for zerops.yaml in the working directory.
```

`pathToFileOrDir` defines paths to directories and/or files relative to the working directory. The working directory defaults to the current directory and can be changed using the `--working-dir` flag.

Place `zerops.yaml` in the working directory.

:::info
You can modify the deploy pipeline anytime by updating the `zerops.yaml` in your working directory.
:::

## Manage builds and deployments

### Cancel running build

When you need to cancel an incorrect running build, use the Zerops GUI. Go to the service detail, open the running processes list, and click **Open pipeline detail**. Then click **Cancel build**.

:::caution
Build cancellation is only available before the build pipeline finishes. Once the build completes, deployment cannot be cancelled.
:::

### Application versions

Zerops keeps the 10 most recent versions of your application in internal storage.

Access the application versions list in Zerops GUI by going to service detail and choosing the **Pipelines & CI/CD settings** section from the left menu. The active version is highlighted - click the button below to show all archived versions.

Access pipeline details from the additional menu. Pipeline details contain:

- Pipeline configuration (`zerops.yaml`) used for the selected version
- Build log (if available)
- Prepare runtime log (if available)

You can download the build artifact for selected versions or manually delete inactive versions.

### Restore an archived version

Restore archived versions by choosing **Activate** from the additional menu. Zerops will deploy the selected version and archive the currently active version.

Environment variables restore to their state from the last moment when the selected version was active.

----------------------------------------

# Features > Rbac


Zerops provides granular access control through a role-based permission system, allowing you to precisely manage who can access and modify your organization's resources. This system operates at two levels: **organization-wide roles** and **per-project role overrides**.

## Core Concepts

When a user performs an action on a project or its resources, Zerops first checks for a project-specific role override. If none exists, the organization role applies:

#### Organization Role
The primary role assigned to a user, determining their **default permissions** across the entire organization and all its projects.

#### Project Role Override
An optional per-project permission that **supersedes the organization role** for that specific project and its resources (services, containers, environment variables, routing, etc.).

## User Roles

Zerops supports four user roles, listed from highest to lowest permission level:

<table className="w-full my-1.5">
    <thead>
    <tr>
        <th className="w-fit font-semibold">Role</th>
        <th className="w-fit font-semibold">Organization Access</th>
        <th className="w-fit font-semibold">Default Project Access</th>
        <th className="w-fit font-semibold">Can Create Projects</th>
        <th className="w-fit font-semibold">Can Manage Team</th>
    </tr>
    </thead>
    <tbody>
    <tr>
        <td className="w-fit"><strong>Owner</strong></td>
        <td className="w-fit">Full (incl. billing)</td>
        <td className="w-fit">Full</td>
        <td className="w-fit">✓</td>
        <td className="w-fit">All roles</td>
    </tr>
    <tr>
        <td className="w-fit"><strong>Admin</strong></td>
        <td className="w-fit">Full (excl. billing)</td>
        <td className="w-fit">Full</td>
        <td className="w-fit">✓</td>
        <td className="w-fit">Developer, Guest</td>
    </tr>
    <tr>
        <td className="w-fit"><strong>Developer</strong></td>
        <td className="w-fit">None</td>
        <td className="w-fit">None (per-project only)</td>
        <td className="w-fit">✓</td>
        <td className="w-fit">✗</td>
    </tr>
    <tr>
        <td className="w-fit"><strong>Guest</strong></td>
        <td className="w-fit">None</td>
        <td className="w-fit">None (per-project only)</td>
        <td className="w-fit">✗</td>
        <td className="w-fit">✗</td>
    </tr>
    </tbody>
</table>

### Owner

:::note
Every organization must have at least one Owner at all times.
:::

The **Owner** role has unrestricted access to all organization resources:

- Full access to billing, invoices, and payment management
- Can invite, edit, and remove users of any role
- Automatic *Full access* to all projects
- Can create unlimited projects
- Minimum access level on any project is *Read only*

### Admin

The **Admin** role provides comprehensive access without billing permissions:

- Cannot view or manage billing information
- Can invite, edit, and remove users with Developer or Guest roles only
- Cannot manage other Admins or Owners
- Automatic *Full access* to all projects
- Can create unlimited projects
- Minimum access level on any project is *Read only*

### Developer

The **Developer** role is designed for team members who need to work on specific projects:

- No access to organization-level settings
- No default access to any projects — access must be granted per-project
- Can create new projects (automatically receives full access to projects they create)
- Cannot invite or manage other team members

### Guest

The **Guest** role provides the most restricted access:

- No access to organization-level settings
- No default access to any projects — access must be granted per-project
- Cannot create new projects
- Cannot invite or manage other team members

## Project Access Levels

When granting project access (either as a default for Owners/Admins or as an override for any role), two permission levels are available:

### Full Access

Users with full access to a project can:

- Start, stop, and restart services
- Deploy applications
- Create, edit, and delete services
- Manage environment variables (including sensitive variables)
- Access logs, metrics, and service status
- Use SSH web terminal and file browser
- Create and manage VPN key pairs
- Download backups and deployed code
- Manage project settings and routing
- Delete the project

### Read Only

Users with read-only access to a project can:

- View project structure and service status
- View logs and metrics
- View deployment history
- View non-sensitive environment variables
- View backup existence and metadata
- View VPN public keys (but not create new key pairs)

Users with read-only access **cannot**:

- Make any changes to project configuration
- Start, stop, or deploy services
- Access SSH web terminal or file browser
- Download backups or deployed code
- View sensitive environment variables (displayed as `REDACTED`)
- Create VPN key pairs

:::info Coming Soon
**Sensitive Environment Variables**: You will soon be able to mark specific environment variables as sensitive. These variables will be stored encrypted and hidden from users with read-only access, providing additional security for credentials and secrets.
:::

## Managing Team Members

Access team management at **Organization → Team**.

### Inviting New Members

1. Navigate to the Team section
2. Click **Invite Member**
3. Enter the user's email address
4. Select their organization role (Owner, Admin, Developer, or Guest)
5. Send the invitation

If the email belongs to an existing Zerops account, they'll receive an invitation to join your organization. If not, they'll be invited to create an account and will set up their password upon accepting.

### Editing Member Permissions

You can modify a team member's permissions in two ways:

**From the Team section**:
- Edit the user's organization role
- Configure their access to all projects at once

**From Project Settings**:
- Manage access for all users to that specific project
- Useful when onboarding a team to a new project

### Role Change Restrictions

- Users cannot modify their own role
- Admins can only modify users with Developer or Guest roles
- A user cannot be demoted if they have integration tokens with higher permissions — those tokens must be modified or deleted first
- At least one Owner must exist in the organization at all times

## Project Role Overrides

Project role overrides allow you to customize access for specific projects without changing a user's organization-wide role.

### Common Use Cases

**Restricting Admin access to production**:
An Admin who should have full access to development projects but only read-only access to production can have a Read only override set on the production project.

**Granting Developer access to specific projects**:
A Developer (who has no default project access) can be granted Full access to the projects they work on, while remaining unable to see other projects.

**Temporary project access for Guests**:
A Guest user (perhaps an external contractor) can be granted Read only or Full access to specific projects for the duration of their engagement.

### How Overrides Work

:::note
Owners and Admins cannot be set to "No access" on any project — the minimum override available for these roles is Read only.
:::

<table className="w-full my-1.5">
    <thead>
    <tr>
        <th className="w-fit"><strong>Organization Role</strong></th>
        <th className="w-fit"><strong>Without Override</strong></th>
        <th className="w-fit"><strong>With Full Access Override</strong></th>
        <th className="w-fit"><strong>With Read Only Override</strong></th>
    </tr>
    </thead>
    <tbody>
    <tr>
        <td className="w-fit">Owner</td>
        <td className="w-fit">Full access</td>
        <td className="w-fit">Full access</td>
        <td className="w-fit">Read only</td>
    </tr>
    <tr>
        <td className="w-fit">Admin</td>
        <td className="w-fit">Full access</td>
        <td className="w-fit">Full access</td>
        <td className="w-fit">Read only</td>
    </tr>
    <tr>
        <td className="w-fit">Developer</td>
        <td className="w-fit">No access</td>
        <td className="w-fit">Full access</td>
        <td className="w-fit">Read only</td>
    </tr>
    <tr>
        <td className="w-fit">Guest</td>
        <td className="w-fit">No access</td>
        <td className="w-fit">Full access</td>
        <td className="w-fit">Read only</td>
    </tr>
    </tbody>
</table>

## Integration Tokens

Integration tokens provide programmatic access to the Zerops API, ideal for CI/CD pipelines, automation scripts, and third-party integrations.

### Token Access Levels

<table className="w-full my-1.5">
    <thead>
    <tr>
        <th className="w-fit"><strong>Token Type</strong></th>
        <th className="w-fit"><strong>Description</strong></th>
    </tr>
    </thead>
    <tbody>
    <tr>
        <td className="w-fit"><strong>Full access to all projects</strong></td>
        <td className="w-fit">Can perform all operations on all current and future projects</td>
    </tr>
    <tr>
        <td className="w-fit"><strong>Read access to all projects</strong></td>
        <td className="w-fit">Can view all projects and their resources, but cannot make changes</td>
    </tr>
    <tr>
        <td className="w-fit"><strong>Custom access per project</strong></td>
        <td className="w-fit">No default access; each project must be explicitly added with Full or Read only permission</td>
    </tr>
    </tbody>
</table>

### Creating Tokens

Access token management at **Settings → Access Tokens Management**.

1. Click **Create Token**
2. Enter a descriptive name for the token
3. Select the access level
4. If using custom per-project access, add each project and set its permission level
5. Create the token

:::warning
The token value is displayed only once upon creation. Store it securely — you cannot retrieve it later.
:::

### Token Permission Constraints

Tokens cannot have higher permissions than the user who creates them:

<table className="w-full my-1.5">
    <thead>
    <tr>
        <th className="w-fit"><strong>Your Role</strong></th>
        <th className="w-fit"><strong>Available Token Types</strong></th>
    </tr>
    </thead>
    <tbody>
    <tr>
        <td className="w-fit">Owner</td>
        <td className="w-fit">Full access, Read access, Custom per project</td>
    </tr>
    <tr>
        <td className="w-fit">Admin</td>
        <td className="w-fit">Full access, Read access, Custom per project</td>
    </tr>
    <tr>
        <td className="w-fit">Developer</td>
        <td className="w-fit">Custom per project only</td>
    </tr>
    <tr>
        <td className="w-fit">Guest</td>
        <td className="w-fit">Custom per project only</td>
    </tr>
    </tbody>
</table>

### Managing Tokens

:::note
Admins can manage tokens created by Developers and Guests, but cannot manage tokens created by other Admins or Owners.
:::

- **View**: Owners and Admins can see all tokens; Developers and Guests can only see their own tokens
- **Edit**: A token's name, access level, or per-project permissions can be modified at any time
- **Regenerate**: Creates a new token value while preserving all settings (the old token immediately stops working)
- **Delete**: Permanently removes the token

---

## API Access & Advanced Configuration

The Zerops API provides additional flexibility beyond what's available in the dashboard. This section covers capabilities accessible only through the API.

:::info
For complete API documentation, see the [Zerops OpenAPI Specification](/references/api).
:::

### Backend Role System

The API uses a more granular role system than the dashboard interface:

<table className="w-full my-1.5">
    <thead>
    <tr>
        <th className="w-fit"><strong>Dashboard Role</strong></th>
        <th className="w-fit"><strong>API Role Code</strong></th>
        <th className="w-fit"><strong>Notes</strong></th>
    </tr>
    </thead>
    <tbody>
    <tr>
        <td className="w-fit">Owner</td>
        <td className="w-fit"><code>OWNER</code></td>
        <td className="w-fit">Includes <code>canViewFinances</code>, <code>canEditFinances</code>, and <code>canCreateProjects</code> flags (always enabled)</td>
    </tr>
    <tr>
        <td className="w-fit">Admin</td>
        <td className="w-fit"><code>ADMIN</code></td>
        <td className="w-fit">Includes <code>canCreateProjects</code> flag (always enabled)</td>
    </tr>
    <tr>
        <td className="w-fit">Developer</td>
        <td className="w-fit"><code>NO_ACCESS</code></td>
        <td className="w-fit">With <code>canCreateProjects: true</code></td>
    </tr>
    <tr>
        <td className="w-fit">Guest</td>
        <td className="w-fit"><code>NO_ACCESS</code></td>
        <td className="w-fit">With <code>canCreateProjects: false</code></td>
    </tr>
    <tr>
        <td className="w-fit">—</td>
        <td className="w-fit"><code>BASIC_USER</code></td>
        <td className="w-fit">Available via API only</td>
    </tr>
    <tr>
        <td className="w-fit">—</td>
        <td className="w-fit"><code>READ_ONLY</code></td>
        <td className="w-fit">Available via API only</td>
    </tr>
    </tbody>
</table>

### Additional Roles (API Only)

**BASIC_USER**
- Can view all projects (unless overridden to `NO_ACCESS`)
- Can perform all project operations (start/stop services, deploy, view logs, etc.)
- Cannot delete projects
- Cannot create projects without the `canCreateProjects` flag
- Cannot manage team members

**READ_ONLY**
- Can view all projects (unless overridden to `NO_ACCESS`)
- Cannot make any changes
- Cannot access SSH terminal, file browser, or VPN key creation
- Cannot download backups or deployed code
- Sensitive environment variables displayed as `REDACTED`

### Permission Flags

The API supports additional permission flags that can be set on any user regardless of role:

<table className="w-full my-1.5">
    <thead>
    <tr>
        <th className="w-fit"><strong>Flag</strong></th>
        <th className="w-fit"><strong>Description</strong></th>
    </tr>
    </thead>
    <tbody>
    <tr>
        <td className="w-fit"><code>canViewFinances</code></td>
        <td className="w-fit">Allows viewing billing information, invoices, and payment sources</td>
    </tr>
    <tr>
        <td className="w-fit"><code>canEditFinances</code></td>
        <td className="w-fit">Allows modifying billing information and processing payments (automatically enables <code>canViewFinances</code>)</td>
    </tr>
    <tr>
        <td className="w-fit"><code>canCreateProjects</code></td>
        <td className="w-fit">Allows creating new projects (user receives <code>OWNER</code> role on projects they create)</td>
    </tr>
    </tbody>
</table>

These flags enable scenarios like:
- An Admin who needs to view (but not edit) billing information
- A Developer who should be able to create projects but also view invoices
- A read-only user who monitors billing status

### Project Role Overrides via API

The API allows setting any role as a project override, including `NO_ACCESS`:

```yaml
# Example: Set NO_ACCESS override for a user on a specific project
PUT /api/rest/public/client-user/{id}/roles
{
  "projectRoleList": [
    {
      "projectId": "{projectId}",
      "roleCode": "NO_ACCESS"
    }
  ]
}
```

This enables scenarios not possible through the dashboard, such as hiding specific projects from users who would otherwise have access based on their organization role.

### Role Resolution Logic

When determining a user's effective permissions for a project:

1. Check if a project-specific role override exists
2. If yes, use that role for all project-related operations
3. If no, use the organization role

For non-project operations (billing, team management), only the organization role applies.


----------------------------------------

# Features > Scaling


Zerops delivers enterprise-grade infrastructure with built-in automatic scaling and high availability. This means applications and databases dynamically adjust to traffic demands—scaling up during peak loads to maintain performance and scaling down during quiet periods to reduce costs.

Unlike traditional hosting where resources must be predicted and pre-provisioned, Zerops continuously monitors workloads and automatically allocates exactly what is needed, when it is needed. This intelligent resource management ensures optimal performance without wasted spend.

## Key Benefits

- **Cost Optimization**: Only pay for resources actually used
- **Performance Reliability**: Maintain responsiveness during traffic spikes
- **Automatic Management**: Built-in best practices with customizable settings
- **High Availability**: Redundancy options for production environments

## Understanding Zerops Scaling Architecture

Zerops uses two fundamentally different approaches for optimizing infrastructure:

#### **Resource Management (Vertical Scaling)**
- **Applies to:** Runtime services, databases, shared storage, and Linux containers (Alpine and Ubuntu)
- **What it does:** Adjusts CPU, RAM, and disk resources within individual containers
- **Management:** Automated by Zerops, but customizable by users

:::note
Docker services do not support automatic vertical scaling. Resource values can be manually changed, but this triggers a VM restart.
:::

#### **Container Architecture**
- **For Runtime Services, Linux Containers, and Docker:** Horizontal Scaling (dynamic container count)
  - Adds or removes containers/VMs based on load
  - Requires applications to be designed for HA operation
  - Container/VM creation limits can be controlled
  - Docker containers run in VMs rather than native containers

- **For Databases & Shared Storage:** High Availability Mode (fixed container count)
  - Single Container OR Multi-Container HA configuration
  - Must be chosen at service creation (cannot be changed later)
  - Managed by Zerops (no application changes needed)

### At-a-Glance Comparison

* ✓ = Available *(configurable, defaults vary according to service type)*
<table className="w-full my-1.5">
  <thead>
    <tr>
      <th className="">Feature</th>
      <th className="">Runtime Services & Linux Containers</th>
      <th className="">Databases</th>
      <th className="">Shared Storage</th>
      <th className="">Docker</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td className="w-fit font-semibold whitespace-nowrap">Automatic Resource Scaling</td>
      <td className="w-fit text-center">✓</td>
      <td className="w-fit text-center">✓</td>
      <td className="w-fit text-center">✓</td>
      <td className="w-fit text-center">Manual (triggers VM restart)</td>
    </tr>
    <tr>
      <td className="w-fit font-semibold whitespace-nowrap">Automatic Horizontal Scaling</td>
      <td className="w-fit text-center">✓</td>
      <td className="w-fit text-center">Fixed # of containers</td>
      <td className="w-fit text-center">Fixed # of containers</td>
      <td className="w-fit text-center">✓</td>
    </tr>
    <tr>
      <td className="w-fit font-semibold whitespace-nowrap">High Availability</td>
      <td className="w-fit text-center">User-implemented</td>
      <td className="w-fit text-center">Zerops-managed HA mode</td>
      <td className="w-fit text-center">Zerops-managed HA mode</td>
      <td className="w-fit text-center">User-implemented</td>
    </tr>
  </tbody>
</table>

## When to Configure Scaling

You can configure scaling settings at three different stages:

- **During service creation** - Configure initial scaling parameters when creating services in the Zerops GUI. Set resource limits, CPU mode, and container counts from the start.

- **During import** - Use YAML configuration files to define comprehensive scaling settings including `verticalAutoscaling` parameters and horizontal scaling limits. See [Import & Export YAML Configuration](/references/import) for complete syntax.

- **After service creation** - Modify most scaling settings anytime through your service's **Automatic scaling configuration** page. Note that some parameters like deployment mode for databases and shared storage cannot be changed after creation.

This flexibility lets you plan scaling strategies upfront or adapt them as requirements evolve.

## Part 1: Resource Management

Resource management in Zerops focuses on efficiently allocating and adjusting CPU, RAM, and disk resources within individual containers based on actual usage patterns.

These resource management capabilities apply to **runtime** services, **databases**, **shared storage**, and **Linux containers** (Alpine and Ubuntu).

:::note
Docker services do not support automatic vertical scaling. Resources for Docker services are fixed at the values set manually and do not automatically adjust based on usage.
:::

:::tip Disable Scaling for Specific Resources
To prevent automatic scaling of specific resources, simply set identical minimum and maximum values for CPU, RAM, or Disk.
:::

### CPU Settings

#### CPU Mode

Two CPU allocation modes are available for any service:

**Shared CPU**

Shared CPU provides a physical CPU core shared with up to 10 other applications. Performance varies depending on neighbors, ranging from 1/10 to 10/10 power. This option is cost-effective for non-critical workloads, development, and testing environments.

**Dedicated CPU**

Dedicated CPU gives exclusive access to a full physical CPU core(s), ensuring consistent and predictable performance. This option is ideal for production environments and CPU-intensive applications.

:::tip
CPU mode can be changed (once per hour) as needed.
:::

See the [pricing](/company/pricing#resource-pricing) for the difference between CPU modes.

#### Minimum and Maximum CPU Cores

Set boundaries for CPU core allocation. Zerops will scale CPU resources within these limits based on actual usage.

#### Start CPU Core Count

Determines how many CPU cores are allocated when containers start:
- Default: 2 cores
- Applies to both dedicated and shared CPU modes
- Higher values provide more processing power during application initialization
- After startup, resources are automatically adjusted based on actual usage and limits

#### CPU Scaling Thresholds

For services using [dedicated CPU](#cpu-mode) only, CPU scaling is controlled by:

**Min. Free CPU Cores (%)**
- Scale-up is triggered when free capacity drops below a fixed fraction of a single CPU core
- Default: 10%
- Set as a percentage of a single core's capacity
- Example: Setting to 20% means that with one core, at least 20% of that core should remain free

**Dynamic Min. Free Total Core Percent**
- Scale-up is triggered when total free capacity across all cores falls below a percentage of total capacity
- Default: 0% (disabled)
- Dynamically adjusts as the number of cores changes
- Ideal for accommodating varying load distributions
- Example: 20% setting ensures at least 20% of the combined capacity of all cores remains free

### RAM Settings

#### Minimum and Maximum RAM

Set boundaries for RAM allocation. Zerops will scale RAM within these limits based on actual usage.

#### RAM Scaling Thresholds

RAM usage is monitored every 10 seconds to ensure optimal performance. The minimum free RAM settings serve multiple important purposes: they prevent Out of Memory (OOM) errors, provide space for kernel disk caching (which improves application performance), and maintain a buffer for sudden memory demands.

Swap is enabled for all containers to help prevent OOM errors, but proper minimum free RAM configuration is still essential—especially for services that use large amounts of RAM or benefit from kernel disk caching. Without sufficient free memory, performance may degrade due to increased disk access.

Two threshold types determine RAM scaling:

**Minimum Free RAM (absolute value in GB)**
- Specifies an absolute threshold for free RAM
- Additional memory is triggered when available RAM falls below this fixed amount
- Default: 0.0625 GB (64 MB) for most services
- Ideal for maintaining system stability and responsiveness

**Minimum Free RAM (% of Granted)**
- Establishes a dynamic threshold based on a percentage of total granted memory
- Default: 0% (disabled)
- The buffer scales proportionally as total memory increases
- Particularly useful for handling varying loads

:::note
Whichever setting provides more free memory is used.
:::

[Video: /vids/ram-scaling.webm](/vids/ram-scaling.webm)

### Disk Settings

#### Minimum and Maximum Disk

Set boundaries for disk space allocation. Zerops will scale disk space within these limits based on actual usage.

### Resource Scaling Behavior

Zerops implements an exponential growth pattern ensuring that **resources grow gradually** for minor load increases but can scale rapidly when significant additional capacity is needed. When resource usage triggers scaling, Zerops initially adds smaller increments, but as demand continues to increase, it can add larger increments to quickly meet the needs of your application.

Below are the parameters that control this behavior across all services that support vertical scaling:

- **Data Collection Interval:** How frequently resource usage metrics are collected
- **Scale-Up Window Interval:** The timeframe in which high usage must persist before adding resources
- **Scale-Down Window Interval:** The timeframe in which low usage must persist before reducing resources
- **Scale-Up Threshold Percentile:** The usage percentile that triggers resource scaling up
- **Scale-Down Threshold Percentile:** The usage percentile that triggers resource scaling down
- **Minimum Step:** The smallest increment by which resources can increase during scaling
- **Maximum Step:** The largest possible increment for resources when scaling rapidly under high load

<table className="w-full my-1.5">
  <thead>
    <tr>
      <th className="">Parameter</th>
      <th className="">CPU</th>
      <th className="">RAM</th>
      <th className="">Disk</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td className="w-fit font-semibold">Data Collection Interval</td>
      <td className="w-fit">10 seconds</td>
      <td className="w-fit">10 seconds</td>
      <td className="w-fit">10 seconds</td>
    </tr>
    <tr>
      <td className="w-fit font-semibold">Scale-Up Window Interval</td>
      <td className="w-fit">20 seconds</td>
      <td className="w-fit">10 seconds</td>
      <td className="w-fit">10 seconds</td>
    </tr>
    <tr>
      <td className="w-fit font-semibold">Scale-Down Window Interval</td>
      <td className="w-fit">60 seconds</td>
      <td className="w-fit">120 seconds</td>
      <td className="w-fit">300 seconds</td>
    </tr>
    <tr>
      <td className="w-fit font-semibold">Scale-Up Threshold Percentile</td>
      <td className="w-fit">60</td>
      <td className="w-fit">50</td>
      <td className="w-fit">50</td>
    </tr>
    <tr>
      <td className="w-fit font-semibold">Scale-Down Threshold Percentile</td>
      <td className="w-fit">40</td>
      <td className="w-fit">50</td>
      <td className="w-fit">50</td>
    </tr>
    <tr>
      <td className="w-fit font-semibold">Minimum Step</td>
      <td className="w-fit">1 (0.1 cores)</td>
      <td className="w-fit">0.125 GB</td>
      <td className="w-fit">0.5 GB</td>
    </tr>
    <tr>
      <td className="w-fit font-semibold">Maximum Step</td>
      <td className="w-fit">40</td>
      <td className="w-fit">32 GB</td>
      <td className="w-fit">128 GB</td>
    </tr>
  </tbody>
</table>

## Part 2: Container Architecture — Service-Specific Approaches

Container architecture in Zerops defines how services are distributed across containers. Different service types use fundamentally different approaches:

1. **Horizontal Scaling** (Runtime Services, Linux Containers, and Docker)
2. **Deployment Modes** (Databases and Shared Storage)

### Horizontal Scaling (Runtime Services, Linux Containers, and Docker)

Horizontal scaling adds or removes entire containers (or VMs for Docker) as demand fluctuates.
* When vertical scaling reaches its defined maximum, new containers/VMs are automatically added to handle additional load.
* As demand decreases, containers/VMs are gradually removed to optimize resource usage.

:::important HA-ready Applications
For applications to work properly across multiple containers, they must be designed to be HA-ready.
:::

#### Setting Horizontal Scaling Parameters

To configure horizontal scaling, users need to set the minimum and maximum number of containers:

- **Minimum Containers**: The baseline number of containers that should always be running (system limit: 1)
- **Maximum Containers**: The upper limit of containers that can be created during high demand (system limit: 10)

:::tip Disable Horizontal Scaling
Setting identical minimum and maximum values creates a fixed number of containers (disables automatic horizontal scaling).
:::

### Deployment Modes (Databases and Shared Storage)

For databases and shared storage services, Zerops offers two deployment modes focused on reliability and data integrity.

:::warning
Deployment mode cannot be changed after creation.
:::

#### Single Container Mode

Single Container Mode provides one container with vertical scaling only. This is suitable for development environments or non-critical data storage.

**Characteristics:**
- Limited redundancy
- No automatic recovery if the container fails
- Data since last backup (if available) may be lost if failure occurs
- Cost-effective for non-production environments

#### Highly Available (HA) Mode

Highly Available (HA) Mode creates multiple containers with built-in redundancy. This mode is strongly recommended for production environments and mission-critical data.

**Characteristics:**
- Multiple containers distributed across different physical machines
- Automatic failover and recovery mechanisms
- Data redundancy and integrity protection
- Higher reliability and availability
- Recommended for production use

:::important
Database and shared storage services in HA mode have a **fixed number of containers** that cannot be increased or decreased.
:::

**Recovery process:**

In HA mode, when a container or physical machine fails, recovery is handled automatically:

1. The failed container is disconnected from the cluster
2. A new container is created on a different physical machine
3. Data is synchronized from remaining healthy copies
4. The failed container is removed
5. Service continues with minimal disruption

[Video: /vids/database-scaling.webm](/vids/database-scaling.webm)

### Fixed Resource Allocation (Docker Services)

Docker services in Zerops operate differently from other service types:

#### Docker Service Characteristics

- **VM-Based Deployment**: Docker services run in virtual machines rather than containers
- **Fixed Resources**: Unlike other services, Docker services do not support automatic vertical scaling
- **User-Defined Resources**: Resources are set at creation and remain fixed until manually changed
- **VM Count Changes**: The number of VMs can be changed, but this requires a VM restart
- **No Automatic Scaling**: Resource levels do not automatically adjust based on usage

**Important Considerations for Docker Services:**
- Initial resource values should be chosen carefully, as they cannot automatically scale
- Planning for expected peak loads is important when setting resource values
- Runtime services or Linux containers should be considered instead if dynamic scaling is essential
- VM restarts cause temporary service disruption when changing VM count or resources

:::warning
Docker services use fixed resources that do not automatically scale. Sufficient resources should be allocated at creation to handle expected workload. Additionally, disk space for Docker services can only be increased, not decreased without recreation of the service.
:::

## Monitoring Your Infrastructure

Zerops provides comprehensive monitoring tools in the user interface to track both resource usage and container scaling activities:

### Resource History Graphs

Resource and container scaling can be visualized over time:
- CPU utilization per container
- RAM usage patterns
- Disk space consumption
- Container count changes

These graphs help understand application resource needs, identify usage patterns, and fine-tune scaling settings for optimal performance and cost efficiency.

[Video: /vids/containers.webm](/vids/containers.webm)

## Troubleshooting

#### Resource-Related Issues (All Service Types Except Docker)

**Out of Memory Errors**
* **Issue:** Application crashes with OOM errors despite resource scaling.
* **Possible Cause:** Insufficient minimum free RAM setting.
* **Solution:**
    - Increase the "Minimum free RAM" setting
    - Check for memory leaks in the application
    - Consider setting a higher minimum RAM value

**Excessive Resource Costs**
* **Issue:** Resources scaling up but not scaling down efficiently.
* **Possible Cause:** Scale-down thresholds not optimized.
* **Solution:**
    - Review usage patterns in monitoring graphs
    - Adjust scale-down thresholds to be more aggressive
    - Set appropriate resource minimums based on base requirements

#### Runtime Service and Linux Container Issues (Horizontal Scaling)

**Application Not Working Properly Across Multiple Containers**
* **Issue:** Application errors or inconsistent behavior when horizontally scaled.
* **Possible Cause:** Application not designed for distributed operation.
* **Solution:**
    - Ensure the application properly handles stateless operation
    - Implement proper session management across containers
    - Review and modify application code to support multiple instances

#### Docker Service Issues

**Insufficient Resources for Workload**
* **Issue:** Docker service experiencing performance issues or crashes.
* **Possible Cause:** Fixed resources inadequate for actual workload.
* **Solution:**
    - Since Docker services don't support automatic vertical scaling, a new service with higher resource allocations may be needed
    - Consider migrating to a runtime service or Linux container if dynamic resource scaling is needed

*Need help implementing scaling in your project? Join our [Discord community](https://discord.gg/zerops) where our team and other Zerops users can assist you!*

----------------------------------------

# Gleam > How To > Build Pipeline


Zerops provides a customizable build and runtime environment for your Gleam application.

## Add zerops.yaml to your repository

Start by adding `zerops.yaml` file to the **root of your repository** and modify it to fit your application:

```yaml
zerops:
  # define hostname of your service
  - setup: app
    # ==== how to build your application ====
    build:
      # REQUIRED. Set the base technology for the build environment:
      base: gleam@latest

      # OPTIONAL. Set the operating system for the build environment.
      # os: ubuntu

      # OPTIONAL. Customise the build environment by installing additional packages
      # or tools to the base build environment.
      # prepareCommands:
      #   - sudo apt-get something
      #   - curl something else

      # OPTIONAL. Build your application
      buildCommands:
        - npm i
        - npm run build

      # REQUIRED. Select which files / folders to deploy after
      # the build has successfully finished
      deployFiles:
        - dist
        - package.json
        - node_modules

      # OPTIONAL. Which files / folders you want to cache for the next build.
      # Next builds will be faster when the cache is used.
      cache: node_modules

    # ==== how to run your application ====
    run:
      # OPTIONAL. Sets the base technology for the runtime environment:
      base: gleam@latest

      # OPTIONAL. Sets the internal port(s) your app listens on:
      ports:
        # port number
        - port: 3000

      # OPTIONAL. Customise the runtime Gleam environment by installing additional
      # dependencies to the base Gleam runtime environment.
      # prepareCommands:
      #   - sudo apt-get something
      #   - curl something else

      # OPTIONAL. Run one or more commands each time a new runtime container
      # is started or restarted. These commands are triggered before
      # your Gleam application is started.
      # initCommands:
      #  - rm -rf ./cache

      # REQUIRED. Your Gleam application start command
      start: npm start
```

The top-level element is always `zerops`.

### Setup

The first element `setup` contains the **hostname** of your service. A runtime service with the same hostname must exist in Zerops.
Zerops supports the definition of multiple runtime services in a single `zerops.yaml`. This is useful when you use a monorepo. Just add multiple setup elements in your `zerops.yaml`:

```yaml
zerops:
  # definition for app service
  - setup: app
    # optional
    build: ...
    # optional
    deploy: ...
    # required
    run: ...

  # definition for api service
  - setup: api
    # optional
    build: ...
    # optional
    deploy: ...
    # required
    run: ...
```

Each service configuration contains at least the `run` section. Optional `build` and `deploy` sections can be added to further customize your process.

## Build pipeline configuration

### base

_REQUIRED._ Sets the base technology for the build environment.

Following options are available for Gleam builds:

- `gleam@1.5`, `gleam@1`, `gleam@latest`

```yaml
zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build:
      # REQUIRED. Sets the base technology for the build environment:
      base: gleam@latest
      ...
```

<p>
  The base build environment contains {data.alpine.default}, the selected
  major version of Gleam, [Zerops command line tool](/references/cli), `npm`, `yarn`, `git` and `npx` tools.
</p>

:::info
You can change the base environment when you need to. Just simply modify the `zerops.yaml` in your repository.
:::

If you need to install more technologies to the build environment, set multiple values as a yaml array. For example:

```yaml
zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build:
      # REQUIRED. Sets the base technology for the build environment:
      base:
        - gleam@latest
      prepareCommands:
        - zsc add go@latest
      ...
```

See the full list of supported [build base environments](/zerops-yaml/base-list#runtime-services).

To customise your build environment use the [prepareCommands](#preparecommands) attribute.

:::note
Modifying the base technology will invalidate your build cache. See our [Build Cache Documentation](/features/build-cache) for more details about cache invalidation.
:::

### os

_OPTIONAL._ Sets the operating system for the build environment.

Following options are available:

- `alpine`
- `ubuntu`

Default value is `alpine`.

We are currently using following os version:

- <span>{data.alpine.default}</span>
- <span>{data.ubuntu.default}</span>

:::caution
The os version is fixed and cannot be customised.
:::

:::note
Changing the OS setting will invalidate your build cache. See our [Build Cache Documentation](/features/build-cache) for details about cache behavior.
:::

### prepareCommands

_OPTIONAL._ Customises the build environment by installing additional dependencies or tools to the base build environment.

The base build environment contains:

- <span>{data.alpine.default}</span>
- selected version of Gleam defined in the [base](#base) attribute
- [Zerops command line tool](/references/cli)
- `npm`, `yarn`, `git` and `npx` tools

To install additional packages or tools add one or more prepare commands:

```yaml
zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build:
      # REQUIRED. Set the base technology for the build environment:
      base: gleam@latest

      # OPTIONAL. Customise the build environment by installing additional packages
      # or tools to the base build environment.
      prepareCommands:
        - sudo apt-get something
        - curl something else
      ...
```

When the first build is triggered, Zerops will

1. create a build container
2. download your application code from your repository
3. run the prepare commands in the defined order

The application code is available in `/build/source` before the prepare commands are triggered, so you can use any file from your repository in your prepare commands (e.g. a configuration file). The commands themselves run in the `/home/zerops` directory.

:::note
These commands are skipped when using cached environment. Modifying `prepareCommands` will invalidate your build cache. See our [Build Cache Documentation](/features/build-cache) for details about cache invalidation.
:::

#### Command exit code

If any command fails, it returns an exit code other than 0 and the build is canceled. Read the [build log](/gleam/how-to/logs#build-log) to troubleshoot the error. If the command ends successfully, it returns the exit code 0 and Zerops triggers the following command. When all prepare commands are finished, your custom build environment is ready for the build phase.

#### Single or separated shell instances

You can configure your prepare commands to be run in a single shell instance or multiple shell instances. The format is identical to [build commands](#buildcommands).

### buildCommands

_OPTIONAL._ Defines build commands.

```yaml
zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build:
      # REQUIRED. Set the base technology for the build environment:
      base: gleam@latest

      # OPTIONAL. Build your application
      buildCommands:
        - npm i
        - npm run build
      ...
```

Build commands are optional. Zerops triggers each command in the defined order in a dedicated build container, running from the `/build/source` directory.

Before the build commands are triggered the build container contains:

1. base environment defined by the [base](#base) attribute
2. optional customisation of the base environment defined in the [prepareCommands](#preparecommands) attribute
3. your application code

#### Run build commands as a single shell instance

Use following syntax to run all commands in the same environment context. For example, if one command changes the current directory, the next command continues in that directory. When one command creates an environment variable, the next command can access it.

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

#### Run build commands as a separate shell instances

When the following syntax is used, each command is triggered in a separate environment context. For example, each shell instance starts in the home directory again. When one command creates an environment variable, it won't be available for the next command.

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

#### Command exit code

If any command fails, it returns an exit code other than 0 and the build is canceled. Read the [build log](/gleam/how-to/logs#build-log) to troubleshoot the error. If the error log doesn't contain any specific error message, try to run your build with the --verbose option.

```yaml
buildCommands:
  - npm i --verbose
  - npm run build
```

If the command ends successfully, it returns the exit code 0 and Zerops triggers the following command. When all `buildCommands` are finished, the application build is completed and ready for the deploy phase.

### deployFiles

_REQUIRED._ Selects which files or folders will be deployed after the build has successfully finished. To filter out specific files or folders, use [`.deployignore`](#deployignore) file.

```yaml
# REQUIRED. Select which files / folders to deploy after
# the build has successfully finished
deployFiles:
  - dist
  - package.json
  - node_modules
```

Determines files or folders produced by your build, which should be deployed to your runtime service containers.

The path starts from the **root directory** of your project (the location of `zerops.yaml`). You must enclose the name in quotes if the folder or the file name contains a space.

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

#### Examples

Deploys a folder, and a file from the project root directory:

```yaml
deployFiles:
  - dist
  - package.json
```

Deploys the whole content of the build container:

```yaml
deployFiles: .
```

Deploys a folder, and a file in a defined path:

```yaml
deployFiles:
  - ./path/to/file.txt
  - ./path/to/dir/
```

#### How to use a wildcard in the path

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

Deploys all folders that are located in any path that begins with `/path/to/`

```yaml
deployFiles: ./path/to/~/
```

Deploys all folders that are located in any path that begins with `/path/` and ends with `/to/`

```yaml
deployFiles: ./path/~/to/
```

:::note Example
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 will be cached for the next build.

```yaml
# OPTIONAL. Which files / folders you want to cache for the next build.
# Next builds will be faster when the cache is used.
cache: file.txt
```

The cache attribute helps optimize build times by preserving specified files between builds.

The cache attribute supports the [~ wildcard character](#how-to-use-a-wildcard-in-the-path).

Learn more about the [build cache system](/features/build-cache) in Zerops.

### envVariables

_OPTIONAL._ Defines the environment variables for the build environment.

Enter one or more env variables in following format:

```yaml
zerops:
  # define hostname of your service
  - setup: app
    # ==== how to build your application ====
    build:
      base: gleam@latest
        …

      # OPTIONAL. Defines the env variables for the build environment:
      envVariables:
        NODE_ENV: production
        DB_NAME: db
        DB_HOST: db
        DB_USER: db
        DB_PASS: ${db_password}
```

Read more about [environment variables](/gleam/how-to/env-variables) in Zerops.

## Runtime configuration

### base

_OPTIONAL._ Sets the base technology for the runtime environment.
If you don't specify the `run.base` attribute, Zerops keeps the current Gleam version for your runtime.

Following options are available for Gleam runtimes:

- `gleam@1.5`, `gleam@1`, `gleam@latest`

```yaml
zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build:
      # REQUIRED. Sets the base technology for the build environment:
      base: gleam@latest
      ...

    # ==== how to run your application ====
    run:
      # OPTIONAL. Sets the base technology for the runtime environment:
        base: gleam@latest
      ...
```

<p>
  The base runtime environment contains {data.alpine.default}, the
  selected major version of Gleam, Zerops command line tool, `npm`, `yarn`, `git` and `npx` tools.
</p>

:::info
You can change the base environment when you need to. Just simply modify the `zerops.yaml` in your repository.
:::

If you need to install more technologies to the runtime environment, set multiple values as a yaml array. For example:

```yaml
zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build:
      # REQUIRED. Sets the base technology for the build environment:
      base: gleam@latest
      ...

    # ==== how to run your application ====
    run:
      # OPTIONAL. Sets the base technology for the runtime environment:
      base:
        - gleam@latest
      prepareCommands:
        - zsc add go@latest
      ...
```

See the full list of supported [run base environments](/zerops-yaml/base-list).

To customise your build environment use the `prepareCommands` attribute.

### os

_OPTIONAL._ Sets the operating system for the runtime environment.

Following options are available:

- `alpine`
- `ubuntu`

Default value is `alpine`.

We are currently using following os version:

- <span>{data.alpine.default}</span>
- <span>{data.ubuntu.default}</span>

:::caution
The os version is fixed and cannot be customised.
:::

### ports

_OPTIONAL._ Specifies one or more internal ports on which your application will listen.

Projects in Zerops represent a group of one or more services. Services can be of different types (runtime services, databases, message brokers, object storage, etc.). All services of the same project share a **dedicated private network**. To connect to a service within the same project, just use the service hostname and its internal port.

For example, to connect to a Gleam service with hostname = "app" and port = 3000 from another service of the same project, simply use `app:3000`. Read more about [how to access a Gleam service](/references/networking/internal-access#basic-service-communication).

Each port has following attributes:

| parameter   | description                                                                                                                                                                                                                                                                                                            |
| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| port        | Defines the port number. You can set any port number between _10_ and _65435_. Ports outside this interval are reserved for internal Zerops systems.                                                                                                                                                                   |
| protocol    | **Optional.** Defines the protocol. Allowed values are `TCP` or `UDP`. Default value is `TCP`.                                                                                                                                                                                                                         |
| httpSupport | **Optional.** `httpSupport = true` is the default setting for TCP protocol. Set `httpSupport = false` if a web server isn't running on the port. Zerops uses this information for the configuration of [public access](/features/access). `httpSupport = true` is available only in combination with the TCP protocol. |
| httpSupport | **Optional.** `httpSupport = true` is the default setting for TCP protocol. Set `httpSupport = false` if a web server isn't running on the port. Zerops uses this information for the configuration of [public access](/features/access). `httpSupport = true` is available only in combination with the TCP protocol. |

### prepareCommands

_OPTIONAL._ Customises the Gleam runtime environment by installing additional dependencies or tools to the runtime base environment.

<p>
  The base Gleam environment contains {data.alpine.default} the selected
  major version of Gleam, [Zerops command line tool](/references/cli) and `npm`, `yarn`, `git` and `npx` tools. To install
  additional packages or tools add one or more prepare commands:
</p>

```yaml
zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build:
      ...

    # ==== how to run your application ====
    run:
      # OPTIONAL. Customise the runtime environment by installing additional packages
      # or tools to the base Gleam runtime environment.
      prepareCommands:
        - sudo apt-get something
        - curl something else
      ...
```

When the first deploy with a defined prepare attribute is triggered, Zerops will

1. create a prepare runtime container
2. optionally: [copy selected folders or files from your build container](#copy-folders-or-files-from-your-build-container)
3. run the `prepareCommands` commands in the defined order

:::note
`run.prepareCommands` run in the `/home/zerops` directory.
:::

#### Command exit code

If any command fails, it returns an exit code other than 0 and the deploy is canceled. Read the [prepare runtime log](/gleam/how-to/logs#prepare-runtime-log) to troubleshoot the error. If the command ends successfully, it returns the exit code 0 and Zerops triggers the following command. When all `prepareCommands` commands are finished, your custom runtime environment is ready for the deploy phase.

#### Cache of your custom runtime environment

Some packages or tools can take a long time to install. Therefore, Zerops caches your custom runtime environment after the installation of your custom packages or tools is completed. When the second or following deploy is triggered, Zerops will use the custom runtime cache from the previous deploy if following conditions are met:

1. Content of the [build.addToRunPrepare](#copy-folders-or-files-from-your-build-container) and `run.prepareCommands` attributes didn't change from the previous deploy
2. The custom runtime cache wasn't invalidated in the Zerops GUI.

To invalidate the custom runtime cache go to `yyy`

When the custom runtime cache is used, Zerops doesn't create a prepare runtime container and executes the deployment of your application directly.

#### Single or separated shell instances

You can configure your prepare commands to be run in a single shell instance or multiple shell instances. The format is identical to [build commands](#buildcommands).

### Copy folders or files from your build container

<p>
  The prepare runtime container contains {data.alpine.default}, the
  selected major version of Gleam, [Zerops command line tool](/references/cli) and `npm`, `yarn`, `git` and `npx` tools.
</p>

The prepare runtime container does not contain your application code nor the built application. If you need to copy some folders or files from the build container to the runtime container (e.g. a configuration file) use the `addToRunPrepare` attribute in the [build section](#build-pipeline-configuration).

```yaml
zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build:
      ...
      addToRunPrepare: ./runtime-config.yaml

    # ==== how to run your application ====
    run:
      # OPTIONAL. Customise the runtime environment by installing additional packages
      # or tools to the base Gleam runtime environment.
      prepareCommands:
        - sudo apt-get something
        - curl something else
      ...
```

In the example above Zerops will copy the `runtime-config.yaml` file from your build container **after the build has finished** into the new **prepare runtime** container. The copied files and folders will be available in the `/home/zerops` folder in the new prepare runtime container before the prepare commands are triggered.

### initCommands

_OPTIONAL._ Defines one or more commands to be run each time a new runtime container is started or a container is restarted.

```yaml
zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build: ...

    # ==== how to run your application ====
    run:
      # OPTIONAL. Run one or more commands each time a new runtime container
      # is started or restarted. These commands are triggered before
      # your Gleam application is started.
      initCommands:
        - rm -rf ./cache
```

These commands are triggered in the runtime container before your Gleam application is started via the [start command](#start).

:::note
`run.initCommands` run in the `/var/www` directory.
:::

Use init commands to clean or initialise your application cache or similar operations.

:::caution
The init commands will delay the start of your application each time a new runtime container is started (including the horizontal [scaling](/gleam/how-to/scaling) or when a runtime container is restarted).

Do not use the init commands for customising your runtime environment. Use the [run:prepareCommands](#preparecommands-1) attribute instead.
:::

#### Command exit code

If any of the `initCommands` fails, it returns an exit code other than 0, but deploy is **not** canceled. After all init commands are finished, regardless of the status code, the application is started. Read the [runtime log](/gleam/how-to/logs#runtime-log) to troubleshoot the error.

#### Single or separated shell instances

You can configure your `initCommands` to be run in a single shell instance or multiple shell instances. The format is identical to [build commands](#buildcommands).

### envVariables

_OPTIONAL._ Defines the environment variables for the runtime environment.

Enter one or more env variables in following format:

```yaml
zerops:
  # define hostname of your service
  - setup: app
    # ==== how to run your application ====
    run:
      # OPTIONAL. Defines the env variables for the runtime environment:
      envVariables:
        NODE_ENV: production
        DB_NAME: db
        DB_HOST: db
        DB_USER: db
        DB_PASS: ${db_password}
```

Read more about [environment variables](/gleam/how-to/env-variables) in Zerops.

### start

_REQUIRED._ Defines the start command for your Gleam application.

```yaml
zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build: ...

    # ==== how to run your application ====
    run:
      # REQUIRED. Your Gleam application start command
      start: npm start
```

We recommend starting your Gleam application using `npm start`.

### health check

_OPTIONAL._ Defines a health check.

`healthCheck` requires either one `httpGet` object or one `exec` object.

#### httpGet

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

Following attributes are available:

<table className="w-full my-1.5">
  <thead>
    <tr>
      <th className="w-fit whitespace-nowrap">Parameter</th>
      <th className="w-fit whitespace-nowrap">Description</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td className="w-fit whitespace-nowrap font-semibold">port</td>
      <td>Defines the port of the HTTP GET request.
The readiness check will trigger a GET request on <code>{'http://127.0.0.1:{port}/{path}'}</code></td>
    </tr>
    <tr>
      <td className="w-fit whitespace-nowrap font-semibold">path</td>
      <td>Defines the URL path of the HTTP GET request.
The readiness check will trigger a GET request on <code>{'http://127.0.0.1:{port}/{path}'}</code></td>
    </tr>
    <tr>
      <td className="w-fit whitespace-nowrap font-semibold">host</td>
      <td><strong>Optional.</strong> The readiness check is triggered from inside of your runtime container so it always uses the localhost <code>127.0.0.1</code>. If you need to add a <code>host</code> to the request header, specify it in the <code>host</code> attribute.</td>
    </tr>
    <tr>
      <td className="w-fit whitespace-nowrap font-semibold">scheme</td>
      <td><strong>Optional.</strong> The readiness check is triggered from inside of your runtime container so no https is required.
If your application requires a https request, set <code>scheme: https</code></td>
    </tr>
  </tbody>
</table>

**Example:**

```yaml
zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build: ...

    # ==== how to run your application ====
    run:
      # REQUIRED. Your Gleam application start command
      start: npm start

      # OPTIONAL. Define a health check with a HTTP GET request option.
      # Configures the check on http://127.0.0.1:80/status
      healthCheck:
        httpGet:
          port: 80
          path: /status
```

#### exec

Configures the health check to run a local command.
Following attributes are available:

| Parameter   | Description                                                                                                                                                                                                                                                                                                                     |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **command** | Defines a local command to be run.
The command has access to the same [environment variables](/gleam/how-to/create#set-secret-environment-variables) as your Gleam application.
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 below. |

**Example:**

```yaml
zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build: ...

    # ==== how to run your application ====
    run:
      # REQUIRED. Your Gleam application start command
      start: npm start

      # OPTIONAL. Define a health check with a shell command.
      healthCheck:
        exec:
          command: |
            touch grass
            rm -rf life
            mv /outside/user /home/user
```

### crontab

_OPTIONAL._ Defines cron jobs.

Setup cron jobs in the following format:

```yaml
zerops:
  # define hostname of your service
  - setup: app

    # ==== how to run your application ====
    run:
      crontab:
        # REQUIRED. Sets the command to execute:
        - command: ""
        # REQUIRED. Sets the interval time to execute:
          timing: "0 * * * *"
```

Read more about setting up [cron](/zerops-yaml/cron) in Zerops.

## Deploy configuration

### readiness check

_OPTIONAL._ Defines a readiness check. Read more about how the [readiness check works](/gleam/how-to/deploy-process#readiness-checks) in Zerops.

`readinessCheck` requires either one `httpGet` object or one `exec` object.

#### httpGet

Configures the readiness check to request a local URL using a http GET method.

Following attributes are available:

<table className="w-full my-1.5">
  <thead>
    <tr>
      <th className="w-fit whitespace-nowrap">Parameter</th>
      <th className="w-fit whitespace-nowrap">Description</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td className="w-fit whitespace-nowrap font-semibold">port</td>
      <td>Defines the port of the HTTP GET request.
The readiness check will trigger a GET request on <code>{'http://127.0.0.1:{port}/{path}'}</code></td>
    </tr>
    <tr>
      <td className="w-fit whitespace-nowrap font-semibold">path</td>
      <td>Defines the URL path of the HTTP GET request.
The readiness check will trigger a GET request on <code>{'http://127.0.0.1:{port}/{path}'}</code></td>
    </tr>
    <tr>
      <td className="w-fit whitespace-nowrap font-semibold">host</td>
      <td><strong>Optional.</strong> The readiness check is triggered from inside of your runtime container so it always uses the localhost <code>127.0.0.1</code>. If you need to add a <code>host</code> to the request header, specify it in the <code>host</code> attribute.</td>
    </tr>
    <tr>
      <td className="w-fit whitespace-nowrap font-semibold">scheme</td>
      <td><strong>Optional.</strong> The readiness check is triggered from inside of your runtime container so no https is required.
If your application requires a https request, set <code>scheme: https</code></td>
    </tr>
  </tbody>
</table>

**Example:**

```yaml
zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build: ...

    # ==== how to deploy your application ====
    deploy:
      # OPTIONAL. Define a readiness check with a HTTP GET request option.
      # Configures the check on http://127.0.0.1:80/status
      readinessCheck:
        httpGet:
          port: 80
          path: /status

    # ==== how to run your application ====
    run: ...
```

Read more about how the [readiness check works](/gleam/how-to/deploy-process#readiness-checks) in Zerops.

#### exec

Configures the readiness check to run a local command.
Following attributes are available:

| Parameter   | Description                                                                                                                                                                                                                                                                                                                     |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **command** | Defines a local command to be run.
The command has access to the same [environment variables](/gleam/how-to/create#set-secret-environment-variables) as your Gleam application.
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 below. |

**Example:**

```yaml
zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build: ...

    # ==== how to deploy your application ====
    deploy:
      # OPTIONAL. Define a readiness check with a HTTP GET request option.
      # Configures the check on http://127.0.0.1:80/status
      readinessCheck:
        exec:
          command: |
            touch grass
            rm -rf life
            mv /outside/user /home/user
```

Read more about how the [readiness check works](/gleam/how-to/deploy-process#readiness-checks) in Zerops.


----------------------------------------

# Gleam > How To > Build Process



----------------------------------------

# Gleam > How To > Controls



----------------------------------------

# Gleam > How To > Create


Zerops provides a powerful Gleam runtime service with extensive build support. The Gleam runtime is highly scalable and customizable to suit your development and production needs. With just a few clicks or commands, you can have a production-ready Gleam environment up and running in no time.

## Create a Gleam service using Zerops GUI

First, set up a project in the Zerops GUI. Then go to the project dashboard page and choose **Add new service** in the left menu under the **Services** section. From there, you can add a new Gleam service:

[Video: /vids/services/gleam.webm](/vids/services/gleam.webm)

### Choose a Gleam version

Zerops supports the following Gleam versions:

:::info
You can easily [upgrade](/gleam/how-to/upgrade) the major version at any time later.
:::

### Set a hostname

Enter a unique service identifier like "app", "cache", "gui", etc. Duplicate services with the same name within the same project are not allowed.

#### Limitations:

- Maximum 25 characters
- Must contain only lowercase ASCII letters (a-z) or numbers (0-9)

:::caution
The hostname is fixed after the service is created and cannot be changed later.
:::

### Set secret environment variables

Add environment variables with sensitive data, such as passwords, tokens, salts, certificates, etc. These will be securely saved inside Zerops and added to your runtime service upon start.

Setting secret environment variables is optional. You can always set them later in the Zerops GUI.

Read more about the [different types of environment variables](/gleam/how-to/env-variables#service-env-variables) in Zerops.

## Create a Gleam service using zCLI

zCLI is the Zerops command-line tool. To create a new Gleam service via the command line, follow these steps:

1. [Install & setup zCLI](/references/cli)
2. [Create a project description file](/gleam/how-to/create#create-a-project-description-file)
3. [Create a project with a Gleam and PostgreSQL service](#full-example)

### Create a project description file

Zerops uses a YAML format to describe the project infrastructure.

#### Basic example:

Create a directory called `my-project`. Inside the `my-project` directory, create a `description.yaml` file with the following content:
```yaml
# basic project data
project:
  # project name
  name: my-project
# array of project services
services:
  - # service name
    hostname: app
    # service type and version number in gleam@{version} format
    type: gleam@latest
    # defines the minimum number of containers for horizontal autoscaling
    minContainers: 1
    # defines the maximum number of containers for horizontal autoscaling. Max value = 6.
    maxContainers: 6
    # optional: create env variables
    envSecrets:
      S3_ACCESS_KEY_ID: 'P8cX1vVVb'
      S3_ACCESS_SECRET: 'ogFthuiLYki8XoL73opSCQ'
```

The yaml file describes your future project infrastructure. The project will contain one Gleam version 20 service with default [auto scaling](/gleam/how-to/scaling) configuration. Hostname will be set to "app", the internal port(s) the service listens on will be defined later in the [zerops.yaml](/gleam/how-to/build-pipeline#ports). Following secret env variables will be configured:

```env
S3_ACCESS_KEY_ID="P8cX1vVVb"
S3_ACCESS_SECRET="ogFthuiLYki8XoL73opSCQ"
```

#### Full example:

Create a directory my-project. Create an description.yaml file inside the my-project directory with following content:

```yaml
# basic project data
project:
  # project name
  name: my-project
  # optional: project description
  description: A project with a Gleam and PostgreSQL database
  # optional: project tags
  tags:
    - DEMO
    - ZEROPS
# array of project services
services:
  - # service name
    hostname: app
    # service type and version number in gleam@{version} format
    type: gleam@latest
    # optional: vertical auto scaling customization
    verticalAutoscaling:
      cpuMode: DEDICATED
      minCpu: 2
      maxCpu: 5
      minRam: 2
      maxRam: 24
      minDisk: 6
      maxDisk: 50
      startCpuCoreCount: 3
      minFreeRamGB: 0.5
      minFreeRamPercent: 20
    # defines the minimum number of containers for horizontal autoscaling. Max value = 6.
    minContainers: 2
    # defines the maximum number of containers for horizontal autoscaling. Max value = 6.
    maxContainers: 4
    # optional: create env variables
    envSecrets:
      S3_ACCESS_KEY_ID: 'P8cX1vVVb'
      S3_ACCESS_SECRET: 'ogFthuiLYki8XoL73opSCQ'
  - # second service hostname
    hostname: db
    # service type and version number in postgresql@{version} format
    type: postgresql@12
    # mode of operation "HA"/"non_HA"
    mode: NON_HA
```

The yaml file describes your future project infrastructure. The project will contain a Gleam service and a [PostgreSQL](/postgresql/overview) service.

Gleam service with "app" hostname, the internal port(s) the service listens on will be defined later in the [zerops.yaml](/gleam/how-to/build-pipeline#ports). Gleam service will run on version 20 with a custom vertical and horizontal scaling. Following secret env variables will be configured:

```env
S3_ACCESS_KEY_ID="P8cX1vVVb"
S3_ACCESS_SECRET="ogFthuiLYki8XoL73opSCQ"
```

The hostname of the PostgreSQL service will be set to "db". The [single container](/features/scaling#single-container-mode)(/features/scaling#deployment-modes-databases-and-shared-storage) mode will be chosen and the default auto [scaling configuration](/postgresql/how-to/scale#configure-scaling) will be set.

#### Description of description.yaml parameters

The `project:` section is required. Only one project can be defined.

| Parameter       | Description                                                                                                                     | Limitations             |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------- | ----------------------- |
| **name**        | The name of the new project. Duplicates are allowed.                                                                            |                         |
| **description** | **Optional.** Description of the new project.                                                                                   | Maximum 255 characters. |
| **tags**        | **Optional.** One or more string tags. Tags do not have a functional meaning, they only provide better orientation in projects. |
| **tags**        | **Optional.** One or more string tags. Tags do not have a functional meaning, they only provide better orientation in projects. |

At least one service in `services:` section is required. You can create a project with multiple services. The example above contains Gleam and PostgreSQL services but you can create a `description.yaml` with your own combination of [services](/features/infrastructure).

<table className="w-full my-1.5">
  <thead>
    <tr>
      <th className="w-fit">Parameter</th>
      <th className="w-fit">Description</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td className="w-fit">
        <b>hostname</b>
      </td>
      <td className="w-fit">
        The unique service identifier.
        <ul>
        <li>duplicate services with the same name in the same project are forbidden</li>
        <li>maximum 25 characters</li>
        <li>must contain only lowercase ASCII letters (a-z) or numbers (0-9)</li>
        </ul>
      </td>
    </tr>
    <tr>
      <td className="w-fit">
        <b>type</b>
      </td>
      <td className="w-fit">
        Specifies the service type and version.

        See what [Gleam service types](/references/import-yaml/type-list#runtime-services) are currently supported.
      </td>
    </tr>
    <tr>
      <td className="w-fit">
        <b>verticalAutoscaling</b>
      </td>
      <td className="w-fit">
        <b>Optional.</b> Defines [custom vertical auto scaling parameters](/gleam/how-to/create#set-auto-scaling-configuration).

        All verticalAutoscaling attributes are optional. Not specified
        attributes will be set to their default values.
      </td>
    </tr>
    <tr>
      <td className="w-fit">
        <b> - cpuMode</b>
      </td>
      <td className="w-fit">
        <b>Optional.</b> Accepts `SHARED`, `DEDICATED` values. Default is `SHARED`
      </td>
    </tr>
    <tr>
      <td className="w-fit">
        <b> - minCpu/maxCpu</b>
      </td>
      <td className="w-fit">
        <b>Optional.</b> Set the minCpu or maxCpu in CPU cores (integer).
      </td>
    </tr>
    <tr>
      <td className="w-fit">
        <b> - minRam/maxRam</b>
      </td>
      <td className="w-fit">
        <b>Optional.</b> Set the minRam or maxRam in GB (float).
      </td>
    </tr>
    <tr>
      <td className="w-fit">
        <b> - minDisk/maxDisk</b>
      </td>
      <td className="w-fit">
        <b>Optional.</b> Set the minDisk or maxDisk in GB (float).
      </td>
    </tr>
    <tr>
      <td className="w-fit">
        <b>minContainers</b>
      </td>
      <td className="w-fit">
        <b>Optional.</b> Default = 1. Defines the minimum number of containers
        for [horizontal autoscaling](/gleam/how-to/create#horizontal-auto-scaling).

        <b>Limitations:</b>

        Current maximum value = 10.
      </td>
    </tr>
    <tr>
      <td className="w-fit">
        <b>maxContainers</b>
      </td>
      <td className="w-fit">
        Defines the maximum number of containers for [horizontal autoscaling](/gleam/how-to/create#horizontal-auto-scaling).

        <b>Limitations:</b>

        Current maximum value = 10.
      </td>
    </tr>
    <tr>
      <td className="w-fit">
        <b>envSecrets</b>
      </td>
      <td className="w-fit">
        <b>Optional.</b> Defines one or more secret env variables as a key value
        map. See env variable [restrictions](/gleam/how-to/env-variables#env-variable-restrictions).
      </td>
    </tr>
  </tbody>
</table>

### Create a project based on the description.yaml

When you have your `description.yaml` ready, use the `zcli project project-import` command to create a new project and the service infrastructure.

```sh
Usage:
  zcli project project-import importYamlPath [flags]

Flags:
  -h, --help                Help for the project import command.
      --org-id string        If you have access to more than one organization, you must specify the org ID for which the
                            project is to be created.
      --working-dir string   Sets a custom working directory. Default working directory is the current directory. (default "./")
```

Zerops will create a project and one or more services based on the `description.yaml` content.

Maximum size of the `description.yaml` file is 100 kB.

You don't specify the project name in the `zcli project project-import` command, because the project name is defined in the `description.yaml`.

If you have access to more than one client, you must specify the client ID for which the project is to be created. The `clientID` is located in the Zerops GUI under the client name on the project dashboard page.

### Add Gleam service to an existing project

#### Example:

Create a directory `my-project` if it doesn't exist. Create an `import.yaml` file inside the `my-project` directory with following content:

```yaml
# basic project data
project:
  # project name
  name: my-project
# array of project services
services:
  - # service name
    hostname: app
    # service type and version number in gleam@{version} format
    type: gleam@latest
    # defines the minimum number of containers for horizontal autoscaling
    minContainers: 1
    # defines the maximum number of containers for horizontal autoscaling. Max value = 6.
    maxContainers: 6
    # optional: create env variables
    envSecrets:
      S3_ACCESS_KEY_ID: 'P8cX1vVVb'
      S3_ACCESS_SECRET: 'ogFthuiLYki8XoL73opSCQ'
```

The yaml file describes the list of one or more services that you want to add to your existing project. In the example above, one Gleam service version 20 with default [auto scaling](/gleam/how-to/scaling) configuration will be added to your project. Hostname of the new service will be set to `app`. Following secret env variables will be configured:

```env
S3_ACCESS_KEY_ID="P8cX1vVVb"
S3_ACCESS_SECRET="ogFthuiLYki8XoL73opSCQ"
```

The content of the `services:` section of `import.yaml` is identical to the project description file. The `import.yaml` never contains the `project:` section because the project already exists.

When you have your `import.yaml` ready, use the `zcli project service-import` command to add one or more services to your existing Zerops project.

```sh
Usage:
  zcli project service-import importYamlPath [flags]

Flags:
  -h, --help                Help for the project service import command.
  -P, --project-id string   If you have access to more than one project, you must specify the project ID for which the
                           command is to be executed.
```

zCLI commands are interactive, when you press enter after `zcli project service-import importYamlPath`, you will be given a list of your projects to choose from.

Maximum size of the import.yaml file is 100 kB.


----------------------------------------

# Gleam > How To > Customize Runtime



----------------------------------------

# Gleam > How To > Deploy Process



----------------------------------------

# Gleam > How To > Env Variables



----------------------------------------

# Gleam > How To > Filebrowser



----------------------------------------

# Gleam > How To > Logs



----------------------------------------

# Gleam > How To > Scaling



----------------------------------------

# Gleam > How To > Shared Storage



----------------------------------------

# Gleam > How To > Trigger Pipeline



----------------------------------------

# Gleam > How To > Upgrade



----------------------------------------

# Gleam > Overview


[Gleam ↗](https://gleam.org/en) is an asynchronous event-driven JavaScript runtime, which is designed to build scalable network applications.

As said, there is no need for coding yet, we have created a [Github repository ↗](https://github.com/zeropsio/recipe-gleam), a **_recipe_**, containing the most simple Gleam web application. The repo will be used as a source from which the app will be built.

### 🚀 Feel free to deploy the recipe yourself

This is the most bare-bones example of Gleam app running in Zerops — as few libraries as possible,
  just a simple endpoint with connect, read and write to a Zerops PostgreSQL database.

  [Deploy "gleam" recipe on Zerops](https://app.zerops.io/recipe/?lf=gleam)

1. Log in/sign up to [Zerops GUI ↗](https://app.zerops.io)

2. In the **Projects** box click on **Import a project** and paste in the following YAML config ([source ↗](https://github.com/zeropsio/recipe-gleam/blob/main/zerops-project-import.yaml)):

```yaml
project:
  name: recipe-gleam
  tags:
    - zerops-recipe

services:
  - hostname: api
    type: gleam@1.5
    enableSubdomainAccess: true
    buildFromGit: https://github.com/zeropsio/recipe-gleam

  - hostname: db
    type: postgresql@16
    mode: NON_HA
    priority: 1
```

3. Click on **Import project** and wait until all pipelines have finished.

**That's it, your application is now up and running! :star: Let's check it works:**

1. A _subdomain_ should have been enabled and visible in the project's **IP addressed & Public Routing Overview** box. Its format should look similar to this `https://api-808-3000.prg1.zerops.app`.
2. Click or the `subdomain` URL to open it in a browser and you should see

```
{"message":"This is a simple Gleam application running in Zerops.io, each request adds an entry to the PostgreSQL database and returns a count. See the source repository (https://github.com/zeropsio/recipe-gleam) for more information.","newEntry":"e64be640-d6c2-4be8-93ac-d1e40e56fa06","count":1}
```

:::tip
Do you have any questions? Check the step-by-step tutorial, browse the documentation and join our **[Discord](https://discord.com/invite/WDvCZ54)** community to get help from our team and other members.
:::

## How to start

It doesn't matter whether it's your first curious introduction to Zerops, you have already mastered the basics and are looking for a tiny detail or inspiration. Below, choose a section that fits your needs:

- [Care for details?](/gleam/how-to/create) — Dive in all Zerops has to offer for your Gleam application.
- [Gleam recipes](https://github.com/zeropsio?q=gleam&type=all&language=&sort=) — Get inspired by already existing repositories, ready to be imported to Zerops.

## Feature Highlights

- [Create Gleam service](/gleam/how-to/create) — Start with creating a Gleam service using GUI or zCLI.
- [Zerops.yaml](/gleam/how-to/build-pipeline#add-zeropsyaml-to-your-repository) — See a full example of zerops.yaml file to create your own app.
- [Scaling configuration](/gleam/how-to/scaling) — Set up scaling of your Gleam application so that it runs smoothly while using only necessary resources.

{" "}

- [Customize build environment](/gleam/how-to/build-process#customize-build-environment)
- [Customize runtime environment](/gleam/how-to/customize-runtime)

## When in doubt, reach out

Don't know how to start or got stuck during the process? You might not be the first one, visit the FAQ section to find out.

In case you haven't found an answer (and also if you have), we and our community are looking forward to hearing from you on Discord.

Have you build something that others might find useful? Don't hesitate to share your knowledge!

- [FAQ](/gleam/faq) — Most common questions in one place.
- [Discord](https://discord.com/invite/WDvCZ54) — Join our core team and Zerops community on Discord. Ask questions and share your tips with other members.

## Popular Guides

- [zCLI](/references/cli) — Get even more out of Zerops with the zCLI command line tool.
- [Zerops VPN](/references/networking/vpn) — Connect to your services easily with Zerops VPN.


----------------------------------------

# Go > How To > Build Pipeline


Zerops provides a customizable build and runtime environment for your Go application.

## Add zerops.yaml to your repository

Start by adding `zerops.yaml` file to the **root of your repository** and modify it to fit your application:

```yaml
zerops:
  # define hostname of your service
  - setup: app
    # ==== how to build your application ====
    build:
      # REQUIRED. Set the base technology for the build environment:
      base: go@latest

      # OPTIONAL. Set the operating system for the build environment.
      # os: ubuntu

      # OPTIONAL. Customize the build environment by installing additional packages
      # or tools to the base build environment.
      # prepareCommands:
      #   - sudo apt-get something
      #   - curl something else

      # OPTIONAL. Build your application
      buildCommands:
        - go build -o app main.go
      # REQUIRED. Select which files / folders to deploy after
      # the build has successfully finished
      deployFiles: app

      # OPTIONAL. Which files / folders you want to cache for the next build.
      # Next builds will be faster when the cache is used.
      # cache: some_file

    # ==== how to run your application ====
    run:
      # OPTIONAL. Sets the base technology for the runtime environment:
      base: go@latest

      # OPTIONAL. Sets the internal port(s) your app listens on:
      ports:
        # port number
        - port: 8080

      # OPTIONAL. Customize the runtime Go environment by installing additional
      # dependencies to the base Go runtime environment.
      # prepareCommands:
      #   - sudo apt-get something
      #   - curl something else

      # OPTIONAL. Run one or more commands each time a new runtime container
      # is started or restarted. These commands are triggered before
      # your Go application is started.
      # initCommands:
      #  - rm -rf ./cache

      # REQUIRED. Your Go application start command
      start: ./app
```

The top-level element is always `zerops`.

### Setup

The first element `setup` contains the **hostname** of your service. A runtime service with the same hostname must exist in Zerops.
Zerops supports the definition of multiple runtime services in a single `zerops.yaml`. This is useful when you use a monorepo. Just add multiple setup elements in your `zerops.yaml`:

```yaml
zerops:
  # definition for app service
  - setup: app
    # optional
    build: ...
    # optional
    deploy: ...
    # required
    run: ...

  # definition for api service
  - setup: api
    # optional
    build: ...
    # optional
    deploy: ...
    # required
    run: ...
```

Each service configuration contains at least the `run` section. Optional `build` and `deploy` sections can be added to further customize your process.

## Build pipeline configuration

### base

_REQUIRED._ Sets the base technology for the build environment.

Following options are available for Go builds:

- `go@1.22`, `go@1`, `golang@1`, `go@latest`, `golang@latest`

```yaml
zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build:
      # REQUIRED. Sets the base technology for the build environment:
      base: go@latest
      ...
```

<p>
  The base build environment contains {data.alpine.default}, the selected
  version of Go, [Zerops command line tool](/references/cli), `git` and `wget`.
</p>

:::info
You can change the base environment when you need to. Just simply modify the `zerops.yaml` in your repository.
:::

If you need to install more technologies to the build environment, set multiple values as a yaml array. For example:

```yaml
zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build:
      # REQUIRED. Sets the base technology for the build environment:
      base:
        - go@latest
      prepareCommands:
        - zsc add nodejs@latest
      ...
```

See the full list of supported [build base environments](/zerops-yaml/base-list#runtime-services).

To customize your build environment use the [prepareCommands](#preparecommands) attribute.

:::note
Modifying the base technology will invalidate your build cache. See our [Build Cache Documentation](/features/build-cache) for more details about cache invalidation.
:::

### os

_OPTIONAL._ Sets the operating system for the build environment.

Following options are available:

- `alpine`
- `ubuntu`

Default value is `alpine`.

We are currently using following os version:

- <span>{data.alpine.default}</span>
- <span>{data.ubuntu.default}</span>

:::caution
The os version is fixed and cannot be customized.
:::

:::note
Changing the OS setting will invalidate your build cache. See our [Build Cache Documentation](/features/build-cache) for details about cache behavior.
:::

### prepareCommands

_OPTIONAL._ Customizes the build environment by installing additional dependencies or tools to the base build environment.

The base build environment contains:

- <span>{data.alpine.default}</span>
- selected version of Go defined in the [base](#base) attribute
- [Zerops command line tool](/references/cli)
- `git` and `wget`

To install additional packages or tools add one or more prepare commands:

```yaml
zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build:
      # REQUIRED. Set the base technology for the build environment:
      base: go@latest

      # OPTIONAL. Customize the build environment by installing additional packages
      # or tools to the base build environment.
      prepareCommands:
        - sudo apt-get something
        - curl something else
      ...
```

When the first build is triggered, Zerops will

1. create a build container
2. download your application code from your repository
3. run the prepare commands in the defined order

The application code is available in `/build/source` before the prepare commands are triggered, so you can use any file from your repository in your prepare commands (e.g. a configuration file). The commands themselves run in the `/home/zerops` directory.

:::note
These commands are skipped when using cached environment. Modifying `prepareCommands` will invalidate your build cache. See our [Build Cache Documentation](/features/build-cache) for details about cache invalidation.
:::

#### Command exit code

If any command fails, it returns an exit code other than 0 and the build is canceled. Read the [build log](/go/how-to/logs#build-log) to troubleshoot the error. If the command ends successfully, it returns the exit code 0 and Zerops triggers the following command. When all prepare commands are finished, your custom build environment is ready for the build phase.

#### Single or separated shell instances

You can configure your prepare commands to be run in a single shell instance or multiple shell instances. The format is identical to [build commands](#buildcommands).

### buildCommands

_OPTIONAL._ Defines build commands.

```yaml
zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build:
      # REQUIRED. Set the base technology for the build environment:
      base: go@latest

      # OPTIONAL. Build your application
      buildCommands:
        - go build -o app main.go
      ...
```

Build commands are optional. Zerops triggers each command in the defined order in a dedicated build container, running from the `/build/source` directory.

Before the build commands are triggered the build container contains:

1. base environment defined by the [base](#base) attribute
2. optional customisation of the base environment defined in the [prepareCommands](#preparecommands) attribute
3. your application code

#### Run build commands as a single shell instance

Use following syntax to run all commands in the same environment context. For example, if one command changes the current directory, the next command continues in that directory. When one command creates an environment variable, the next command can access it. Suppose your `main.go` file is in a `src` directory.

```yaml
buildCommands:
  - |
    cd src
    go build -o app main.go
```

#### Run build commands as a separate shell instances

When the following syntax is used, each command is triggered in a separate environment context. For example, each shell instance starts in the home directory again. When one command creates an environment variable, it won't be available for the next command. Suppose your `main.go` file is in a `src` directory.

```yaml
buildCommands:
  - cd src
  - go build -o app src/main.go
```

#### Command exit code

If any command fails, it returns an exit code other than 0 and the build is canceled. Read the [build log](/go/how-to/logs#build-log) to troubleshoot the error. If the error log doesn't contain any specific error message, try to run your build with the --verbose option.

```yaml
buildCommands:
  - go build -v -o app main.go
```

If the command ends successfully, it returns the exit code 0 and Zerops triggers the following command. When all `buildCommands` are finished, the application build is completed and ready for the deploy phase.

### deployFiles

_REQUIRED._ Selects which files or folders will be deployed after the build has successfully finished. To filter out specific files or folders, use [`.deployignore`](#deployignore) file.

```yaml
# REQUIRED. Select which files / folders to deploy after
# the build has successfully finished
deployFiles:
  - app
```

Determines files or folders produced by your build, which should be deployed to your runtime service containers.

The path starts from the **root directory** of your project (the location of `zerops.yaml`). You must enclose the name in quotes if the folder or the file name contains a space.

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

#### Examples

Deploys a folder, and a file from the project root directory:

```yaml
deployFiles:
  - app
  - file.txt
```

Deploys the whole content of the build container:

```yaml
deployFiles: .
```

Deploys a folder, and a file in a defined path:

```yaml
deployFiles:
  - ./path/to/file.txt
  - ./path/to/dir/
```

#### How to use a wildcard in the path

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

Deploys all folders that are located in any path that begins with `/path/to/`

```yaml
deployFiles: ./path/to/~/
```

Deploys all folders that are located in any path that begins with `/path/` and ends with `/to/`

```yaml
deployFiles: ./path/~/to/
```

:::note Example
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 will be cached for the next build.

```yaml
# OPTIONAL. Which files / folders you want to cache for the next build.
# Next builds will be faster when the cache is used.
cache: file.txt
```

The cache attribute helps optimize build times by preserving specified files between builds.

The cache attribute supports the [~ wildcard character](#how-to-use-a-wildcard-in-the-path).

Learn more about the [build cache system](/features/build-cache) in Zerops.

### envVariables

_OPTIONAL._ Defines the environment variables for the build environment.

Enter one or more env variables in following format:

```yaml
zerops:
  # define hostname of your service
  - setup: app
    # ==== how to build your application ====
    build:
      base: go@latest
        …

      # OPTIONAL. Defines the env variables for the build environment:
      envVariables:
        GO_ENV: production
        DB_NAME: db
        DB_HOST: db
        DB_USER: db
        DB_PASS: ${db_password}
```

Read more about [environment variables](/go/how-to/env-variables) in Zerops.

## Runtime configuration

### base

_OPTIONAL._ Sets the base technology for the runtime environment.
If you don't specify the `run.base` attribute, Zerops keeps the current Go version for your runtime.

Following options are available for Go builds:

- `go@1.22`, `go@1`, `golang@1`, `go@latest`, `golang@latest`

```yaml
zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build:
      # REQUIRED. Sets the base technology for the build environment:
      base: go@latest
      ...

    # ==== how to run your application ====
    run:
      # OPTIONAL. Sets the base technology for the runtime environment:
        base: go@latest
      ...
```

<p>
  The base runtime environment contains {data.alpine.default}, the
  selected major version of Go, Zerops command line tool, `git` and `wget`.
</p>

:::info
You can change the base environment when you need to. Just simply modify the `zerops.yaml` in your repository.
:::

If you need to install more technologies to the runtime environment, set multiple values as a yaml array. For example:

```yaml
zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build:
      # REQUIRED. Sets the base technology for the build environment:
      base: go@latest
      ...

    # ==== how to run your application ====
    run:
      # OPTIONAL. Sets the base technology for the runtime environment:
      base:
        - go@latest
      prepareCommands:
        - zsc add nodejs@latest
      ...
```

See the full list of supported [run base environments](/zerops-yaml/base-list).

To customise your build environment use the `prepareCommands` attribute.

### os

_OPTIONAL._ Sets the operating system for the runtime environment.

Following options are available:

- `alpine`
- `ubuntu`

Default value is `alpine`.

We are currently using following os version:

- <span>{data.alpine.default}</span>
- <span>{data.ubuntu.default}</span>

:::caution
The os version is fixed and cannot be customised.
:::

### ports

_OPTIONAL._ Specifies one or more internal ports on which your application will listen.

Projects in Zerops represent a group of one or more services. Services can be of different types (runtime services, databases, message brokers, object storage, etc.). All services of the same project share a **dedicated private network**. To connect to a service within the same project, just use the service hostname and its internal port.

For example, to connect to a Go service with hostname = "app" and port = 8080 from another service of the same project, simply use `app:8080`. Read more about [how to access a Go service](/references/networking/internal-access#basic-service-communication).

Each port has following attributes:

<table className="w-full my-1.5">
  <thead>
    <tr>
      <th className="w-fit"><strong>Parameter</strong></th>
      <th className="w-fit"><strong>Description</strong></th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td className="w-fit">port</td>
      <td className="w-fit">Defines the port number. You can set any port number between <em>10</em> and <em>65435</em>. Ports outside this interval are reserved for internal Zerops systems.</td>
    </tr>
    <tr>
      <td className="w-fit">protocol</td>
      <td className="w-fit"><strong>Optional.</strong> Defines the protocol. Allowed values are <code>TCP</code> or <code>UDP</code>. Default value is <code>TCP</code>.</td>
    </tr>
    <tr>
      <td className="w-fit">httpSupport</td>
      <td className="w-fit"><strong>Optional.</strong> <code>httpSupport = true</code> is the default setting for TCP protocol. Set <code>httpSupport = false</code> if a web server isn't running on the port. Zerops uses this information for the configuration of [public access](/features/access). <code>httpSupport = true</code> is available only in combination with the TCP protocol.</td>
    </tr>
  </tbody>
</table>

### prepareCommands

_OPTIONAL._ Customises the Go runtime environment by installing additional dependencies or tools to the runtime base environment.

<p>
  The base Go environment contains {data.alpine.default}, the selected
  major version of Go, [Zerops command line tool](/references/cli) and `git` and `wget`. To install additional packages or tools add one or more prepare commands:
</p>

```yaml
zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build:
      ...

    # ==== how to run your application ====
    run:
      # OPTIONAL. Customise the runtime environment by installing additional packages
      # or tools to the base Go runtime environment.
      prepareCommands:
        - sudo apt-get something
        - curl something else
      ...
```

When the first deploy with a defined prepare attribute is triggered, Zerops will

1. create a prepare runtime container
2. optionally: [copy selected folders or files from your build container](#copy-folders-or-files-from-your-build-container)
3. run the `prepareCommands` commands in the defined order

:::note
`run.prepareCommands` run in the `/home/zerops` directory.
:::

#### Command exit code

If any command fails, it returns an exit code other than 0 and the deploy is canceled. Read the [prepare runtime log](/go/how-to/logs#prepare-runtime-log) to troubleshoot the error. If the command ends successfully, it returns the exit code 0 and Zerops triggers the following command. When all `prepareCommands` commands are finished, your custom runtime environment is ready for the deploy phase.

#### Cache of your custom runtime environment

Some packages or tools can take a long time to install. Therefore, Zerops caches your custom runtime environment after the installation of your custom packages or tools is completed. When the second or following deploy is triggered, Zerops will use the custom runtime cache from the previous deploy if following conditions are met:

1. Content of the [build.addToRunPrepare](#copy-folders-or-files-from-your-build-container) and `run.prepareCommands` attributes didn't change from the previous deploy
2. The custom runtime cache wasn't invalidated in the Zerops GUI.

To invalidate the Zerops runtime cache go to your service detail in Zerops GUI, choose **Service dashboard & runtime containers** from the left menu and click on the **Open pipeline detail** button. Then click on the **Clear runtime prepare cache** button.

When the prepare cache is used, Zerops doesn't create a prepare runtime container and executes the deployment of your application directly.

#### Single or separated shell instances

You can configure your prepare commands to be run in a single shell instance or multiple shell instances. The format is identical to [build commands](#buildcommands).

### Copy folders or files from your build container

<p>
  The prepare runtime container contains {data.alpine.default}, the
  selected major version of Go, [Zerops command line tool](/references/cli) and `git` and `wget`.
</p>

The prepare runtime container does not contain your application code nor the built application. If you need to copy some folders or files from the build container to the runtime container (e.g. a configuration file) use the `addToRunPrepare` attribute in the [build section](#build-pipeline-configuration).

```yaml
zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build:
      ...
      addToRunPrepare: ./runtime-config.yaml

    # ==== how to run your application ====
    run:
      # OPTIONAL. Customise the runtime environment by installing additional packages
      # or tools to the base Go runtime environment.
      prepareCommands:
        - sudo apt-get something
        - curl something else
      ...
```

In the example above Zerops will copy the `runtime-config.yaml` file from your build container **after the build has finished** into the new **prepare runtime** container. The copied files and folders will be available in the `/home/zerops` folder in the new prepare runtime container before the prepare commands are triggered.

### initCommands

_OPTIONAL._ Defines one or more commands to be run each time a new runtime container is started or a container is restarted.

```yaml
zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build: ...

    # ==== how to run your application ====
    run:
      # OPTIONAL. Run one or more commands each time a new runtime container
      # is started or restarted. These commands are triggered before
      # your Go application is started.
      initCommands:
        - rm -rf ./cache
```

These commands are triggered in the runtime container before your Go application is started via the [start command](#start).

:::note
`run.initCommands` run in the `/var/www` directory.
:::

Use init commands to clean or initialise your application cache or similar operations.

:::caution
The init commands will delay the start of your application each time a new runtime container is started (including the horizontal [scaling](/go/how-to/scaling) or when a runtime container is restarted).

Do not use the init commands for customising your runtime environment. Use the [run:prepareCommands](#preparecommands-1) attribute instead.
:::

#### Command exit code

If any of the `initCommands` fails, it returns an exit code other than 0, but deploy is **not** canceled. After all init commands are finished, regardless of the status code, the application is started. Read the [runtime log](/go/how-to/logs#runtime-log) to troubleshoot the error.

#### Single or separated shell instances

You can configure your `initCommands` to be run in a single shell instance or multiple shell instances. The format is identical to [build commands](#buildcommands).

### envVariables

_OPTIONAL._ Defines the environment variables for the runtime environment.

Enter one or more env variables in following format:

```yaml
zerops:
  # define hostname of your service
  - setup: app
    # ==== how to run your application ====
    run:
      # OPTIONAL. Defines the env variables for the runtime environment:
      envVariables:
        GO_ENV: production
        DB_NAME: db
        DB_HOST: db
        DB_USER: db
        DB_PASS: ${db_password}
```

Read more about [environment variables](/go/how-to/env-variables) in Zerops.

### start

_REQUIRED._ Defines the start command for your Go application.

```yaml
zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build: ...

    # ==== how to run your application ====
    run:
      # REQUIRED. Your Go application start command
      start: ./app
```

We recommend starting your Go application using `./app`.

### health check

_OPTIONAL._ Defines a health check.

`healthCheck` requires either one `httpGet` object or one `exec` object.

#### httpGet

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

Following attributes are available:

<table className="w-full my-1.5">
  <thead>
    <tr>
      <th className="w-fit whitespace-nowrap">Parameter</th>
      <th className="w-fit whitespace-nowrap">Description</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td className="w-fit whitespace-nowrap font-semibold">port</td>
      <td>Defines the port of the HTTP GET request.
The readiness check will trigger a GET request on <code>{'http://127.0.0.1:{port}/{path}'}</code></td>
    </tr>
    <tr>
      <td className="w-fit whitespace-nowrap font-semibold">path</td>
      <td>Defines the URL path of the HTTP GET request.
The readiness check will trigger a GET request on <code>{'http://127.0.0.1:{port}/{path}'}</code></td>
    </tr>
    <tr>
      <td className="w-fit whitespace-nowrap font-semibold">host</td>
      <td><strong>Optional.</strong> The readiness check is triggered from inside of your runtime container so it always uses the localhost <code>127.0.0.1</code>. If you need to add a <code>host</code> to the request header, specify it in the <code>host</code> attribute.</td>
    </tr>
    <tr>
      <td className="w-fit whitespace-nowrap font-semibold">scheme</td>
      <td><strong>Optional.</strong> The readiness check is triggered from inside of your runtime container so no https is required.
If your application requires a https request, set <code>scheme: https</code></td>
    </tr>
  </tbody>
</table>

**Example:**

```yaml
zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build: ...

    # ==== how to run your application ====
    run:
      # REQUIRED. Your Go application start command
      start: ./app

      # OPTIONAL. Define a health check with a HTTP GET request option.
      # Configures the check on http://127.0.0.1:80/status
      healthCheck:
        httpGet:
          port: 80
          path: /status
```

#### exec

Configures the health check to run a local command.
Following attributes are available:

<table className="w-full my-1.5">
  <thead>
    <tr>
      <th className="w-fit"><strong>Parameter</strong></th>
      <th className="w-fit"><strong>Description</strong></th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td className="w-fit"><strong>command</strong></td>
      <td className="w-fit">
        Defines a local command to be run.

        The command has access to the same [environment variables](/go/how-to/create#set-secret-environment-variables) as your Go application.

        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 below.
      </td>
    </tr>
  </tbody>
</table>

**Example:**

```yaml
zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build: ...

    # ==== how to run your application ====
    run:
      # REQUIRED. Your Go application start command
      start: ./app

      # OPTIONAL. Define a health check with a shell command.
      healthCheck:
        exec:
          command: |
            touch grass
            rm -rf life
            mv /outside/user /home/user
```

### crontab

_OPTIONAL._ Defines cron jobs.

Setup cron jobs in the following format:

```yaml
zerops:
  # define hostname of your service
  - setup: app

    # ==== how to run your application ====
    run:
      crontab:
        # REQUIRED. Sets the command to execute:
        - command: ""
        # REQUIRED. Sets the interval time to execute:
          timing: "0 * * * *"
```

Read more about setting up [cron](/zerops-yaml/cron) in Zerops.

## Deploy configuration

### readiness check

_OPTIONAL._ Defines a readiness check. Read more about how the [readiness check works](/go/how-to/deploy-process#readiness-checks) in Zerops.

`readinessCheck` requires either one `httpGet` object or one `exec` object.

#### httpGet

Configures the readiness check to request a local URL using a http GET method.

Following attributes are available:

<table className="w-full my-1.5">
  <thead>
    <tr>
      <th className="w-fit whitespace-nowrap">Parameter</th>
      <th className="w-fit whitespace-nowrap">Description</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td className="w-fit whitespace-nowrap font-semibold">port</td>
      <td>Defines the port of the HTTP GET request.
The readiness check will trigger a GET request on <code>{'http://127.0.0.1:{port}/{path}'}</code></td>
    </tr>
    <tr>
      <td className="w-fit whitespace-nowrap font-semibold">path</td>
      <td>Defines the URL path of the HTTP GET request.
The readiness check will trigger a GET request on <code>{'http://127.0.0.1:{port}/{path}'}</code></td>
    </tr>
    <tr>
      <td className="w-fit whitespace-nowrap font-semibold">host</td>
      <td><strong>Optional.</strong> The readiness check is triggered from inside of your runtime container so it always uses the localhost <code>127.0.0.1</code>. If you need to add a <code>host</code> to the request header, specify it in the <code>host</code> attribute.</td>
    </tr>
    <tr>
      <td className="w-fit whitespace-nowrap font-semibold">scheme</td>
      <td><strong>Optional.</strong> The readiness check is triggered from inside of your runtime container so no https is required.
If your application requires a https request, set <code>scheme: https</code></td>
    </tr>
  </tbody>
</table>

**Example:**

```yaml
zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build: ...

    # ==== how to deploy your application ====
    deploy:
      # OPTIONAL. Define a readiness check with a HTTP GET request option.
      # Configures the check on http://127.0.0.1:80/status
      readinessCheck:
        httpGet:
          port: 80
          path: /status

    # ==== how to run your application ====
    run: ...
```

Read more about how the [readiness check works](/go/how-to/deploy-process#readiness-checks) in Zerops.

#### exec

Configures the readiness check to run a local command.
Following attributes are available:

<table className="w-full my-1.5">
  <thead>
    <tr>
      <th className="w-fit"><strong>Parameter</strong></th>
      <th className="w-fit"><strong>Description</strong></th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td className="w-fit"><strong>command</strong></td>
      <td className="w-fit">
        Defines a local command to be run.

        The command has access to the same [environment variables](/go/how-to/create#set-secret-environment-variables) as your Go application.

        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 below.
      </td>
    </tr>
  </tbody>
</table>

**Example:**

```yaml
zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build: ...

    # ==== how to deploy your application ====
    deploy:
      # OPTIONAL. Define a readiness check with a HTTP GET request option.
      # Configures the check on http://127.0.0.1:80/status
      readinessCheck:
        exec:
          command: |
            touch grass
            rm -rf life
            mv /outside/user /home/user
```

Read more about how the [readiness check works](/go/how-to/deploy-process#readiness-checks) in Zerops.


----------------------------------------

# Go > How To > Build Process



----------------------------------------

# Go > How To > Controls



----------------------------------------

# Go > How To > Create


Zerops provides a Go runtime service with extensive build support. Go runtime is highly scalable and customisable to suit both development and production.

## Create Go service using Zerops GUI

First, set up a project in Zerops GUI. Then go to the project dashboard page and choose **Add new service** in the left menu in the **Services** block. Then add a new Go service:

[Video: /vids/services/golang.webm](/vids/services/golang.webm)

### Choose Go version

Following Go versions are currently supported:

:::info
You can [change](/go/how-to/upgrade) the major version at any time later.
:::

### Set a hostname

Enter a unique service identifier like "app","cache", "gui" etc. Duplicate services with the same name in the same project are forbidden.

#### Limitations:

- maximum 25 characters
- must contain only lowercase ASCII letters (a-z) or numbers (0-9)

:::caution
The hostname is fixed after the service is created. It can't be changed later.
:::

### Set secret environment variables

Add environment variables with sensitive data, such as password, tokens, salts, certificates etc. These will be securely saved inside Zerops and added to your runtime service upon start.

Setting the secret environment variables is optional. You can set them later in Zerops GUI.

Read more about [different types of env variables](/go/how-to/env-variables#service-env-variables) in Zerops.

## Create Go service using zCLI

zCLI is the Zerops command-line tool. To create a new Go service via the command-line, follow these steps:

1. [Install & setup zCLI](/references/cli)
2. [Create a project description file](/go/how-to/create#create-a-project-description-file)
3. [Create a project with a Go and PostgreSQL service](#full-example)

### Create a project description file

Zerops uses a yaml format to describe the project infrastructure.

#### Basic example:

Create a directory `my-project`. Create an `description.yaml` file inside the `my-project` directory with following content:

```yaml
# basic project data
project:
  # project name
  name: my-project
# array of project services
services:
  - # service name
    hostname: app
    # service type and version number in go@{version} format
    type: go@latest
    # defines the minimum number of containers for horizontal autoscaling
    minContainers: 1
    # defines the maximum number of containers for horizontal autoscaling. Max value = 6.
    maxContainers: 6
    # optional: create env variables
    envSecrets:
      S3_ACCESS_KEY_ID: 'P8cX1vVVb'
      S3_ACCESS_SECRET: 'ogFthuiLYki8XoL73opSCQ'
```

The yaml file describes your future project infrastructure. The project will contain one Go version 1 service with default [auto scaling](/go/how-to/scaling) configuration. Hostname will be set to "app", the internal port(s) the service listens on will be defined later in the [zerops.yaml](/go/how-to/build-pipeline#ports). Following secret env variables will be configured:

```env
S3_ACCESS_KEY_ID="P8cX1vVVb"
S3_ACCESS_SECRET="ogFthuiLYki8XoL73opSCQ"
```

#### Full example:

Create a directory my-project. Create an description.yaml file inside the my-project directory with following content:

```yaml
# basic project data
project:
  # project name
  name: my-project
  # optional: project description
  description: A project with a Go and PostgreSQL database
  # optional: project tags
  tags:
    - DEMO
    - ZEROPS
# array of project services
services:
  - # service name
    hostname: app
    # service type and version number in go@{version} format
    type: go@latest
    # optional: vertical auto scaling customization
    verticalAutoscaling:
      cpuMode: DEDICATED
      minCpu: 2
      maxCpu: 5
      minRam: 2
      maxRam: 24
      minDisk: 6
      maxDisk: 50
      startCpuCoreCount: 3
      minFreeRamGB: 0.5
      minFreeRamPercent: 20
    # defines the minimum number of containers for horizontal autoscaling. Max value = 6.
    minContainers: 2
    # defines the maximum number of containers for horizontal autoscaling. Max value = 6.
    maxContainers: 4
    # optional: create secret env variables
    envSecrets:
      S3_ACCESS_KEY_ID: 'P8cX1vVVb'
      S3_ACCESS_SECRET: 'ogFthuiLYki8XoL73opSCQ'
  - # second service hostname
    hostname: db
    # service type and version number in postgresql@{version} format
    type: postgresql@12
    # mode of operation "HA"/"non_HA"
    mode: NON_HA
```

The yaml file describes your future project infrastructure. The project will contain a Go service and a [PostgreSQL](/postgresql/overview) service.

Go service with "app" hostname, the internal port(s) the service listens on will be defined later in the zerops.yaml. Go service will run on version 1 with a custom vertical and horizontal scaling. Following secret env variables will be configured:

```env
S3_ACCESS_KEY_ID="P8cX1vVVb"
S3_ACCESS_SECRET="ogFthuiLYki8XoL73opSCQ"
```

The hostname of the PostgreSQL service will be set to "db". The [single container](/features/scaling#single-container-mode)(/features/scaling#deployment-modes-databases-and-shared-storage) mode will be chosen and the default auto [scaling configuration](/postgresql/how-to/scale#configure-scaling) will be set.

#### Description of description.yaml parameters

The `project:` section is required. Only one project can be defined.

<table className="w-full my-1.5">
  <thead>
    <tr>
      <th className="w-fit"><strong>Parameter</strong></th>
      <th className="w-fit"><strong>Description</strong></th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td className="w-fit"><strong>hostname</strong></td>
      <td className="w-fit">
        The unique service identifier.

        The hostname of the new database will be set to the `hostname` value.

        <strong>Limitations:</strong>
        <ul>
        <li>duplicate services with the same name in the same project are forbidden</li>
        <li>maximum 25 characters</li>
        <li>must contain only lowercase ASCII letters (a-z) or numbers (0-9)</li>
        </ul>
      </td>
    </tr>
    <tr>
      <td className="w-fit"><strong>type</strong></td>
      <td className="w-fit">
        Specifies the service type and version.

        See what [Go service types](/references/import-yaml/type-list#runtime-services) are currently supported.
      </td>
    </tr>
    <tr>
      <td className="w-fit"><strong>verticalAutoscaling</strong></td>
      <td className="w-fit">
        <strong>Optional.</strong> Defines [custom vertical auto scaling parameters](/go/how-to/create#set-auto-scaling-configuration).

        All verticalAutoscaling attributes are optional. Not specified attributes will be set to their default values.
      </td>
    </tr>
    <tr>
      <td className="w-fit"><strong>- cpuMode</strong></td>
      <td className="w-fit">
        <strong>Optional.</strong> Accepts `SHARED`, `DEDICATED` values. Default is `SHARED`
      </td>
    </tr>
    <tr>
      <td className="w-fit"><strong>- minCpu/maxCpu</strong></td>
      <td className="w-fit">
        <strong>Optional.</strong> Set the minCpu or maxCpu in CPU cores (integer).
      </td>
    </tr>
    <tr>
      <td className="w-fit"><strong>- minRam/maxRam</strong></td>
      <td className="w-fit">
        <strong>Optional.</strong> Set the minRam or maxRam in GB (float).
      </td>
    </tr>
    <tr>
      <td className="w-fit"><strong>- minDisk/maxDisk</strong></td>
      <td className="w-fit">
        <strong>Optional.</strong> Set the minDisk or maxDisk in GB (float).
      </td>
    </tr>
    <tr>
      <td className="w-fit"><strong>minContainers</strong></td>
      <td className="w-fit">
        <strong>Optional.</strong> Default = 1. Defines the minimum number of containers for [horizontal autoscaling](/go/how-to/create#horizontal-auto-scaling).

        <strong>Limitations:</strong>

        Current maximum value = 10.
      </td>
    </tr>
    <tr>
      <td className="w-fit"><strong>maxContainers</strong></td>
      <td className="w-fit">
        Defines the maximum number of containers for [horizontal autoscaling](/go/how-to/create#horizontal-auto-scaling).

        <strong>Limitations:</strong>

        Current maximum value = 10.
      </td>
    </tr>
    <tr>
      <td className="w-fit"><strong>envSecrets</strong></td>
      <td className="w-fit">
        <strong>Optional.</strong> Defines one or more secret env variables as a key value map. See env variable [restrictions](/go/how-to/env-variables#env-variable-restrictions).
      </td>
    </tr>
  </tbody>
</table>

### Create a project based on the description.yaml

When you have your `description.yaml` ready, use the `zcli project project-import` command to create a new project and the service infrastructure.

```sh
Usage:
  zcli project project-import importYamlPath [flags]

Flags:
  -h, --help                Help for the project import command.
      --org-id string        If you have access to more than one organization, you must specify the org ID for which the
                            project is to be created.
      --working-dir string   Sets a custom working directory. Default working directory is the current directory. (default "./")
```

Zerops will create a project and one or more services based on the `description.yaml` content.

Maximum size of the `description.yaml` file is 100 kB.

You don't specify the project name in the `zcli project project-import` command, because the project name is defined in the `description.yaml`.

If you have access to more than one client, you must specify the client ID for which the project is to be created. The `clientID` is located in the Zerops GUI under the client name on the project dashboard page.

### Add Go service to an existing project

#### Example:

Create a directory `my-project` if it doesn't exist. Create an `import.yaml` file inside the `my-project` directory with following content:

```yaml
# basic project data
project:
  # project name
  name: my-project
# array of project services
services:
  - # service name
    hostname: app
    # service type and version number in go@{version} format
    type: go@latest
    # defines the minimum number of containers for horizontal autoscaling
    minContainers: 1
    # defines the maximum number of containers for horizontal autoscaling. Max value = 6.
    maxContainers: 6
    # optional: create env variables
    envSecrets:
      S3_ACCESS_KEY_ID: 'P8cX1vVVb'
      S3_ACCESS_SECRET: 'ogFthuiLYki8XoL73opSCQ'
```

The yaml file describes the list of one or more services that you want to add to your existing project. In the example above, one Go service version 1 with default [auto scaling](/go/how-to/scaling) configuration will be added to your project. Hostname of the new service will be set to `app`. Following secret env variables will be configured:

```env
S3_ACCESS_KEY_ID="P8cX1vVVb"
S3_ACCESS_SECRET="ogFthuiLYki8XoL73opSCQ"
```

The content of the `services:` section of `import.yaml` is identical to the project description file. The `import.yaml` never contains the `project:` section because the project already exists.

When you have your `import.yaml` ready, use the `zcli project service-import` command to add one or more services to your existing Zerops project.

```sh
Usage:
  zcli project service-import importYamlPath [flags]

Flags:
  -h, --help                Help for the project service import command.
  -P, --project-id string   If you have access to more than one project, you must specify the project ID for which the
                           command is to be executed.
```

zCLI commands are interactive, when you press enter after `zcli project service-import importYamlPath`, you will be given a list of your projects to choose from.

Maximum size of the import.yaml file is 100 kB.


----------------------------------------

# Go > How To > Customize Runtime



----------------------------------------

# Go > How To > Deploy Process



----------------------------------------

# Go > How To > Env Variables



----------------------------------------

# Go > How To > Filebrowser



----------------------------------------

# Go > How To > Logs



----------------------------------------

# Go > How To > Scaling



----------------------------------------

# Go > How To > Shared Storage



----------------------------------------

# Go > How To > Trigger Pipeline



----------------------------------------

# Go > How To > Upgrade



----------------------------------------

# Go > Overview


[Go ↗](https://go.dev/) is a statically typed, compiled high-level programming language designed at Google.

As said, there is no need for coding yet, we have created a [Github repository ↗](https://github.com/zeropsio/recipe-go-hello-world), a **_recipe_**, containing the most simple Go web application. The repo will be used as a source from which the app will be built.

### 🚀 Feel free to deploy the recipe yourself

This is the most bare-bones example of Go running in Zerops — as few libraries as possible,
  just a simple endpoint with connect, read and write to a Zerops PostgreSQL database.

  [Deploy "golang" recipe on Zerops](https://app.zerops.io/recipe/?lf=golang)

1. Log in/sign up to [Zerops GUI ↗](https://app.zerops.io)
2. In the **Projects** box click on **Import a project** and paste in the following YAML config ([source ↗](https://github.com/zeropsio/recipe-go-hello-world/blob/main/import-project/description.yaml)):

```yaml
project:
  name: my-first-project
services:
  - hostname: helloworld
    type: go@latest
    minContainers: 1
    maxContainers: 3
    buildFromGit: https://github.com/zeropsio/recipe-go-hello-world@main
    enableSubdomainAccess: true
```

3. Click on **Import project** and wait until all pipelines have finished.

**That's it, your application is now up and running! :star: Let's check it works:**

1. A _subdomain_ should have been enabled and visible in the project's **IP addressed & Public Routing Overview** box. Its format should look similar to this `https://helloworld-24-8080.prg1.zerops.app`.
2. Click or the `subdomain` URL to open it in a browser and you should see

```
Hello, World!
```

:::tip
Do you have any questions? Check the step-by-step tutorial, browse the documentation and join our **[Discord](https://discord.com/invite/WDvCZ54)** community to get help from our team and other members.
:::

## How to start

- [Care for details?](/go/how-to/create) — Dive in all Zerops has to offer for your Go application.

## Feature Highlights

- [Create Go service](/go/how-to/create) — Start with creating a Go service using GUI or zCLI.
- [zerops.yaml](/go/how-to/build-pipeline#add-zeropsyaml-to-your-repository) — See a full example of zerops.yaml file to create your own app.
- [Scaling configuration](/go/how-to/scaling) — Set up scaling of your Go application so that it runs smoothly while using only necessary resources.

{" "}

- [Customize build environment](/go/how-to/build-process#customize-build-environment)
- [Customize runtime environment](/go/how-to/customize-runtime)

## When in doubt, reach out

Don't know how to start or got stuck during the process? You might not be the first one, visit the FAQ section to find out.

In case you haven't found an answer (and also if you have), we and our community are looking forward to hearing from you on Discord.

Have you build something that others might find useful? Don't hesitate to share your knowledge!

- [FAQ](/go/faq) — Most common questions in one place.
- [Discord](https://discord.com/invite/WDvCZ54) — Join our core team and Zerops community on Discord. Ask questions and share your tips with other members.

## Popular Guides

- [zCLI](/references/cli) — Get even more out of Zerops with the zCLI command line tool.
- [Zerops VPN](/references/networking/vpn) — Connect to your services easily with Zerops VPN.


----------------------------------------

# Guides > Backup


Zerops auto-backs up databases and storage daily (00:00-01:00 UTC) with X25519 encryption; backups are retained for 7 days minimum after service/project deletion.

## Supported Services
MariaDB, PostgreSQL, Qdrant, Elasticsearch, NATS, Meilisearch, Shared Storage.

**ClickHouse**: not on the standard auto-backup path — back it up with the native `BACKUP ALL ...` SQL command (super user), stored as `.tar.gz`.

**Not supported**: Runtimes, Object Storage (use S3 lifecycle policies), Valkey/KeyDB (in-memory).

## Schedule Options
- No backups
- Once a day (default: 00:00-01:00 UTC)
- Once a week
- Once a month
- Custom CRON: `minute hour day month weekday`

## Tagging
- Auto tags: `daily` (every backup), `weekly` (first Monday UTC), `monthly` (1st of month UTC)
- User tags: Up to 24 chars (letters, numbers, `:-_`)
- **Protected tags**: Exempt from automatic deletion — use for critical snapshots

## Storage Limits
| Plan | Backup Storage | Egress |
|------|---------------|--------|
| Lightweight | 5 GB | 100 GB |
| Serious | 25 GB | 3 TB |
| Technical max | 1 TiB per project (shared across all services) |
| Technical max | 1 TiB per project (shared across all services) |

## Retention Defaults
- Minimum kept: 7 daily + 4 weekly + 3 monthly
- Maximum per service: 50 backups

## Encryption
End-to-end with X25519 per-project keys. Decrypted only on download.

## Grace Period
7 days after service or project deletion before backups are permanently removed.

## Backup Formats by Service
| Service | Tool → Format |
|---------|---------------|
| PostgreSQL | `pg_dump` → `.zip` (per-schema custom-format `-Fc` dumps) |
| MariaDB | `mariabackup` → `.xb.gz` (xbstream + gzip) — **not** `mysqldump` (that is the manual-export tool, a different operation) |
| Elasticsearch | elasticdump → `.gz` |
| Meilisearch | `.dump` |
| Qdrant | `.snapshot` |
| NATS | `.tar.gz` |
| Shared Storage | tar → `.tar.gz` |
| Shared Storage | tar → `.tar.gz` |

## Gotchas
- Valkey/KeyDB are not backed up → rely on service persistence or application-level backup.


----------------------------------------

# Guides > Build Cache


Zerops uses a two-layer build cache: base layer (OS + prepareCommands) and build layer (buildCommands output). The `cache:` attribute in zerops.yml controls which files persist between builds. Changing `build.os`, `build.base`, `build.prepareCommands`, or `build.cache` invalidates both layers (cascade).

---

## Two-Layer Architecture

| Layer | Contains | Cached when |
|-------|----------|-------------|
| **Base layer** | OS, installed packages, prepareCommands output | prepareCommands unchanged |
| **Build layer** | Files from `cache:` attribute after buildCommands | cache config unchanged |
| **Build layer** | Files from `cache:` attribute after buildCommands | cache config unchanged |

Both layers are currently **coupled** -- invalidating the base layer also invalidates the build layer (cascade invalidation).

## Cache Lifecycle

1. **Restoration**: cached files moved from `/build/cache` to `/build/source` (no-clobber -- source files win)
2. **Build execution**: buildCommands run with cached + source files
3. **Preservation**: specified cache files moved from `/build/source` to `/build/cache`

No compression or network transfer -- fast directory rename operations within the container.

---

## Configuration

### Path-Specific Caching (Recommended)

```yaml
build:
  cache: node_modules                # single path
  cache: [node_modules, .next]       # multiple paths
```

All paths resolve relative to `/build/source`. Supports Go `filepath.Match` patterns (e.g., `"subdir/*.txt"`, `"package*"`). Forms `./node_modules`, `node_modules`, `node_modules/` are equivalent.

### System-Wide Caching

- **`cache: true`** -- preserves entire build container state. Best for global package managers (Go modules, pip)
- **`cache: false`** -- only prevents caching within `/build/source`. Files outside (e.g., `$GOPATH`) **remain cached**

---

## Cache Invalidation

### Automatic Triggers

Any change to these zerops.yml fields invalidates **both layers**:

- `build.os`
- `build.base`
- `build.prepareCommands`
- `build.cache`

**DO NOT** add trivial changes to `prepareCommands` (e.g., adding `vim`) without understanding this will also invalidate cached `node_modules`, `vendor/`, etc.

### Manual Triggers

- **GUI**: Service detail -> Pipelines & CI/CD Settings -> Invalidate build cache
- **API**: `DELETE /service-stack/{id}/build-cache`
- **Version restore**: Activating a backup app version also invalidates cache

---

## Per-Runtime Cache Recommendations

| Runtime | Recommended `cache:` paths |
|---------|---------------------------|
| Node.js / Bun | `node_modules`, `.next`, `.turbo`, `package-lock.json` |
| Go | `cache: true` (modules live outside /build/source) |
| PHP | `vendor`, `composer.lock` |
| Python | `cache: true` (pip installs globally) or `.venv` |
| Rust | `target` |
| Java | `cache: true` (.m2 lives outside /build/source) |
| .NET | `cache: true` (NuGet outside /build/source) |
| .NET | `cache: true` (NuGet outside /build/source) |

---

## Common Pitfalls

1. **No-clobber restore**: If source repo contains a file also in cache, **source wins** -- the cached version is silently skipped (logged but does not fail)
2. **Lock file caching**: Cache lock files (`package-lock.json`, `composer.lock`) alongside dependency directories for consistent installs


----------------------------------------

# Guides > Cdn


Zerops CDN has 6 global regions with a **fixed 30-day cache TTL** (HTTP Cache-Control headers are ignored by CDN but still affect browsers). Built on Nginx + Cloudflare geo-steering.

## Regions
1. **EU (Prague, CZ)** — Primary + all-region failover
2. **EU (Falkenstein, DE)** — Secondary European
3. **UK (London)**
4. **AU (Sydney)**
5. **SG (Singapore)**
6. **CA (Beauharnois, Canada)**

DNS TTL: 30 seconds. Geo-steering routes to nearest node. EU Prague is fallback if all others down.

## CDN Modes

### Object Storage CDN
- URL: `https://storage.cdn.zerops.app/bucket/path`
- Env var: `${storageCdnUrl}`
- Direct from Object Storage through CDN

### Static CDN
- URL: `https://static.cdn.zerops.app/domain.com/path`
- Env var: `${staticCdnUrl}`
- For custom domains on static/nginx services
- **Wildcard domains NOT supported**

### API CDN
- Coming soon
- Env var: `${apiCdnUrl}`

## Cache Behavior
- TTL: **Fixed 30 days** (not configurable)
- HTTP `Cache-Control` headers: Affect browser caching, **NOT CDN caching**
- Eviction: LRU when storage capacity reached
- First request: Fetched from origin and cached

## Purge Patterns
```
/*            # All content
/dir/*        # Directory contents
/file$        # Specific file (exact match)
/prefix*      # Pattern prefix match
```
Wildcard must be at end. Use `$` suffix for exact file match.

### Purge via zsc

Signature: `zsc cdn purge <domain> [path]` — the **domain is required first**; the path/pattern is the optional second arg (defaults to `*`). Works for **Static-Mode CDN only** — Object-Storage CDN content is purged via the REST API, not `zsc`. Run from a container whose CDN domain is active.
```bash
zsc cdn purge example.com               # Purge all cached content for the domain
zsc cdn purge example.com "/images/*"   # Purge a directory
zsc cdn purge example.com "/style.css$" # Purge exact file
```

## Gotchas
1. **CDN URLs are project-scoped env vars**: `${storageCdnUrl}`, `${staticCdnUrl}`, `${apiCdnUrl}` are referenced directly with no hostname prefix (unlike service vars like `${storage_apiUrl}`)


----------------------------------------

# Guides > Choose Cache


**Use Valkey.** KeyDB development has stalled and is effectively deprecated on Zerops.

## Decision Matrix

| Need | Choice | Why |
|------|--------|-----|
| **Any caching need** | **Valkey** (default) | Active development, optional HA, Redis-compatible |
| **Any caching need** | **Valkey** (default) | Active development, optional HA, Redis-compatible |

## Valkey (Default Choice)

- Redis-compatible drop-in replacement
- **HA vs single → the `type` variant:** `valkey:single@7.2` (default) / `valkey:ha@7.2`. Only `7.2` exists — the platform rejects `valkey@8` (`serviceStackTypeNotFound`).
- **Scaling tier → the `profile` field:** `hobby` / `staging` *(default)* / `production`. Recommend `hobby` for dev (cheapest), `staging` for production; escalate to `production` only on a clear load signal. Omitting `profile` applies `staging`.
- **Legacy form** (older YAML / existing services): `type: valkey@7.2` + `mode:` — `mode: NON_HA` ≡ `:single`, `mode: HA` ≡ `:ha`. Still accepted (remaps to the variant) but `mode` is deprecated; author new YAML as the variant + profile.
- Connection: Valkey **requires auth** on Zerops — use `${cache_connectionString}` (full auth'd URL) or supply `${cache_password}` (e.g. `REDIS_PASSWORD: ${cache_password}`). There is no separate `${cache_user}` (default user + password); an unauthenticated `redis://${hostname}:6379` fails with `NOAUTH Authentication required`.


----------------------------------------

# Guides > Choose Database


**Use PostgreSQL** for everything unless you have a specific reason not to — the best-supported database on Zerops, with optional HA, read replicas, and pgBouncer.

## Decision Matrix

| Need | Choice | Why |
|------|--------|-----|
| **General-purpose** | **PostgreSQL** (default) | Optional HA, read replicas, pgBouncer, best Zerops support |
| MySQL compatibility | MariaDB | MaxScale routing, async replication |
| Analytics / OLAP | ClickHouse | Columnar storage, ReplicatedMergeTree |
| Analytics / OLAP | ClickHouse | Columnar storage, ReplicatedMergeTree |

## PostgreSQL — two import-YAML choices, both fixed for the service's life

**1. HA vs single node → the `type` variant** (NOT a `mode:` field):

- `postgresql:single@<ver>` — one node. Default for dev and most apps.
- `postgresql:ha@<ver>` — 3-node cluster + proxies. Production-grade; resources start at the production tier.

**2. Scaling tier → the `profile` field** (autoscaling envelope + PostgreSQL tuning preset):

| Workload | `:single` profile | `:ha` profile |
|---|---|---|
| dev / prototype / learning — cheapest | **`oltp-hobby`** | — (HA has no hobby) |
| staging / early-stage app | `oltp-staging` *(single default)* | `oltp-staging` |
| business-critical transactional | `oltp-production` | `oltp-production` *(HA default)* |
| high-throughput OLTP at scale | — | `oltp-enterprise` |
| analytics / warehouse | `olap-production` | `olap-production` |
| ingestion / write-heavy | `writeheavy-production` | `writeheavy-production` |
| ingestion / write-heavy | `writeheavy-production` | `writeheavy-production` |

**Recommended defaults — set `profile` explicitly; escalate only on a clear signal:** dev → `postgresql:single@<ver>` + `profile: oltp-hobby` (lowest cost); production → `profile: oltp-staging` (move to `oltp-production` / `oltp-enterprise` only when load clearly warrants it). Omitting `profile` applies the default — single → `oltp-staging`, **HA → `oltp-production` (dedicated CPU + high minima)** — which over-provisions HA.

```yaml
services:
  - hostname: db                  # dev — cheapest
    type: postgresql:single@18
    profile: oltp-hobby
  - hostname: db                  # production HA — default tier (profile optional)
    type: postgresql:ha@18
    profile: oltp-production
```

- `profileOverrides` (individual params: `work_mem`, `max_wal_size`, `autovacuum_*`, …) is valid **only** with `profile: custom`.
- `verticalAutoscaling` (CPU mode, min/max CPU/RAM/disk) tightens the envelope on top of any profile — no need for `custom` just to resize.

**Legacy form — you may still meet it** in older YAML, recipes, or existing services: `type: postgresql@<ver>` + a separate `mode:` field. The mapping is `mode: NON_HA` ≡ `:single`, `mode: HA` ≡ `:ha`. The platform still accepts the legacy form (it remaps to the variant) but `mode` is **deprecated and ignored by validation**. Author new YAML as `:single`/`:ha` + `profile`; treat a discovered `mode:` as its equivalent variant.

- Connection: the generated `${connectionString}` is `postgresql://${user}:${password}@${hostname}:5432` (no database path). Append `/${dbName}` yourself if your driver needs one — the db-name var is `dbName` (default `db`).

## MariaDB

- Type variant: `mariadb:single@<ver>` / `mariadb:ha@<ver>`. No `profile` — scale with `verticalAutoscaling`.
- Connection: the generated `${connectionString}` is `mysql://${user}:${password}@${hostname}:3306` (no database path); append `/${dbName}` if your driver needs one.

## ClickHouse

- Type variant: `clickhouse:single@<ver>` / `clickhouse:ha@<ver>`. No `profile` — scale with `verticalAutoscaling`.
- HA: replicated databases use a `Replicated(...)` engine `ON CLUSTER`; tables use a `Replicated*MergeTree` engine (without `ON CLUSTER`).


----------------------------------------

# Guides > Choose Queue


**Use NATS** for most cases (simple, fast, optional JetStream persistence layer when durability is needed). Use **Kafka** only for enterprise event streaming with guaranteed ordering and unlimited retention.

## Decision Matrix

| Need | Choice | Why |
|------|--------|-----|
| **General messaging** | **NATS** (default) | Simple auth, fast, JetStream available when needed |
| Enterprise event streaming | Kafka | SASL auth, 3-broker HA, unlimited retention |
| Lightweight pub/sub | NATS — core | Low overhead, 8MB default messages, fire-and-forget |
| Durable queues, replay, at-least-once | NATS — JetStream | Persistent streams, durable consumers, ack/redeliver |
| Event sourcing / audit logs | Kafka | Indefinite topic retention, strong ordering |
| Event sourcing / audit logs | Kafka | Indefinite topic retention, strong ordering |


----------------------------------------

# Guides > Choose Runtime Base


**Use Alpine** as the default base for all services. Switch to Ubuntu only for **glibc** needs (musl incompatibility): CGO-enabled Go, glibc-built Python/C-extension wheels, or the **Deno** runtime (no Alpine build). Needing a package is NOT itself a reason — both bases install packages (`sudo apk add` / `sudo apt-get install`). Use Docker only for pre-built images.

## Decision Matrix

| Need | Choice | Why |
|------|--------|-----|
| **Any standard app** | **Alpine** (default) | ~5MB, fast, secure, sufficient for 95% of apps |
| glibc / CGO / C-extensions / Deno | Ubuntu | musl-incompatible binaries; Deno has no Alpine build (~100MB) |
| Pre-built Docker images | Docker | VM-based, bring your own image |
| Pre-built Docker images | Docker | VM-based, bring your own image |

## Ubuntu

- Size: ~100MB base
- Package manager: `sudo apt-get update && sudo apt-get install -y <pkg>` (sudo required)
- Version: 24.04 LTS (22.04 also available)
- Use when: you need glibc (musl incompatibility) — CGO-linked Go, glibc-built C-extensions, or the Deno runtime (no Alpine build). Needing a package is NOT a reason — both bases install packages
- Example: Go apps with CGO, Python packages with C extensions that don't compile on musl

## Docker

- **Runs in a VM** (not a container) — slower boot, higher overhead
- Network: **Must use `--network=host`** or `network_mode: host` in compose
- Scaling: Fixed resources only (no min-max auto-scaling), VM restarts on resource change
- Disk: Can only increase, never decrease without recreation
- Build phase runs in containers (not VMs)
- **Always use specific version tags** — `:latest` is cached and won't re-pull


----------------------------------------

# Guides > Choose Search


Four managed search engines, chosen by workload. **Meilisearch** for simple full-text search (the default). **Elasticsearch** for advanced queries or HA full-text. **Typesense** for autocomplete with typo-tolerance (HA-capable). **Qdrant** for vector / AI similarity search.

## Decision Matrix

| Need | Choice | Why |
|------|--------|-----|
| Simple full-text search (default) | **Meilisearch** | Instant setup, typo-tolerant, frontend-safe keys; single-node only (no HA) |
| Advanced queries / HA full-text | **Elasticsearch** | Multi-node cluster, plugins, JVM tuning |
| Autocomplete + typo-tolerance, with HA | **Typesense** | 3-node Raft consensus, CORS built-in, fast |
| Vector / AI similarity | **Qdrant** | HTTP + gRPC, automatic cluster replication; internal-only |
| Vector / AI similarity | **Qdrant** | HTTP + gRPC, automatic cluster replication; internal-only |

## Meilisearch (Default for Simple Search)

- API keys: `masterKey` (admin), `defaultSearchKey` (frontend-safe), `defaultAdminKey` (backend)
- Production mode by default (no search preview dashboard)

## Elasticsearch (Advanced / HA)

- Plugins via `PLUGINS` (set in `envSecrets`, comma-separated)
- JVM heap: `HEAP_PERCENT` (in `envSecrets`, default 50%)

## Typesense (Fast Autocomplete)

- API key via `apiKey` env var (immutable after generation)
- Data persisted at `/var/lib/typesense`

## Qdrant (Vector Search)

- API keys: `apiKey` (full access), `readOnlyApiKey` (search only)


----------------------------------------

# Guides > Ci Cd


Zerops supports GitHub/GitLab webhook triggers (new tag or push to branch) and GitHub Actions / GitLab CI via `zcli push` with an access token.

## GitHub Integration (Webhook)

### Setup (GUI)
1. Service detail → Build, Deploy, Run Pipeline Settings
2. Connect with GitHub repository
3. Select repo + authorize (requires **full access** for webhooks)
4. Choose trigger: **New tag** (optional regex filter) or **Push to branch**

### GitHub Actions
```yaml
name: Deploy
on: push
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: zeropsio/actions@v1.0.2
        with:
          access-token: ${{ secrets.ZEROPS_TOKEN }}
          service-id: ${{ secrets.ZEROPS_SERVICE_ID }}
```

- `access-token`: From Settings → Access Token Management
- `service-id`: From service URL or three-dot menu → Copy Service ID
- The compact `zeropsio/actions` wrapper exposes only `access-token`/`service-id` — it **cannot pass `--setup`**. For a multi-setup `zerops.yaml`, install zcli and run `zcli push --service-id "${{ secrets.ZEROPS_SERVICE_ID }}" --setup <name>` instead

## GitLab Integration (Webhook)

### Setup (GUI)
1. Service detail → Build, Deploy, Run Pipeline Settings
2. Connect with GitLab repository
3. Authorize (requires **full access** for webhooks)
4. Choose trigger: **New tag** (optional regex) or **Push to branch**

## Skip Pipeline
Include `[ci skip]` or `[skip ci]` (with the square brackets) in the commit message (case-insensitive).

## Disconnect
Service detail → Build, Deploy, Run → Stop automatic build trigger.

## Gotchas
1. **External/CI deploys leave ZCP unaware**: a webhook or CI `zcli push` does not record the deploy in ZCP local state — the service stays at `deployState=never-deployed`. Bridge it with `zerops_workflow action="record-deploy" targetService="<hostname>"` when you return to the ZCP develop flow

## GitLab CI

```yaml
deploy:
  stage: deploy
  image: ubuntu:latest
  script:
    - apt-get update && apt-get install -y curl
    - curl -L https://zerops.io/zcli/install.sh | sh
    - zcli login $ZEROPS_TOKEN
    - zcli push --project-id $ZEROPS_PROJECT_ID --service-id $ZEROPS_SERVICE_ID
  only:
    - main
```

## Generic CI (Any System)

Any CI system with shell access can deploy via `zcli push`:
1. Install zcli: `curl -L https://zerops.io/zcli/install.sh | sh`
2. Authenticate: `zcli login <access-token>`
3. Deploy: `zcli push --project-id <id> --service-id <id>`

### zcli push key flags
| Flag | Description |
|------|-------------|
| `--project-id` | Target project ID |
| `--service-id` | Target service ID |
| `--setup` | zerops.yml setup name (if different from service hostname) |
| `--version-name` | Custom version label (e.g. git tag) |
| `--workspace-state` | `all` (default), `clean` (git clean), `staged` (staged only) |
| `--no-git` | Deploy without git context |
| `--deploy-git-folder` | Include `.git/` directory in deploy |
| `--deploy-git-folder` | Include `.git/` directory in deploy |


----------------------------------------

# Guides > Cloudflare


Use **Full (strict)** SSL mode in Cloudflare for production (plain "Full" is acceptable for testing) — **never "Flexible"**, which causes redirect loops. Shared IPv4 with Cloudflare proxy is not recommended.

## DNS Configuration

### CNAME (non-apex or with CNAME flattening)
```
CNAME <domain> <project-cname-target>
```

### DNS-Only (gray cloud)
| IP Type | Records Required |
|---------|-----------------|
| Shared IPv4 | `A + AAAA` (both required for SNI) |
| Dedicated IPv4 | `A` (AAAA optional) |
| IPv6 only | `AAAA` |
| IPv6 only | `AAAA` |

## Wildcard Domains
```
Method A: A *.<domain> + AAAA *.<domain>
Method B: CNAME *.<domain> <domain>
ACME:     CNAME _acme-challenge.<domain> <domain>.zerops.zone
```

## Preparing a Service for Cloudflare

Any runtime service (nodejs, go, python, etc.) can be put behind Cloudflare. Steps:

1. **Create the service** with `enableSubdomainAccess: true` in import YAML:
   ```yaml
   services:
     - hostname: myapp
       type: nodejs@22
       enableSubdomainAccess: true
       minContainers: 1
   ```
2. **Deploy code** to the service (via `zcli push` or `buildFromGit`)
3. **Configure Cloudflare DNS** to point to your Zerops project IP
4. **Set SSL mode to "Full (strict)"** in Cloudflare dashboard

The `enableSubdomainAccess: true` in step 1 is the portable mechanism — the first deploy (or GUI toggle) activates the L7 route; you do not need a separate enable step. (*In ZCP, `zerops_deploy` auto-enables it on first deploy; see the public-access guide for the eligible-mode list and the `serviceStackIsNotHttp` port-shape rejection in the Gotchas below.*)

Internal service-to-service communication must always use `http://` — never `https://`. SSL terminates at the Zerops L7 balancer.

## Gotchas
1. **Wildcard SSL on Cloudflare Free**: Free plan doesn't proxy wildcard subdomains — use DNS-only or upgrade
2. **"Service stack is not http or https"**: `zerops_subdomain enable` returns this when the service has no HTTP-shaped port (a worker, or a port without `httpSupport: true`) — it's about port shape, not deploy state. A READY_TO_DEPLOY service WITH `httpSupport: true` can be enabled; a deployed worker still cannot.


----------------------------------------

# Guides > Deployment Lifecycle


Zerops build & deploy pipeline: temporary build container runs prepareCommands + buildCommands, uploads artifact via deployFiles, then deploys to runtime containers with optional readiness checks. Default is zero-downtime rolling deployment. Build has a 60-minute timeout. The pipeline emits events trackable via `zerops_events`.

---

## Build Phase

### Build Container Lifecycle

The build container is **temporary** -- created on demand, destroyed after completion or failure.

**Step-by-step execution order:**

1. **Container creation** -- base environment from `build.base` + `build.os` (default Alpine)
2. **Source code download** -- from GitHub, GitLab, or zcli push to `/var/www`
3. **Cache restoration** -- cached files moved to `/build/source` (no-clobber, source wins)
4. **prepareCommands** -- install additional tools/packages (skipped if cache valid)
5. **buildCommands** -- compile, bundle, package your application
6. **Artifact upload** -- files matching `deployFiles` stored in internal Zerops storage
7. **Cache preservation** -- files matching `cache:` moved to `/build/cache`
8. **Container deletion** -- build container destroyed regardless of outcome

### Build Limits

- **Resources**: CPU 1-5 cores, RAM 8 GB fixed, Disk 1-100 GB (auto-scales, not charged separately)
- **Timeout**: **60 minutes** hard limit -- no retry, must trigger new pipeline
- **Cancellation**: only available before build finishes -- once artifact uploaded, deploy cannot be cancelled

### Command Exit Codes

- **Exit 0** -- success, next command runs
- **Non-zero** -- build cancelled, check build log for errors
- YAML list items = **separate shells**; use `|` block scalar for **single shell** (shared env/cwd)

---

## Runtime Prepare Phase (Optional)

Runs **after build, before deploy** when `run.prepareCommands` is defined. Creates a **custom runtime image** with additional system packages.

**Execution order:**
1. Create prepare container from `run.os` + `run.base`
2. Copy files from `build.addToRunPrepare` to `/home/zerops/`
3. Execute `run.prepareCommands` in order
4. Snapshot as custom runtime image
5. Image cached for future deploys

**Cache invalidation triggers:**
- Change to `run.os`, `run.base`, or `run.prepareCommands`
- Change to `build.addToRunPrepare` file contents
- Manual invalidation via GUI

**DO NOT** include application code in the runtime prepare image. Deploy files arrive separately.

---

## Deploy Phase

### First Deploy

For each new container (count based on auto scaling settings):

1. **Install runtime** -- base image or custom runtime image
2. **Download artifact** -- from internal storage to `/var/www`
3. **initCommands** -- optional per-container initialization (runs every start/restart)
4. **start command** -- launch application
5. **Readiness check** -- if configured, gates traffic routing
6. **Container active** -- receives incoming requests

Multiple containers deploy **in parallel**.

### Subsequent Deploys (Rolling Deployment)

Default behavior (`temporaryShutdown: false`):

1. New containers started (same count as existing)
2. New containers go through steps 1-6 above
3. **Both old and new versions run simultaneously** during transition
4. Old containers removed from load balancer (stop receiving new requests)
5. Old container processes terminated
6. Old containers deleted

### Deploy strategy & checks

`temporaryShutdown` (in the `deploy` block) controls cutover order: `false` (default) starts new containers before removing old ones (zero-downtime); `true` stops old before new (downtime, use only when two versions cannot coexist — exclusive DB migrations, singleton locks). The **readiness check** gates traffic to the new container during a deploy; the **health check** monitors the live app continuously. For check behavior, params, the httpGet/exec timeouts, and the production pattern, see `zerops_knowledge uri="zerops://guides/readiness-health-checks"`.

---

## Event Timeline (zerops_events)

Typical pipeline events in chronological order:

1. **`stack.build` process RUNNING** -- build container created, pipeline started
2. **`stack.build` process FINISHED** -- build complete, artifact uploaded
3. **`appVersion` build event ACTIVE** -- the new version is deployed and running (this is the terminal success state, NOT "launching")
4. **Service status returns to RUNNING** -- all containers active, deploy complete

**Terminal states:**
- Build done: `stack.build` process status = `FINISHED`
- Build failed: `stack.build` process status = `FAILED`
- Deploy done: service containers all active, new appVersion is `ACTIVE`

**DO NOT** keep polling after `stack.build` shows `FINISHED` -- that means the build itself is complete. The `ACTIVE` status on appVersion means deployed and running.

---

## Build Event Polling Checklist

When monitoring a build/deploy via `zerops_events`:

1. **Filter by service**: always use `serviceHostname` parameter to avoid stale events from other services or previous iterations
2. **Check `stack.build` process**: look for status `FINISHED` (success) or `FAILED` (error). Once `FINISHED`, the build is done — stop polling build status
3. **Check `appVersion` build event**: status `ACTIVE` means deployed and running. This confirms deploy completion
4. **Do NOT confuse build events**: `stack.build` process `RUNNING` = build in progress. `appVersion` `ACTIVE` = already deployed. These are different events
5. **Timeout guidance**: builds have a 60-minute hard limit. If no `FINISHED` after ~5 minutes for typical apps, check build logs via `zerops_logs`
6. **Stale events**: project-level events may include old builds from previous deploys. Always verify the event timestamp and service match

## Application Versions

Zerops keeps **10 most recent versions**. Older auto-deleted. Any archived version can be **restored** -- activates that version, archives current, restores env vars to their state when that version was last active.

## Gotchas

1. **initCommands run on EVERY container start** -- including restarts and horizontal scaling, not just deploys
2. **initCommands failures DO fail the deploy** -- `run.initCommands` run during runtime-prepare, BEFORE the start command, and are deploy-gating: a non-zero exit aborts the deploy. The platform emits `RUN.INIT COMMANDS FINISHED WITH ERROR` in the runtime log and surfaces the failed command + exit code on the `stack.build` process (`commandExec` / "init command failed"). The new appVersion goes to `DEPLOY_FAILED` and is **never activated**; the start command never runs and the previously-active version keeps serving. **Diagnose via `appVersion.status` (`DEPLOY_FAILED`) + `activationDate` (`null`), NOT the service status** — the service stays `ACTIVE` on the old version, so service-status alone reads as "fine". Keep init commands idempotent and exit 0.

## SSHFS Mount and Deploy Interaction

When using SSHFS (`zerops_mount`) for dev workflows, deploy replaces the container. This has important consequences:

1. **After deploy, run container only has `deployFiles` content.** All other files (including zerops.yml if not in deployFiles) are gone. Use `deployFiles: [.]` for dev services to ensure zerops.yml and source files survive the deploy cycle.
2. **SSHFS mount auto-reconnects only while the service is running.** Usually no remount is needed, but if the mount goes stale after a deploy (stat/ls returns empty, writes hang), recover it explicitly with `zerops_mount action="mount"`. A stopped service has no live mount until it starts again.
3. **zerops.yml must be in deployFiles** for dev self-deploy lifecycle. Without it, subsequent deploys from the container fail because zerops.yml is missing.

**Two kinds of "mount" (disambiguation):**
- `zerops_mount` -- SSHFS tool, mounts service `/var/www` locally for development. This is a dev workflow tool.
- Shared storage mount -- platform feature, attaches a shared-storage volume at `/mnt/{hostname}` via the service-level `mount:` parameter in import.yml. There is no `mount` field in zerops.yml (a `run.mount` is silently ignored). These are completely unrelated features.


----------------------------------------

# Guides > Environment Variables


Zerops manages environment variables at two scopes (project and service) with strict build/runtime isolation. Variables are set via zerops.yml, import.yml, or GUI. **Project vars auto-inherit into every service** — read them directly, no declaration. **Cross-service (sibling) vars do NOT auto-inject under the default `envIsolation=service`** — reference a sibling's value explicitly as `${hostname_varname}` in `run.envVariables` (only legacy `none` mode injects siblings as bare vars). Secret reads are privilege-gated (an admin token returns the value; a read-only token gets `REDACTED`). A running process keeps its boot-time env — restart it (not reload) to pick up a changed value.

---

## Scope Hierarchy

| Scope | Defined In | Visibility | Editable Without Redeploy |
|-------|-----------|------------|--------------------------|
| **Project** | import.yml `project.envVariables`, GUI | All services (auto-inherited) | Yes (restart to apply) |
| **Service secret** | import.yml `envSecrets`, GUI | Single service | Yes (restart to apply) |
| **Service basic (build)** | zerops.yml `build.envVariables` | Build container only | No (redeploy required) |
| **Service basic (runtime)** | zerops.yml `run.envVariables` | Runtime container only | No (redeploy required) |
| **Service basic (runtime)** | zerops.yml `run.envVariables` | Runtime container only | No (redeploy required) |

## Variable Precedence

Total order for the bare key (highest wins): **system/platform > yaml-baked `run.envVariables` > service secret/userData > project**.

1. **yaml-baked `run.envVariables` owns its key** — a service secret/userData set on the same key is **rejected** (`userDataDuplicateKey`); the two never coexist. To change a yaml-baked value, edit `zerops.yml` and redeploy.
2. **Service-level** wins over **project-level**.
3. Build and runtime are **separate environments** -- same key can have different values in each.

**DO NOT** set a secret/service var on a key already declared in `run.envVariables` — the platform rejects it. The yaml var owns the key; edit the yaml and redeploy instead.

## Build/Runtime Isolation

Build and runtime run in **separate containers**. Variables from one phase are not visible in the other unless explicitly referenced with prefixes:

| Want to access | From | How |
|---------------|------|-----|
| Runtime var `API_KEY` | Build container | `${RUNTIME_API_KEY}` — runtime `run.envVariables` are known at build time, so the build can read them |
| Build var `BUILD_ID` | Runtime container | **Not available.** The build container is destroyed after build and its vars are not carried into the runtime env store — `${BUILD_BUILD_ID}` reaches the runtime process as the literal string `${BUILD_BUILD_ID}`. Persist the value into a deployed file, or recompute it at runtime. |
| Build var `BUILD_ID` | Runtime container | **Not available.** The build container is destroyed after build and its vars are not carried into the runtime env store — `${BUILD_BUILD_ID}` reaches the runtime process as the literal string `${BUILD_BUILD_ID}`. Persist the value into a deployed file, or recompute it at runtime. |

```yaml
zerops:
  - setup: app
    build:
      envVariables:
        API_KEY: ${RUNTIME_API_KEY}   # reads runtime API_KEY during build
    run:
      envVariables:
        API_KEY: "12345-abcde"
```

## Cross-Service References — Explicit `${hostname_varname}` Required

Under the default `envIsolation=service`, a service does **NOT** automatically see another service's variables — **not even a managed database's connection vars**. To use a sibling's value, reference it explicitly in `run.envVariables`; the left-hand key is the name your app reads, the right-hand `${hostname_varname}` is the source:

```yaml
run:
  envVariables:
    DB_HOST: ${db_hostname}
    DB_PASS: ${db_password}
    DATABASE_URL: ${db_connectionString}
    CACHE_URL: ${cache_connectionString}
```

- The reference **resolves at container start**, independent of isolation mode — the referenced var does not need to exist at definition time.
- An **unresolved ref stays literal** (`${db_hostname}` reaches the process verbatim) — no error, no blank. A wrong hostname/var on the right-hand side becomes a literal string and the app fails at connect time.
- **Hostname charset**: service hostnames are lowercase alphanumeric only (`[a-z0-9]`) — the platform rejects dashes, underscores, and uppercase with `serviceStackNameInvalid`. So a ref is simply `${hostname_varname}` with the literal hostname (service `cache` → `${cache_port}`); there is no dash-to-underscore rewrite to reason about, because a dashed hostname cannot exist.

Only legacy `envIsolation=none` auto-injects every sibling's vars as bare `<host>_KEY` OS env vars without a ref — see Isolation Modes. New projects are `service`; rely on explicit refs.

### Cross-Service References in API vs Runtime

Cross-service references (`${hostname_varname}`) are **resolved at container start time**, not at definition time:

- **`zerops_discover` with `includeEnvs=true`** returns the **literal template** (e.g., `${db_password}`), NOT the resolved value. The service-env API stores templates, not resolved values, and returns only the service's own user-set + intrinsic vars — yaml-baked `run.envVariables` come from the app-version, project vars from the project scope. Assemble across scopes (or read in-container) for the effective env.
- **Inside the running container**, environment variables contain the actual resolved values.
- **Restarting a service does NOT change** what `zerops_discover` returns — it always shows templates. To verify resolved values, check from inside the container.

### Isolation Modes (envIsolation)

`envIsolation` is a project-scope setting that controls whether sibling-service vars are auto-injected.

| Mode | Behavior |
|------|----------|
| `service` (default) | **Siblings are isolated.** A service sees only its own vars + project vars + the explicit `${hostname_varname}` refs it declares in `run.envVariables`. Managed-service connection vars also require an explicit ref. |
| `none` (legacy) | Every service's vars are auto-injected into every other container as bare `<host>_KEY` OS env vars (source-side, directional). Ambiguous and broad — avoid for new projects. |
| `none` (legacy) | Every service's vars are auto-injected into every other container as bare `<host>_KEY` OS env vars (source-side, directional). Ambiguous and broad — avoid for new projects. |

Set in import.yml at project or service level:
```yaml
project:
  envIsolation: none       # legacy — avoid; default is service
services:
  - hostname: db
    envIsolation: none     # per-service: expose THIS service's vars to siblings
```

**Default (`service`) is the right choice.** Wire cross-service explicitly with `${hostname_varname}` — it works in both modes, so code stays correct if isolation ever changes.

## Project Variables -- Auto-Inherited

Project variables are **automatically available in every service, in both runtime AND build containers** — injected as OS env vars at container start. From application code, read them directly (`process.env.API_URL`). From zerops.yaml, reference them by name with `${VAR_NAME}` — **no `RUNTIME_` prefix** (that prefix is only for lifting a service's own runtime var into its build context).

**In shell commands** (buildCommands, initCommands, start) project vars are directly readable:
```yaml
build:
  buildCommands:
    - echo "building for $API_URL"                # shell reads the OS env var
    - VITE_API_URL=$API_URL npm run build         # or pass it forward by shell prefix
```

**In `build.envVariables` / `run.envVariables` YAML** (to forward a project var under a framework-conventional name) reference it directly without prefix:
```yaml
build:
  envVariables:
    VITE_API_URL: ${API_URL}              # project var API_URL read as-is
run:
  envVariables:
    CORS_ALLOWED_ORIGIN: ${FRONTEND_URL}  # forwarded under a different name
```

To **override** a project variable for one service, define a service-level variable with the same key and a DIFFERENT VALUE (not a reference to the project var):
```yaml
run:
  envVariables:
    LOG_LEVEL: debug    # overrides project-level LOG_LEVEL for this service
```

### Self-Shadow Trap — same name on both sides

Writing `varname: ${varname}` (the left key identical to the source on the right) is always wrong:

```yaml
run:
  envVariables:
    API_URL: ${API_URL}            # project-level self-shadow
    db_hostname: ${db_hostname}    # cross-service self-shadow
```

The interpolator sees the service-level variable of that name first, can't recurse back to the inherited/referenced value, and the OS env var resolves to the literal string `${varname}` — the app then connects to `"${db_hostname}:5432"` and crashes.

- For a **project var** you only want to read: delete the line — it already auto-inherits.
- For a **cross-service** value: use a **different** left-hand name (`DB_HOST: ${db_hostname}`), never the same name.

### Typical pattern: project-level URL constants for dual-runtime recipes

Dual-runtime recipes (frontend SPA + backend API) use project-level URL constants as the single source of truth for cross-service URLs, derived from `${zeropsSubdomainHost}` (a platform-generated project-scope var present from project creation):

```yaml
project:
  envVariables:
    API_URL: https://apistage-${zeropsSubdomainHost}-3000.prg1.zerops.app
    FRONTEND_URL: https://appstage-${zeropsSubdomainHost}.prg1.zerops.app
```

The frontend consumes `API_URL` via plain `${API_URL}` in `build.envVariables` (baked into the bundle at compile time). The API consumes `FRONTEND_URL` via plain `${FRONTEND_URL}` in `run.envVariables` (CORS allow-list). Set the same names on the workspace project via `zerops_env project=true action=set` after provision.

## Secret Variables

- Defined via GUI, import.yml `envSecrets`, or `dotEnvSecrets`
- **Read is privilege-gated** -- masked in GUI; via API an admin/write token returns the value verbatim, a read-only token returns `REDACTED` (keyed on `sensitive=true`). In-container the value is plaintext (the app needs it). Project-level `sensitive=true` does NOT persist — only service-level is a true secret surface.
- Can be updated without redeploy, but the service **must be restarted** to pick it up.
- A yaml-baked `run.envVariables` key and a secret on the **same key cannot coexist** — the platform rejects the secret with `userDataDuplicateKey`. The yaml owns the key; edit the yaml and redeploy to change it.

### dotEnvSecrets

Import secrets in `.env` format within import.yml:
```yaml
services:
  - hostname: app
    dotEnvSecrets: |
      APP_KEY=generated_value
      DB_PASSWORD=secure123
```
All entries become secret variables. Requires `#zeropsPreprocessor=on` if using generator functions.

## envReplace -- File-Level Substitution

Replaces placeholders in deployed files with environment variable values **during deployment** (not at runtime).

```yaml
run:
  envReplace:
    delimiter: "%%"
    target:
      - ./config/
      - ./templates/settings.json
```

| Parameter | Required | Description |
|-----------|----------|-------------|
| `delimiter` | Yes | Wrapping characters (e.g., `%%` makes `%%VAR%%`). String or array |
| `target` | Yes | Files or directories to process. String or array |
| `target` | Yes | Files or directories to process. String or array |

**DO NOT** expect directory targets to recurse into subdirectories. `./config/` processes only files directly in `config/`, not `config/jwt/`. Specify each subdirectory explicitly.

## Naming Restrictions

**Key**: must match `[a-zA-Z_]+[a-zA-Z0-9_]*`. Case-sensitive. Must be unique within scope regardless of case.

**Value**: ASCII only. No EOL characters.

## Restart Requirement

An env-store change (secret or project) propagates to the container in ~5–10s without a redeploy, but the **running process keeps its boot-time environ** — only newly-spawned processes see it.

**DO NOT** expect hot-reload of env vars. After changing secrets or project vars, **restart the service** (not reload — reload does not re-read env for the running process; PHP-FPM keeps its boot config). For `zerops.yml` `run.envVariables` changes, a **full redeploy** is required (they are baked into the app version).

## System-Generated Variables

Zerops auto-generates variables per service (e.g., `hostname`, `PATH`, DB connection strings). Some are **hard-reserved** and rejected if you try to set them — `PATH` (uppercase) returns `userDataUseOfSystemKey` in any `envVariables` block. Overridable platform vars include `envIsolation` / `sshIsolation` / `zeropsSubdomainHost` (and the CDN URLs) — but never `PATH`. Reference any of them from another service with an explicit `${hostname_varname}`.


----------------------------------------

# Guides > Firewall


Zerops uses nftables with restricted TCP ports 1-1024 (only 22, 53, 80, 123, 443, 587 allowed); UDP and ports 1025-65535 are unrestricted.

## Port Modification
Contact `support@zerops.io` with Project ID + Organization ID to request changes to restricted ports.


----------------------------------------

# Guides > Local Development


Develop locally with hot reload while connecting to Zerops managed services (DB, cache, storage) via VPN. ZCP generates `.env` with real credentials. Deploy to Zerops with `zerops_deploy` which uses `zcli push` under the hood.

---

## Setup

### Prerequisites
- **zcli** installed: `npm i -g @zerops/zcli` or [docs.zerops.io/references/cli](https://docs.zerops.io/references/cli)
- **VPN**: WireGuard (installed by zcli automatically on first `zcli vpn up`)
- **Project-scoped token**: Create in Zerops GUI → Settings → Access Tokens → Custom access per project

### Configuration
```json
// .mcp.json (in project root)
{
  "mcpServers": {
    "zcp": {
      "command": "zcp",
      "env": { "ZCP_API_KEY": "<project-scoped-token>" }
    }
  }
}
```

---

## Workflow

### 1. Connect to Zerops services
```bash
zcli vpn up <project-id>
```
- All services accessible by hostname (e.g., `db`, `cache`)
- One project at a time — switching disconnects the current
- **Env vars NOT available via VPN** — use `.env` file instead

### 2. Load credentials
ZCP writes `.env` via `zerops_env action="generate-dotenv"` (it merges three input channels — project `envVariables`, zerops.yaml `run.envVariables`, and `.env.local` — into one resolved file):
```
db_hostname=db
db_port=5432
db_password=<actual-password>
db_connectionString=postgresql://db:<actual>@db:5432
```
> Don't hand-edit `.env` directly — the next `generate-dotenv` refuses with a diff if it finds keys it didn't produce. Put manual overrides in `.env.local` (a no-touch input channel that survives regeneration), or pass `force=true`.

### 3. Develop locally
Start your dev server as usual — hot reload works against Zerops managed services over VPN.

### 4. Deploy to Zerops
```
zerops_deploy targetService="appstage"
```
Uses `zcli push` under the hood. Blocks until build completes.

---

## zerops.yml for Local Mode

The same `zerops.yml` works for both local push and container deploy:

```yaml
zerops:
  - setup: appstage
    build:
      base: nodejs@22
      buildCommands:
        - npm ci
        - npm run build
      deployFiles: ./dist
    run:
      start: node dist/server.js
      ports:
        - port: 3000
          httpSupport: true
      envVariables:
        DB_URL: ${db_connectionString}
```

`${hostname_varName}` references are resolved by Zerops at container runtime — they work regardless of push source (local or container).

---

## Connection Troubleshooting

| Symptom | Diagnosis | Fix |
|---------|-----------|-----|
| `nc -zv db 5432` times out | VPN not connected | `zcli vpn up <project-id>` |
| VPN connected, still timeout | Wrong project | `zcli vpn up <correct-project-id>` |
| Connected but auth fails | Stale .env | Regenerate: `zerops_env action="generate-dotenv"` |
| Service unreachable | Service stopped | `zerops_manage action="start" serviceHostname="db"` |
| Service unreachable | Service stopped | `zerops_manage action="start" serviceHostname="db"` |

### Diagnostic sequence
1. `zerops_discover service="db"` — is service RUNNING?
2. `nc -zv db 5432 -w 3` — network reachable?
3. Compare `.env` vs `zerops_env action="generate-dotenv" preview=true` (or `zerops_discover includeEnvValues=true` for stored values — `includeEnvs` returns key templates, not resolved values) — credentials current?

---

## Multi-Project

Each project directory has its own `.mcp.json` + `.zcp/state/`. VPN is one per machine — switch manually.

---

## Gotchas

1. **`.env` contains secrets**: Add to `.gitignore` immediately — never commit
2. **Object storage (S3)**: Uses HTTPS apiUrl — may work without VPN but not fully verified. Include VPN as fallback


----------------------------------------

# Guides > Logging


Zerops captures stdout/stderr as logs; use syslog output format for severity filtering. Supports forwarding to Better Stack, Papertrail, or self-hosted ELK via syslog.

## Log Types
1. **Build logs** — output from build pipeline
2. **Prepare runtime logs** — output from custom runtime image creation
3. **Runtime/Database logs** — operational output (stdout/stderr)

## Access Methods

### CLI
```bash
zcli service log -S <service-id>                     # Runtime logs (select via -S/--service-id, NOT a positional name)
zcli service log -S <service-id> --show-build-logs   # Build logs
```
Agents in this ecosystem read runtime logs via the `zerops_logs` MCP tool — it fetches **runtime logs only** (no build-log flag); build logs surface by auto-attachment on a deploy-failure response.

## Severity Filtering
Logs must output to **syslog format** for severity filtering to work. Plain stdout/stderr logs appear as "info" level.

## Log Forwarding

### Ready-Made Integrations
- **Better Stack** — cloud log management
- **Papertrail** — cloud log aggregation
- **ELK Stack** — self-hosted (Elasticsearch + Logstash + Kibana)

### ELK Stack Setup (Self-Hosted on Zerops)

Services needed:
- `elkstorage` — Elasticsearch
- `kibana` — UI
- `logstash` — Log collection (UDP syslog)

Multi-project forwarding: make Logstash public with firewall whitelist rules.

### Custom syslog-ng Configuration

**Critical**: Use source name `s_src` (not `s_sys`):
```
source s_src {
    system();
    internal();
};
```

Certificate paths:
- System certs: `/etc/ssl/certs`
- Custom certs: `ca-file("/etc/syslog-ng/user.crt")`

## Gotchas
1. **UDP for Logstash**: Zerops forwards logs via UDP syslog — ensure Logstash listens on UDP


----------------------------------------

# Guides > Metrics


Zerops supports ELK (APM + logs) and Prometheus/Grafana stacks; expose `/metrics` endpoint and set `ZEROPS_PROMETHEUS_PORT` for auto-scraping.

## Deployment Modes
- **Local**: Monitoring services in the same project as your app
- **Global**: Dedicated observability project (recommended for multi-project)

## ELK Stack Services
| Service | Purpose |
|---------|---------|
| `elkstorage` | Elasticsearch (data storage) |
| `kibana` | Visualization UI |
| `apmserver` | APM traces (made public via Zerops subdomain) |
| `logstash` | Log collection |
| `logstash` | Log collection |

### APM Configuration

Set these on your app as service env vars (GUI or `run.envVariables`). Copy the real APM server URL from the `apmserver` service's subdomain in the GUI — it's a generated subdomain (`apmserver-<subdomainHost>-<port>.<region>.zerops.app`), **not** a fixed `apmserver.zerops.app` host:
```
ELASTIC_APM_ACTIVE=true
ELASTIC_APM_SERVICE_NAME=my-app
ELASTIC_APM_SERVER_URL=https://<apmserver-subdomain-from-gui>
ELASTIC_APM_SECRET_TOKEN=<your-secret>
```

## Prometheus + Grafana Stack Services
| Service | Purpose |
|---------|---------|
| `prometheus` | Metrics collection |
| `grafana` | Visualization UI |
| `grafanadb` | PostgreSQL for Grafana |
| `prometheusbackups` | S3 for Prometheus data |
| `prometheuslight` | Forwarder (in source project for cross-project) |
| `prometheuslight` | Forwarder (in source project for cross-project) |

### Custom Metrics
1. Expose HTTP `/metrics` endpoint in your app
2. Set env var: `ZEROPS_PROMETHEUS_PORT=<port your /metrics endpoint listens on>` (e.g. `9090`; comma-separated for multiple ports)
3. Prometheus auto-discovers and scrapes

## Built-in Metrics
- Service scaling & resource usage
- PostgreSQL (some metrics require the `pg_stat_statements` extension — superuser `CREATE EXTENSION` + restart)
- MariaDB
- Valkey


----------------------------------------

# Guides > Networking


Zerops networking has two layers: a private VXLAN network per project (service-to-service via hostname, plain HTTP) and an L7 balancer for public traffic (SSL termination, round-robin, health checks). Apps must bind `0.0.0.0` — binding localhost causes 502. The L7 balancer is nginx-based with configurable timeouts, buffers, rate limiting, and access policies.

---

## Architecture Overview

**Per-project infrastructure:**
- **Private VXLAN network** — isolated overlay network shared by all services
- **L7 HTTP Balancer** — 2 HA containers, auto-scales, domain routing + SSL
- **L3 Core Balancer** — IP addresses and direct port access (TCP/UDP)

---

## Internal Networking (VXLAN)

Services in the same project communicate by **hostname and internal port**:

```
http://api:3000/health
http://postgres:5432
```

**Rules:**
- Always **`http://`** — never `https://` for internal traffic
- Isolated per project — no cross-project private networking
- Service discovery is automatic — no manual network config
- VPN uses same hostnames: `http://api:3000` from local machine (both `api` and `api.zerops` resolve — VPN sets up DNS search domain)

**Cross-service env vars**: under the default `envIsolation=service`, reference a sibling's var explicitly as `${hostname_varname}` in `run.envVariables` (e.g. `${app_API_TOKEN}`) — siblings are NOT auto-injected. The bare `<host>_KEY` injected form only appears under legacy `envIsolation=none`. Zerops auto-generates connection vars for managed services — reference them the same way (`${db_*}`).

**DO NOT** use `https://` for service-to-service calls — SSL terminates at the L7 balancer, internal network is already isolated.

---

## L7 Balancer (HTTP/HTTPS)

The L7 balancer is **nginx-based**, deployed as 2 HA containers per project. It handles SSL/TLS termination (Let's Encrypt, auto-renewed), domain routing, round-robin load balancing with health checks, and connection pooling.

### Proxy Headers

The balancer forwards client info via standard headers:
- **`X-Forwarded-For`** / **`X-Real-IP`** — original client IP
- **`X-Forwarded-Proto`** — original protocol (`http` or `https`)
- **`X-Forwarded-Host`** / **`X-Forwarded-Port`** — original host and port

These headers are set by the balancer itself (client-sent values are overwritten), and the `Forwarded` and `Proxy` headers are stripped from incoming requests.

Your app receives plain HTTP but can inspect these headers for the real client info.

### Key Default Settings

| Parameter | Default | Range | Notes |
|-----------|---------|-------|-------|
| `worker_connections` | 4000 | 1024-65535 | Simultaneous connections per worker |
| `keepalive_timeout` | 30s | 1s-300s | Idle connection lifetime |
| `keepalive_requests` | 100000 | 1-1000000 | Max requests per connection |
| `client_max_body_size` | 512m | 1k-2048m | Max upload size (custom domain) |
| `client_header_timeout` | 10s | 1s-300s | Header receive timeout |
| `client_body_timeout` | 10s | 1s-300s | Body receive timeout |
| `send_timeout` | 2s | 1s-300s | Response transmission timeout |
| `proxy_buffering` | on | on/off | Buffer backend responses |
| `proxy_buffering` | on | on/off | Buffer backend responses |

**Zerops subdomain** balancer: fixed **50 MB** upload limit (not configurable).

### Advanced Routing Features (GUI)

| Feature | Description |
|---------|-------------|
| **Redirects** | 301/302/307/308 with `preservePath` and `preserveQuery` options |
| **Access Policy** | CIDR-based IP allow/deny lists, returns 403 on denied request |
| **Rate Limiting** | Per-IP or per-domain, configurable burst queue, returns 503 when exceeded |
| **Basic Auth** | HTTP Basic Authentication per location |
| **Custom Content** | Return static content with custom status code and MIME type |
| **Custom Content** | Return static content with custom status code and MIME type |

---

## 502 Bad Gateway Diagnostic Checklist

Work through these steps **in order**:

1. **Binding address** — App bound to `0.0.0.0`? Binding `127.0.0.1`/`localhost` is the #1 cause
2. **Port match** — App listening on the port declared in `zerops.yml` `ports[]`?
3. **App running** — Check runtime logs (`zerops_logs`) for crash/startup errors
4. **Health check** — If configured, returning 2xx / exit 0? 5-minute retry window
5. **Readiness check** — If configured, traffic only routes after it passes
6. **Service status** — Is the service ACTIVE? (check `zerops_discover`)
7. **Timeout settings** — For slow responses, increase `send_timeout` (default 2s)

**Fix:** bind the listen address to `0.0.0.0` (e.g. `app.listen(3000, '0.0.0.0')`), never `127.0.0.1`/`localhost`.

---

## Shared vs Dedicated IPv4

| Feature | Shared IPv4 | Dedicated IPv4 |
|---------|-------------|----------------|
| Cost | Free | $3 / 30 days |
| Protocol support | HTTP/HTTPS only | All (TCP/UDP/HTTP) |
| Connections | Limited, shorter timeouts | Full capacity |
| Blacklist risk | Shared with other users | Isolated |
| DNS requirement | A + AAAA (both mandatory) | A only (AAAA optional) |
| SNI routing | AAAA record used for verification | Not needed |
| Production use | No | Yes |
| Production use | No | Yes |

**Shared IPv4 SNI mechanism**: Zerops reverse-looks-up the domain's AAAA record to verify project ownership. Without it, routing fails silently.

---

## Cloudflare Integration Summary

- **SSL mode**: Always **Full (strict)** — "Flexible" causes redirect loops
- **Shared IPv4 + proxy**: **DO NOT** — reverse AAAA lookup breaks with Cloudflare proxy
- **Best setup**: IPv6-only AAAA record, Cloudflare proxied (handles IPv4 translation)
- **ACME challenge**: WAF skip rule for `/.well-known/acme-challenge/`
- **Wildcard SSL**: `_acme-challenge.<domain>` CNAME to `<domain>.zerops.zone`

---

## Gotchas
1. **Cross-project networking impossible**: Each project is an isolated VXLAN — to bridge projects, use public access (L7/public endpoint), not private hostnames


----------------------------------------

# Guides > Object Storage Integration


Zerops Object Storage is S3-compatible (MinIO). Always set `AWS_USE_PATH_STYLE_ENDPOINT: true`. Use env var references `${storage_*}` for credentials. Container filesystem is lost on deploy — use Object Storage for any files that must persist across deployments.

## Environment Variables

When you create an Object Storage service, Zerops auto-generates these env vars (prefix with hostname for cross-service access, e.g. `${storage_apiUrl}`):

| Variable | Description |
|----------|-------------|
| `apiUrl` | S3 endpoint URL — full `https://...` URL ready for any S3 SDK's `endpoint` option |
| `apiHost` | S3 endpoint host only (no scheme); use only if the client library needs host separately |
| `accessKeyId` | S3 access key |
| `secretAccessKey` | S3 secret key |
| `bucketName` | Auto-generated bucket name (hostname + random prefix, immutable) |
| `quotaGBytes` | Bucket quota in GB |
| `projectId` | Project ID (Zerops-generated) |
| `serviceId` | Service ID (Zerops-generated) |
| `hostname` | Service hostname |
| `hostname` | Service hostname |

**Use `${storage_apiUrl}` as the S3 endpoint** — it carries the complete `https://` scheme and is what every S3 SDK's `endpoint` option expects. The `apiHost` variant is host-only; if a client library requires host separately, combine `https://${storage_apiHost}` manually — **never `http://`**. The object-storage gateway rejects plaintext HTTP with a 301 redirect to the HTTPS equivalent, and most S3 SDKs don't follow the redirect automatically. The symptom of a misconfigured endpoint is `UnknownError` or connection-refused on the first bucket call.

Reference them in zerops.yml `run.envVariables`:
```yaml
S3_ENDPOINT: ${storage_apiUrl}
S3_ACCESS_KEY: ${storage_accessKeyId}
S3_SECRET_KEY: ${storage_secretAccessKey}
S3_BUCKET: ${storage_bucketName}
S3_REGION: us-east-1
AWS_USE_PATH_STYLE_ENDPOINT: "true"
```

## Path Style Endpoint (Required)

Zerops uses MinIO which requires **path-style** URLs (not virtual-hosted):

```
https://endpoint.com/bucket-name/object-key

https://bucket-name.endpoint.com/object-key
```

**Every S3 client must be configured for path-style access** (the SDK-specific
flag: `forcePathStyle`/`use_path_style_endpoint`/`addressing_style: path`/
`pathStyleAccessEnabled`). Framework wiring lives in the recipe for that stack.

## import.yaml Definition

```yaml
services:
  - hostname: storage
    type: object-storage             # or "objectstorage" (both valid)
    objectStorageSize: 2              # GB (1-100, changeable in GUI later)
    objectStoragePolicy: public-read  # predefined policy
    priority: 10
```

**Predefined policies** (`objectStoragePolicy`):
- `private` — no anonymous access (documents, backups)
- `public-read` — anonymous list + get (media, avatars, static assets)
- `public-objects-read` — anonymous get only, no listing (direct links only)
- `public-write` — anonymous put only
- `public-read-write` — full anonymous access

**Custom policy**: use `objectStorageRawPolicy` with IAM Policy JSON instead (template var `{{ .BucketName }}` available).

Each service = one bucket (auto-named, immutable). Need multiple buckets? Create multiple services.

## When to Use Object Storage

| Scenario | Use Object Storage? |
|----------|-------------------|
| User uploads (avatars, documents) | Yes — lost on deploy |
| Media files (images, videos) | Yes — serve via public URL |
| Build artifacts | No — deploy via zerops.yaml |
| Temporary files | No — container disk is fine |
| Logs | No — use Zerops logging |
| Database dumps | Yes — for backup storage |
| Database dumps | Yes — for backup storage |

## Gotchas
1. **`forcePathStyle: true` / `AWS_USE_PATH_STYLE_ENDPOINT: true` is REQUIRED**: Zerops uses MinIO which doesn't support virtual-hosted style
2. **Container filesystem is replaced on deploy**: Files on disk survive restarts but are lost when a new container is created (deploy, scale-up). Always use Object Storage for persistent data
3. **Region is required but ignored**: Set `us-east-1` — MinIO ignores it but SDKs require it
4. **Public URL format**: `{apiUrl}/{bucketName}/path/to/file`
5. **Independent infrastructure**: Object Storage runs on separate infra from other services — accessible from Zerops and remotely over internet
6. **One bucket per service**: Bucket name auto-generated (hostname + random prefix), cannot be changed. Need multiple buckets? Add more object-storage services
7. **No Zerops backup**: Object Storage is not covered by the Zerops backup system
8. **No autoscaling**: Quota (1-100 GB) must be set manually, changeable in GUI after creation


----------------------------------------

# Guides > Php Tuning


Override php.ini via `PHP_INI_*` env vars, FPM via `PHP_FPM_*`. **Applying a change depends on the channel**: values in `run.envVariables` are baked into the app version → changing one requires a **redeploy**; values set via `zerops_env`/GUI service env → changing one requires a **restart** (never reload — see Gotchas). Zerops defaults: upload/post = 1024M, FPM dynamic 20/2/1/3. Upload bottleneck is L7 balancer (50MB subdomain), not PHP.

## PHP Configuration (`PHP_INI_*`)

Override any php.ini directive via `PHP_INI_{directive}` env vars in `run.envVariables` or via `zerops_env` API.

To apply a CHANGE: if the value lives in `run.envVariables` (baked into the app version), **redeploy**; if set via `zerops_env`/GUI service env, **restart**. A plain reload rewrites the config files (`/etc/php*/conf.d/overwrite.ini`) but the FPM master does not re-read INI on reload, so reload alone never applies the change.

### Zerops Platform Defaults

Zerops overrides several stock PHP values for production use:

| Directive | Zerops default | Stock PHP | Why |
|-----------|---------------|-----------|-----|
| `upload_max_filesize` | **1024M** | 2M | Generous upload limit (L7 balancer is the real gate) |
| `post_max_size` | **1024M** | 8M | Matches upload limit |
| `display_errors` | **off** | on | Production: errors to logs, not browser |
| `error_reporting` | **22527** | 32767 | E_ALL & ~E_DEPRECATED & ~E_STRICT |
| `log_errors` | **1** | 0 | Errors go to log files |
| `output_buffering` | **4096** | 0 | Buffered output for performance |
| `date.timezone` | **UTC** | (empty) | Consistent timezone |
| `sendmail_path` | `/usr/sbin/sendmail -t -i` | (empty) | System sendmail wired |
| `sendmail_path` | `/usr/sbin/sendmail -t -i` | (empty) | System sendmail wired |

### Example

```yaml
zerops:
  - setup: app
    run:
      base: php-nginx@8.4
      envVariables:
        PHP_INI_upload_max_filesize: 10M
        PHP_INI_post_max_size: 12M
        PHP_INI_memory_limit: 256M
        PHP_INI_max_execution_time: 60
        PHP_INI_max_input_vars: 5000
```

## PHP-FPM (`PHP_FPM_*`)

Configure FPM process management via `PHP_FPM_*` env vars — same change semantics as `PHP_INI_*`: redeploy for `run.envVariables`, restart for `zerops_env`/GUI service env, never reload.

Config files are written to `/etc/php*/php-fpm.d/www.conf` by `zerops-zenv` at container startup.

### Dynamic Mode (default)

Pre-forks a pool of workers. Good for consistent traffic.

| Variable | Default |
|----------|---------|
| `PHP_FPM_PM` | `dynamic` |
| `PHP_FPM_PM_MAX_CHILDREN` | `20` |
| `PHP_FPM_PM_START_SERVERS` | `2` |
| `PHP_FPM_PM_MIN_SPARE_SERVERS` | `1` |
| `PHP_FPM_PM_MAX_SPARE_SERVERS` | `3` |
| `PHP_FPM_PM_MAX_SPAWN_RATE` | `32` |
| `PHP_FPM_PM_MAX_REQUESTS` | `500` |
| `PHP_FPM_PM_MAX_REQUESTS` | `500` |

High-traffic example:

```yaml
run:
  envVariables:
    PHP_FPM_PM_MAX_CHILDREN: 50
    PHP_FPM_PM_START_SERVERS: 10
    PHP_FPM_PM_MIN_SPARE_SERVERS: 5
    PHP_FPM_PM_MAX_SPARE_SERVERS: 15
    PHP_FPM_PM_MAX_REQUESTS: 1000
```

### Ondemand Mode

Spawns workers only when requests arrive. Saves memory for low-traffic sites.

```yaml
run:
  envVariables:
    PHP_FPM_PM: ondemand
    PHP_FPM_PM_MAX_CHILDREN: 20
    PHP_FPM_PM_PROCESS_IDLE_TIMEOUT: 60s
    PHP_FPM_PM_MAX_REQUESTS: 500
```

Available parameters for ondemand:
- `PHP_FPM_PM_MAX_CHILDREN` -- maximum child processes
- `PHP_FPM_PM_PROCESS_IDLE_TIMEOUT` -- idle timeout before termination (default: 60s)
- `PHP_FPM_PM_MAX_REQUESTS` -- requests per process before recycling (default: 500)

## Upload Limits (3-layer chain)

File uploads pass through three layers -- ALL must allow the size:

1. **L7 Balancer**: `client_max_body_size` = 512m (custom domain) / **50MB fixed** (subdomain)
2. **PHP**: `upload_max_filesize` = 1024M (Zerops default)
3. **PHP**: `post_max_size` = 1024M (Zerops default)

Zerops pre-configures generous PHP limits, so the **L7 balancer is typically the bottleneck**:
- Subdomain (zerops.app): hard 50MB cap, cannot be changed
- Custom domain: 512m default, configurable via custom Nginx template

## Extensions (Alpine)

Install via `sudo apk add --no-cache php84-<ext>` — version prefix must match PHP major+minor (e.g. `php84-` for PHP 8.4). Sudo required — containers run as `zerops` user.

Build and runtime are **separate containers with separate images**. The build base (`php@X`) is Alpine-minimal. The runtime base (`php-nginx@X`, `php-apache@X`) bundles more extensions but not all.

If a Composer dependency requires an extension that's missing from the build image:
- Install it in `build.prepareCommands` so Composer validates platform requirements properly
- If also needed at runtime, install in `run.prepareCommands` too (separate container, separate image)
- **Never** use `--ignore-platform-reqs` — it suppresses all platform checks, hiding real problems that crash at runtime

Common extensions not in the build base: `ext-pcntl`, `ext-posix` (needed by Horizon), `ext-gd`, `ext-intl`.

```yaml
build:
  base: php@8.4
  prepareCommands:
    - sudo apk add --no-cache php84-pcntl php84-posix
  buildCommands:
    - composer install --no-dev --optimize-autoloader
run:
  base: php-nginx@8.4
  prepareCommands:
    - sudo apk add --no-cache php84-pcntl php84-posix
```

## Gotchas

- **Reload never applies the change** -- a value in `run.envVariables` needs a **redeploy** (it's baked into the app version); a value in `zerops_env`/GUI service env needs a **restart**. Reload rewrites config files via `zerops-zenv` but does not signal FPM to re-read them.
- **Upload fails at 50MB on subdomain** -- this is the L7 balancer limit, not PHP. Use a custom domain for larger uploads.
- **`post_max_size` must be >= `upload_max_filesize`** -- PHP silently drops the POST body if it exceeds `post_max_size`, even if the file itself is under `upload_max_filesize`.


----------------------------------------

# Guides > Production Checklist


Before going to production: (1) databases to HA (the `:ha` type variant), (2) minContainers: 2 on app services, (3) replace Mailpit with real SMTP, (4) remove Adminer, (5) use Object Storage for uploads, (6) use Valkey for sessions.

## Database

| Item | Dev | Production |
|------|-----|------------|
| Deployment variant | `:single` (e.g. `postgresql:single@18`) | `:ha` (e.g. `postgresql:ha@18`) — must recreate |
| Scaling profile | `oltp-hobby` | `oltp-staging` (escalate to `oltp-production` only on clear load) |
| Backups | Optional | Enabled |
| Connection | Single primary | Primary + read replicas |
| Connection | Single primary | Primary + read replicas |

**HA is immutable** — cannot switch after creation. Delete and recreate with the `:ha` variant.

**Legacy form** you may still see in older YAML or existing services: `type: postgresql@18` + a separate `mode:` field — `mode: NON_HA` ≡ `:single`, `mode: HA` ≡ `:ha`. Still accepted (remapped to the variant) but `mode` is deprecated and ignored by validation; author new YAML in the variant form.

## Application Services

| Item | Dev | Production |
|------|-----|------------|
| minContainers | 1 | 2+ |
| Health checks | Optional | Enabled |
| Logging | Console/debug | Structured (syslog) |
| Debug mode | Enabled | Disabled |
| Debug mode | Enabled | Disabled |

```yaml
- hostname: app
  type: nodejs@22
  minContainers: 2
  maxContainers: 4
```

## Dev Services to Remove

### Mailpit → Production SMTP

Mailpit (the dev mail catcher) is defined as:
```yaml
services:
  - hostname: mailpit
    type: alpine@3.20
    buildFromGit: https://github.com/zeropsio/recipe-mailpit
```
For production, point your app at a real provider — non-secret settings in the app's `run.envVariables` (zerops.yaml), the key in `envSecrets` (import.yaml). They are different files; a bare top-level `envVariables:` block is schema-invalid.
```yaml
run:
  envVariables:
    SMTP_HOST: smtp.sendgrid.net
    SMTP_PORT: "587"
```
```yaml
services:
  - hostname: app
    envSecrets:
      SMTP_PASSWORD: your-production-key
```

### Adminer → Remove or Restrict
Remove entirely or disable `enableSubdomainAccess`. Use VPN + pgAdmin/DBeaver locally.

## File Storage

**Container filesystem survives restarts but is replaced on every deploy** — files stored on disk persist through reload/restart/stop+start but are lost on deploy or container replacement (scale-up/down).

| Use case | Solution |
|----------|----------|
| User uploads | Object Storage (S3) |
| Media files | Object Storage (S3) |
| Temp files | Container disk (OK) |
| Build artifacts | Deploy via zerops.yaml |
| Build artifacts | Deploy via zerops.yaml |

```yaml
- hostname: storage
  type: object-storage
  objectStorageSize: 2
  objectStoragePolicy: public-read
```

## Sessions & Cache

**File-based sessions break with multiple containers and are lost on deploy.**

| Use case | Solution |
|----------|----------|
| PHP sessions | Valkey |
| Laravel sessions | Redis driver |
| Django sessions | Redis backend |
| Express sessions | Redis store |
| Express sessions | Redis store |

```yaml
- hostname: cache
  type: valkey:single@7.2  # valkey:ha@7.2 for production
```

## Framework-Specific Production Settings

### PHP/Laravel
- `APP_ENV: production`, `APP_DEBUG: "false"`
- Trusted proxies: `TRUSTED_PROXIES: 127.0.0.1,10.0.0.0/8`
- Sessions in Redis, not files
- Optimize: `php artisan config:cache && route:cache && view:cache`

### PHP/Symfony
- `APP_ENV: prod`
- `TRUSTED_PROXIES: 127.0.0.1,10.0.0.0/8`
- Logging via Monolog SyslogHandler

### Python/Django
- `DEBUG: "false"`
- `CSRF_TRUSTED_ORIGINS: https://your-domain.com`
- `ALLOWED_HOSTS: .zerops.app,your-domain.com`
- Static files via `collectstatic`

### Node.js
- `NODE_ENV: production`
- `HOST: 0.0.0.0`
- Health check endpoint at `/status` or `/health`

### Java/Spring
- `server.address: 0.0.0.0` (required — default binds localhost)
- Actuator health endpoints enabled
- JVM memory flags: `-Xmx512m` (match container limits)

### Elixir/Phoenix
- `PHX_SERVER: "true"` (required to start server in releases)
- `SECRET_KEY_BASE` generated via preprocessor
- `PHX_HOST` set to domain

## HA Checklist

| Item | Recommendation |
|------|---------------|
| Core package | **Serious Core** for production (better SLA, dedicated resources) |
| CPU mode | `cpuMode: DEDICATED` for consistent performance under load |
| Environment separation | Separate projects for dev/staging/prod |
| Stateless design | Sessions in Valkey, uploads in Object Storage — no local state |
| Database HA | the `:ha` type variant for all HA-capable managed services (immutable — plan before creation) |
| Min containers | `minContainers: 2+` on app services for throughput + crash-tolerance (rolling deploys are already zero-downtime at any count via the default `temporaryShutdown: false` — don't conflate the two) |
| Min containers | `minContainers: 2+` on app services for throughput + crash-tolerance (rolling deploys are already zero-downtime at any count via the default `temporaryShutdown: false` — don't conflate the two) |

## Health Check Pattern

Production services should pair a `deploy.readinessCheck` (gates traffic during deploy) with a `run.healthCheck` (continuous — the LB routes around an unhealthy container). The combined pattern, params, and behavior are in `zerops_knowledge uri="zerops://guides/readiness-health-checks"`.

## Gotchas
1. **HA is immutable**: Must delete and recreate service to switch modes
2. **Container filesystem survives restarts but is replaced on every deploy**: use external storage for persistent data
3. **File sessions break with scaling**: Multiple containers don't share filesystem
4. **Mailpit is not production SMTP**: Only for dev — no delivery guarantees
5. **Debug mode leaks secrets**: Disable APP_DEBUG in production
6. **Missing health checks**: Load balancer can't route around unhealthy containers


----------------------------------------

# Guides > Public Access


Zerops offers three public access methods: zerops.app subdomains (dev only, 50MB upload limit), custom domains (production, needs IPv4/IPv6), and direct port access (TCP/UDP on 10-65435).

## Access Methods

### 1. Zerops Subdomains (`.zerops.app`)
- Shared HTTPS balancer (scalability bottleneck)
- Max upload: **50 MB**
- **Not for production** — use for development/testing only
- Auto-provisioned SSL
- **Enable it:** set `enableSubdomainAccess: true` in the import YAML (works for all runtime/web types) to pre-configure intent; the first deploy (or the GUI toggle) activates the L7 subdomain route, and re-deploys never deactivate it.
- *In ZCP:* `zerops_deploy` auto-enables the subdomain on the first deploy for eligible service modes (dev/stage/simple/standard/local-stage) and waits HTTP-ready — the deploy response carries `subdomainAccessEnabled: true` and the URL. `zerops_subdomain enable` is the explicit recovery/ops command if auto-enable was skipped (a worker / non-HTTP service, or launch-production which deliberately opts out in favor of a custom domain). `zerops_discover` shows current status (`subdomainEnabled` + `subdomainUrl`).
- **Port-specific subdomains**: If HTTP ports are defined in zerops.yml, each port gets its own subdomain: `{hostname}-{subdomainHost_prefix}-{port}.{subdomainHost_rest}`. Example: hostname `appdev`, subdomainHost `1df2.prg1.zerops.app`, port 3000 → actual URL `https://appdev-1df2-3000.prg1.zerops.app`. Port 80 omits the port suffix: `https://appdev-1df2.prg1.zerops.app`
- **Internal network fallback**: Every service is accessible internally via `http://{hostname}:{port}` (e.g., `http://appdev:3000`). Use this to verify the app is running when subdomain access is uncertain — `curl http://appdev:3000/health` from the ZCP container or any other service in the project
- Works for: nodejs, static, nginx, go, python, php, java, rust, dotnet, and all other runtime types

### 2. Custom Domains (Production)
- Per-project HTTPS balancer (2 containers, HA)
- Round-robin load balancing + health checks
- Upload limit: 512 MB default (`client_max_body_size`, configurable up to 2048m on a custom domain) — not a hard cap
- Requires IP address assignment

### 3. Direct Port Access
- Available for: Runtime services, PostgreSQL
- Port range: 10-65435 (80, 443 reserved)
- Protocols: TCP, UDP
- Configurable firewall: blacklist or whitelist per port

## Gotchas
1. **Dedicated IPv4 is non-refundable**: $3/30 days, auto-renews — the fee isn't refunded if removed early, but the address can be reused in another project until the subscription ends


----------------------------------------

# Guides > Readiness Health Checks


Two distinct mechanisms, often confused. **Readiness check** (`deploy.readinessCheck`) runs ONLY during a deploy — it gates when the new container starts receiving traffic; if it never passes, the deploy fails and the old version keeps serving. **Health check** (`run.healthCheck`) runs CONTINUOUSLY on the live app — it disconnects an unhealthy container from the load balancer, restarts it, and reconnects it on recovery. Both support `httpGet` or `exec` (mutually exclusive within one block). The field shape lives in the zerops.yml schema; this guide owns the behavior.

---

## The distinction (the #1 confusion)

| | Readiness check | Health check |
|---|---|---|
| Location | `deploy.readinessCheck` | `run.healthCheck` |
| When it runs | **During a deploy only** | **Continuously, after startup** |
| Purpose | Gate traffic to a NEW container | Detect runtime failure of a LIVE container |
| On failure | Deploy fails; new appVersion not activated; old version keeps serving | Container removed from LB → restarted → reconnected on recovery |
| On failure | Deploy fails; new appVersion not activated; old version keeps serving | Container removed from LB → restarted → reconnected on recovery |

A readiness check makes a deploy wait for the app to actually answer before cutting traffic over. A health check keeps a degraded container out of rotation while it's live. Use both on production services.

## Readiness check (`deploy.readinessCheck`)

Checks the **new** container at `localhost`. Until it passes, traffic stays on the old container.

```yaml
deploy:
  readinessCheck:
    httpGet: { port: 3000, path: /health }
    failureTimeout: 60   # seconds until the container is marked failed
    retryPeriod: 10      # seconds between attempts
```

Mechanics: `start` runs → readiness check runs → on fail, wait `retryPeriod` and retry → on success, the container is marked active and receives traffic → if still failing after `failureTimeout`, the container is deleted and the deploy fails (the previous appVersion stays active). Set `failureTimeout`/`retryPeriod` explicitly — there is no fixed schema default to rely on.

## Health check (`run.healthCheck`)

Runs on every container continuously after startup.

```yaml
run:
  healthCheck:
    httpGet: { port: 3000, path: /health }
    failureTimeout: 30     # consecutive-failure seconds before restart (reset by a success)
    disconnectTimeout: 30  # seconds before a failing container is pulled from the LB
    recoveryTimeout: 30    # seconds of success before a restarted container takes traffic again
    execPeriod: 10         # seconds between attempts
```

**Failure sequence**: repeated failures → `disconnectTimeout` removes the container from the load balancer → `failureTimeout` triggers a restart → `recoveryTimeout` gates traffic reconnection once it's healthy again.

## httpGet vs exec (both checks)

- **`httpGet`** — GET to `localhost:{port}{path}`, triggered **inside** the container. Success = HTTP `2xx` (follows `3xx` redirects), 5-second per-request timeout. `host` sets a custom Host header; `scheme: https` only if the app demands TLS internally (default is plain HTTP — the L7 balancer terminates SSL upstream).
- **`exec`** — a local shell command, success = exit `0`, 5-second per-command timeout. Has access to all env vars. Use a YAML `|` block for multi-step scripts.

**DO NOT** put both `httpGet` and `exec` in the same check block — they are mutually exclusive.

## temporaryShutdown (deploy container ordering)

Readiness gating only buys zero-downtime when the old container stays up during cutover — that is `temporaryShutdown` (in the `deploy` block):

| Value | Behavior | Downtime |
|---|---|---|
| `false` (default) | New containers start and pass readiness BEFORE old ones are removed | None (zero-downtime rolling deploy) |
| `true` | Old containers stop BEFORE new ones start | Yes |
| `true` | Old containers stop BEFORE new ones start | Yes |

Use `true` only when you cannot run two versions simultaneously (exclusive DB-migration access, singleton locks). Rolling cutover is zero-downtime at any `minContainers` value — don't conflate replica count with the deploy strategy.

## Dev/stage placement

In dev+stage pairs, `healthCheck` and `readinessCheck` belong ONLY on the **stage** entry. Dynamic-runtime dev services run `start: zsc noop --silent` (a no-op keepalive that idles the container while the agent drives the real dev server's lifecycle) — adding a `healthCheck` to a dev service causes unwanted container restarts during iteration.

## Production pattern

Combine both on a production service so deploys wait for readiness and the LB routes around runtime failures:

```yaml
zerops:
  - setup: app
    deploy:
      readinessCheck:
        httpGet: { port: 3000, path: /health }
    run:
      healthCheck:
        httpGet: { port: 3000, path: /health }
      start: node server.js
```

Without health checks, the load balancer cannot route around an unhealthy container — it keeps sending traffic to a degraded instance.


----------------------------------------

# Guides > Scaling


Zerops autoscales vertically (CPU/RAM/disk) and horizontally (container count). Runtimes support both. Managed services (DB, cache, shared-storage) support vertical only with fixed container count (the `:single` type variant = 1 node, `:ha` = 3). Object-storage and Docker have no autoscaling. Extends grammar.md section 9 with mechanics, thresholds, YAML syntax, and common mistakes.

## When to Scale Which Way

| Symptom | Scale type | Why |
|---------|-----------|-----|
| CPU/memory pressure on existing containers | Vertical (CPU/RAM) | More resources per container |
| High request volume, stateless service | Horizontal (containers) | Distribute load across more instances |
| Disk filling up | Vertical (disk) | More storage per container |
| Latency-sensitive workload on SHARED CPU | CPU mode → DEDICATED | Guaranteed cores, no burstable throttling |
| Latency-sensitive workload on SHARED CPU | CPU mode → DEDICATED | Guaranteed cores, no burstable throttling |

## Applicability Matrix

| Service type | Vertical autoscaling | Horizontal scaling | Notes |
|---|---|---|---|
| **Runtime** (Node.js, Go, PHP, Python, Java, etc.) | Yes | Yes (1-10 containers) | Full autoscaling |
| **Linux containers** (Alpine, Ubuntu) | Yes | Yes (1-10 containers) | Same as runtimes |
| **Managed DB** (PostgreSQL, MariaDB) | Yes | No (fixed: `:single`=1, `:ha`=3) | Variant immutable after creation |
| **Managed cache** (Valkey) | Yes | No (fixed: `:single`=1, `:ha`=3) | Variant immutable after creation |
| **Shared storage** | Yes (cpu/ram/disk configurable) | No (fixed: `:single`=1, `:ha`=3) | Accepts verticalAutoscaling in import.yml |
| **Object storage** | No | No | Fixed size at creation, no verticalAutoscaling |
| **Docker** | No (manual, triggers VM restart) | Manual only (change VM count, triggers restart) | No automatic autoscaling |
| **Docker** | No (manual, triggers VM restart) | Manual only (change VM count, triggers restart) | No automatic autoscaling |

## Vertical Autoscaling

### CPU Modes

| Mode | Behavior | Best for |
|---|---|---|
| **SHARED** | Physical core shared with up to 10 tenants. Performance ranges 1/10 to 10/10 depending on neighbors | Dev, staging, low-traffic production |
| **DEDICATED** | Exclusive full physical core(s). Consistent performance | Production, CPU-intensive workloads |
| **DEDICATED** | Exclusive full physical core(s). Consistent performance | Production, CPU-intensive workloads |

- CPU mode can be changed **once per hour**
- **startCpuCoreCount**: cores allocated at container start (default: 2). Increase for apps with heavy initialization

### CPU Scaling Thresholds (DEDICATED mode only)

- **Min free CPU cores** (`minFreeCpuCores`): scale-up triggers when free capacity on a single core drops below this fraction, range 0.0-1.0 (default: 0.1 = 10%)
- **Min free CPU percent** (`minFreeCpuPercent`): scale-up triggers when total free capacity across all cores drops below this percentage, range 0-100 (default: 0, disabled)

### RAM Dual-Threshold System

RAM is monitored every **10 seconds**. Two independent thresholds control scale-up -- whichever provides **more free memory** wins:

| Threshold | Field | Default | Behavior |
|---|---|---|---|
| **Absolute** | `minFreeRamGB` | 0.0625 GB (64 MB) | Scale up when free RAM drops below this fixed amount |
| **Percentage** | `minFreeRamPercent` | 0% (disabled) | Scale up when free RAM drops below this % of granted RAM |
| **Percentage** | `minFreeRamPercent` | 0% (disabled) | Scale up when free RAM drops below this % of granted RAM |

Both thresholds serve dual purpose: prevent OOM crashes and preserve space for kernel disk caching. Swap is enabled as a safety net but does not replace proper threshold configuration.

**Higher wins example**: with 12 GB granted RAM, `minFreeRamGB=0.5` (500 MB buffer) and `minFreeRamPercent=5` (600 MB buffer) — the 600 MB threshold applies. As granted RAM grows, the percentage threshold automatically provides a larger buffer.

### Disk
- **Grows only -- never shrinks** (no scale-down). Set `minDisk = maxDisk` to disable.

### Resource Limits (Defaults)

| Resource | Min | Max |
|---|---|---|
| CPU cores | 1 | 8 |
| RAM | 0.125 GB | 48 GB |
| Disk | 1 GB | 250 GB |
| Disk | 1 GB | 250 GB |

PostgreSQL and MariaDB override RAM minimum to **0.25 GB**.

### Scaling Behavior Parameters

| Parameter | CPU | RAM | Disk |
|---|---|---|---|
| Collection interval | 10s | 10s | 10s |
| Scale-up window | 20s | 10s | 10s |
| Scale-down window | 60s | 120s | 300s |
| Scale-up percentile | 60th | 50th | 50th |
| Scale-down percentile | 40th | 50th | 50th |
| Minimum step | 1 (0.1 cores) | 0.125 GB | 0.5 GB |
| Maximum step | 40 | 32 GB | 128 GB |
| Maximum step | 40 | 32 GB | 128 GB |

Scaling uses exponential growth: small increments initially, larger jumps under sustained high load.

**Scale-up behavior summary:**
- **RAM/Disk**: immediate scale-up when free resources drop below threshold (single measurement)
- **CPU**: requires 2 consecutive measurements below threshold (~20s window) to avoid spikes
- **Scale-down is conservative**: 3-5 consecutive measurements above threshold (60-300s depending on resource) — prevents flapping

### Spike Protection via minRam

Autoscaling reacts within 10-20 seconds. Compilation and package installation create RAM spikes faster than scaling can respond. Set `minRam` high enough to absorb the first spike WITHOUT relying on autoscaling:

- **Dev services** (compilation on container via SSH): `minRam` must cover the build tool peak — `npm install`, `go build`, `cargo build` spike within seconds
- **Stage/prod services** (pre-built artifacts): `minRam` only needs to cover the startup peak (JVM heap allocation, SSR warming)

Thresholds (`minFreeRamGB`, `minFreeRamPercent`) handle gradual load growth. They cannot protect against sub-10s spikes that exceed the total allocated RAM. See runtime guides for per-runtime `minRam` recommendations.

**Disabling autoscaling**: set **minimum = maximum** for any resource to pin it at a fixed value (e.g., `minRam: 2, maxRam: 2`).

## Horizontal Scaling

Applies to **runtimes and Linux containers only**. New containers are added when vertical scaling reaches configured maximums.

- **minContainers**: baseline always running (system range: 1-10)
- **maxContainers**: upper limit during peak (system range: 1-10)
- Set `minContainers = maxContainers` to disable horizontal autoscaling

**HA requirement**: applications must be stateless and handle distributed operation (no local file sessions, no local uploads).

### Managed Services (DB, Cache, Shared Storage)

Container count is **fixed by the deployment variant in the type** (`postgresql:single@18` / `postgresql:ha@18`), set at creation, **immutable**:

| Variant | Containers | Use case |
|---|---|---|
| `:single` | 1 | Development, non-critical |
| `:ha` | 3 (on separate physical machines) | Production, automatic failover |
| `:ha` | 3 (on separate physical machines) | Production, automatic failover |

**Legacy form** you may still see in older YAML: a separate `mode:` field — `mode: NON_HA` ≡ `:single`, `mode: HA` ≡ `:ha`. Still accepted (remapped to the variant) but deprecated and ignored by validation.

HA recovery: failed container is disconnected, new one created on different hardware, data synchronized from healthy copies, failed container removed.

PostgreSQL HA exposes read replica port **5433** for distributing SELECT queries.

## Autoscaling Thresholds

The dual-threshold trigger controls WHEN vertical scaling fires. All four fields (`minFreeRamGB`, `minFreeRamPercent`, `minFreeCpuCores`, `minFreeCpuPercent`) are optional and live in the `verticalAutoscaling` block (see import.yml Syntax below). (*In ZCP they can also be set live: `zerops_scale serviceHostname="api" minFreeRamGB=0.5 minFreeRamPercent=5 minFreeCpuCores=0.2`, combinable with any other scaling parameter in one call.*)

## Docker Services
- Run in **VMs**, not containers. **No autoscaling** -- resources fixed at creation
- Changing resources or VM count triggers **VM restart** (downtime). Disk can only increase
- Consider runtime services or Linux containers if dynamic scaling is needed

## import.yml Syntax

```yaml
services:
  # Runtime with full scaling
  - hostname: api
    type: nodejs@22
    minContainers: 2
    maxContainers: 6
    verticalAutoscaling:
      cpuMode: SHARED
      minCpu: 1
      maxCpu: 4
      startCpuCoreCount: 2
      minRam: 0.5
      maxRam: 8
      minFreeRamGB: 0.125
      minFreeRamPercent: 10
      minDisk: 1
      maxDisk: 20

  # Managed DB (vertical only, no container settings)
  - hostname: db
    type: postgresql:ha@16
    verticalAutoscaling:
      cpuMode: DEDICATED
      minCpu: 1
      maxCpu: 4
      minRam: 1
      maxRam: 16
      minDisk: 5
      maxDisk: 100
```

## Strategy Presets

**Development** — SHARED CPU, min resources, single container (cost-effective for dev/staging):
```yaml
minContainers: 1
maxContainers: 1
verticalAutoscaling: { cpuMode: SHARED, minCpu: 1, maxCpu: 2, minRam: 0.25, maxRam: 1 }
```

**Production** — DEDICATED CPU, higher minimums, multiple containers for HA:
```yaml
minContainers: 2
maxContainers: 6
verticalAutoscaling: { cpuMode: DEDICATED, minCpu: 2, maxCpu: 8, minRam: 2, maxRam: 8 }
```

**Burst workloads** — wide autoscaling range, SHARED CPU:
```yaml
minContainers: 1
maxContainers: 10
verticalAutoscaling: { cpuMode: SHARED, minCpu: 1, maxCpu: 8, minRam: 1, maxRam: 16 }
```

(*In ZCP, the same presets apply live via `zerops_scale serviceHostname=... cpuMode=... minCpu=... ...`.*)

## Common Mistakes

**DO NOT** set `minFreeRamGB: 0` and `minFreeRamPercent: 0` simultaneously -- the API rejects this with "Invalid custom autoscaling value". Always keep at least the default absolute threshold (0.0625 GB).

**DO NOT** forget that disk **never shrinks** -- setting a high `minDisk` is permanent for that container's lifetime.

**DO NOT** assume horizontal scaling works automatically -- your application must be stateless. File-based sessions, local uploads, and in-memory state break with multiple containers.


----------------------------------------

# Guides > Shared Storage Integration


Shared storage is a managed SeaweedFS volume mounted as a POSIX filesystem at `/mnt/<storageHostname>` into one or more runtime services — for files that must be shared *between containers/services* (shared config, plugin directories, a common working set). It is mounted via the import.yaml `mount:` field; there is **no `zerops.yaml` mount**. For high-write workloads or user uploads, prefer Object Storage (S3) instead — shared storage is POSIX/NFS-style and not built for high-throughput churn.

## Mounting — import.yaml `mount:` is the only config-file mechanism

Declare the storage service, then list it under the runtime's service-level `mount:`. This auto-connects the storage at provision — import alone is sufficient, no second step:

```yaml
services:
  - hostname: storage
    type: shared-storage
  - hostname: app
    type: nodejs@22
    buildFromGit: https://github.com/myorg/myapp   # mount: requires buildFromGit
    mount:
      - storage          # list one or more shared-storage hostnames
```

After deploy, the runtime has `/mnt/storage` (SeaweedFS FUSE, writable). Multiple volumes can be mounted to one service (`/mnt/files1`, `/mnt/files2`, …).

**There is NO `zerops.yaml` mount field.** A `mount:` under `run:` is silently stripped by the platform — it even passes yaml validation (validation-passing ≠ honored), but produces no mount and no connection. Mounting is import.yaml-only (or `connect-storage`, below).

## Connecting a storage to a runtime that missed the import mount

A runtime that was READY_TO_DEPLOY at import time (e.g. a stage service created but not yet deployed) does NOT pick up the import `mount:`. Once it's ACTIVE, connect explicitly:

```
zerops_manage action="connect-storage" serviceHostname="app" storageHostname="storage"
```

This registers the connection, but the FUSE mount materializes **only on the next fresh deploy (new container creation)** — a plain restart does NOT bring it up. Redeploy the service after connecting.

## Constraints & behavior

- **Mount path**: always `/mnt/<storageHostname>`. Runtime containers only — NOT available during build or `run.prepareCommands` phases.
- **Mounting overwrites** any existing content in the mount directory.
- **Capacity**: max 60 GB total (raise via support request); file size is unbounded within the 60 GB. `verticalAutoscaling` floors: RAM 0.5 GB, disk 5 GB.
- **HA**: 1:1 replication with auto-failover; during a master failover the mount is briefly unavailable (~30s).
- **POSIX**: standard filesystem ops (with minor permission-setting limits). Filesystem operations are logged to runtime logs tagged `zerops-mount-<serviceHostname>`. `df` can report misleading numbers — use the Zerops GUI for accurate storage metrics.
- **No env vars**: shared storage exposes no connection variables — it's a filesystem, not a networked service.

## Shared storage vs object storage

Use **shared storage** when you need a POSIX filesystem shared across services (shared config, plugin/extension directories, a common scratch area). Use **object storage** (S3/MinIO) for user uploads, media, and any high-throughput or write-heavy file operations — and for anything that must survive independent of any single service. Don't reach for shared storage as a generic uploads bucket.


----------------------------------------

# Guides > Smtp


Only port **587** (STARTTLS) is allowed for outbound email — ports 25 and 465 are permanently blocked. Use an external email service.

## Port Configuration
| Port | Status | Protocol |
|------|--------|----------|
| 25 | **Blocked** | Traditional SMTP (spam risk) |
| 465 | **Blocked** | Legacy SMTPS (deprecated) |
| **587** | **Allowed** | SMTP submission with STARTTLS |
| **587** | **Allowed** | SMTP submission with STARTTLS |

## Provider Configurations

| Provider | Host | Port | Username | Password |
|----------|------|------|----------|----------|
| Gmail | smtp.gmail.com | 587 | user@gmail.com | App password |
| Google Workspace | smtp-relay.gmail.com | 587 | user@domain.com | Regular/App pass |
| Office 365 | smtp.office365.com | 587 | user@domain.com | Account password |
| SendGrid | smtp.sendgrid.net | 587 | `apikey` | API key |
| Mailgun | smtp.mailgun.org | 587 | postmaster@domain | Password |
| Amazon SES | `email-smtp.{region}.amazonaws.com` | 587 | Access key | Secret key |
| Amazon SES | `email-smtp.{region}.amazonaws.com` | 587 | Access key | Secret key |

## Configuration Example

Non-secret SMTP settings belong in `run.envVariables` (zerops.yaml); the password is a secret in `envSecrets` (import.yaml, service level). These live in **different files** — a bare top-level `envVariables:`/`envSecrets:` block is rejected (`envVariables` is valid only under `build`/`run`).

```yaml
zerops:
  - setup: app
    run:
      envVariables:
        SMTP_HOST: smtp.sendgrid.net
        SMTP_PORT: "587"
        SMTP_USER: apikey
```

```yaml
services:
  - hostname: app
    type: nodejs@22
    envSecrets:
      SMTP_PASSWORD: <sendgrid-api-key>
```

A change to `envSecrets` requires a **service restart** to take effect.

## Gotchas
- **Gmail SMTP**: a regular Gmail password fails auth — generate an App Password in Google Account settings and use it as `SMTP_PASSWORD`.


----------------------------------------

# Guides > Verify Web Agent Protocol


Sub-agent dispatch protocol for end-to-end verification of a Zerops web
service. The main agent reads `develop-verify-matrix` (atom) for which
services need this protocol; the protocol body itself lives here so it
ships only when fetched, not on every per-turn payload.

Spawn one sub-agent per web-facing target. Substitute `{targetHostname}`
and `{runtime}` with that service's values when constructing the prompt.

---

## Sub-agent dispatch prompt

```
Agent(model="sonnet", prompt="""
Verify Zerops service "{targetHostname}" ({runtime}) works for end users.

## Protocol
1. `zerops_verify serviceHostname="{targetHostname}"` — infrastructure baseline
2. If NOT healthy → VERDICT: FAIL (cite failed checks from zerops_verify response)
3. `zerops_discover service="{targetHostname}"` — get subdomainUrl or connection info
4. Determine reachable URL:
   - subdomainUrl available → use it (public HTTPS)
   - no subdomain, no custom domain → VERDICT: UNCERTAIN (cannot reach from outside)
   - unreachable after timeout → VERDICT: UNCERTAIN
5. `agent-browser open {url}`
6. `agent-browser snapshot` — accessibility tree for AI analysis
7. Evaluate: does the page render meaningful content?
   - Interactive elements (buttons, links, forms)?
   - Text content (headings, paragraphs)?
   - Or empty/broken (empty root div, error page, blank screen)?
8. If concerns: `agent-browser eval "JSON.stringify(Array.from(document.querySelectorAll('script[src]')).map(s=>s.src))"` for loaded scripts
9. For SPAs: `agent-browser eval "window.__errors || []"` AND check if console has errors

## Rules
- zerops_verify unhealthy/degraded → always VERDICT: FAIL (never override infra checks)
- HTTP 401/403 with rendered content (login page, auth challenge) → VERDICT: PASS (auth is working correctly)
- HTTP 401/403 with empty body → VERDICT: UNCERTAIN (cannot determine if intentional)
- zerops_verify healthy + page empty/broken → VERDICT: FAIL (cite what you see)
- zerops_verify healthy + page renders real content → VERDICT: PASS
- agent-browser unavailable or URL unreachable → VERDICT: UNCERTAIN

## Output (mandatory format)
### Infrastructure
zerops_verify status and check summary

### Application
what you observed — DOM content, JS errors, visual state

### Evidence
accessibility tree excerpt or error details

### VERDICT: PASS or FAIL or UNCERTAIN — one-line justification
""")
```


----------------------------------------

# Guides > Vpn


Zerops VPN uses WireGuard via `zcli vpn up <project-id>` — connects to one project at a time, services accessible by hostname, but env vars are NOT available through VPN.

## Commands
```bash
zcli vpn up <project-id>                    # Connect
zcli vpn up <project-id> --auto-disconnect  # First disconnect an already-active VPN, then connect
zcli vpn up <project-id> --mtu 1350        # Custom MTU (default 1420)
zcli vpn down                               # Disconnect
```

## Behavior
- All services accessible via hostname (e.g., `db`, `api`) — `.zerops` suffix optional
- **One project at a time** — connecting to another disconnects the current
- Automatic reconnection with daemon
- **Environment variables NOT available** through VPN — use GUI or API to read them

## Hostname Resolution
- Both plain hostname (`db`) and suffixed (`db.zerops`) work — VPN configures a DNS search domain
- Plain hostname is resolved via the `.zerops` search domain automatically (e.g., `db` → `db.zerops`)
- Example: `postgresql://user:pass@db:5432/mydb` or `postgresql://user:pass@db.zerops:5432/mydb`
- Note: CLI tools like `dig`, `nslookup`, `host` bypass the system resolver and may show false NXDOMAIN — use `dscacheutil -q host -a name db` on macOS to verify, or just test with `nc -zv db 5432`

## Troubleshooting

| Problem | Solution |
|---------|----------|
| Interface already exists | `zcli vpn down` then `zcli vpn up` |
| Hostname not resolving | Try `db.zerops` suffix. On Windows, add `zerops` to DNS suffix list. Note: `dig`/`nslookup` bypass system resolver — use `nc -zv db 5432` to test |
| WSL2 not working | Set `systemd=true` in `/etc/wsl.conf` under `[boot]`, then `wsl --shutdown` |
| Conflicting VPN | Use `--mtu 1350` |
| Ubuntu 25.* issues | Install AppArmor utilities |
| Ubuntu 25.* issues | Install AppArmor utilities |


----------------------------------------

# Guides > Zerops Yaml Advanced


Behavioral semantics for advanced zerops.yml features: health/readiness checks, deploy strategies, cron, background processes, runtime init, envReplace, routing, and `extends`. Schema is in grammar.md -- this file covers what the schema cannot express.

---

## Health / Readiness Checks & temporaryShutdown

Health checks (`run.healthCheck`, continuous), readiness checks (`deploy.readinessCheck`, deploy-time traffic gate), the httpGet/exec shape + params + failure sequence, the dev/stage placement rule (dev uses `start: zsc noop --silent`, no healthCheck), and `temporaryShutdown` deploy ordering are all owned by `zerops_knowledge uri="zerops://guides/readiness-health-checks"`.

---

## Crontab Execution

```yaml
run:
  crontab:
    - command: "php artisan schedule:run"
      timing: "* * * * *"
      workingDir: /var/www/html
      allContainers: false
```

Parameters: `command` (required), `timing` (required, 5-field cron: `min hour dom mon dow`), `allContainers` (**required** by the schema — `false` = one container, `true` = all containers), `workingDir` (optional, default `/var/www`).

Cron runs inside the runtime container with full env var access. When `allContainers: false`, Zerops picks **one** container (good for DB jobs). Use `true` for cache clearing or log rotation everywhere. Minimum granularity is 1 minute.

---

## startCommands (Background Processes)

Runs **multiple named processes** in parallel. **Mutually exclusive** with `start`.

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

Each entry: `command` (**required** — the only field the schema requires), `name` (optional, distinguishes processes in logs), `workingDir` (optional), `initCommands` (optional, per-process init). **DO NOT** use both `start` and `startCommands`.

---

## initCommands vs prepareCommands

| Feature | `run.initCommands` | `run.prepareCommands` |
|---------|-------------------|----------------------|
| **When** | Every container start/restart | Only when building runtime image |
| **Cached** | Never | Yes (base layer cache) |
| **Use for** | Migrations, cache warming, cleanup | OS packages, system deps |
| **Deploy files** | Present in `/var/www` | **Not available** -- DO NOT reference app files |
| **Reruns on** | Restart, scaling, deploy | Only when commands change |
| **Reruns on** | Restart, scaling, deploy | Only when commands change |

---

## envReplace (Variable Substitution)

Replaces placeholders in deployed files with env var values at deploy time.

```yaml
run:
  envReplace:
    delimiter: "%%"
    target: [./config/, ./templates/settings.json]
```

File containing `%%DATABASE_URL%%` gets the placeholder replaced with the actual value. Multiple delimiters supported: `delimiter: ["%%", "##"]`. Use for: secrets in config files, PEM certificates, frontend configs.

**Directory targets are NOT recursive** -- `./config/` processes only files directly in that directory. Specify subdirectories explicitly.

---

## routing (Static Services Only)

```yaml
run:
  routing:
    cors: "'*' always"
    redirects:
      - { from: /old, to: /new, status: 301 }
      - { from: /blog/*, to: /articles/, preservePath: true, status: 302 }
    headers:
      - for: "/*"
        values: { X-Frame-Options: "'DENY'" }
```

- **`cors`**: Sets Access-Control-Allow-Origin. `"*"` auto-converted to `'*'`
- **`redirects[]`**: `from` (wildcards `*`), `to`, `status`, `preservePath`, `preserveQuery`
- **`headers[]`**: `for` (path pattern), `values` (header key-value pairs)
- **`root`**: Custom root directory

**DO NOT** use on non-static services -- silently ignored.

---

## extends (Configuration Inheritance)

```yaml
zerops:
  - setup: base
    build: { buildCommands: [npm run build], deployFiles: ./dist }
    run: { start: npm start }
  - setup: prod
    extends: base
    run: { envVariables: { NODE_ENV: production } }
```

Supports single parent (`extends: base`) or multiple parents (`extends: [base, logging]`) -- later parents override earlier ones:

```yaml
zerops:
  - setup: base
    build: { buildCommands: [npm run build], deployFiles: ./dist }
  - setup: logging
    run: { envVariables: { LOG_LEVEL: info } }
  - setup: prod
    extends: [base, logging]
    run: { envVariables: { NODE_ENV: production } }
```

Configuration is **merged at the section level** -- child values override parent values within each section (build, run, deploy), but unspecified sections inherit from parent. Must reference another `setup` name in the same file.

## Base Images

Available runtimes and versions are listed in **Service Stacks (live)** -- injected by `zerops_knowledge` and workflow responses. Some key rules:

- PHP: build `php@X`, run `php-nginx@X` or `php-apache@X` (different bases)
- Deno: REQUIRES `os: ubuntu` (no Alpine build exists). Gleam runs on both Alpine and Ubuntu.
- Static sites: build `nodejs@latest`, run `static`
- `@latest` = newest stable version

---


----------------------------------------

# Help > Contacts


:construction: **We apologize for any inconvenience, we are doing our best to finish this documentation ASAP to make your Zerops experience a blast!** :construction:

In the meantime, if you have any troubles setting up your application, or if you find a specific part of the documentation missing, don't hesitate to contact our team via:

- [Discord (recommended)](https://discord.com/invite/WDvCZ54) — The fastest way to get help from our team and other community members.
- [Report an issue](https://github.com/zeropsio/docs/issues/new/choose) — If you want to report an issue, please click here.
- [Email](mailto:support@zerops.io) — Reach the team directly, this might take longer as the community won
- [Twitter](https://x.com/zeropsio) — Reach out to us by direct messagining or by tagging @zeropsio in your tweets for a response.


----------------------------------------

# Help > Faq


Get quick answers to your related questions about Zerops from frequently asked questions we get asked.

### General

  **Question: Where can I find the Zerops Dashboard GUI?**

You can access the Zerops Dashboard GUI directly at [app.zerops.io](https://app.zerops.io).

  **Question: How much does it cost to get started?**

It's free to get started, and no credit card is required! However, we
    recommend visiting our [pricing page](/company/pricing) to explore the options that best suit your needs.

    We also have a calculator on our pricing page that can help you estimate the cost of your project.

  **Question: Where are your servers located?**

Our infrastructure spans multiple regions. In Europe, we operate our own high-tier
    data center in **Prague**, Czech Republic, running on bare metal servers managed by
    vshosting's senior admin team — [vshosting.eu](https://vshosting.eu/),
    one of the largest providers of managed hosting in Europe. In the US, we have servers
    in **New York**, with additional US East Coast capacity on its way through a trusted
    infrastructure partner.

    Stay tuned for updates on our [Discord server](https://docs.zerops.io/discord) and checkout our [roadmap](https://zerops.io/#about)!

  **Question: Why should I use Zerops over Self-Hosted PaaS?**

We have a detailed article discussing whether you should go for a Self-hosted PaaS → [The rise of self-hosted PaaS — is $5 VPS all you need?](https://zerops.io/article/the-rise-of-self-hosted-paa-s-is-5-vps-all-you-need).

  **Question: How do I change my email?**

Navigate to the main menu in the Zerop GUI (with your icon) and add a new user with the selected email to your team.

  **Question: I have more questions. Where can I reach out to get help?**

You can reach us on our [Discord server](https://docs.zerops.io/discord) for support. For additional contact options, please visit our [contacts page](https://docs.zerops.io/help/contacts).


----------------------------------------

# Homepage


export const runtimes = [
    { name: "Node.js", link: "/nodejs/overview", icon:  },
    { name: "PHP", link: "/php/overview", icon:  },
    { name: "Python", link: "/python/overview", icon:  },
    { name: "Go", link: "/go/overview", icon:  },
    { name: ".NET", link: "/dotnet/overview", icon:  },
    { name: "Rust", link: "/rust/overview", icon:  },
    { name: "Java", link: "/java/overview", icon:  },
    { name: "Deno", link: "/deno/overview", icon:  },
    { name: "Bun", link: "/bun/overview", icon:  },
    { name: "Elixir", link: "/elixir/overview", icon:  },
    { name: "Gleam", link: "/gleam/overview", icon:  },
    { name: "Ruby", link: "/ruby/overview", icon:  },
    { name: "Nginx", link: "/nginx/overview", icon:  },
    { name: "Static", link: "/static/overview", icon:  },
]

export const containers = [
    { name: "Ubuntu", link: "/ubuntu/overview", icon:  },
    { name: "Alpine", link: "/alpine/overview", icon:  },
    { name: "Docker", link: "/docker/overview", icon:  },
]

export const databases = [
    { name: "PostgreSQL", link: "/postgresql/overview", icon:  },
    { name: "MariaDB", link: "/mariadb/overview", icon:  },
    { name: "Valkey", link: "/valkey/overview", icon:  },
    { name: "Elasticsearch", link: "/elasticsearch/overview", icon:  },
    { name: "Typesense", link: "/typesense/overview", icon:  },
    { name: "Meilisearch", link: "/meilisearch/overview", icon:  },
    { name: "Qdrant", link: "/qdrant/overview", icon:  },
    { name: "NATS", link: "/nats/overview", icon:  },
    { name: "Kafka", link: "/kafka/overview", icon:  },
    { name: "ClickHouse", link: "/clickhouse/overview", icon:  },
    { name: "KeyDB", link: "/keydb/overview", icon:  },
]

export const storages = [
    { name: "Object storage", link: "/object-storage/overview", icon:  },
    { name: "Shared storage", link: "/shared-storage/overview", icon:  },
]

<div className="!max-w-xxl !mx-none">

Zerops is a **developer-first Platform-as-a-Service**, running on bare metal, with every part built from scratch. Zerops aims to be the perfect mix of **developer experience**, **flexibility**, **scalability** and **affordability**, making it a great fit for applications of any size, complexity and traffic.

## Natively supported services

### Runtimes & web servers

For these services Zerops provides pre-prepared build and runtime images and flexible pipeline that allows you to modify them and build your applications.

### Linux containers & VMs

These services can be deployed either as plain Linux containers or using Docker images, giving you flexibility to run any application or service.

### Databases, search engines & message brokers

These services are fully managed by Zerops and offered in highly available and single container modes.

### Storages

Fully managed S3 compatible storage running on a separate infrastructure and persistent disk that can be mounted to multiple services.

## Quicklinks

- [zCLI](/references/cli)
- [zerops.yaml](/zerops-yaml/specification)
- [Import YAML](/references/import)

## Feature highlights

Four concepts that play together to make Zerops developer-first and live up to the claim "no matter the size or environment".

### ➡️ Custom dedicated infrastructure deployed with each project

Zerops is made of three levels: **project** -> **service** -> **container**. For each project Zerops deploys dedicated **core services**, these consist of:

- **L3 balancer** with a firewall and unique IP addresses assigned to it, this serves as the main entry point from the internet,
- **Logger** and **Statistics** containers that gather logs and resource metrics from all services inside the project and allow for log forwarding
- **L7 load balancer** that handles and routes http traffic, SSL termination and SSL certificates

User services (which consist of one or more containers) inside the project share a private network created with VXLAN, have resources isolated with cgroups and can securely communicate with each other simply by using the hostname and ports and read and reference each other's environment variables.

:::tip[**What does this mean for you?**]

You get a fully managed, professional infrastructure setup that will scale no matter how much traffic you get and deals with all the networking, balancing and security stuff, so you can just focus on your actual applications.

[Read more about the project infrastructure](/features/infrastructure)

:::

### ➡️ Granular resource configuration, autoscaling and high availability of services

Zerops has fully automatic horizontal and vertical scaling with configuration steps as small as 0.125 GB RAM and 1 CPU core. Your runtime services can go from a single container with 0.25 RAM and 1 CPU core to 10 containers each with 32 GB RAM and 10 CPU cores and then back in a matter of minutes. At the same time, all database and storage services are offered in well-crafted setups that go through performance optimizations while scaling and are available in both non-HA (single container) and high availability (multiple containers and balancers) modes.

:::tip[**What does this mean for you?**]

You won't ever overprovision or underprovision your resources and your services will always have the exact resources they need. There won't be any cutting corners like sharing too few CPU cores between too many services. You will be able to rely on professional, reliable and highly available database setups with auto-repairing abilities that will scale along with your applications.

[Read more about autoscaling and high availability](/features/scaling)

:::

### ➡️ Full Linux OS containers with a powerful, flexible build and deploy pipeline

Zerops uses Incus to create containers, which means that you get a full Linux OS, either Ubuntu or Alpine, depending on your choices. This provides the perfect middle ground between a containerized process (Docker) and a full-fledged VM (Proxmox). Zerops provides build and runtime bases for all the popular runtime technologies and a powerful and flexible pipeline that allows you to modify and cache both the build and runtime images. This circumvents the need for Docker registries. The pipeline can be triggered either automatically, by connecting the service with GitHub or GitLab repositories, or manually using our CLI - either for triggering from your machine, or from any existing CI/CD process.

:::tip[**What does this mean for you?**]

You get a built-in powerful and flexible pipeline to modify build and runtime images and deploy your code, without any downtime. It can be used standalone or easily plugged into any existing CI/CD process.

[Read more about the build and deploy pipeline](/features/pipeline)

:::

### ➡️ Pricing model that doesn't get in the way of good development practices

"Simple and predictable pricing"... is what others say and what we actually do. In Zerops, cost per hardware resource (CPU, RAM, Disk) is 3-5x cheaper than with popular alternatives. And there are no plans, no feature tiers, no fees for seats. PaaS is just hardware with a cherry and bow on top, so why would we charge you for anything else but hardware resources?

:::tip[**What does this mean for you?**]

You get a powerful managed platform with all the best features unlocked for a price that's nearly on par with VPS. You can create as many environments as you need, even one for each developer working on a project, all with the same infrastructure as production, so they can utilize Zerops for their local development. No more "but it works on my machine".

:::
</div>


----------------------------------------

# Java > How To > Build Pipeline


Zerops provides a customizable build and runtime environment for your Java application.

## Add zerops.yaml to your repository

Start by adding `zerops.yaml` file to the **root of your repository** and modify it to fit your application:

```yaml
zerops:
  # define hostname of your service
  - setup: app
    # ==== how to build your application ====
    build:
      # REQUIRED. Set the base technology for the build environment:
      base: java@latest

      # OPTIONAL. Set the operating system for the build environment.
      # os: ubuntu

      # OPTIONAL. Customize the build environment by installing additional packages
      # or tools to the base build environment.
      # prepareCommands:
      #   - sudo apt-get something
      #   - curl something else

      # OPTIONAL. Build your application
      buildCommands:
        - ./mvnw clean install
      # REQUIRED. Select which files / folders to deploy after
      # the build has successfully finished
      deployFiles: target/app.jar

      # OPTIONAL. Which files / folders you want to cache for the next build.
      # Next builds will be faster when the cache is used.
      # cache: some_file

    # ==== how to run your application ====
    run:
      # OPTIONAL. Sets the base technology for the runtime environment:
      base: java@latest

      # OPTIONAL. Sets the internal port(s) your app listens on:
      ports:
        # port number
        - port: 8080

      # OPTIONAL. Customize the runtime Java environment by installing additional
      # dependencies to the base Java runtime environment.
      # prepareCommands:
      #   - sudo apt-get something
      #   - curl something else

      # OPTIONAL. Run one or more commands each time a new runtime container
      # is started or restarted. These commands are triggered before
      # your Java application is started.
      # initCommands:
      #  - rm -rf ./cache

      # REQUIRED. Your Java application start command
      start: java -jar target/app.jar
```

The top-level element is always `zerops`.

### Setup

The first element `setup` contains the **hostname** of your service. A runtime service with the same hostname must exist in Zerops.
Zerops supports the definition of multiple runtime services in a single `zerops.yaml`. This is useful when you use a monorepo. Just add multiple setup elements in your `zerops.yaml`:

```yaml
zerops:
  # definition for app service
  - setup: app
    # optional
    build: ...
    # optional
    deploy: ...
    # required
    run: ...

  # definition for api service
  - setup: api
    # optional
    build: ...
    # optional
    deploy: ...
    # required
    run: ...
```

Each service configuration contains at least the `run` section. Optional `build` and `deploy` sections can be added to further customize your process.

## Build pipeline configuration

### base

_REQUIRED._ Sets the base technology for the build environment.

Following options are available for Java builds:

```yaml
zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build:
      # REQUIRED. Sets the base technology for the build environment:
      base: java@latest
      ...
```

<p>
  The base build environment contains {data.alpine.default}, the selected version
  of Java, [Zerops command line tool](/references/cli), `git` and
  `wget`.
</p>

:::info
You can change the base environment when you need to. Just simply modify the `zerops.yaml` in your repository.
:::

If you need to install more technologies to the build environment, set multiple values as a yaml array. For example:

```yaml
zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build:
      # REQUIRED. Sets the base technology for the build environment:
      base:
        - java@latest
      prepareCommands:
        - zsc add nodejs@latest
      ...
```

See the full list of supported [build base environments](/zerops-yaml/base-list#runtime-services).

To customize your build environment use the [prepareCommands](#preparecommands) attribute.

:::note
Modifying the base technology will invalidate your build cache. See our [Build Cache Documentation](/features/build-cache) for more details about cache invalidation.
:::

### os

_OPTIONAL._ Sets the operating system for the build environment.

Following options are available:

- `alpine`
- `ubuntu`

Default value is `alpine`.

We are currently using following os version:

- <span>{data.alpine.default}</span>
- <span>{data.ubuntu.default}</span>

:::caution
The os version is fixed and cannot be customized.
:::

:::note
Changing the OS setting will invalidate your build cache. See our [Build Cache Documentation](/features/build-cache) for details about cache behavior.
:::

### prepareCommands

_OPTIONAL._ Customizes the build environment by installing additional dependencies or tools to the base build environment.

The base build environment contains:

- <span>{data.alpine.default}</span>
- selected version of Java defined in the [base](#base) attribute
- [Zerops command line tool](/references/cli)
- `git` and `wget`

To install additional packages or tools add one or more prepare commands:

```yaml
zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build:
      # REQUIRED. Set the base technology for the build environment:
      base: java@latest

      # OPTIONAL. Customize the build environment by installing additional packages
      # or tools to the base build environment.
      prepareCommands:
        - sudo apt-get something
        - curl something else
      ...
```

When the first build is triggered, Zerops will

1. create a build container
2. download your application code from your repository
3. run the prepare commands in the defined order

The application code is available in `/build/source` before the prepare commands are triggered, so you can use any file from your repository in your prepare commands (e.g. a configuration file). The commands themselves run in the `/home/zerops` directory.

:::note
These commands are skipped when using cached environment. Modifying `prepareCommands` will invalidate your build cache. See our [Build Cache Documentation](/features/build-cache) for details about cache invalidation.
:::

#### Command exit code

If any command fails, it returns an exit code other than 0 and the build is canceled. Read the [build log](/java/how-to/logs#build-log) to troubleshoot the error. If the command ends successfully, it returns the exit code 0 and Zerops triggers the following command. When all prepare commands are finished, your custom build environment is ready for the build phase.

#### Single or separated shell instances

You can configure your prepare commands to be run in a single shell instance or multiple shell instances. The format is identical to [build commands](#buildcommands).

### buildCommands

_OPTIONAL._ Defines build commands.

```yaml
zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build:
      # REQUIRED. Set the base technology for the build environment:
      base: java@latest

      # OPTIONAL. Build your application
      buildCommands:
        - ./mvnw clean install
      ...
```

Build commands are optional. Zerops triggers each command in the defined order in a dedicated build container, running from the `/build/source` directory.

Before the build commands are triggered the build container contains:

1. base environment defined by the [base](#base) attribute
2. optional customisation of the base environment defined in the [prepareCommands](#preparecommands) attribute
3. your application code

#### Run build commands as a single shell instance

Use following syntax to run all commands in the same environment context. For example, if one command changes the current directory, the next command continues in that directory. When one command creates an environment variable, the next command can access it. Suppose your `mvnw` executable file is in a `cmd` directory.

```yaml
buildCommands:
  - |
    cd cmd
    ./mvnw clean install
```

#### Run build commands as a separate shell instances

When the following syntax is used, each command is triggered in a separate environment context. For example, each shell instance starts in the home directory again. When one command creates an environment variable, it won't be available for the next command. Suppose your `mvnw` executable file is in a `cmd` directory.

```yaml
buildCommands:
  - cd cmd
  - ./cmd/mvnw clean install
```

#### Command exit code

If any command fails, it returns an exit code other than 0 and the build is canceled. Read the [build log](/java/how-to/logs#build-log) to troubleshoot the error. If the error log doesn't contain any specific error message, try to run your build with the `-X` debug option.

```yaml
buildCommands:
  - ./mvnw -X clean install
```

If the command ends successfully, it returns the exit code 0 and Zerops triggers the following command. When all `buildCommands` are finished, the application build is completed and ready for the deploy phase.

### deployFiles

_REQUIRED._ Selects which files or folders will be deployed after the build has successfully finished. To filter out specific files or folders, use [`.deployignore`](#deployignore) file.

```yaml
# REQUIRED. Select which files / folders to deploy after
# the build has successfully finished
deployFiles:
  - app.jar
```

Determines files or folders produced by your build, which should be deployed to your runtime service containers.

The path starts from the **root directory** of your project (the location of `zerops.yaml`). You must enclose the name in quotes if the folder or the file name contains a space.

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

#### Examples

Deploys a folder, and a file from the project root directory:

```yaml
deployFiles:
  - api
  - app.jar
```

Deploys the whole content of the build container:

```yaml
deployFiles: .
```

Deploys a folder, and a file in a defined path:

```yaml
deployFiles:
  - ./path/to/file.txt
  - ./path/to/dir/
```

#### How to use a wildcard in the path

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

Deploys all folders that are located in any path that begins with `/path/to/`

```yaml
deployFiles: ./path/to/~/
```

Deploys all folders that are located in any path that begins with `/path/` and ends with `/to/`

```yaml
deployFiles: ./path/~/to/
```

:::note Example
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 will be cached for the next build.

```yaml
# OPTIONAL. Which files / folders you want to cache for the next build.
# Next builds will be faster when the cache is used.
cache: file.txt
```

The cache attribute helps optimize build times by preserving specified files between builds.

The cache attribute supports the [~ wildcard character](#how-to-use-a-wildcard-in-the-path).

Learn more about the [build cache system](/features/build-cache) in Zerops.

### envVariables

_OPTIONAL._ Defines the environment variables for the build environment.

Enter one or more env variables in following format:

```yaml
zerops:
  # define hostname of your service
  - setup: app
    # ==== how to build your application ====
    build:
      base: java@latest
        …

      # OPTIONAL. Defines the env variables for the build environment:
      envVariables:
        DB_NAME: db
        DB_HOST: db
        DB_USER: db
        DB_PASS: ${db_password}
```

Read more about [environment variables](/java/how-to/env-variables) in Zerops.

## Runtime configuration

### base

_OPTIONAL._ Sets the base technology for the runtime environment.
If you don't specify the `run.base` attribute, Zerops keeps the current Java version for your runtime.

Following options are available for Java builds:

```yaml
zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build:
      # REQUIRED. Sets the base technology for the build environment:
      base: java@latest
      ...

    # ==== how to run your application ====
    run:
      # OPTIONAL. Sets the base technology for the runtime environment:
        base: java@latest
      ...
```

<p>
  The base runtime environment contains {data.alpine.default}, the selected major
  version of Java, Zerops command line tool, git` and `wget`.
</p>

:::info
You can change the base environment when you need to. Just simply modify the `zerops.yaml` in your repository.
:::

If you need to install more technologies to the runtime environment, set multiple values as a yaml array. For example:

```yaml
zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build:
      # REQUIRED. Sets the base technology for the build environment:
      base: java@latest
      ...

    # ==== how to run your application ====
    run:
      # OPTIONAL. Sets the base technology for the runtime environment:
      base:
        - java@latest
      prepareCommands:
        - zsc add nodejs@latest
      ...
```

See the full list of supported [run base environments](/zerops-yaml/base-list).

To customize your build environment use the `prepareCommands` attribute.

### os

_OPTIONAL._ Sets the operating system for the runtime environment.

Following options are available:

- `alpine`
- `ubuntu`

Default value is `alpine`.

We are currently using following os version:

- <span>{data.alpine.default}</span>
- <span>{data.ubuntu.default}</span>

:::caution
The os version is fixed and cannot be customized.
:::

### ports

_OPTIONAL._ Specifies one or more internal ports on which your application will listen.

Projects in Zerops represent a group of one or more services. Services can be of different types (runtime services, databases, message brokers, object storage, etc.). All services of the same project share a **dedicated private network**. To connect to a service within the same project, just use the service hostname and its internal port.

For example, to connect to a Java service with hostname = "app" and port = 8080 from another service of the same project, simply use `app:8080`. Read more about [how to access a Java service](/references/networking/internal-access#basic-service-communication).

Each port has following attributes:

<table className="w-full my-1.5">
  <thead>
    <tr>
      <th className="w-fit"><strong>Parameter</strong></th>
      <th className="w-fit"><strong>Description</strong></th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td className="w-fit">port</td>
      <td className="w-fit">Defines the port number. You can set any port number between <em>10</em> and <em>65435</em>. Ports outside this interval are reserved for internal Zerops systems.</td>
    </tr>
    <tr>
      <td className="w-fit">protocol</td>
      <td className="w-fit"><strong>Optional.</strong> Defines the protocol. Allowed values are <code>TCP</code> or <code>UDP</code>. Default value is <code>TCP</code>.</td>
    </tr>
    <tr>
      <td className="w-fit">httpSupport</td>
      <td className="w-fit"><strong>Optional.</strong> <code>httpSupport = true</code> is the default setting for TCP protocol. Set <code>httpSupport = false</code> if a web server isn't running on the port. Zerops uses this information for the configuration of [public access](/features/access). <code>httpSupport = true</code> is available only in combination with the TCP protocol.</td>
    </tr>
  </tbody>
</table>

### prepareCommands

_OPTIONAL._ Customizes the Java runtime environment by installing additional dependencies or tools to the runtime base environment.

<p>
  The base Java environment contains {data.alpine.default}, the selected major
  version of Java, [Zerops command line tool](/references/cli) and
  `git` and `wget`. To install additional packages or tools add one or more
  prepare commands:
</p>

```yaml
zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build:
      ...

    # ==== how to run your application ====
    run:
      # OPTIONAL. Customise the runtime environment by installing additional packages
      # or tools to the base Java runtime environment.
      prepareCommands:
        - sudo apt-get something
        - curl something else
      ...
```

When the first deploy with a defined prepare attribute is triggered, Zerops will

1. create a prepare runtime container
2. optionally: [copy selected folders or files from your build container](#copy-folders-or-files-from-your-build-container)
3. run the `prepareCommands` commands in the defined order

:::note
`run.prepareCommands` run in the `/home/zerops` directory.
:::

#### Command exit code

If any command fails, it returns an exit code other than 0 and the deploy is canceled. Read the [prepare runtime log](/java/how-to/logs#prepare-runtime-log) to troubleshoot the error. If the command ends successfully, it returns the exit code 0 and Zerops triggers the following command. When all `prepareCommands` commands are finished, your custom runtime environment is ready for the deploy phase.

#### Cache of your custom runtime environment

Some packages or tools can take a long time to install. Therefore, Zerops caches your custom runtime environment after the installation of your custom packages or tools is completed. When the second or following deploy is triggered, Zerops will use the custom runtime cache from the previous deploy if following conditions are met:

1. Content of the [build.addToRunPrepare](#copy-folders-or-files-from-your-build-container) and `run.prepareCommands` attributes didn't change from the previous deploy
2. The custom runtime cache wasn't invalidated in the Zerops GUI.

To invalidate the Zerops runtime cache go to your service detail in Zerops GUI, choose **Service dashboard & runtime containers** from the left menu and click on the **Open pipeline detail** button. Then click on the **Clear runtime prepare cache** button.

When the prepare cache is used, Zerops doesn't create a prepare runtime container and executes the deployment of your application directly.

#### Single or separated shell instances

You can configure your prepare commands to be run in a single shell instance or multiple shell instances. The format is identical to [build commands](#buildcommands).

### Copy folders or files from your build container

<p>
  The prepare runtime container contains {data.alpine.default}, the selected
  major version of Java, [Zerops command line tool](/references/cli) and `git` and `wget`.
</p>

The prepare runtime container does not contain your application code nor the built application. If you need to copy some folders or files from the build container to the runtime container (e.g. a configuration file) use the `addToRunPrepare` attribute in the [build section](#build-pipeline-configuration).

```yaml
zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build:
      ...
      addToRunPrepare: ./runtime-config.yaml

    # ==== how to run your application ====
    run:
      # OPTIONAL. Customise the runtime environment by installing additional packages
      # or tools to the base Java runtime environment.
      prepareCommands:
        - sudo apt-get something
        - curl something else
      ...
```

In the example above Zerops will copy the `runtime-config.yaml` file from your build container **after the build has finished** into the new **prepare runtime** container. The copied files and folders will be available in the `/home/zerops` folder in the new prepare runtime container before the prepare commands are triggered.

### initCommands

_OPTIONAL._ Defines one or more commands to be run each time a new runtime container is started or a container is restarted.

```yaml
zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build: ...

    # ==== how to run your application ====
    run:
      # OPTIONAL. Run one or more commands each time a new runtime container
      # is started or restarted. These commands are triggered before
      # your Java application is started.
      initCommands:
        - rm -rf ./cache
```

These commands are triggered in the runtime container before your Java application is started via the [start command](#start).

:::note
`run.initCommands` run in the `/var/www` directory.
:::

Use init commands to clean or initialise your application cache or similar operations.

:::caution
The init commands will delay the start of your application each time a new runtime container is started (including the horizontal [scaling](/java/how-to/scaling) or when a runtime container is restarted).

Do not use the init commands for customising your runtime environment. Use the [run:prepareCommands](#preparecommands-1) attribute instead.
:::

#### Command exit code

If any of the `initCommands` fails, it returns an exit code other than 0, but deploy is **not** canceled. After all init commands are finished, regardless of the status code, the application is started. Read the [runtime log](/java/how-to/logs#runtime-log) to troubleshoot the error.

#### Single or separated shell instances

You can configure your `initCommands` to be run in a single shell instance or multiple shell instances. The format is identical to [build commands](#buildcommands).

### envVariables

_OPTIONAL._ Defines the environment variables for the runtime environment.

Enter one or more env variables in following format:

```yaml
zerops:
  # define hostname of your service
  - setup: app
    # ==== how to run your application ====
    run:
      # OPTIONAL. Defines the env variables for the runtime environment:
      envVariables:
        DB_NAME: db
        DB_HOST: db
        DB_USER: db
        DB_PASS: ${db_password}
```

Read more about [environment variables](/java/how-to/env-variables) in Zerops.

### start

_REQUIRED._ Defines the start command for your Java application.

```yaml
zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build: ...

    # ==== how to run your application ====
    run:
      # REQUIRED. Your Java application start command
      start: java -jar target/app.jar
```

We recommend starting your Java application using `java -jar target/app.jar`.

### health check

_OPTIONAL._ Defines a health check.

`healthCheck` requires either one `httpGet` object or one `exec` object.

#### httpGet

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

Following attributes are available:

<table className="w-full my-1.5">
  <thead>
    <tr>
      <th className="w-fit whitespace-nowrap">Parameter</th>
      <th className="w-fit whitespace-nowrap">Description</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td className="w-fit whitespace-nowrap font-semibold">port</td>
      <td>Defines the port of the HTTP GET request.
The readiness check will trigger a GET request on <code>{'http://127.0.0.1:{port}/{path}'}</code></td>
    </tr>
    <tr>
      <td className="w-fit whitespace-nowrap font-semibold">path</td>
      <td>Defines the URL path of the HTTP GET request.
The readiness check will trigger a GET request on <code>{'http://127.0.0.1:{port}/{path}'}</code></td>
    </tr>
    <tr>
      <td className="w-fit whitespace-nowrap font-semibold">host</td>
      <td><strong>Optional.</strong> The readiness check is triggered from inside of your runtime container so it always uses the localhost <code>127.0.0.1</code>. If you need to add a <code>host</code> to the request header, specify it in the <code>host</code> attribute.</td>
    </tr>
    <tr>
      <td className="w-fit whitespace-nowrap font-semibold">scheme</td>
      <td><strong>Optional.</strong> The readiness check is triggered from inside of your runtime container so no https is required.
If your application requires a https request, set <code>scheme: https</code></td>
    </tr>
  </tbody>
</table>

**Example:**

```yaml
zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build: ...

    # ==== how to run your application ====
    run:
      # REQUIRED. Your Java application start command
      start: java -jar target/app.jar

      # OPTIONAL. Define a health check with a HTTP GET request option.
      # Configures the check on http://127.0.0.1:80/status
      healthCheck:
        httpGet:
          port: 80
          path: /status
```

#### exec

Configures the health check to run a local command.
Following attributes are available:

<table className="w-full my-1.5">
  <thead>
    <tr>
      <th className="w-fit"><strong>Parameter</strong></th>
      <th className="w-fit"><strong>Description</strong></th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td className="w-fit"><strong>command</strong></td>
      <td className="w-fit">
        Defines a local command to be run.

        The command has access to the same [environment variables](/java/how-to/create#set-secret-environment-variables) as your Java application.

        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 below.
      </td>
    </tr>
  </tbody>
</table>

**Example:**

```yaml
zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build: ...

    # ==== how to run your application ====
    run:
      # REQUIRED. Your Java application start command
      start: java -jar target/app.jar

      # OPTIONAL. Define a health check with a shell command.
      healthCheck:
        exec:
          command: |
            touch grass
            rm -rf life
            mv /outside/user /home/user
```

### crontab

_OPTIONAL._ Defines cron jobs.

Setup cron jobs in the following format:

```yaml
zerops:
  # define hostname of your service
  - setup: app

    # ==== how to run your application ====
    run:
      crontab:
        # REQUIRED. Sets the command to execute:
        - command: ""
        # REQUIRED. Sets the interval time to execute:
          timing: "0 * * * *"
```

Read more about setting up [cron](/zerops-yaml/cron) in Zerops.

## Deploy configuration

### readiness check

_OPTIONAL._ Defines a readiness check. Read more about how the [readiness check works](/java/how-to/deploy-process#readiness-checks) in Zerops.

`readinessCheck` requires either one `httpGet` object or one `exec` object.

#### httpGet

Configures the readiness check to request a local URL using a http GET method.

Following attributes are available:

<table className="w-full my-1.5">
  <thead>
    <tr>
      <th className="w-fit whitespace-nowrap">Parameter</th>
      <th className="w-fit whitespace-nowrap">Description</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td className="w-fit whitespace-nowrap font-semibold">port</td>
      <td>Defines the port of the HTTP GET request.
The readiness check will trigger a GET request on <code>{'http://127.0.0.1:{port}/{path}'}</code></td>
    </tr>
    <tr>
      <td className="w-fit whitespace-nowrap font-semibold">path</td>
      <td>Defines the URL path of the HTTP GET request.
The readiness check will trigger a GET request on <code>{'http://127.0.0.1:{port}/{path}'}</code></td>
    </tr>
    <tr>
      <td className="w-fit whitespace-nowrap font-semibold">host</td>
      <td><strong>Optional.</strong> The readiness check is triggered from inside of your runtime container so it always uses the localhost <code>127.0.0.1</code>. If you need to add a <code>host</code> to the request header, specify it in the <code>host</code> attribute.</td>
    </tr>
    <tr>
      <td className="w-fit whitespace-nowrap font-semibold">scheme</td>
      <td><strong>Optional.</strong> The readiness check is triggered from inside of your runtime container so no https is required.
If your application requires a https request, set <code>scheme: https</code></td>
    </tr>
  </tbody>
</table>

**Example:**

```yaml
zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build: ...

    # ==== how to deploy your application ====
    deploy:
      # OPTIONAL. Define a readiness check with a HTTP GET request option.
      # Configures the check on http://127.0.0.1:80/status
      readinessCheck:
        httpGet:
          port: 80
          path: /status

    # ==== how to run your application ====
    run: ...
```

Read more about how the [readiness check works](/java/how-to/deploy-process#readiness-checks) in Zerops.

#### exec

Configures the readiness check to run a local command.
Following attributes are available:

<table className="w-full my-1.5">
  <thead>
    <tr>
      <th className="w-fit"><strong>Parameter</strong></th>
      <th className="w-fit"><strong>Description</strong></th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td className="w-fit"><strong>command</strong></td>
      <td className="w-fit">
        Defines a local command to be run.

        The command has access to the same [environment variables](/java/how-to/create#set-secret-environment-variables) as your Java application.

        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 below.
      </td>
    </tr>
  </tbody>
</table>

**Example:**

```yaml
zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build: ...

    # ==== how to deploy your application ====
    deploy:
      # OPTIONAL. Define a readiness check with a HTTP GET request option.
      # Configures the check on http://127.0.0.1:80/status
      readinessCheck:
        exec:
          command: |
            touch grass
            rm -rf life
            mv /outside/user /home/user
```

Read more about how the [readiness check works](/java/how-to/deploy-process#readiness-checks) in Zerops.


----------------------------------------

# Java > How To > Build Process



----------------------------------------

# Java > How To > Controls



----------------------------------------

# Java > How To > Create


Zerops provides a Java runtime service with extensive build support. Java runtime is highly scalable and customisable to suit both development and production.

## Create Java service using Zerops GUI

First, set up a project in Zerops GUI. Then go to the project dashboard page and choose **Add new service** in the left menu in the **Services** block. Then add a new Java service:

[Video: /vids/services/java.webm](/vids/services/java.webm)

### Choose Java version

Following Java versions are currently supported:

:::info
You can [change](/java/how-to/upgrade) the major version at any time later.
:::

### Set a hostname

Enter a unique service identifier like "app","cache", "gui" etc. Duplicate services with the same name in the same project are forbidden.

#### Limitations:

- maximum 25 characters
- must contain only lowercase ASCII letters (a-z) or numbers (0-9)

:::caution
The hostname is fixed after the service is created. It can't be changed later.
:::

### Set secret environment variables

Add environment variables with sensitive data, such as password, tokens, salts, certificates etc. These will be securely saved inside Zerops and added to your runtime service upon start.

Setting the secret environment variables is optional. You can set them later in Zerops GUI.

Read more about [different types of env variables](/java/how-to/env-variables#service-env-variables) in Zerops.

## Create Java service using zCLI

zCLI is the Zerops command-line tool. To create a new Java service via the command-line, follow these steps:

1. [Install & setup zCLI](/references/cli)
2. [Create a project description file](/java/how-to/create#create-a-project-description-file)
3. [Create a project with a Java and PostgreSQL service](#full-example)

### Create a project description file

Zerops uses a yaml format to describe the project infrastructure.

#### Basic example:

Create a directory `my-project`. Create an `description.yaml` file inside the `my-project` directory with following content:

```yaml
# basic project data
project:
  # project name
  name: my-project
# array of project services
services:
  - # service name
    hostname: app
    # service type and version number in java@{version} format
    type: java@latest
    # defines the minimum number of containers for horizontal autoscaling
    minContainers: 1
    # defines the maximum number of containers for horizontal autoscaling. Max value = 6.
    maxContainers: 6
    # optional: create env variables
    envSecrets:
      S3_ACCESS_KEY_ID: 'P8cX1vVVb'
      S3_ACCESS_SECRET: 'ogFthuiLYki8XoL73opSCQ'
```

The yaml file describes your future project infrastructure. The project will contain one Java version 1 service with default [auto scaling](/java/how-to/scaling) configuration. Hostname will be set to "app", the internal port(s) the service listens on will be defined later in the [zerops.yaml](/java/how-to/build-pipeline#ports). Following secret env variables will be configured:

```env
S3_ACCESS_KEY_ID="P8cX1vVVb"
S3_ACCESS_SECRET="ogFthuiLYki8XoL73opSCQ"
```

#### Full example:

Create a directory my-project. Create an description.yaml file inside the my-project directory with following content:

```yaml
# basic project data
project:
  # project name
  name: my-project
  # optional: project description
  description: A project with a Java and PostgreSQL database
  # optional: project tags
  tags:
    - DEMO
    - ZEROPS
# array of project services
services:
  - # service name
    hostname: app
    # service type and version number in java@{version} format
    type: java@latest
    # optional: vertical auto scaling customization
    verticalAutoscaling:
      cpuMode: DEDICATED
      minCpu: 2
      maxCpu: 5
      minRam: 2
      maxRam: 24
      minDisk: 6
      maxDisk: 50
      startCpuCoreCount: 3
      minFreeRamGB: 0.5
      minFreeRamPercent: 20
    # defines the minimum number of containers for horizontal autoscaling. Max value = 6.
    minContainers: 2
    # defines the maximum number of containers for horizontal autoscaling. Max value = 6.
    maxContainers: 4
    # optional: create secret env variables
    envSecrets:
      S3_ACCESS_KEY_ID: 'P8cX1vVVb'
      S3_ACCESS_SECRET: 'ogFthuiLYki8XoL73opSCQ'
  - # second service hostname
    hostname: db
    # service type and version number in postgresql@{version} format
    type: postgresql@12
    # mode of operation "HA"/"non_HA"
    mode: NON_HA
```

The yaml file describes your future project infrastructure. The project will contain a Java service and a [PostgreSQL](/postgresql/overview) service.

Java service with "app" hostname, the internal port(s) the service listens on will be defined later in the zerops.yaml. Java service will run on version 1 with a custom vertical and horizontal scaling. Following secret env variables will be configured:

```env
S3_ACCESS_KEY_ID="P8cX1vVVb"
S3_ACCESS_SECRET="ogFthuiLYki8XoL73opSCQ"
```

The hostname of the PostgreSQL service will be set to "db". The [single container](/features/scaling#single-container-mode)(/features/scaling#deployment-modes-databases-and-shared-storage) mode will be chosen and the default auto [scaling configuration](/postgresql/how-to/scale#configure-scaling) will be set.

#### Description of description.yaml parameters

The `project:` section is required. Only one project can be defined.

<table className="w-full my-1.5">
  <thead>
    <tr>
      <th className="w-fit"><strong>Parameter</strong></th>
      <th className="w-fit"><strong>Description</strong></th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td className="w-fit"><strong>hostname</strong></td>
      <td className="w-fit">
        The unique service identifier.

        The hostname of the new database will be set to the `hostname` value.

        <strong>Limitations:</strong>
        <ul>
        <li>duplicate services with the same name in the same project are forbidden</li>
        <li>maximum 25 characters</li>
        <li>must contain only lowercase ASCII letters (a-z) or numbers (0-9)</li>
        </ul>
      </td>
    </tr>
    <tr>
      <td className="w-fit"><strong>type</strong></td>
      <td className="w-fit">
        Specifies the service type and version.

        See what [Java service types](/references/import-yaml/type-list#runtime-services) are currently supported.
      </td>
    </tr>
    <tr>
      <td className="w-fit"><strong>verticalAutoscaling</strong></td>
      <td className="w-fit">
        <strong>Optional.</strong> Defines [custom vertical auto scaling parameters](/java/how-to/create#set-auto-scaling-configuration).

        All verticalAutoscaling attributes are optional. Not specified attributes will be set to their default values.
      </td>
    </tr>
    <tr>
      <td className="w-fit"><strong>- cpuMode</strong></td>
      <td className="w-fit">
        <strong>Optional.</strong> Accepts `SHARED`, `DEDICATED` values. Default is `SHARED`
      </td>
    </tr>
    <tr>
      <td className="w-fit"><strong>- minCpu/maxCpu</strong></td>
      <td className="w-fit">
        <strong>Optional.</strong> Set the minCpu or maxCpu in CPU cores (integer).
      </td>
    </tr>
    <tr>
      <td className="w-fit"><strong>- minRam/maxRam</strong></td>
      <td className="w-fit">
        <strong>Optional.</strong> Set the minRam or maxRam in GB (float).
      </td>
    </tr>
    <tr>
      <td className="w-fit"><strong>- minDisk/maxDisk</strong></td>
      <td className="w-fit">
        <strong>Optional.</strong> Set the minDisk or maxDisk in GB (float).
      </td>
    </tr>
    <tr>
      <td className="w-fit"><strong>minContainers</strong></td>
      <td className="w-fit">
        <strong>Optional.</strong> Default = 1. Defines the minimum number of containers for [horizontal autoscaling](/java/how-to/create#horizontal-auto-scaling).

        <strong>Limitations:</strong>

        Current maximum value = 10.
      </td>
    </tr>
    <tr>
      <td className="w-fit"><strong>maxContainers</strong></td>
      <td className="w-fit">
        Defines the maximum number of containers for [horizontal autoscaling](/java/how-to/create#horizontal-auto-scaling).

        <strong>Limitations:</strong>

        Current maximum value = 10.
      </td>
    </tr>
    <tr>
      <td className="w-fit"><strong>envSecrets</strong></td>
      <td className="w-fit">
        <strong>Optional.</strong> Defines one or more secret env variables as a key value map. See env variable [restrictions](/java/how-to/env-variables#env-variable-restrictions).
      </td>
    </tr>
  </tbody>
</table>

### Create a project based on the description.yaml

When you have your `description.yaml` ready, use the `zcli project project-import` command to create a new project and the service infrastructure.

```sh
Usage:
  zcli project project-import importYamlPath [flags]

Flags:
  -h, --help                Help for the project import command.
      --org-id string        If you have access to more than one organization, you must specify the org ID for which the
                            project is to be created.
      --working-dir string   Sets a custom working directory. Default working directory is the current directory. (default "./")
```

Zerops will create a project and one or more services based on the `description.yaml` content.

Maximum size of the `description.yaml` file is 100 kB.

You don't specify the project name in the `zcli project project-import` command, because the project name is defined in the `description.yaml`.

If you have access to more than one client, you must specify the client ID for which the project is to be created. The `clientID` is located in the Zerops GUI under the client name on the project dashboard page.

### Add Java service to an existing project

#### Example:

Create a directory `my-project` if it doesn't exist. Create an `import.yaml` file inside the `my-project` directory with following content:

```yaml
# basic project data
project:
  # project name
  name: my-project
# array of project services
services:
  - # service name
    hostname: app
    # service type and version number in java@{version} format
    type: java@latest
    # defines the minimum number of containers for horizontal autoscaling
    minContainers: 1
    # defines the maximum number of containers for horizontal autoscaling. Max value = 6.
    maxContainers: 6
    # optional: create env variables
    envSecrets:
      S3_ACCESS_KEY_ID: 'P8cX1vVVb'
      S3_ACCESS_SECRET: 'ogFthuiLYki8XoL73opSCQ'
```

The yaml file describes the list of one or more services that you want to add to your existing project. In the example above, one Java service version 1 with default [auto scaling](/java/how-to/scaling) configuration will be added to your project. Hostname of the new service will be set to `app`. Following secret env variables will be configured:

```env
S3_ACCESS_KEY_ID="P8cX1vVVb"
S3_ACCESS_SECRET="ogFthuiLYki8XoL73opSCQ"
```

The content of the `services:` section of `import.yaml` is identical to the project description file. The `import.yaml` never contains the `project:` section because the project already exists.

When you have your `import.yaml` ready, use the `zcli project service-import` command to add one or more services to your existing Zerops project.

```sh
Usage:
  zcli project service-import importYamlPath [flags]

Flags:
  -h, --help                Help for the project service import command.
  -P, --project-id string   If you have access to more than one project, you must specify the project ID for which the
                           command is to be executed.
```

zCLI commands are interactive, when you press enter after `zcli project service-import importYamlPath`, you will be given a list of your projects to choose from.

Maximum size of the import.yaml file is 100 kB.


----------------------------------------

# Java > How To > Customize Runtime



----------------------------------------

# Java > How To > Deploy Process



----------------------------------------

# Java > How To > Env Variables



----------------------------------------

# Java > How To > Filebrowser



----------------------------------------

# Java > How To > Logs



----------------------------------------

# Java > How To > Scaling



----------------------------------------

# Java > How To > Shared Storage



----------------------------------------

# Java > How To > Trigger Pipeline



----------------------------------------

# Java > How To > Upgrade



----------------------------------------

# Java > Overview


# Java overview

[Java ↗](https://www.java.com/en/) is a high-level, class-based, object-oriented programming language that is designed to have as few implementation dependencies as possible.

As said, there is no need for coding yet, we have created a [Github repository ↗](https://github.com/zeropsio/recipe-java-hello-world), a **_recipe_**, containing the most simple Java web application. The repo will be used as a source from which the app will be built.

### 🚀 Feel free to deploy the recipe yourself

This is the most bare-bones example of Java running in Zerops — as few libraries as possible,
  just a simple endpoint with connect, read and write to a Zerops PostgreSQL database.

  [Deploy "java" recipe on Zerops](https://app.zerops.io/recipe/?lf=java)

1. Log in/sign up to [Zerops GUI ↗](https://app.zerops.io)
2. In the **Projects** box click on **Import a project** and paste in the following YAML config ([source ↗](https://github.com/zeropsio/recipe-java-hello-world/blob/main/import-project/description.yaml)):

```yaml
project:
  name: my-first-project
services:
  - hostname: helloworld
    type: java@latest
    minContainers: 1
    maxContainers: 3
    buildFromGit: https://github.com/zeropsio/recipe-java-hello-world@main
    enableSubdomainAccess: true
```

3. Click on **Import project** and wait until all pipelines have finished.

**That's it, your application is now up and running! :star: Let's check it works:**

1. A _subdomain_ should have been enabled and visible in the project's **IP addressed & Public Routing Overview** box. Its format should look similar to this `https://helloworld-24-8080.prg1.zerops.app`.
2. Click or the `subdomain` URL to open it in a browser and you should see

```
Hello, World!
```

:::tip
Do you have any questions? Check the step-by-step tutorial, browse the documentation and join our **[Discord](https://discord.com/invite/WDvCZ54)** community to get help from our team and other members.
:::

## How to start

- [Care for details?](/java/how-to/create) — Dive in all Zerops has to offer for your Java application.

## Feature Highlights

- [Create Java service](/java/how-to/create) — Start with creating a Java service using GUI or zCLI.
- [zerops.yaml](/java/how-to/build-pipeline#add-zeropsyaml-to-your-repository) — See a full example of zerops.yaml file to create your own app.
- [Scaling configuration](/java/how-to/scaling) — Set up scaling of your Java application so that it runs smoothly while using only necessary resources.

{" "}

- [Customize build environment](/java/how-to/build-process#customize-build-environment)
- [Customize runtime environment](/java/how-to/customize-runtime)

## When in doubt, reach out

Don't know how to start or got stuck during the process? You might not be the first one, visit the FAQ section to find out.

In case you haven't found an answer (and also if you have), we and our community are looking forward to hearing from you on Discord.

Have you build something that others might find useful? Don't hesitate to share your knowledge!

- [FAQ](/java/faq) — Most common questions in one place.
- [Discord](https://discord.com/invite/WDvCZ54) — Join our core team and Zerops community on Discord. Ask questions and share your tips with other members.

## Popular Guides

- [zCLI](/references/cli) — Get even more out of Zerops with the zCLI command line tool.
- [Zerops VPN](/references/networking/vpn) — Connect to your services easily with Zerops VPN.


----------------------------------------

# Kafka > Overview


Zerops provides a fully managed [Apache Kafka](https://kafka.apache.org/) messaging platform with automated scaling and zero infrastructure overhead, letting developers focus entirely on development.

## Supported Versions

Currently supported Kafka version:

Import configuration version:

- `kafka@3.9`
- `kafka@3.8`

## Service Configuration

Our Kafka implementation features optimized default settings designed for common use cases.

### Key Configuration

* **Client Connections:** Data brokers available on port `9092`
* **Authentication:** Secure SASL PLAIN with automatically generated credentials
* **Data Persistence:** Topic data stored indefinitely (no time or size limit)
* **Performance:** Optimized settings for reliability and throughput

### Resource Allocation

Zerops automatically allocates resources to your Kafka service based on demand:

* **Memory:** Up to 40GB RAM for high-performance message processing
* **Storage:** Up to 250GB for persistent storage of messages and logs
* **Auto-scaling:** Resources scale up and down automatically based on workload

## Deployment Modes

:::important
Deployment mode is selected during service creation and cannot be changed later.
:::

### High-Availability (HA) Setup

The recommended solution for production workloads and mission-critical data:

* Creates a multi-node Kafka cluster with 3 broker nodes
* Configures 6 partitions across the cluster
* Implements replication factor of 3 (each broker node has a copy of each partition)
* Default topic replication is also 3 (overridable by user application)
* Zerops automatically attempts to repair the cluster and data replication in case of a node failure

### Single Node Instance

Suitable for development and testing environments:

* Consists of 1 broker node
* Configures 3 partitions
* No data replication
* Lower resource requirements

:::note
Use for development or non-critical data only, as data loss may occur due to container volatility.
:::

## Authentication Management

Authentication credentials are automatically generated and managed by the platform using SASL PLAIN authentication.

**Access your credentials through:**
* The service access details in the Zerops GUI
* Environment variables in your service configuration:
  * `user` - Username for authentication
  * `password` - Generated secure password
  * `port` - Kafka port (value: `9092`)

## Client Access

Client implementations differ, please refer to your chosen client's configuration manual for specific details.

### Access Methods

#### Seed Broker Connection
Connect to the Kafka cluster using the "seed" (or "bootstrap") broker server:
```
<hostname>:9092
```

#### Specific Broker Access
To access a single specific broker or a list of all/some brokers:
```
node-stable-1.db.<hostname>.zerops:9092,node-stable-2.db.<hostname>.zerops:9092,...
```

## Best Practices

### Production Workloads
* Use HA mode for all production deployments
* Configure proper retention policies for your topics based on your data requirements
* Monitor consumer lag to ensure messages are being processed efficiently
* Use consumer groups to distribute processing load

### Development Environments
* Single node instances are suitable for development and testing
* Be aware of potential data loss in non-HA deployments
* Consider using smaller message sizes during development to reduce resource usage

## Support

For advanced configurations or custom requirements:
* Join our [Discord community](https://discord.gg/zerops)
* Contact support via [email](mailto:support@zerops.io)

----------------------------------------

# Keydb > How To > Connect


## Copy access details from Zerops GUI

You will find the KeyDB access details under the **Access details** button in the project dashboard page.

The same information is available in the service detail page in the left menu under the **Peek access details** button.

### KeyDB access parameters:

| Parameter             | Description                                                                      |
| --------------------- | -------------------------------------------------------------------------------- |
| **Hostname**          | The service hostname specified when the KeyDB service was created.               |
| **Hostname**          | The service hostname specified when the KeyDB service was created.               |
| **Port**              | **6379**
This port is fixed for all KeyDB services and cannot be customized. |
| **Connection string** | The connection string for KeyDB service is:
`redis://{hostname}:6379`        |

## Connect to KeyDB from runtime services of the same project

Projects in Zerops represent a group of one or more services. Services can be of different types (runtime services, databases, message brokers, object storage, etc.). All services of the same project share a **dedicated private network**. To connect to a service within the same project, just use the service hostname and its internal port.

#### Example

To connect to KeyDB `database1` service, set

```
host = database1
```

You will find the password under the [**Access details**](#copy-access-details-from-zerops-gui) button in Zerops GUI.

:::caution
Do not use SSL/TLS protocols when connecting to KeyDB from other runtime services in the same project. Zerops KeyDB is not configured to support these protocols. The security is assured by the project private network. Due to security reasons Zerops doesn't allow exposing KeyDB service to the internet.
:::

## Use KeyDB environment variables

Zerops creates default environment variables for each KeyDB service to help you with connection from runtime services in the same project. To avoid the need to copy database access parameters manually, use environment variables in your [runtime service].

### Prefix the environment variable key

All services of the same project can reference environment variables from other services. To use an environment variable from one service in another service in the same project, you must prefix the environment variable key with the service hostname and underscore.

#### Example

To access the `connectionString` env variable of the `keydb1` service, use `keudb1_connectionString` as the env variable key.

### KeyDB environment variables

List of service environment variables is available in Zerops GUI. Go to a KeyDB service detail and choose **Environment variables** in the left menu.

Zerops creates following environment variables when the KeyDB service is created:

| Variable              | Description                                                                      |
| --------------------- | -------------------------------------------------------------------------------- |
| **Hostname**          | The service hostname specified when the KeyDB service was created.               |
| **Hostname**          | The service hostname specified when the KeyDB service was created.               |
| **Port**              | **5432**
This port is fixed for all KeyDB services and cannot be customized. |
| **projectId**         | ID of the project. Generated by Zerops.                                          |
| **serviceId**         | ID of the KeyDB service. Generated by Zerops.                                    |
| **Connection string** | The connection string for KeyDB service is:
`redis://{hostname}:6379`        |

You can create own custom [environment variables](/features/env-variables) for the KeyDB service in Zerops GUI and use them in the same way as the default variables.

## Connect to KeyDB in Zerops remotely

:::caution
Due to security reasons Zerops doesn't allow exposing KeyDB service directly to the internet.
:::

### Start VPN connection

You can securely connect to KeyDB from your local workspace via Zerops VPN. Zerops VPN client is included into zCLI, the Zerops command-line tool. To start a VPN connection to the selected Zerops project, follow these steps:

1. [Install & setup zCLI](/references/cli)
2. [Start the Zerops VPN](/references/networking/vpn#start-vpn)

### Access KeyDB through VPN

Once the VPN session is established, you have the secured connection to the project's private network in Zerops. You can access all project services locally by using their hostname. The only difference is that no [environment variables](#use-keydb-environment-variables) are available when connected through VPN. To connect to KeyDB in Zerops you have to copy the [access details](#copy-access-details-from-zerops-gui) manually from Zerops GUI.

:::caution
Do not use SSL/TLS protocols when connecting to KeyDB over VPN. Zerops KeyDB is not configured to support these protocols. The security is assured by the VPN.
:::

### Stop VPN connection

[Stop the Zerops VPN](/references/networking/vpn#stop-vpn) in zCLI.

### Connect to KeyDB from another Zerops project

All services of the same project share a **dedicated private network**. You can use the service hostname to connect from one service to another within the same project.

Different Zerops projects have no special connection. They can communicate with each other only via the internet. If you need to connect to a KeyDB service in a Zerops project from a runtime service in another project, you need to use the [Zerops VPN](#access-keydb-through-vpn). Due to security reasons Zerops doesn't allow exposing KeyDB service directly to the internet.


----------------------------------------

# Keydb > How To > Control



----------------------------------------

# Keydb > How To > Create


[KeyDB ↗](https://docs.keydb.dev/) is a fully open source database, backed by Snap, and a faster drop in alternative to Redis.

## Create KeyDB using Zerops GUI

First, set up a project in Zerops GUI. Then go to the project dashboard page and choose **Add new service** in the left menu in the **Services** block. Then add a new KeyDB service:

### Choose KeyDB version

Following KeyDB versions are currently supported:

### Set a hostname

Enter a unique service identifier like `keydb`, `db` etc.

#### Limitations:

- Duplicate services with the same name within the same project are not allowed
- Maximum 25 characters
- Must contain only lowercase ASCII letters (a-z) or numbers (0-9)

:::caution
The hostname is fixed after the service is created and cannot be changed later.
:::

### Configure auto scaling

Zerops automatically scales KeyDB services based on actual database usage. Configure the scaling parameters to match your database needs and control costs.

**CPU Mode**: Choose between shared (cost-effective) or dedicated (consistent performance).

**Resource Limits**: Set minimum and maximum resources for CPU, RAM, and disk to control costs and ensure performance.

**Deployment Mode**: Choose the reliability configuration for your KeyDB service:

- **Highly Available**: Multiple containers with redundancy across different physical machines. Recommended for production environments.
- **Single Container**: One container suitable for development and non-critical environments.

:::warning
Deployment mode cannot be changed after service creation.
:::

:::tip Learn More
For detailed scaling configuration, deployment mode details, and troubleshooting, see:
- [How Zerops scales KeyDB](/keydb/how-to/scale) - Database-specific scaling guide
- [Automatic Scaling and High Availability](/features/scaling) - Complete technical details
:::

## Create KeyDB using zCLI

zCLI is the Zerops command-line tool. To create a new KeyDB service via the command-line, follow these steps:

1. [Install & setup zCLI](/references/cli)
2. [Create a project description file](#create-a-project-description-file)
3. Create a project and a KeyDB service

### Create a project description file

Zerops uses a yaml format file to describe the project infrastructure.

#### Basic example

Create a directory `my-project`. Create a `description.yaml` file inside the directory with the following content:

```yaml
# basic project data
project:
  # project name
  name: my-project
# array of project services
services:
  - # service name
    hostname: keydb1
    # service type and version number in keydb@6 format
    type: keydb@6
    # mode of operation "HA"/"NON_HA"
    mode: NON_HA
```

The yaml file describes your future project infrastructure. The project will contain one KeyDB service in single container mode with default [auto scaling](/keydb/how-to/scale) configuration. Hostname will be set to `keydb1`.

#### Full example

Create a directory `my-project`. Create a `description.yaml` file inside the directory with the following content:

```yaml
# basic project data
project:
  # project name
  name: my-project
  # optional: project description
  description: A project with a KeyDB database
  # optional: project tags
  tags:
    - DEMO
    - ZEROPS
# array of project services
services:
  - # first service hostname
    hostname: keydb1
    # service type and version number in keydb@6 format
    type: keydb@6
    # mode of operation "HA"/"NON_HA"
    mode: HA
    # optional: vertical auto scaling customization
    verticalAutoscaling:
      cpuMode: DEDICATED
      minCpu: 2
      maxCpu: 5
      minRam: 2
      maxRam: 24
      minDisk: 6
      maxDisk: 50
      startCpuCoreCount: 3
      minFreeRamGB: 0.5
      minFreeRamPercent: 20
  - # second service hostname
    hostname: keydb2
    # service type and version number in keydb@6 format
    type: keydb@6
    # mode of operation "HA"/"non_HA"
    mode: NON_HA
```

The yaml file describes your future project infrastructure. The project will contain two KeyDB services.

The hostname of the first service will be set to `keydb1`. The highly available mode will be chosen and the custom [auto scaling configuration](/keydb/how-to/scale) will be set.

The hostname of the second service will be set to `keydb2`. The single container mode will be chosen and the default [auto scaling configuration](/keydb/how-to/scale) will be set.

#### Description of description.yaml parameters

The `project:` section is required. Only one project can be defined.

<table className="w-full my-1.5">
  <thead>
    <tr>
      <th className="w-fit"><strong>Parameter</strong></th>
      <th className="w-fit"><strong>Description</strong></th>
      <th className="w-fit"><strong>Limitations</strong></th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td className="w-fit"><strong>name</strong></td>
      <td className="w-fit">The name of the new project. Duplicates are allowed.</td>
      <td className="w-fit"></td>
    </tr>
    <tr>
      <td className="w-fit"><strong>description</strong></td>
      <td className="w-fit"><strong>Optional.</strong> Description of the new project.</td>
      <td className="w-fit">Maximum 255 characters.</td>
    </tr>
    <tr>
      <td className="w-fit"><strong>tags</strong></td>
      <td className="w-fit"><strong>Optional.</strong> One or more string tags. Tags do not have a functional meaning, they only provide better orientation in projects.</td>
      <td className="w-fit"></td>
    </tr>
  </tbody>
</table>

At least one service in `services:` section is required. You can create a project with multiple services. The example above contains only KeyDB services but you can create a `description.yaml` with [different types] of services.

<table className="w-full my-1.5">
  <thead>
    <tr>
      <th className="w-fit"><strong>Parameter</strong></th>
      <th className="w-fit"><strong>Description</strong></th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td className="w-fit"><strong>hostname</strong></td>
      <td className="w-fit">
        The unique service identifier.

        The hostname of the new database will be set to the `hostname` value.

        <strong>Limitations:</strong>
        <ul>
        <li>duplicate services with the same name in the same project are forbidden</li>
        <li>maximum 25 characters</li>
        <li>must contain only lowercase ASCII letters (a-z) or numbers (0-9)</li>
        </ul>
      </td>
    </tr>
    <tr>
      <td className="w-fit"><strong>type</strong></td>
      <td className="w-fit">
        Specifies the service type and version.

        See what [KeyDB service types](/references/import-yaml/type-list#database-services) are currently supported.
      </td>
    </tr>
    <tr>
      <td className="w-fit"><strong>mode</strong></td>
      <td className="w-fit">
        Defines the operation mode of KeyDB service.

        <strong>HA</strong>

        Creates a KeyDB cluster with 2 database containers. This mode is suited for production.

        Zerops always keeps the 2 database containers on different physical machines. All your data is stored redundantly in 2 identical copies. In case of a failure of a container or the underlying physical machine, Zerops automatically disconnects the failed container from the cluster, creates a new container and syncs all data from the remaining copy. Finally the broken container is automatically deleted.

        <strong>NON_HA</strong>

        Zerops will create a KeyDB database installed in a single container. Useful for non-essential data or dev environments.

        Your data is stored only in a single container. If the container or the underlying physical machine fails, your data since the last backup are lost. Zerops doesn't provide any automatic repairs of single node KeyDB services.
      </td>
    </tr>
    <tr>
      <td className="w-fit"><strong>verticalAutoscaling</strong></td>
      <td className="w-fit">
        <strong>Optional.</strong> Defines [custom vertical auto scaling parameters](/keydb/how-to/scaling#configure-scaling).

        All verticalAutoscaling attributes are optional. Not specified attributes will be set to their default values.
      </td>
    </tr>
    <tr>
      <td className="w-fit"><strong>- cpuMode</strong></td>
      <td className="w-fit">
        <strong>Optional.</strong> Accepts `SHARED`, `DEDICATED` values. Default is `SHARED`
      </td>
    </tr>
    <tr>
      <td className="w-fit"><strong>- minCpu/maxCpu</strong></td>
      <td className="w-fit">
        <strong>Optional.</strong> Set the minCpu or maxCpu in CPU cores (integer).
      </td>
    </tr>
    <tr>
      <td className="w-fit"><strong>- minRam/maxRam</strong></td>
      <td className="w-fit">
        <strong>Optional.</strong> Set the minRam or maxRam in GB (float).
      </td>
    </tr>
    <tr>
      <td className="w-fit"><strong>- minDisk/maxDisk</strong></td>
      <td className="w-fit">
        <strong>Optional.</strong> Set the minDisk or maxDisk in GB (float).
      </td>
    </tr>
  </tbody>
</table>

:::caution
The KeyDB service **hostname** and **mode** are fixed after the service is created. They can't be changed later.
:::

### Create a project based on the description.yaml

When you have your `description.yaml` ready, use the `zcli project project-import` command to create a new project and the service infrastructure.

```sh
Usage:
  zcli project project-import importYamlPath [flags]

Flags:
  -h, --help                Help for the project import command.
      --org-id string        If you have access to more than one organization, you must specify the org ID for which the
                            project is to be created.
      --working-dir string   Sets a custom working directory. Default working directory is the current directory. (default "./")
```

Zerops will create a project and one or more services based on the `description.yaml` content.

Maximum size of the `description.yaml` file is 100 kB.

You don't specify the project name in the `zcli project project-import` command, because the project name is defined in the `description.yaml`.

If you have access to more than one client, you must specify the client ID for which the project is to be created. The `clientID` is located in the Zerops GUI under the client name on the project dashboard page.

### Add KeyDB service to an existing project

#### Example

Create a directory `my-project` if it doesn't exist. Create an `import.yaml` file inside the `my-project` directory with following content:

```bash
# array of project services
services:
  -
    # service name
    hostname: keydb1
    # service type and version number in keydb@6 format
    type: keydb@6
    # mode of operation "HA"/"NON_HA"
    mode: NON_HA
```

The yaml file describes the list of one or more services that you want to add to your existing project. In the example above, one KeyDB service in single container mode with default [auto scaling](/keydb/how-to/scale) configuration will be added to your project. Hostname of the new service will be set to `keydb1`.

The content of the `services:` section of `import.yaml` is identical to the [project description file](#create-a-project-description-file). The `import.yaml` never contains the `project:` section because the project already exists.

When you have your `import.yaml` ready, use the `zcli project service-import` command to add one or more services to your existing Zerops project.

```sh
Usage:
  zcli project service-import importYamlPath [flags]

Flags:
  -h, --help                Help for the project service import command.
  -P, --project-id string   If you have access to more than one project, you must specify the project ID for which the
                           command is to be executed.
```

zCLI commands are interactive, when you press enter after `zcli project service-import importYamlPath`, you will be given a list of your projects to choose from.

Maximum size of the `import.yaml` file is 100 kB.

----------------------------------------

# Keydb > How To > Manage


## How to use a database management tool on your workstation

Do you already use a database management tool that supports KeyDB on your workstation? Connect it securely to KeyDB from your local workspace via Zerops VPN.

Zerops VPN client is included into zCLI, the Zerops command-line tool. To start the VPN connection, read [how to connect to KeyDB remotely](/keydb/how-to/connect#connect-to-keydb-in-zerops-remotely).

:::caution
Do not use SSL/TLS protocols when connecting to KeyDB over VPN. Zerops KeyDB is not configured to support these protocols. The security is assured by the VPN.
:::

## How to use KeyDB Client CLI on your workstation

If you use the [keydb-cli ↗](https://docs.keydb.dev/docs/keydbcli/) command-line client to manage your KeyDB on your local workspace, you can connect it securely to KeyDB via Zerops VPN.

Zerops VPN client is included into zCLI, the Zerops command-line tool. To start the VPN connection, read [how to connect to KeyDB remotely](/keydb/how-to/connect#connect-to-keydb-in-zerops-remotely).

Once the VPN session is established, you have the secured connection to the project's private network in Zerops. You can access all project services locally by using their hostname. The only difference is that no [environment variables](/keydb/how-to/connect#connect-to-keydb-in-zerops-remotely) are available when connected through VPN. To connect to KeyDB in Zerops you have to copy the [access details](/keydb/how-to/connect#connect-to-keydb-in-zerops-remotely) manually from Zerops GUI.

Use `keydb-cli` command to connect to KeyDB in Zerops:

```sh
keydb-cli -h [hostname]
```

:::caution
Do not use SSL/TLS protocols when connecting to KeyDB over VPN. Zerops KeyDB is not configured to support these protocols. The security is assured by the VPN.
:::


----------------------------------------

# Keydb > How To > Scale


Zerops automatically scales your KeyDB service based on actual database usage. When your database needs more power, resources increase. When demand drops, resources scale down to reduce costs.

:::tip Read More
For complete scaling details across all services, see [Automatic Scaling and High Availability](/features/scaling).
:::

## How KeyDB scaling works

KeyDB services use **vertical scaling** to adjust CPU, RAM, and disk resources within containers based on usage patterns. Unlike runtime services, KeyDB does not use horizontal scaling (adding/removing containers). Instead, KeyDB services use deployment modes for high availability.

## Configure scaling

You can configure scaling settings:

- **During service creation** - Set initial scaling parameters when [creating](/keydb/how-to/create) your KeyDB service
- **During import** - Define scaling configuration in your YAML import file using `verticalAutoscaling` parameters
- **After service creation** - Navigate to your KeyDB service and select **Automatic scaling configuration** to modify settings

### Basic settings

**CPU Mode**: Choose between shared (cost-effective, variable performance) or dedicated (consistent performance, higher cost). You can change CPU mode once per hour. See [pricing](https://zerops.io/#pricing) for costs.

**Resource limits**: Configure minimum and maximum resources for your KeyDB service:

- **Lower the maximum** to control costs and prevent over-scaling
- **Raise the minimum** when you need guaranteed baseline performance
- **Set minimum = maximum** to disable automatic scaling for that specific resource

**Deployment mode**: Choose the reliability configuration for your KeyDB service:

- **Single Container**: One container with vertical scaling only. Suitable for development environments.
- **Highly Available**: Multiple containers with built-in redundancy. Recommended for production environments.

:::warning
Deployment mode cannot be changed after service creation.
:::

When a container fails in HA mode, Zerops automatically replaces it with a new container on a different physical machine and synchronizes data from healthy copies.

### Advanced settings

**Start CPU cores**: Determines how many CPU cores are allocated during database startup. Increase this value if your KeyDB service starts slowly or requires more processing power during initialization.

**RAM thresholds**: Help prevent out-of-memory crashes by maintaining buffer space:

- **Absolute (GB)**: Maintains this amount of free RAM at all times
- **Percentage**: Keeps this percentage of total RAM free

Consider increasing these values if your database experiences memory-related issues.

:::info Read More
For detailed technical parameters and scaling behavior, see [Automatic Scaling and High Availability](/features/scaling#resource-scaling-behavior).
:::

## Monitor usage

Navigate to your KeyDB service and select **Service containers & Overview** to view:
- CPU, RAM, and disk usage over time
- Historical scaling events
- Container health status

## Technical details

Zerops monitors database usage and automatically adjusts resources based on predefined thresholds and timing parameters. The scaling behavior follows the same principles as other services in the platform.

For complete technical specifications including:
- Resource monitoring intervals and thresholds
- Scale-up and scale-down timing parameters
- Scaling increments and steps
- Detailed scaling behavior patterns

See [Resource Scaling Behavior](/features/scaling#resource-scaling-behavior) in the general scaling documentation.

## Common issues

**Out of memory errors**
- Increase minimum free RAM settings in your scaling configuration
- Consider raising the minimum RAM allocation
- Check for memory-intensive operations

**Higher than expected costs**
- Consider lowering your maximum resource limits
- Review scaling patterns in the monitoring dashboard

**Slow database startup**
- Increase the "Start CPU cores" setting
- Consider switching to dedicated CPU mode for consistent performance

*Need help? Join our [Discord community](https://discord.gg/zerops) for assistance!*

----------------------------------------

# Keydb > Overview


[KeyDB ↗](https://docs.keydb.dev/) is a fully open source database, a faster drop-in alternative to Redis. It offers enhanced performance, multithreading capabilities, and maintains full compatibility with Redis clients and APIs.

:::important
While KeyDB is available in Zerops, please note that KeyDB development has not been very active recently. For new Redis-compatible deployments, we recommend considering [Valkey](/valkey/overview) as the preferred alternative due to its active development and ongoing support.
:::

## Feature Highlights

- [Create KeyDB service](/keydb/how-to/create) — Start with creating a KeyDB service using GUI or zCLI.
- [Import config file](/keydb/how-to/create#full-example) — Use an example config file to import your KeyDB service.

### Connect to KeyDB service

- [Manage KeyDB database](/keydb/how-to/manage)
- [Connect from the same project](/keydb/how-to/connect#connect-to-keydb-from-runtime-services-of-the-same-project)
- [Connect remotely](/keydb/how-to/connect#connect-to-keydb-in-zerops-remotely)

## Popular Guides

- [zCLI](/references/cli) — Get even more out of Zerops with the zCLI command line tool.
- [Zerops VPN](/references/networking/vpn) — Connect to your KeyDB service securely with Zerops VPN.

*Need help? Join our [Discord community](https://discord.gg/zeropsio).*

----------------------------------------

# Mariadb > How To > Backup


Zerops provides automated data backup for MariaDB services with full encryption and flexible management options.

For general backup information including configuration, scheduling, and management options, see the [Zerops Backups](/features/backup) documentation, which covers:
- Backup scheduling and retention policies
- Tagging system and storage quotas
- Manual backup creation and CLI tools
- Security and encryption details

This page focuses on MariaDB-specific backup details.

## MariaDB Backup Format

MariaDB backups are created using `mariabackup` and stored in `.xb.gz` format:

- **Format**: `.xb.gz` (single archive)
- **Tooling**: `mariabackup`
- **Compression**: Uses `xbstream` format, gzip compressed
- **Storage**: Encrypted and stored in isolated object storage

## Restoring MariaDB Backups

To restore a MariaDB backup, follow these steps:

:::tip
If the backup is large and the export/import has higher demands, consider scaling up the RAM in the container before starting. You can use [zsc](/references/zsc) to temporarily scale up:
```bash
zsc scale ram +2GB 10m
```
:::

### Step 1: Deploy the restore helper service

Import the [MariaDB restore recipe](https://github.com/zeropsio/recipe-mariadb-restore) as a service into the project where your MariaDB service is located.

Use the `zerops-import.yaml` file from the repository to import the service. See the [import documentation](/references/import) for details, or follow the steps in the [recipe README](https://github.com/zeropsio/recipe-mariadb-restore?tab=readme-ov-file#deploy-on-zerops).

### Step 2: Get the backup download URL

1. Navigate to your MariaDB service in the Zerops GUI
2. Go to the **Backups List & Configuration** section
3. Find the backup you want to restore
4. Click the **three dots menu** (⋮) on that backup
5. Select **Copy download link**

### Step 3: Run the backup script

Connect to the `mariadbrestore` service using the GUI terminal or via [VPN](/references/networking/vpn) and [SSH](/references/networking/ssh).

:::note
To use environment variables from your MariaDB service in the backup and restore commands, make sure the `envIsolation` project variable is set to `none`. See [Environment Variable Isolation](/features/env-variables#environment-variable-isolation) and [Referencing Variables](/features/env-variables#referencing-variables) for details.
:::

Run the backup script:

```bash
backup.sh -d <source_database_name> -u "<backup_download_url>"
```

Verify the backup was created:

```bash
ls -lh backup.sql
```

:::note
You can also verify the backup file exists by checking the **File browser** in the `mariadbrestore` service.
:::

:::info
After the export completes, the terminal may become unresponsive. If this happens, refresh the terminal.
:::

### Step 4: Import data to the target database

Import the data to your target MariaDB database:

```bash
mariadb -u <target_user> -h <target_host> -p<target_password> <target_database_name> < backup.sql
```

Alternatively, you can download the `backup.sql` dump file for later use or to restore to a database outside of Zerops.

## High Availability

For MariaDB services running in High Availability mode:
- Backups are created on a randomly selected healthy node
- Other nodes remain operational during the backup process
- Manual backups typically run on the primary node

## Best Practices

- Always create a manual backup with a protected tag before database migrations or major schema changes
- Test your restore process periodically in a non-production environment
- Monitor your backup storage usage in the Project Overview
- Use descriptive tags like `pre-migration-v2` for important snapshots

For additional best practices and troubleshooting, refer to the [main backup documentation](/features/backup).

----------------------------------------

# Mariadb > How To > Connect


## Default MariaDB database and user

Zerops creates a default database and a default user automatically when a new MariaDB service is [created](/mariadb/how-to/create).

#### Database

The default database name is identical to the service hostname. The default encoding is set to `utf8mb4`.

#### DB user

Default user name is identical to the service hostname. Default user password is generated randomly. You will find the password in [Zerops GUI](/mariadb/how-to/connect#copy-access-details-from-zerops-gui) or you can use the [environment variable](#use-mariadb-environment-variables).

:::info
Zerops creates a second DB user: `zps` for maintenance reasons with full privileges. Do not delete, change the password or remove privileges from this user, it will disrupt Zerops ability to maintain the database cluster.
:::

## Copy access details from Zerops GUI

You will find the MariaDB access details under the **Access details** button in the project dashboard page.

The same information is available in the service detail page in the left menu under the **Peek access details** button.

### MariaDB access parameters:

| Parameter             | Description                                                                                                                          |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| **Hostname**          | The service hostname specified when the MariaDB service was created.                                                                 |
| **Hostname**          | The service hostname specified when the MariaDB service was created.                                                                 |
| **Port**              | **3306**
This port is fixed for all MariaDB services and cannot be customized.                                                   |
| **User**              | Zerops creates a database user automatically when the service is created. The user name is always identical to the service hostname. |
| **Password**          | Zerops sets a random password when the service is created.                                                                           |
| **Connection string** | The connection string for MariaDB service is:
`mysql://${user}:${password}@{hostname}:3306`                                      |

## Connect to MariaDB from runtime services of the same project

Projects in Zerops represent a group of one or more services. Services can be of different types (runtime services, databases, message brokers, object storage, etc.). All services of the same project share a **dedicated private network**. To connect to a service within the same project, just use the service hostname and its internal port.

#### Example

To connect to MariaDB `database1` service, set

```
host = database1
user = database1
password = **********
```

You will find the password under the [**Access details**](/mariadb/how-to/connect#copy-access-details-from-zerops-gui) button in Zerops GUI.

:::caution
Do not use SSL/TLS protocols when connecting to MariaDB from other runtime services in the same project. Zerops MariaDB is not configured to support these protocols. The security is assured by the project private network. Due to security reasons Zerops doesn't allow exposing MariaDB service to the internet.
:::

## Use MariaDB environment variables

Zerops creates default environment variables for each MariaDB service to help you with connection from runtime services in the same project. To avoid the need to copy database access parameters manually, use environment variables in your [runtime service].

### Prefix the environment variable key

All services of the same project can reference environment variables from other services. To use an environment variable from one service in another service in the same project, you must prefix the environment variable key with the service hostname and underscore.

#### Example

To access the `connectionString` env variable of the `mariadb1` service, use `mariadb1_connectionString` as the env variable key.
To access the `password` env variable of the `mariadb2` service, use `mariadb2_password` as the env variable key.

### MariaDB environment variables

List of service environment variables is available in Zerops GUI. Go to a MariaDB service detail and choose **Environment variables** in the left menu.

Zerops creates following environment variables when the MariaDB service is created:

| Variable              | Description                                                                                                                                                                                                                                                                                                                                                       |
| --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Hostname**          | The service hostname specified when the MariaDB service was created.                                                                                                                                                                                                                                                                                              |
| **Hostname**          | The service hostname specified when the MariaDB service was created.                                                                                                                                                                                                                                                                                              |
| **Port**              | **3306**
This port is fixed for all MariaDB services and cannot be customized.                                                                                                                                                                                                                                                                                |
| **projectId**         | ID of the project. Generated by Zerops.                                                                                                                                                                                                                                                                                                                           |
| **serviceId**         | ID of the MariaDB service. Generated by Zerops.                                                                                                                                                                                                                                                                                                                   |
| **Connection string** | The connection string for MariaDB service is:
`mysql://${user}:${password}@{hostname}:3306`

Connection string contains [references](/mariadb/how-to/connect#mariadb-access-parameters) to `user` and `password` variables. Each time the `user` or `password` variable is updated, the `connectionString` variable is automatically updated as well. |
| **User**              | Zerops creates a database user automatically when the service is created. The user name is always identical to the service hostname.                                                                                                                                                                                                                              |
| **Password**          | Zerops sets a random password when the service is created.                                                                                                                                                                                                                                                                                                        |

:::caution
When you change the value of the password env variable, only the env variable is updated, not the actual password of the MariaDB user. You have to update the password of the database user manually.
:::
:::caution
When you change the password of the default MariaDB user in the database, the new password is not synchronised to the password env variable. You have to update the `password` env variable manually.
:::

You can create own custom [environment variables](/features/env-variables) for the MariaDB service in Zerops GUI and use them in the same way as the default variables.

## Connect to MariaDB in Zerops remotely

:::caution
Due to security reasons Zerops doesn't allow exposing MariaDB service directly to the internet.
:::

### Start VPN connection

You can securely connect to MariaDB from your local workspace via Zerops VPN. Zerops VPN client is included into zCLI, the Zerops command-line tool. To start a VPN connection to the selected Zerops project, follow these steps:

1. [Install & setup zCLI](/references/cli)
2. [Start the Zerops VPN](/references/networking/vpn#start-vpn)

### Access MariaDB through VPN

Once the VPN session is established, you have the secured connection to the project's private network in Zerops. You can access all project services locally by using their hostname. The only difference is that no [environment variables](#use-mariadb-environment-variables) are available when connected through VPN. To connect to MariaDB in Zerops you have to copy the [access details](#copy-access-details-from-zerops-gui) manually from Zerops GUI.

:::caution
Do not use SSL/TLS protocols when connecting to MariaDB over VPN. Zerops MariaDB is not configured to support these protocols. The security is assured by the VPN.
:::

### Stop VPN connection

[Stop the Zerops VPN](/references/networking/vpn#stop-vpn) in zCLI.

### Connect to MariaDB from another Zerops project

All services of the same project share a **dedicated private network**. You can use the service hostname to connect from one service to another within the same project.

Different Zerops projects have no special connection. They can communicate with each other only via the internet. If you need to connect to a MariaDB service in a Zerops project from a runtime service in another project, you need to use the [Zerops VPN](#access-mariadb-through-vpn). Due to security reasons Zerops doesn't allow exposing MariaDB service directly to the internet.


----------------------------------------

# Mariadb > How To > Control



----------------------------------------

# Mariadb > How To > Create


MariaDB is the open source relational database loved by developers all over the world. Created by MySQL's original developers, MariaDB is compatible with MySQL and guaranteed to stay open source forever.

## Create MariaDB using Zerops GUI

:::note
If you're migrating from another database system such as MySQL, please review the [migration information](#migrating-from-other-database-systems) section first, as some critical settings must be configured at creation time.
:::

First, set up a project in Zerops GUI. Then go to the project dashboard page and choose **Add new service** in the left menu in the **Services** block. Then add a new MariaDB service:

[Video: /vids/services/mariadb.webm](/vids/services/mariadb.webm)

### Choose MariaDB version

Following MariaDB versions are currently supported:

### Set a hostname

Enter a unique service identifier like `mariadb`, `sql`, `db` etc.

#### Limitations:

- Duplicate services with the same name within the same project are not allowed
- Maximum 25 characters
- Must contain only lowercase ASCII letters (a-z) or numbers (0-9)

:::caution
The hostname is fixed after the service is created and cannot be changed later.
:::

### Configure auto scaling

Zerops automatically scales MariaDB services based on actual database usage. Configure the scaling parameters to match your database needs and control costs.

**CPU Mode**: Choose between shared (cost-effective) or dedicated (consistent performance).

**Resource Limits**: Set minimum and maximum resources for CPU, RAM, and disk to control costs and ensure performance.

**Deployment Mode**: Choose the reliability configuration for your MariaDB service:

- **Highly Available**: Multiple containers with redundancy across different physical machines. Recommended for production environments.
- **Single Container**: One container suitable for development and non-critical environments.

:::warning
Deployment mode cannot be changed after service creation.
:::

:::tip Learn More
For detailed scaling configuration, deployment mode details, and troubleshooting, see:
- [How Zerops scales MariaDB](/mariadb/how-to/scale) - Database-specific scaling guide
- [Automatic Scaling and High Availability](/features/scaling) - Complete technical details
:::

## Create MariaDB using zCLI

:::note
If you're migrating from another database system such as MySQL, please review the [migration information](#migrating-from-other-database-systems) section first, as some critical settings must be configured at creation time.
:::

zCLI is the Zerops command-line tool. To create a new MariaDB service via the command-line, follow these steps:

1. [Install & setup zCLI](/references/cli)
2. [Create a project description file](#create-a-project-description-file)
3. Create a project and a MariaDB service

### Create a project description file

Zerops uses a yaml format file to describe the project infrastructure.

#### Basic example

Create a directory `my-project`. Create a `description.yaml` file inside the directory with the following content:

```yaml
# basic project data
project:
  # project name
  name: my-project
# array of project services
services:
  - # service name
    hostname: mariadb1
    # service type and version number in mariadb@{version} format
    type: mariadb@10.4
    # mode of operation "HA"/"NON_HA"
    mode: NON_HA
```

The yaml file describes your future project infrastructure. The project will contain one MariaDB 10.4 service in single container mode with default [auto scaling](/mariadb/how-to/scale) configuration. Hostname will be set to `mariadb1`.

#### Full example

Create a directory `my-project`. Create a `description.yaml` file inside the directory with the following content:

```yaml
# basic project data
project:
  # project name
  name: my-project
  # optional: project description
  description: A project with a MariaDB database
  # optional: project tags
  tags:
    - DEMO
    - ZEROPS
# array of project services
services:
  - # first service hostname
    hostname: mariadb1
    # service type and version number in mariadb@{version} format
    type: mariadb@10.4
    # mode of operation "HA"/"NON_HA"
    mode: HA
    # optional: vertical auto scaling customization
    verticalAutoscaling:
      cpuMode: DEDICATED
      minCpu: 2
      maxCpu: 5
      minRam: 2
      maxRam: 24
      minDisk: 6
      maxDisk: 50
      startCpuCoreCount: 3
      minFreeRamGB: 0.5
      minFreeRamPercent: 20
    # optional: system variables configuration
    envSecrets:
      lower_case_table_names: "1"
  - # second service hostname
    hostname: mariadb2
    # service type and version number in mariadb@{version} format
    type: mariadb@10.4
    # mode of operation "HA"/"non_HA"
    mode: NON_HA
```

The yaml file describes your future project infrastructure. The project will contain two MariaDB 10.4 services.

The hostname of the first service will be set to `mariadb1`. The highly available mode will be chosen and the custom [auto scaling configuration](/mariadb/how-to/scale) will be set. The `lower_case_table_names` system variable will be set to "1".

The hostname of the second service will be set to `mariadb2`. The single container mode will be chosen and the default [auto scaling configuration](/mariadb/how-to/scale) will be set.

#### Description of description.yaml parameters

The `project:` section is required. Only one project can be defined.

<table className="w-full my-1.5">
  <thead>
    <tr>
      <th className="w-fit"><strong>Parameter</strong></th>
      <th className="w-fit"><strong>Description</strong></th>
      <th className="w-fit"><strong>Limitations</strong></th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td className="w-fit"><strong>name</strong></td>
      <td className="w-fit">The name of the new project. Duplicates are allowed.</td>
      <td className="w-fit"></td>
    </tr>
    <tr>
      <td className="w-fit"><strong>description</strong></td>
      <td className="w-fit"><strong>Optional.</strong> Description of the new project.</td>
      <td className="w-fit">Maximum 255 characters.</td>
    </tr>
    <tr>
      <td className="w-fit"><strong>tags</strong></td>
      <td className="w-fit"><strong>Optional.</strong> One or more string tags. Tags do not have a functional meaning, they only provide better orientation in projects.</td>
      <td className="w-fit"></td>
    </tr>
  </tbody>
</table>

At least one service in `services:` section is required. You can create a project with multiple services. The example above contains only MariaDB services but you can create a `description.yaml` with [different types] of services.

<table className="w-full my-1.5">
  <thead>
    <tr>
      <th className="w-fit"><strong>Parameter</strong></th>
      <th className="w-fit"><strong>Description</strong></th>
      <th className="w-fit"><strong>Limitations</strong></th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td className="w-fit"><strong>hostname</strong></td>
      <td className="w-fit">A unique service identifier like `mariadb`,`sql`, `db` etc.</td>
      <td className="w-fit">
        <ul>
        <li>duplicate services with the same name in the same project are forbidden</li>
        <li>maximum 25 characters</li>
        <li>must contain only lowercase ASCII letters (a-z) or numbers (0-9)</li>
        </ul>
      </td>
    </tr>
    <tr>
      <td className="w-fit"><strong>type</strong></td>
      <td className="w-fit">Specifies the service type and version.</td>
      <td className="w-fit">
        See what [MariaDB service types](/references/import-yaml/type-list#database-services) are currently supported.
      </td>
    </tr>
    <tr>
      <td className="w-fit"><strong>mode</strong></td>
      <td className="w-fit">Defines the operation mode of MariaDB service.</td>
      <td className="w-fit">
        <b>HA</b>

        Zerops will create a MariaDB cluster with 3 database containers and 2
        free database proxies. This mode is suited for production.

        Zerops always keep the 3 database containers on different physical
        machines. All your data is stored redundantly in 3 copies. In case of a
        failure of a container or the underlying physical machine, Zerops
        automatically disconnects the failed container from the cluster, creates
        a new container and syncs all data from the remaining 2 copies. Finally
        the broken container is automatically deleted.

        <b>NON_HA</b>

        Zerops will create a MariaDB database installed in a single container.
        Useful for non-essential data or dev environments.

        Your data is stored only in a single container. If the container or the
        underlying physical machine fails, your data since the last backup are
        lost. Zerops doesn't provide any automatic repairs of single node
        MariaDB services.
      </td>
    </tr>
    <tr>
      <td className="w-fit"><strong>verticalAutoscaling</strong></td>
      <td className="w-fit">Defines [custom vertical auto scaling parameters](/mariadb/how-to/scaling#configure-scaling)</td>
      <td className="w-fit">
        All verticalAutoscaling attributes are optional. Not specified
        attributes will be set to their default values.
      </td>
    </tr>
    <tr>
      <td className="w-fit"><strong> - cpuMode</strong></td>
      <td className="w-fit">Accepts `SHARED`, `DEDICATED` values. Default is `SHARED`</td>
      <td className="w-fit"></td>
    </tr>
    <tr>
      <td className="w-fit"><strong> - minCpu/maxCpu</strong></td>
      <td className="w-fit">Set the minCpu or maxCpu in CPU cores (integer).</td>
      <td className="w-fit"></td>
    </tr>
    <tr>
      <td className="w-fit"><strong> - minRam/maxRam</strong></td>
      <td className="w-fit">Set the minRam or maxRam in GB (float).</td>
      <td className="w-fit"></td>
    </tr>
    <tr>
      <td className="w-fit"><strong> - minDisk/maxDisk</strong></td>
      <td className="w-fit">Set the minDisk or maxDisk in GB (float).</td>
      <td className="w-fit"></td>
    </tr>
    <tr>
      <td className="w-fit"><strong>envSecrets</strong></td>
      <td className="w-fit">Defines [secret environment variables](/features/env-variables#2-secret-variables) for the service</td>
      <td className="w-fit"></td>
    </tr>
  </tbody>
</table>

:::caution
The MariaDB service **hostname** and **mode** are fixed after the service is created. They can't be changed later.
:::

### Create a project based on the description.yaml

When you have your `description.yaml` ready, use the `zcli project project-import` command to create a new project and the service infrastructure.

```sh
Usage:
  zcli project project-import importYamlPath [flags]

Flags:
  -h, --help                Help for the project import command.
      --org-id string        If you have access to more than one organization, you must specify the org ID for which the
                            project is to be created.
      --working-dir string   Sets a custom working directory. Default working directory is the current directory. (default "./")
```

Zerops will create a project and one or more services based on the `description.yaml` content.

Maximum size of the `description.yaml` file is 100 kB.

You don't specify the project name in the `zcli project project-import` command, because the project name is defined in the `description.yaml`.

If you have access to more than one client, you must specify the client ID for which the project is to be created. The `clientID` is located in the Zerops GUI under the client name on the project dashboard page.

### Add MariaDB service to an existing project

#### Example

Create a directory `my-project` if it doesn't exist. Create an `import.yaml` file inside the `my-project` directory with following content:

```bash
# array of project services
services:
  -
    # service name
    hostname: mariadb1
    # service type and version number in mariadb@{version} format
    type: mariadb@10.4
    # mode of operation "HA"/"NON_HA"
    mode: NON_HA
    # optional: system variables configuration
    envSecrets:
      lower_case_table_names: "1"
```

The yaml file describes the list of one or more services that you want to add to your existing project. In the example above, one MariaDB 10.4 service in single container mode with default [auto scaling](/mariadb/how-to/scale) configuration will be added to your project. Hostname of the new service will be set to `mariadb1`. The `lower_case_table_names` system variable will be set to "1".

The content of the `services:` section of `import.yaml` is identical to the [project description file](#create-a-project-description-file). The `import.yaml` never contains the `project:` section because the project already exists.

When you have your `import.yaml` ready, use the `zcli project service-import` command to add one or more services to your existing Zerops project.

```sh
Usage:
  zcli project service-import importYamlPath [flags]

Flags:
  -h, --help                Help for the project service import command.
  -P, --project-id string   If you have access to more than one project, you must specify the project ID for which the
                           command is to be executed.
```

zCLI commands are interactive, when you press enter after `zcli project service-import importYamlPath`, you will be given a list of your projects to choose from.

Maximum size of the `import.yaml` file is 100 kB.

## Migrating from other database systems

### Configure system variables

When migrating to MariaDB in Zerops from other database systems, you may need to configure specific system variables to maintain compatibility with your existing applications.

#### Setting `lower_case_table_names` for MySQL compatibility

The `lower_case_table_names` system variable determines how MariaDB handles table name case sensitivity:

<table className="w-full my-1.5">
  <thead>
    <tr>
      <th className="w-fit"><strong>Value</strong></th>
      <th className="w-fit"><strong>Table Name Storage</strong></th>
      <th className="w-fit"><strong>Comparison Behavior</strong></th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td className="w-fit"><strong>0</strong></td>
      <td className="w-fit">Stored as specified (preserves case)</td>
      <td className="w-fit">Case-sensitive</td>
    </tr>
    <tr>
      <td className="w-fit"><strong>1</strong></td>
      <td className="w-fit">Stored in lowercase</td>
      <td className="w-fit">Case-insensitive</td>
    </tr>
    <tr>
      <td className="w-fit"><strong>2</strong></td>
      <td className="w-fit">Stored as specified (preserves case)</td>
      <td className="w-fit">Case-insensitive</td>
    </tr>
  </tbody>
</table>

:::caution
This variable must be configured when the MariaDB instance is first created and cannot be changed afterward. This is a limitation of MariaDB itself, not specific to Zerops.
:::

When configuring this in Zerops:

- **Using GUI**: Set the `lower_case_table_names` parameter in the advanced options section when creating a new MariaDB service
- **Using YAML**: Include it in your service configuration under the `envSecrets` section (see examples in the [Create MariaDB using zCLI](#create-mariadb-using-zcli) section)

##### Migration considerations

If you're migrating from MySQL to MariaDB and your application relies on a specific table name case handling:

1. Determine the value used in your source MySQL installation
2. Configure the same value in your Zerops MariaDB configuration before initializing the database
3. For most migrations from MySQL 5.7, setting the value to "1" is recommended for compatibility

After deploying your MariaDB service, you can verify the settings with this SQL command:

```sql
SELECT @@lower_case_file_system, @@lower_case_table_names;
```

:::important
If you need to change this setting after the database has been initialized, you'll need to create a new MariaDB service with the correct configuration and migrate your data.
:::

----------------------------------------

# Mariadb > How To > Export Import Data


## Use Adminer to export or import data

[Adminer ↗](https://www.adminer.org) is an open source full-featured database management tool written in PHP.

1. [Install Adminer to Zerops](/mariadb/how-to/manage#how-to-install-adminer-to-zerops)
2. Use Adminer standard export or import functions

## Use phpMyAdmin to export or import data

[phpMyAdmin ↗](https://www.phpmyadmin.net) is a free software tool written in PHP, intended to handle the administration of MariaDB over the Web.

1. [Install phpMyAdmin to Zerops](/mariadb/how-to/manage#how-to-install-phpmyadmin-to-zerops)
2. Use phpMyAdmin standard export or import functions

## Use a database management tool on your workstation to export or import data

Do you already use a database management tool that supports MariaDB on your workstation? Connect it securely to MariaDB from your local workspace via Zerops VPN.

Zerops VPN client is included into zCLI, the Zerops command-line tool. To start the VPN connection, read [how to connect to MariaDB remotely](/mariadb/how-to/connect#connect-to-mariadb-in-zerops-remotely).
:::caution
Do not use SSL/TLS protocols when connecting to MariaDB over VPN. Zerops MariaDB is not configured to support these protocols. The security is assured by the VPN.
:::

Once the connection to MariaDB is established, use the standard export or import functions of your favourite management tool.

## Use mysql CLI to export or import data

If you are using the [mysql ↗](https://dev.mysql.com/doc/refman/8.1/en/mysql.html) command-line client to manage your MariaDB on your local workspace, you can connect it securely to MariaDB via Zerops VPN.

Zerops VPN client is included into zCLI, the Zerops command-line tool. To start the VPN connection, read [how to connect to MariaDB remotely](/mariadb/how-to/connect#connect-to-mariadb-in-zerops-remotely).

Once the VPN session is established, you have the secured connection to the project's private network in Zerops. You can access all project services locally by using their hostname. The only difference is that no [environment variables](/mariadb/how-to/connect#use-mariadb-environment-variables) are available when connected through VPN. To connect to MariaDB in Zerops you have to copy the [access details](/mariadb/how-to/connect#connect-to-mariadb-in-zerops-remotely) manually from Zerops GUI.

Use [mysql ↗](https://dev.mysql.com/doc/refman/8.1/en/mysql.html) command to connect to MariaDB in Zerops:

```sh
mysql -h [hostname] -u [user] -p [password] [database_name]
```

:::caution
Do not use SSL/TLS protocols when connecting to MariaDB over VPN. Zerops MariaDB is not configured to support these protocols. The security is assured by the VPN.
:::

To export your database data and structure, use the [mysqldump ↗](https://dev.mysql.com/doc/refman/8.1/en/mysqldump.html) command.

```sh
mysqldump -h [hostname] -u [user] –p [password] [database_name] > dumpfilename.sql
```

To import your database data and structure, use the `mysql` command.

```sh
mysql -h [hostname] -u [user] –p [password] [database_name] < dumpfilename.sql
```


----------------------------------------

# Mariadb > How To > Manage


## Default database and user

Zerops creates a default database and a default user automatically when a new MariaDB service is [created](/mariadb/how-to/create).

#### Database

The default database name is identical to the service hostname. The default encoding is set to `utf8mb4`.

#### DB user

Default user name is identical to the service hostname. Default user password is generated randomly. You will find the password in [Zerops GUI](/mariadb/how-to/connect#copy-access-details-from-zerops-gui) or you can use the [environment variable](/mariadb/how-to/connect#use-mariadb-environment-variables).

:::info
Zerops creates a second DB user: `zps` for maintenance reasons with full privileges. Do not delete, change the password or remove privileges from this user, it will disrupt Zerops ability to maintain the database cluster.
:::

## How to install Adminer to Zerops

[Adminer ↗](https://www.adminer.org) is a open source full-featured database management tool written in PHP.

### Single-click installation

To install Adminer into your project, open your project in Zerops GUI and select **import services** in the left menu.

Copy the following yaml file into the text area and start the import:

```yaml
services:
  - # Service will be accessible through zCLI VPN under: http://adminer
    hostname: adminer
    # Type and version of service used.
    type: php-apache@8.0+2.4
    # Whether the service will be run on one or multiple containers.
    # Since this is a utility service, using a single container is fine.
    minContainers: 1
    maxContainers: 1
    # Folder name used as the root of the publicly accessible web server content.
    documentRoot: public
    # Link to Zerops repository that contains Adminer code with Zerops build and deploy instructions.
    buildFromGit: https://github.com/zeropsio/recipe-adminer@main
```

When the import is finished, Adminer will be running as a PHP service in your project.

## How to access Adminer

### Use Zerops VPN

By default Adminer service is private and is accessible from your local workstation over VPN.

You can securely connect to MariaDB from your local workspace via Zerops VPN. Zerops VPN client is included into zCLI, the Zerops command-line tool. To start a VPN connection to the selected Zerops project, follow these steps:

1. [Install & setup zCLI](/references/cli)
2. [Start the Zerops VPN](/references/networking/vpn)
3. Type `http://adminer` into your browser

:::caution
Do not use https when connecting to Adminer via VPN.
:::

### Enable public access

You can enable the public access to the Adminer service via the [Zerops subdomain].

Or you can configure the [Public routing] on the Adminer service to make it accessible on your own domain.

## How to install phpMyAdmin to Zerops

[phpMyAdmin ↗](https://www.phpmyadmin.net) is a free software tool written in PHP, intended to handle the administration of MariaDB over the Web.

### Single-click installation

To install phpMyAdmin into your project, open your project in Zerops GUI and select **import services** in the left menu.

Copy the following yaml file into the text area and start the import:

```yaml
services:
  - # Service will be accessible through zCLI VPN under: http://phpmyadmin
    hostname: phpmyadmin
    # Type and version of service used.
    type: php-apache@8.1+2.4
    # Whether the service will be run on one or multiple containers.
    # Since this is a utility service, using a single container is fine.
    minContainers: 1
    maxContainers: 1
    # Folder name used as the root of the publicly accessible web server content.
    documentRoot: public
    # Link to Zerops repository that contains Adminer code with Zerops build and deploy instructions.
    buildFromGit: https://github.com/zeropsio/recipe-phpmyadmin@main
```

When the import is finished, phpMyAdmin will be running as a PHP service in your project.

## How to access phpMyAdmin

### Use Zerops VPN

By default phpMyAdmin service is private and is accessible from your local workstation over VPN.

You can securely connect to MariaDB from your local workspace via Zerops VPN. Zerops VPN client is included into zCLI, the Zerops command-line tool. To start a VPN connection to the selected Zerops project, follow these steps:

1. [Install & setup zCLI](/references/cli)
2. [Start the Zerops VPN](/references/networking/vpn)
3. Type `http://phpmyadmin` into your browser

:::caution
Do not use https when connecting to phpMyAdmin via VPN.
:::

### Enable public access

You can enable the public access to the phpMyAdmin service via the [Zerops subdomain].

Or you can configure the [Public routing] on the phpMyAdmin service to make it accessible on your own domain.

## How to use a database management tool on your workstation

Do you already use a database management tool that supports MariaDB on your workstation? Connect it securely to MariaDB from your local workspace via Zerops VPN.

Zerops VPN client is included into zCLI, the Zerops command-line tool. To start the VPN connection, read [how to connect to MariaDB remotely](/mariadb/how-to/connect#connect-to-mariadb-in-zerops-remotely).

:::caution
Do not use SSL/TLS protocols when connecting to MariaDB over VPN. Zerops MariaDB is not configured to support these protocols. The security is assured by the VPN.
:::

## How to use mysql CLI on your workstation

If you use the [mysql ↗](https://dev.mysql.com/doc/refman/8.1/en/mysql.html) command-line client to manage your MariaDB on your local workspace, you can connect it securely to MariaDB via Zerops VPN.

Zerops VPN client is included into zCLI, the Zerops command-line tool. To start the VPN connection, read [how to connect to MariaDB remotely](/mariadb/how-to/connect#connect-to-mariadb-in-zerops-remotely).

Once the VPN session is established, you have the secured connection to the project's private network in Zerops. You can access all project services locally by using their hostname. The only difference is that no [environment variables](/mariadb/how-to/connect#connect-to-mariadb-in-zerops-remotely) are available when connected through VPN. To connect to MariaDB in Zerops you have to copy the [access details](/mariadb/how-to/connect#connect-to-mariadb-in-zerops-remotely) manually from Zerops GUI.

Use `mysql` command to connect to MariaDB in Zerops:

```sh
mysql -h [hostname] -u [user] -p [password] [database_name]
```

:::caution
Do not use SSL/TLS protocols when connecting to MariaDB over VPN. Zerops MariaDB is not configured to support these protocols. The security is assured by the VPN.
:::


----------------------------------------

# Mariadb > How To > Scale


Zerops automatically scales your MariaDB service based on actual database usage. When your database needs more power, resources increase. When demand drops, resources scale down to reduce costs.

:::tip Read More
For complete scaling details across all services, see [Automatic Scaling and High Availability](/features/scaling).
:::

## How MariaDB scaling works

MariaDB services use **vertical scaling** to adjust CPU, RAM, and disk resources within containers based on usage patterns. Unlike runtime services, MariaDB does not use horizontal scaling (adding/removing containers). Instead, MariaDB services use deployment modes for high availability.

## Configure scaling

You can configure scaling settings:

- **During service creation** - Set initial scaling parameters when [creating](/mariadb/how-to/create) your MariaDB service
- **During import** - Define scaling configuration in your YAML import file using `verticalAutoscaling` parameters
- **After service creation** - Navigate to your MariaDB service and select **Automatic scaling configuration** to modify settings

### Basic settings

**CPU Mode**: Choose between shared (cost-effective, variable performance) or dedicated (consistent performance, higher cost). You can change CPU mode once per hour. See [pricing](https://zerops.io/#pricing) for costs.

**Resource limits**: Configure minimum and maximum resources for your MariaDB service:

- **Lower the maximum** to control costs and prevent over-scaling
- **Raise the minimum** when you need guaranteed baseline performance
- **Set minimum = maximum** to disable automatic scaling for that specific resource

**Deployment mode**: Choose the reliability configuration for your MariaDB service:

- **Single Container**: One container with vertical scaling only. Suitable for development environments.
- **Highly Available**: Multiple containers with built-in redundancy. Recommended for production environments.

:::warning
Deployment mode cannot be changed after service creation.
:::

When a container fails in HA mode, Zerops automatically replaces it with a new container on a different physical machine and synchronizes data from healthy copies.

### Advanced settings

**Start CPU cores**: Determines how many CPU cores are allocated during database startup. Increase this value if your MariaDB service starts slowly or requires more processing power during initialization.

**RAM thresholds**: Help prevent out-of-memory crashes by maintaining buffer space:

- **Absolute (GB)**: Maintains this amount of free RAM at all times
- **Percentage**: Keeps this percentage of total RAM free

Consider increasing these values if your database experiences memory-related issues.

:::info Read More
For detailed technical parameters and scaling behavior, see [Automatic Scaling and High Availability](/features/scaling#resource-scaling-behavior).
:::

## Monitor usage

Navigate to your MariaDB service and select **Service containers & Overview** to view:
- CPU, RAM, and disk usage over time
- Historical scaling events
- Container health status

## Technical details

Zerops monitors database usage and automatically adjusts resources based on predefined thresholds and timing parameters. The scaling behavior follows the same principles as other services in the platform.

For complete technical specifications including:
- Resource monitoring intervals and thresholds
- Scale-up and scale-down timing parameters
- Scaling increments and steps
- Detailed scaling behavior patterns

See [Resource Scaling Behavior](/features/scaling#resource-scaling-behavior) in the general scaling documentation.

## Common issues

**Out of memory errors**
- Increase minimum free RAM settings in your scaling configuration
- Consider raising the minimum RAM allocation
- Check for memory-intensive queries or operations

**Higher than expected costs**
- Consider lowering your maximum resource limits
- Review scaling patterns in the monitoring dashboard

**Slow database startup**
- Increase the "Start CPU cores" setting
- Consider switching to dedicated CPU mode for consistent performance

*Need help? Join our [Discord community](https://discord.gg/zerops) for assistance!*

----------------------------------------

# Mariadb > Overview


[MariaDB ↗](https://mariadb.org/) is one of the most popular open source relational databases. It’s made by the original developers of MySQL and guaranteed to stay open source.

## Feature Highlights

- [Create MariaDB service](/mariadb/how-to/create) — Start with creating a MariaDB service using GUI or zCLI.
- [Import config file](/mariadb/how-to/create#full-example) — Use an example config file to import your own app.

### Connect to MariaDB service

- [Manage users and databases](/mariadb/how-to/manage)
- [Connect from the same project](/mariadb/how-to/connect#connect-to-mariadb-from-runtime-services-of-the-same-project)
- [Connect remotely](/mariadb/how-to/connect#connect-to-mariadb-in-zerops-remotely)

### Others

- [Scale MariaDB service](/mariadb/how-to/scale)
- [Export and import data](/mariadb/how-to/export-import-data)

## When in doubt, reach out

Don't know how to start or got stuck during the process? You might not be the first one, visit the FAQ section to find out.

In case you haven't found an answer (and also if you have), we and our community are looking forward to hearing from you on Discord.

Have you build something that others might find useful? Don't hesitate to share your knowledge!

- [FAQ](/mariadb/faq) — Most common questions in one place.
- [Discord](https://discord.com/invite/WDvCZ54) — Join our core team and Zerops community on Discord. Ask questions and share your tips with other members.

## Popular Guides

- [zCLI](/references/cli) — Get even more out of Zerops with the zCLI command line tool.
- [Zerops VPN](/references/networking/vpn) — Connect to your services easily with Zerops VPN.


----------------------------------------

# Mariadb > Tech Details > Cluster


The following description applies only to the [highly available mode](/features/scaling#highly-available-ha-mode) of the MariaDB service.

## Description of MariaDB cluster

MariaDB cluster in highly available mode contains 3 database containers and 2 free database proxies.

#### 1 write node + 2 read nodes

Zerops always keeps the 3 database containers on different physical machines. A MariaDB cluster node is installed in each database container. First a writer node is started followed by 2 read nodes. All your data is stored redundantly in 3 identical copies.

If the container with one of the reader nodes fails, Zerops disconnects it from the MariaDB cluster. Zerops then creates a new container with a MariaDB read node inside, connects it to the cluster and starts the synchronisation of the data to the new node. Finally the broken container is deleted.

If the container with the writer node fails, Zerops disconnects it from the MariaDB cluster and one of the read nodes is automatically promoted to the writer node. Zerops creates a new container with a MariaDB read node inside, connects it to the cluster and starts the synchronisation of the data to the new node. Finally the broken container is deleted.

#### 2 database proxies

Zerops uses [MaxScale 2.5 ↗](https://mariadb.com/kb/en/maxscale/), this database proxy is optimised specifically for MariaDB. MaxScale database proxy understands the mysql protocol. It forwards all **write requests** to the writer node and all **read requests** to read nodes.

Zerops creates 2 containers with MaxScale database proxy and connects them to the database cluster in the highly available infrastructure. Zerops always keep the 2 database proxies on different physical machines.

If a container with the database proxy fails, Zerops starts a new container automatically. Database proxy doesn't contain any data therefore the start of the new database proxy is fast.

## Synchronous vs. Asynchronous replication

#### Synchronous replication

Synchronous replication guarantees that when a change happens on the write node, it is replicated on the read nodes synchronously. Synchronous replication uses a distributed locking which proved to be very slow. The data replication from the write node to the read nodes takes some time and the write transactions must wait until the changed data is successfully replicated to all database nodes. In case one of the database nodes is overloaded, the whole cluster becomes very slow.

#### Asynchronous replication

Asynchronous replication gives no guarantees about the delay between applying changes on the write node and the propagation of changes to all read nodes. The delay is usually very short but when one of the read containers is overloaded the delay can be longer. The main benefit of the asynchronous replication is the performance. Write transaction is completed when the write node successfully commits the transaction locally and writes it to the write-ahead log that prevents the loss of data.

The downside of the asynchronous replication is no guarantee that the read nodes will always return the current data. In some cases a `SELECT` query that quickly follows the previous `COMMIT` may return old data. As mentioned above, the database proxy forwards all read requests to read nodes. When the read node processes the `SELECT` query before the replication of the previous transaction is finished, old data is returned.

Zerops uses the asynchronous replication in MariaDB cluster.

## How to deal with situations when old data is returned

#### Use explicit transactions

MariaDB cluster returns old data most often when you use the `SELECT` query right after the `COMMIT` in the same algorithm. This problem can be solved by moving the `SELECT` query into the transaction. All queries inside a `BEGIN..COMMIT` transaction are always executed against the write node.

#### Enable synchronous checks for SELECT queries

For a critical read that must have the most up-to-date data use the `wsrep_sync_wait` option:

```sh
SET SESSION wsrep_sync_wait=1;
SELECT ...;
SET SESSION wsrep_sync_wait=0;
```

When the `wsrep_sync_wait=1` option is used, the read node will synchronise data from the write node before executing the query. The read node will wait until all updates from the write node that were committed before the `SELECT` query was received and only then executes the query.


----------------------------------------

# Mariadb > Tech Details > Limitations


The following description applies only to the [highly available mode](/features/scaling#highly-available-ha-mode) of the MariaDB service.

#### InnoDB only

Only the InnoDB storage engine is supported.

#### Mandatory table primary key

All database tables should have a primary key. A multi-column primary key can also be used. `DELETE` operations are unsupported on tables without a primary key. Also, rows in tables without a primary key may appear in a different order on different nodes.

#### Limited locks support

No support for explicit locks, including `LOCK TABLES`, `FLUSH TABLES {explicit table list} WITH READ LOCK`, `GET_LOCK`, `RELEASE_LOCK`. These limitations can be overcome using transactions. Global locking operators like `FLUSH TABLES WITH READ LOCK` are supported.

#### Do not use local exports

Do not use `SELECT INTO OUTFILE` or `SELECT INTO DUMPFILE` commands. It will create a file on one of the database containers that will receive the request. Zerops doesn't support direct access into the MariaDB database containers so you won't be able to access the file. Learn more about [how to export and import MariaDB data](/mariadb/how-to/export-import-data).

[Full list of MariaDB cluster limitations ↗](https://mariadb.com/kb/en/mariadb-galera-cluster-known-limitations/)


----------------------------------------

# Meilisearch > Overview


Deploy and manage Meilisearch on a fully managed infrastructure. Get instant access to fast, typo-tolerant search with zero operational overhead.

## Supported Versions

Currently supported Meilisearch versions:

Import configuration version:

- `meilisearch@1.20`
- `meilisearch@1.10`

## Service Configuration

Our Meilisearch implementation runs as a **single-node** setup, as Meilisearch does not currently support cluster configurations.

### Environment Modes

:::note
Environment mode affects the availability of certain features and can impact your application's security. Choose carefully based on your use case.
:::

#### Production Mode (Default)
- Optimized for performance and security
- Search Preview (Mini-dashboard) disabled
- Recommended for production deployments

#### Development Mode
- Includes Search Preview (Mini-dashboard)
- Enhanced debugging capabilities
- Suitable for development and testing

To switch between modes:
1. Navigate to the **Environment variables** section in the Meilisearch service detail and scroll to the **Generated Variables**
2. Set the `environment` variable to either:
   - `production` - for production mode (default)
   - `development` - for development mode with Mini-dashboard
3. Restart the service to apply changes

### API Key Management

The service provides three pre-configured API keys, each with specific access levels:

#### `masterKey`
- Root access to your Meilisearch instance
- Use only for initial setup and key management
- **Never expose in application code or frontend**

#### `defaultSearchKey`
- Read-only search operations across all indices
- Safe for frontend implementations
- **Can be exposed in client-side code**

#### `defaultAdminKey`
- Full administrative access to all indices
- For backend operations and index management
- **Keep secure in backend services only**

[Custom API keys](https://www.meilisearch.com/docs/reference/api/keys) provide fine-grained access control for specific use cases. For example, you might create:
- Search-only keys for specific indices
- Temporary keys with expiration dates
- Keys with restricted actions for third-party integrations

## Network Architecture & Access

### Access Methods

#### Public HTTPS Access
When enabled, access via [Zerops subdomain](/references/networking/public-access#zerops-subdomain-access).

#### Internal Project Access
Services within the same project can reach Meilisearch directly:
```
http://{hostname}:7700
```

## Backup

Meilisearch backups are created using native dump commands:

- **Format**: `.dump` (standard Meilisearch dump)
- **Tooling**: Native dump command
- **Content**: Contains index data and settings

For backup configuration, scheduling, retention policies, and management options, see the [Zerops Backups](/features/backup) documentation.

### Restoring Backups

To restore a Meilisearch backup:

1. **Download** the backup file (`.dump`) from the Zerops UI
2. **Prepare** your target environment (clean existing indices or use a new instance)
3. **Restore** using the Meilisearch API. Use the dump import endpoint to restore your data. Follow the [official Meilisearch documentation](https://www.meilisearch.com/docs/learn/data_backup/dumps#importing-a-dump-in-self-hosted-instances) for detailed restore procedures.

For assistance with the restoration process, contact Zerops support.

## Quick Start Example

Here's a minimal example of implementing search in a React application:

```javascript

const MEILISEARCH_URL = process.env.zeropsSubdomain;
const SEARCH_KEY = process.env.defaultSearchKey;

function SearchComponent() {
  const [results, setResults] = useState([]);

  const handleSearch = async (query) => {
    const response = await fetch(`${MEILISEARCH_URL}/indexes/products/search`, {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${SEARCH_KEY}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        q: query,
        limit: 10
      })
    });

    const data = await response.json();
    setResults(data.hits);
  };

  return (
    <div>
      <input
        type="search"
        onChange={(e) => handleSearch(e.target.value)}
        placeholder="Search products..."
      />
      <ul>
        {results.map(hit => (
          <li key={hit.id}>{hit.name}</li>
        ))}
      </ul>
    </div>
  );
}
```

## Best Practices

#### Security
- Store sensitive keys (`masterKey`, `defaultAdminKey`) securely in backend services
- Use `defaultSearchKey` or custom keys with minimal permissions for frontend
- Rotate custom keys periodically

#### Performance
- Implement debouncing for search inputs
- Cache frequently accessed search results
- Monitor response times and adjust index settings
- Use appropriate batch sizes for bulk operations

#### Error Handling
- Implement retry logic for temporary failures
- Set appropriate timeout values for your use case
- Handle rate limiting gracefully

## Troubleshooting

### Common Issues

#### Connection Problems
- Check if your instance is in the correct environment mode
- Ensure your API keys have the necessary permissions
- Confirm your service is running and healthy in the Zerops dashboard

#### Search Performance
- Review your index settings for optimal search performance
- Monitor your instance's resource usage
- Consider implementing client-side caching for frequent searches

#### API Key Issues
- Verify you're using the correct key type for your operation (search vs. admin)
- Check key permissions match your intended operations
- Ensure keys are properly formatted in your Authorization header
- Remember that master and admin keys should never be used in frontend code

## Learn More

- [Official Meilisearch Documentation](https://www.meilisearch.com/docs) - Comprehensive guide to all Meilisearch features and capabilities
- [API Reference](https://www.meilisearch.com/docs/reference/api/overview) - Detailed API specifications and usage examples

## Support

For advanced configurations or custom requirements:
- Join our [Discord community](https://discord.gg/zeropsio)
- Contact support via [email](mailto:support@zerops.io)

----------------------------------------

# Nats > Overview


Zerops provides a fully managed [NATS](https://nats.io/) messaging system with automated scaling and zero infrastructure overhead, letting developers focus entirely on development.

## Supported Versions

Currently supported NATS version:

Import configuration version:

- `nats@2.12`
- `nats@2.10`

## Service Configuration

Our NATS implementation features optimized default settings designed for common use cases.

**Key configuration aspects** include:
- Standard protocol port `4222` for client connections
- HTTP monitoring interface `8222` for management
- Secure authentication with automatically generated credentials
- Optimized settings for performance and reliability

You can fine-tune your NATS service by adjusting **environment variables**:

### Available Configuration Options

:::note
If certain variables are not visible in your configuration, they may have been introduced after your service was created. Simply add them as [secret variables](/features/env-variables#2-secret-variables) to access the functionality.
:::

<table className="w-full my-1.5">
  <thead>
    <tr>
      <th className="w-fit">Variable</th>
      <th className="w-fit">Description</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td className="w-fit whitespace-nowrap"><code>MAX_PAYLOAD</code></td>
      <td className="w-fit">Defines the maximum allowed message size for all NATS traffic. Default: <code>8MB</code>, Maximum: <code>64MB</code>. See [NATS limits documentation](https://docs.nats.io/running-a-nats-service/configuration#limits) for details.</td>
    </tr>
    <tr>
      <td className="w-fit whitespace-nowrap"><code>JET_STREAM_ENABLED</code></td>
      <td className="w-fit">Controls whether JetStream functionality is enabled. Default: <code>1</code> (enabled), Set to <code>0</code> to disable. See [JetStream Configuration](#jetstream-configuration) section below for more details.</td>
    </tr>
  </tbody>
</table>

:::important
Configuration changes require a service **restart** to take effect. While NATS itself supports configuration hot-reload, this feature will be implemented in a future Zerops update.
:::

After restarting, check your service logs to confirm the changes were applied successfully.

### JetStream Configuration

The service includes [JetStream](https://docs.nats.io/nats-concepts/jetstream) functionality **enabled by default**, providing persistent storage capabilities for your messaging workloads:
- **Memory store**: Up to 40GB for high-performance message caching
- **File store**: Up to 250GB for persistent storage
- **Regular sync intervals**: Ensures data durability and consistency

:::note
In HA deployments, data persistence is further enhanced with 1-minute sync intervals across all nodes, ensuring robust data durability and high availability.
:::

This configuration provides a robust foundation for message persistence while balancing performance and reliability.

:::tip
Disabling JetStream can reduce resource utilization for applications that don't require message persistence.
:::

### Deployment Modes

:::warning
Deployment mode is selected during service creation and cannot be changed later.
:::

#### Non-HA Mode
- Suitable for development and testing
- Data persistence not guaranteed during node failures
- Lower resource requirements

#### HA Mode
- Creates a multi-node NATS cluster
- Configures routes between cluster nodes automatically
- Implements [NATS clustering](https://docs.nats.io/running-a-nats-service/configuration/clustering) for high availability
- Provides improved reliability compared to non-HA deployments

### Authentication Management

Authentication credentials are automatically generated and managed by the platform. The system creates a default user (`zerops`) with a secure 16-character password. You can access these credentials through:
- The service access details in the Zerops GUI
- Environment variables in your service configuration:
  - `user` - Username for authentication (default: "zerops")
  - `password` - Generated secure password
  - `connectionString` - Complete connection string in the format `nats://${dbUser}:${dbPassword}@${hostname}:${port}`

## Health Monitoring

Zerops continuously monitors your NATS service health using built-in health checks:

- **HTTP Health Check**: The system checks the `/healthz` endpoint at port 8222
- **Self-Healing**: The platform automatically recovers unhealthy nodes when issues are detected

### Health Status

You can check the health status of your NATS service:

1. Through the Zerops GUI dashboard
2. By accessing the management interface at port `8222`

## Backup and Recovery

NATS backups are created using filesystem archival:

- **Format**: `.tar.gz` (archive of queue state)
- **Tooling**: Filesystem archival
- **Content**: Captures persistent message state

For backup configuration, scheduling, retention policies, and management options, see the [Zerops Backups](/features/backup) documentation.

### Restoring Backups

To restore a NATS backup:

1. **Download** the backup file (`.tar.gz`) from the Zerops UI
2. **Extract** the archive to access the queue state data
3. **Prepare** your target environment (clear existing data if needed)
4. **Restore** using NATS CLI commands via Zerops VPN or during deployment. Follow the [official NATS documentation](https://docs.nats.io/running-a-nats-service/nats_admin/jetstream_admin/disaster_recovery) for detailed restore procedures.

For assistance with the restoration process, contact Zerops support.

## Support

For advanced configurations or custom requirements:
- Join our [Discord community](https://discord.gg/zerops)
- Contact support via [email](mailto:support@zerops.io)

----------------------------------------

# Nginx > Faq


  **Question: How do I enable SEO optimization with prerender.io?**

Zerops provides built-in prerender.io support. Simply set the `PRERENDER_TOKEN` environment variable with your prerender.io service token. See our [prerender.io documentation](/nginx/how-to/env-variables#prerenderio-support) for details.


----------------------------------------

# Nginx > How To > Build Pipeline


Zerops provides a customizable build and runtime environment for your static content.

:::tip Two Deployment Approaches
You can use the Nginx service in two ways:
- **Runtime only**: Deploy pre-built static files directly (no build phase needed)
- **Build + Runtime**: Use a frontend framework (Node.js, PHP, Python, etc.) to build your application, then serve it with Nginx

The build phase is completely optional. If you already have built files, skip the build section and configure only the [runtime](#runtime-configuration).

If you just need to deploy your static content, use the [manual deploy](/nginx/how-to/trigger-pipeline#manual-deploy-using-zerops-cli) via Zerops CLI.
:::

## Add zerops.yaml to your repository

Start by adding `zerops.yaml` file to the **root of your repository** and modify it to fit your application:

```yaml
zerops:
  # define hostname of your service
  - setup: app
    # ==== how to build your application ====
    # OPTIONAL. If you need to build your static files using a framework,
    # configure the build environment here. If you already have built files,
    # you can skip this entire section and deploy directly to the runtime.
    build:
      # REQUIRED (if using build). Set the base technology for the build environment:
      base: nodejs@latest

      # OPTIONAL. Set the operating system for the build environment.
      # os: ubuntu

      # OPTIONAL. Customize the build environment by installing additional packages
      # or tools to the base build environment.
      # prepareCommands:
      #   - sudo apt-get something
      #   - curl something else

      # OPTIONAL. Build your application
      buildCommands:
        - npm i
        - npm run build

      # REQUIRED (if using build). Select which files / folders to deploy after
      # the build has successfully finished
      deployFiles:
        - dist
        - package.json
        - node_modules

      # OPTIONAL. Which files / folders you want to cache for the next build.
      # Next builds will be faster when the cache is used.
      cache: node_modules

    # ==== how to run your application ====
    run:
      # OPTIONAL. Sets the base technology for the runtime environment:
      base: nginx@latest

      # OPTIONAL. Customize the runtime Nginx environment by installing additional
      # dependencies to the base Nginx runtime environment.
      # prepareCommands:
      #   - sudo apt-get something
      #   - curl something else

      # OPTIONAL. Run one or more commands each time a new runtime container
      # is started or restarted. These commands are triggered before
      # your Nginx application is started.
      # initCommands:
      #  - rm -rf ./cache

      # OPTIONAL. Customize the folder that will be used as the root of the publicly
      # accessible web server content. Enter the path relative to the /var/www folder.
      documentRoot: public

      # OPTIONAL. Sets the custom Nginx configuration. The file must be deployed in
      # the runtime container. Enter the path to the file relative to the /var/www folder
      siteConfigPath: site_config.tmpl
```

The top-level element is always `zerops`.

### Setup

The first element `setup` contains the **hostname** of your service. A runtime service with the same hostname must exist in Zerops.
Zerops supports the definition of multiple runtime services in a single `zerops.yaml`. This is useful when you use a monorepo. Just add multiple setup elements in your `zerops.yaml`:

```yaml
zerops:
  # definition for app service
  - setup: app
    # optional
    build: ...
    # optional
    deploy: ...
    # required
    run: ...

  # definition for api service
  - setup: api
    # optional
    build: ...
    # optional
    deploy: ...
    # required
    run: ...
```

Each service configuration contains at least the `run` section. Optional `build` and `deploy` sections can be added to further customize your process.

## Runtime configuration

### base

_OPTIONAL._ Sets the base technology for the runtime environment.
If you don't specify the `run.base` attribute, Zerops keeps the current Nginx version for your runtime.

Following options are available for Nginx builds:

- `nginx@1.22`, `nginx@latest`

```yaml
zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build:
      # REQUIRED (if using build). Sets the base technology for the build environment:
      base: nodejs@latest
      ...

    # ==== how to run your application ====
    run:
      # OPTIONAL. Sets the base technology for the runtime environment:
        base: nginx@latest
      ...
```

<p>
  The base runtime environment contains {data.alpine.default}, the
  selected major version of Nginx, [Zerops command line tool](/references/cli) and `composer`, `git` and `wget`.
</p>

:::info
You can change the base environment when you need to. Just simply modify the `zerops.yaml` in your repository.
:::

If you need to install more technologies to the runtime environment, set multiple values as a yaml array. For example:

```yaml
zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build:
      # REQUIRED (if using build). Sets the base technology for the build environment:
      base: nodejs@latest
      ...

    # ==== how to run your application ====
    run:
      # OPTIONAL. Sets the base technology for the runtime environment:
      base:
        - nginx@latest
      prepareCommands:
        - zsc add go@latest
      ...
```

See the full list of supported [run base environments](/zerops-yaml/base-list).

To customize your build environment use the `prepareCommands` attribute.

### os

_OPTIONAL._ Sets the operating system for the runtime environment.

Following options are available:

- `alpine`
- `ubuntu`

Default value is `alpine`.

We are currently using following os version:

- <span>{data.alpine.default}</span>
- <span>{data.ubuntu.default}</span>

:::caution
The os version is fixed and cannot be customized.
:::

### ports

_OPTIONAL._ Specifies one or more internal ports on which your application will listen.

:::info
If no ports are specified, Zerops adds the port TCP 80 automatically.
:::

:::caution
If you want the web server to listen on other port(s) than `:80`, you must [customize](/nginx/how-to/customize-web-server) your web server configuration as well.
:::

Projects in Zerops represent a group of one or more services. Services can be of different types (runtime services, databases, message brokers, object storage, etc.). All services of the same project share a **dedicated private network**. To connect to a service within the same project, just use the service hostname and its internal port.

For example, to connect to a Nginx static service with hostname = "app" and port = 80 from another service of the same project, simply use `app:80`. Read more about [how to access a Nginx static service](/references/networking/internal-access#basic-service-communication).

:::info
Do not use the port **:443**. All the incoming traffic is terminated on the Zerops internal balancer where the SSL certificate is installed and the request is forwarded to your Nginx static service as a **http://** on the port **:80**.
:::

Each port has following attributes:

<table className="w-full my-1.5">
  <thead>
  <tr>
    <th className="w-fit"><strong>Parameter</strong></th>
    <th className="w-fit"><strong>Description</strong></th>
  </tr>
  </thead>
  <tbody>
  <tr>
    <td className="w-fit">port</td>
    <td className="w-fit">Defines the port number. You can set any port number between <em>10</em> and <em>65435</em>. Ports outside this interval are reserved for internal Zerops systems.</td>
  </tr>
  <tr>
    <td className="w-fit">protocol</td>
    <td className="w-fit"><strong>Optional.</strong> Defines the protocol. Allowed values are <code>TCP</code> or <code>UDP</code>. Default value is <code>TCP</code>.</td>
  </tr>
  <tr>
    <td className="w-fit">httpSupport</td>
    <td className="w-fit"><strong>Optional.</strong> <code>httpSupport = true</code> is the default setting for TCP protocol. Set <code>httpSupport = false</code> if a web server isn't running on the port. Zerops uses this information for the configuration of [public access](/features/access). <code>httpSupport = true</code> is available only in combination with the TCP protocol.</td>
  </tr>
  </tbody>
</table>

### prepareCommands

_OPTIONAL._ Customizes the Nginx runtime environment by installing additional dependencies or tools to the runtime base environment.

<p>
  The base Nginx environment contains {data.alpine.default}, the selected
  major version of Nginx, [Zerops command line tool](/references/cli) and `composer`, `git` and `wget`. To install
  additional packages or tools add one or more prepare commands:
</p>

```yaml
zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build:
      ...

    # ==== how to run your application ====
    run:
      # OPTIONAL. Customise the runtime environment by installing additional packages
      # or tools to the base Nginx runtime environment.
      prepareCommands:
        - sudo apt-get something
        - curl something else
      ...
```

When the first deploy with a defined prepare attribute is triggered, Zerops will

1. create a prepare runtime container
2. optionally: [copy selected folders or files from your build container](#copy-folders-or-files-from-your-build-container)
3. run the `prepareCommands` commands in the defined order

:::note
`run.prepareCommands` run in the `/home/zerops` directory.
:::

#### Command exit code

If any command fails, it returns an exit code other than 0 and the deploy is canceled. Read the [prepare runtime log](/nginx/how-to/logs#prepare-runtime-log) to troubleshoot the error. If the command ends successfully, it returns the exit code 0 and Zerops triggers the following command. When all `prepareCommands` commands are finished, your custom runtime environment is ready for the deploy phase.

#### Cache of your custom runtime environment

Some packages or tools can take a long time to install. Therefore, Zerops caches your custom runtime environment after the installation of your custom packages or tools is completed. When the second or following deploy is triggered, Zerops will use the custom runtime cache from the previous deploy if following conditions are met:

1. Content of the [build.addToRunPrepare](#copy-folders-or-files-from-your-build-container) and `run.prepareCommands` attributes didn't change from the previous deploy
2. The custom runtime cache wasn't invalidated in the Zerops GUI.

To invalidate the Zerops runtime cache go to your service detail in Zerops GUI, choose **Service dashboard & runtime containers** from the left menu and click on the **Open pipeline detail** button. Then click on the **Clear runtime prepare cache** button.

When the prepare cache is used, Zerops doesn't create a prepare runtime container and executes the deployment of your application directly.

#### Single or separated shell instances

You can configure your prepare commands to be run in a single shell instance or multiple shell instances.

### Copy folders or files from your build container

<p>
  The prepare runtime container contains {data.alpine.default}, the
  selected major version of Nginx, [Zerops command line tool](/references/cli) and `composer`, `git` and `wget`.
</p>

The prepare runtime container does not contain your application code nor the built application. If you need to copy some folders or files from the build container to the runtime container (e.g. a configuration file) use the `addToRunPrepare` attribute in the build section of your chosen technology.

```yaml
zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build:
      ...
      addToRunPrepare: ./runtime-config.yaml

    # ==== how to run your application ====
    run:
      # OPTIONAL. Customise the runtime environment by installing additional packages
      # or tools to the base Nginx runtime environment.
      prepareCommands:
        - sudo apt-get something
        - curl something else
      ...
```

In the example above Zerops will copy the `runtime-config.yaml` file from your build container **after the build has finished** into the new **prepare runtime** container. The copied files and folders will be available in the `/home/zerops` folder in the new prepare runtime container before the prepare commands are triggered.

### initCommands

_OPTIONAL._ Defines one or more commands to be run each time a new runtime container is started or a container is restarted.

```yaml
zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build: ...

    # ==== how to run your application ====
    run:
      # OPTIONAL. Run one or more commands each time a new runtime container
      # is started or restarted. These commands are triggered before
      # your Nginx application is started.
      initCommands:
        - rm -rf ./cache
```

These commands are triggered in the runtime container before your Nginx application is started.

:::note
`run.initCommands` run in the `/var/www` directory.
:::

Use init commands to clean or initialise your application cache or similar operations.

:::caution
The init commands will delay the start of your application each time a new runtime container is started (including the horizontal [scaling](/nginx/how-to/scaling) or when a runtime container is restarted).

Do not use the init commands for customising your runtime environment. Use the [run:prepareCommands](#preparecommands) attribute instead.
:::

#### Command exit code

If any of the `initCommands` fails, it returns an exit code other than 0, but deploy is **not** canceled. After all init commands are finished, regardless of the status code, the application is started. Read the [runtime log](/nginx/how-to/logs#runtime-log) to troubleshoot the error.

#### Single or separated shell instances

You can configure your `initCommands` to be run in a single shell instance or multiple shell instances.

### documentRoot

_OPTIONAL._ Customizes the folder that will be used as the root of the publicly accessible web server content.

:::info
By default, the document root is configured to `/var/www`.
:::

Customize the folder that will be used as the root of the publicly accessible web server content. Enter the path relative to the `/var/www` folder.
E.g. `documentRoot: public` will set the web server document root to `/var/www/public`.

```yaml
zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build: ...

    # ==== how to run your application ====
    run:
      # OPTIONAL. Customise the folder that will be used as the root of the publicly
      # accessible web server content. Enter the path relative to the /var/www folder.
      documentRoot: public
```

### siteConfigPath

_OPTIONAL._ Sets the custom Nginx configuration.

:::info
If you don't set your custom configuratiin Zerops applies the [default](/nginx/how-to/customize-web-server#default-nginx-configuration) configuration.
:::

The file must be deployed in the runtime container. Enter the path to the file relative to the `/var/www` folder.
Read more about the [web server customization](/nginx/how-to/customize-web-server).

### envVariables

_OPTIONAL._ Defines the environment variables for the runtime environment.

Enter one or more env variables in following format:

```yaml
zerops:
  # define hostname of your service
  - setup: app
    # ==== how to run your application ====
    run:
      # OPTIONAL. Defines the env variables for the runtime environment:
      envVariables:
        DB_NAME: db
        DB_HOST: db
        DB_USER: db
        DB_PASS: ${db_password}
```

Read more about [environment variables](/nginx/how-to/env-variables) in Zerops.

### health check

_OPTIONAL._ Defines a health check.

`healthCheck` requires either one `httpGet` object or one `exec` object.

#### httpGet

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

Following attributes are available:

<table className="w-full my-1.5">
  <thead>
  <tr>
    <th className="w-fit whitespace-nowrap">Parameter</th>
    <th className="w-fit whitespace-nowrap">Description</th>
  </tr>
  </thead>
  <tbody>
  <tr>
    <td className="w-fit whitespace-nowrap font-semibold">port</td>
    <td>Defines the port of the HTTP GET request.
The readiness check will trigger a GET request on <code>{'http://127.0.0.1:{port}/{path}'}</code></td>
  </tr>
  <tr>
    <td className="w-fit whitespace-nowrap font-semibold">path</td>
    <td>Defines the URL path of the HTTP GET request.
The readiness check will trigger a GET request on <code>{'http://127.0.0.1:{port}/{path}'}</code></td>
  </tr>
  <tr>
    <td className="w-fit whitespace-nowrap font-semibold">host</td>
    <td><strong>Optional.</strong> The readiness check is triggered from inside of your runtime container so it always uses the localhost <code>127.0.0.1</code>. If you need to add a <code>host</code> to the request header, specify it in the <code>host</code> attribute.</td>
  </tr>
  <tr>
    <td className="w-fit whitespace-nowrap font-semibold">scheme</td>
    <td><strong>Optional.</strong> The readiness check is triggered from inside of your runtime container so no https is required.
If your application requires a https request, set <code>scheme: https</code></td>
  </tr>
  </tbody>
</table>

**Example:**

```yaml
zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build: ...

    # ==== how to run your application ====
    run:
      # OPTIONAL. Customise the folder that will be used as the root of the publicly
      # accessible web server content. Enter the path relative to the /var/www folder.
      documentRoot: public

      # OPTIONAL. Define a health check with a HTTP GET request option.
      # Configures the check on http://127.0.0.1:80/status
      healthCheck:
        httpGet:
          port: 80
          path: /status
```

#### exec

Configures the health check to run a local command.
Following attributes are available:

<table className="w-full my-1.5">
  <thead>
  <tr>
    <th className="w-fit"><strong>Parameter</strong></th>
    <th className="w-fit"><strong>Description</strong></th>
  </tr>
  </thead>
  <tbody>
  <tr>
    <td className="w-fit"><strong>command</strong></td>
    <td className="w-fit">
      Defines a local command to be run.

      The command has access to the same [environment variables](/nginx/how-to/create#set-secret-environment-variables) as your Nginx application.

      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 below.
    </td>
  </tr>
  </tbody>
</table>

**Example:**

```yaml
zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build: ...

    # ==== how to run your application ====
    run:
      # OPTIONAL. Customise the folder that will be used as the root of the publicly
      # accessible web server content. Enter the path relative to the /var/www folder.
      documentRoot: public

      # OPTIONAL. Define a health check with a shell command.
      healthCheck:
        exec:
          command: |
            touch grass
            rm -rf life
            mv /outside/user /home/user
```

## Deploy configuration

### readiness check

_OPTIONAL._ Defines a readiness check. Read more about how the [readiness check works](/nginx/how-to/deploy-process#readiness-checks) in Zerops.

`readinessCheck` requires either one `httpGet` object or one `exec` object.

#### httpGet

Configures the readiness check to request a local URL using a http GET method.

Following attributes are available:

<table className="w-full my-1.5">
  <thead>
  <tr>
    <th className="w-fit whitespace-nowrap">Parameter</th>
    <th className="w-fit whitespace-nowrap">Description</th>
  </tr>
  </thead>
  <tbody>
  <tr>
    <td className="w-fit whitespace-nowrap font-semibold">port</td>
    <td>Defines the port of the HTTP GET request.
The readiness check will trigger a GET request on <code>{'http://127.0.0.1:{port}/{path}'}</code></td>
  </tr>
  <tr>
    <td className="w-fit whitespace-nowrap font-semibold">path</td>
    <td>Defines the URL path of the HTTP GET request.
The readiness check will trigger a GET request on <code>{'http://127.0.0.1:{port}/{path}'}</code></td>
  </tr>
  <tr>
    <td className="w-fit whitespace-nowrap font-semibold">host</td>
    <td><strong>Optional.</strong> The readiness check is triggered from inside of your runtime container so it always uses the localhost <code>127.0.0.1</code>. If you need to add a <code>host</code> to the request header, specify it in the <code>host</code> attribute.</td>
  </tr>
  <tr>
    <td className="w-fit whitespace-nowrap font-semibold">scheme</td>
    <td><strong>Optional.</strong> The readiness check is triggered from inside of your runtime container so no https is required.
If your application requires a https request, set <code>scheme: https</code></td>
  </tr>
  </tbody>
</table>

**Example:**

```yaml
zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build: ...

    # ==== how to deploy your application ====
    deploy:
      # OPTIONAL. Define a readiness check with a HTTP GET request option.
      # Configures the check on http://127.0.0.1:80/status
      readinessCheck:
        httpGet:
          port: 80
          path: /status

    # ==== how to run your application ====
    run: ...
```

Read more about how the [readiness check works](/nginx/how-to/deploy-process#readiness-checks) in Zerops.

#### exec

Configures the readiness check to run a local command.
Following attributes are available:

<table className="w-full my-1.5">
  <thead>
  <tr>
    <th className="w-fit"><strong>Parameter</strong></th>
    <th className="w-fit"><strong>Description</strong></th>
  </tr>
  </thead>
  <tbody>
  <tr>
    <td className="w-fit"><strong>command</strong></td>
    <td className="w-fit">
      Defines a local command to be run.

      The command has access to the same [environment variables](/nginx/how-to/create#set-secret-environment-variables) as your Nginx application.

      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 below.
    </td>
  </tr>
  </tbody>
</table>

**Example:**

```yaml
zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build: ...

    # ==== how to deploy your application ====
    deploy:
      # OPTIONAL. Define a readiness check with a HTTP GET request option.
      # Configures the check on http://127.0.0.1:80/status
      readinessCheck:
        exec:
          command: |
            touch grass
            rm -rf life
            mv /outside/user /home/user
```

Read more about how the [readiness check works](/nginx/how-to/deploy-process#readiness-checks) in Zerops.

----------------------------------------

# Nginx > How To > Controls



----------------------------------------

# Nginx > How To > Create


The Nginx static service contains the Nginx web server optimized for your static content. Nginx static service is highly scalable and customisable to suit both development and production.

## Create Nginx static service using Zerops GUI

First, set up a project in Zerops GUI. Then go to the project dashboard page and choose **Add new service** in the left menu in the **Services** block. Then add a new Nginx static service:

[Video: /vids/services/nginx-static.webm](/vids/services/nginx-static.webm)

### Choose Nginx version

Following Nginx versions are currently supported:

:::info
You can [change](/nginx/how-to/upgrade) the major version at any time later.
:::

### Set a hostname

Enter a unique service identifier like "app","cache", "gui" etc. Duplicate services with the same name in the same project are forbidden.

#### Limitations:

- maximum 25 characters
- must contain only lowercase ASCII letters (a-z) or numbers (0-9)

:::caution
The hostname is fixed after the service is created. It can't be changed later.
:::

### Set secret environment variables

Add environment variables with sensitive data, such as password, tokens, salts, certificates etc. These will be securely saved inside Zerops and added to your runtime service upon start.

Setting the secret environment variables is optional. You can set them later in Zerops GUI.

Read more about [different types of env variables](/nginx/how-to/env-variables#service-env-variables) in Zerops.

## Create Nginx static service using zCLI

zCLI is the Zerops command-line tool. To create a new Nginx static service via the command-line, follow these steps:

1. [Install & setup zCLI](/references/cli)
2. [Create a project description file](/nginx/how-to/create#create-a-project-description-file)
3. [Create a project with a Nginx and PostgreSQL service](#full-example)

### Create a project description file

Zerops uses a yaml format to describe the project infrastructure.

#### Basic example:

Create a directory `my-project`. Create an `description.yaml` file inside the `my-project` directory with following content:

```yaml
# basic project data
project:
  # project name
  name: my-project
# array of project services
services:
  - # service name
    hostname: app
    # service type and version number in nginx@{version} format
    type: nginx@latest
    # defines the minimum number of containers for horizontal autoscaling
    minContainers: 1
    # defines the maximum number of containers for horizontal autoscaling. Max value = 6.
    maxContainers: 6
    # optional: create env variables
    envSecrets:
      S3_ACCESS_KEY_ID: 'P8cX1vVVb'
      S3_ACCESS_SECRET: 'ogFthuiLYki8XoL73opSCQ'
```

The yaml file describes your future project infrastructure. The project will contain one Nginx version 8.1 service with default [auto scaling](/nginx/how-to/scaling) configuration. Hostname will be set to "app", the internal port(s) the service listens on will be defined later in the [zerops.yaml](/nginx/how-to/build-pipeline#ports). Following secret env variables will be configured:

```env
S3_ACCESS_KEY_ID="P8cX1vVVb"
S3_ACCESS_SECRET="ogFthuiLYki8XoL73opSCQ"
```

#### Full example:

Create a directory my-project. Create an description.yaml file inside the my-project directory with following content:

```yaml
# basic project data
project:
  # project name
  name: my-project
  # optional: project description
  description: A project with a Nginx static service
  # optional: project tags
  tags:
    - DEMO
    - ZEROPS
# array of project services
services:
  - # service name
    hostname: app
    # service type and version number in nginx@{version} format
    type: nginx@latest
    # optional: vertical auto scaling customization
    verticalAutoscaling:
      cpuMode: DEDICATED
      minCpu: 2
      maxCpu: 5
      minRam: 2
      maxRam: 24
      minDisk: 6
      maxDisk: 50
      startCpuCoreCount: 3
      minFreeRamGB: 0.5
      minFreeRamPercent: 20
    # defines the minimum number of containers for horizontal autoscaling. Max value = 6.
    minContainers: 2
    # defines the maximum number of containers for horizontal autoscaling. Max value = 6.
    maxContainers: 4
    # optional: create secret env variables
    envSecrets:
      S3_ACCESS_KEY_ID: 'P8cX1vVVb'
      S3_ACCESS_SECRET: 'ogFthuiLYki8XoL73opSCQ'
```

The yaml file describes your future project infrastructure. The project will contain an Nginx static service with `app` hostname. The internal port(s) the service listens on will be defined later in the [zerops.yaml](/nginx/how-to/build-pipeline#ports). Nginx static service will run on version 1.22 with a custom vertical and horizontal scaling. Following secret env variables will be configured:

```env
S3_ACCESS_KEY_ID="P8cX1vVVb"
S3_ACCESS_SECRET="ogFthuiLYki8XoL73opSCQ"
```

#### Description of description.yaml parameters

The `project:` section is required. Only one project can be defined.

<table className="w-full my-1.5">
  <thead>
    <tr>
      <th className="w-fit"><strong>Parameter</strong></th>
      <th className="w-fit"><strong>Description</strong></th>
      <th className="w-fit"><strong>Limitations</strong></th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td className="w-fit"><strong>name</strong></td>
      <td className="w-fit">The name of the new project. Duplicates are allowed.</td>
      <td className="w-fit"></td>
    </tr>
    <tr>
      <td className="w-fit"><strong>description</strong></td>
      <td className="w-fit"><strong>Optional.</strong> Description of the new project.</td>
      <td className="w-fit">Maximum 255 characters.</td>
    </tr>
    <tr>
      <td className="w-fit"><strong>tags</strong></td>
      <td className="w-fit"><strong>Optional.</strong> One or more string tags. Tags do not have a functional meaning, they only provide better orientation in projects.</td>
      <td className="w-fit"></td>
    </tr>
  </tbody>
</table>

At least one service in `services:` section is required. You can create a project with multiple services. The example above contains an Nginx static service but you can create a `description.yaml` with your own combination of [services](/features/infrastructure).

<table className="w-full my-1.5">
  <thead>
    <tr>
      <th className="w-fit">Parameter</th>
      <th className="w-fit">Description</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td className="w-fit">
        <b>hostname</b>
      </td>
      <td className="w-fit">
        The unique service identifier.
        <ul>
        <li>duplicate services with the same name in the same project are forbidden</li>
        <li>maximum 25 characters</li>
        <li>must contain only lowercase ASCII letters (a-z) or numbers (0-9)</li>
        </ul>
      </td>
    </tr>
    <tr>
      <td className="w-fit">
        <b>type</b>
      </td>
      <td className="w-fit">
        Specifies the service type and version.

        See what [nginx service types](/references/import-yaml/type-list#runtime-services) are currently supported.
      </td>
    </tr>
    <tr>
      <td className="w-fit">
        <b>verticalAutoscaling</b>
      </td>
      <td className="w-fit">
        <b>Optional.</b> Defines [custom vertical auto scaling parameters](/nginx/how-to/create#set-auto-scaling-configuration).

        All verticalAutoscaling attributes are optional. Not specified
        attributes will be set to their default values.
      </td>
    </tr>
    <tr>
      <td className="w-fit">
        <b> - cpuMode</b>
      </td>
      <td className="w-fit">
        <b>Optional.</b> Accepts `SHARED`, `DEDICATED` values. Default is `SHARED`
      </td>
    </tr>
    <tr>
      <td className="w-fit">
        <b> - minCpu/maxCpu</b>
      </td>
      <td className="w-fit">
        <b>Optional.</b> Set the minCpu or maxCpu in CPU cores (integer).
      </td>
    </tr>
    <tr>
      <td className="w-fit">
        <b> - minRam/maxRam</b>
      </td>
      <td className="w-fit">
        <b>Optional.</b> Set the minRam or maxRam in GB (float).
      </td>
    </tr>
    <tr>
      <td className="w-fit">
        <b> - minDisk/maxDisk</b>
      </td>
      <td className="w-fit">
        <b>Optional.</b> Set the minDisk or maxDisk in GB (float).
      </td>
    </tr>
    <tr>
      <td className="w-fit">
        <b>minContainers</b>
      </td>
      <td className="w-fit">
        <b>Optional.</b> Default = 1. Defines the minimum number of containers
        for [horizontal autoscaling](/nginx/how-to/create#horizontal-auto-scaling).

        <b>Limitations:</b>

        Current maximum value = 10.
      </td>
    </tr>
    <tr>
      <td className="w-fit">
        <b>maxContainers</b>
      </td>
      <td className="w-fit">
        Defines the maximum number of containers for [horizontal autoscaling](/nginx/how-to/create#horizontal-auto-scaling).

        <b>Limitations:</b>

        Current maximum value = 10.
      </td>
    </tr>
    <tr>
      <td className="w-fit">
        <b>envSecrets</b>
      </td>
      <td className="w-fit">
        <b>Optional.</b> Defines one or more secret env variables as a key value
        map. See env variable [restrictions](/nginx/how-to/env-variables#env-variable-restrictions).
      </td>
    </tr>
  </tbody>
</table>

### Create a project based on the description.yaml

When you have your `description.yaml` ready, use the `zcli project project-import` command to create a new project and the service infrastructure.

```sh
Usage:
  zcli project project-import importYamlPath [flags]

Flags:
  -h, --help                Help for the project import command.
      --org-id string        If you have access to more than one organization, you must specify the org ID for which the
                            project is to be created.
      --working-dir string   Sets a custom working directory. Default working directory is the current directory. (default "./")
```

Zerops will create a project and one or more services based on the `description.yaml` content.

Maximum size of the `description.yaml` file is 100 kB.

You don't specify the project name in the `zcli project project-import` command, because the project name is defined in the `description.yaml`.

If you have access to more than one client, you must specify the client ID for which the project is to be created. The `clientID` is located in the Zerops GUI under the client name on the project dashboard page.

### Add Nginx static service to an existing project

#### Example:

Create a directory `my-project` if it doesn't exist. Create an `import.yaml` file inside the `my-project` directory with following content:

```yaml
# basic project data
project:
  # project name
  name: my-project
# array of project services
services:
  - # service name
    hostname: app
    # service type and version number in nginx@{version} format
    type: nginx@latest
    # defines the minimum number of containers for horizontal autoscaling
    minContainers: 1
    # defines the maximum number of containers for horizontal autoscaling. Max value = 6.
    maxContainers: 6
    # optional: create env variables
    envSecrets:
      S3_ACCESS_KEY_ID: 'P8cX1vVVb'
      S3_ACCESS_SECRET: 'ogFthuiLYki8XoL73opSCQ'
```

The yaml file describes the list of one or more services that you want to add to your existing project. In the example above, one Nginx static service version 1.22 with default [auto scaling](/nginx/how-to/scaling) configuration will be added to your project. Hostname of the new service will be set to `app`. Following secret env variables will be configured:

```env
S3_ACCESS_KEY_ID="P8cX1vVVb"
S3_ACCESS_SECRET="ogFthuiLYki8XoL73opSCQ"
```

The content of the `services:` section of `import.yaml` is identical to the project description file. The `import.yaml` never contains the `project:` section because the project already exists.

When you have your `import.yaml` ready, use the `zcli project service-import` command to add one or more services to your existing Zerops project.

```sh
Usage:
  zcli project service-import importYamlPath [flags]

Flags:
  -h, --help                Help for the project service import command.
  -P, --project-id string   If you have access to more than one project, you must specify the project ID for which the
                           command is to be executed.
```

zCLI commands are interactive, when you press enter after `zcli project service-import importYamlPath`, you will be given a list of your projects to choose from.

Maximum size of the import.yaml file is 100 kB.


----------------------------------------

# Nginx > How To > Customize Runtime


## Build Custom Runtime Images

Zerops allows you to build custom runtime images (CRI) when the default base runtime images don't meet your Nginx Static application's requirements. This is an optional phase in the [build and deploy pipeline](/features/pipeline#runtime-prepare-phase-optional).

:::important
You should not include your application code in the custom runtime image, as your built/packaged code is deployed automatically into fresh containers.
:::

## Configuration

### Default Nginx Static Runtime Environment

The default Nginx Static runtime environment contains:

- <span>{data.alpine.default}</span>
- Selected version of Nginx when the runtime service was created
- [zCLI](/references/cli)
- Git

### When You Need a Custom Runtime Image

If your Nginx Static service needs additional tools beyond the default environment (SSL management, monitoring, security tools, etc.), you'll need to build a custom runtime image.

Here are Nginx Static-specific examples of configuring custom runtime images in your `zerops.yml`:

### Basic Nginx Static Setup

For complete configuration details, see the [runtime prepare phase configuration guide](/features/pipeline#configuration).

## Process and Caching

### How Runtime Prepare Works
The runtime prepare process follows the same steps for all runtimes. See [how runtime prepare works](/features/pipeline#how-it-works) for the complete process details.

### Caching Behavior
Zerops caches custom runtime images to optimize deployment times. Learn about [custom runtime image caching](/features/pipeline#custom-runtime-image-caching) including when images are cached and reused.

### Build Management
For information about managing builds and deployments, see [managing builds and deployments](/features/pipeline#manage-builds-and-deployments).

:::warning
Shared storage mounts are not available during the runtime prepare phase.
:::

## Troubleshooting

If your `prepareCommands` fail, check the [prepare runtime log](/nginx/how-to/logs#prepare-runtime-log) for specific error messages.

----------------------------------------

# Nginx > How To > Customize Web Server


## Default Nginx configuration

The default Nginx static service has following configuration:

```
server {
    listen 80 default_server;
    listen [::]:80 default_server;

    server_name _;
    root {{.DocumentRoot}};

    location / {
        try_files $uri $uri/ /index.html;
    }

    access_log syslog:server=unix:/dev/log,facility=local1,tag=nginx,severity=info default_short;
    error_log syslog:server=unix:/dev/log,facility=local1,tag=nginx,severity=error;
}
```

The configuration contains 2 variables:

- **`{{.DocumentRoot}}`** is replaced by the [`run.documentRoot`](/nginx/how-to/build-pipeline#documentroot) attribute from the `zerops.yaml`. If the attribute is not specified, the default value `/var/www` is used.

## Customize Nginx configuration

Follow these steps to customize the Nginx configuration in Nginx static service:

1. Create a **.tmpl** file with the Nginx configuration in your repository.

2. Optionally use following variables:

- **`{{.DocumentRoot}}`** is replaced by the [`run.documentRoot`](/nginx/how-to/build-pipeline#documentroot) attribute from the `zerops.yaml`. If the attribute is not specified, the default value `/var/www` is used.

Example:

```
root {{.DocumentRoot}};
```

- **`{{.Environment.ENV_NAME}}`** is replaced by the [env variable](/nginx/how-to/env-variables) value. The env variable must be either defined in [run.envVariables](/nginx/how-to/build-pipeline#envvariables) in `zerops.yaml` or set as a [secret](/nginx/how-to/env-variables#set-secret-env-variables-in-zerops-gui) or [generated](/nginx/how-to/env-variables#generated-env-variables) env variable in Zerops GUI.

:::caution
Use the **.tmpl** file extension to make Zerops interpret the file as a template. Zerops will replace the supported variables listed above.
:::

3. Check that your Nginx configuration is consistent with Zerops requirements:

- Do not use IP addresses in the `listen` directive
- If you use other ports than `:80` in the `listen` directive, add them to the [`run.ports`](/nginx/how-to/build-pipeline#ports) in your `zerops.yaml` as well.
- Do not use the port **:443**. All the incoming `https://` traffic is terminated on the Zerops internal balancer where the SSL certificate is installed and the request is forwarded to your Nginx static service as a **http://** on the port **:80**.

4. Add the [`siteConfigPath`](/nginx/how-to/build-pipeline#siteconfigpath) to the run section of your `zerops.yaml`

```yaml
zerops:
  # define hostname of your service
  - setup: app
    # ==== how to build your application ====
    build:
      # REQUIRED. Set the base technology for the build environment:
      base: nodejs@latest

      # REQUIRED. Select which files / folders to deploy after
      # the build has successfully finished
      deployFiles:
        - vendor
        - public

    # ==== how to run your application ====
    run:
      documentRoot: public

      # OPTIONAL. Sets the custom Nginx or Apache configuration. The file must be deployed in the runtime container. Enter the path to the file relative to the /var/www folder
      siteConfigPath: site_config.tmpl
```

5. Ensure that the [`build.deployFiles`](/nginx/how-to/build-pipeline#deployfiles) contains the folder with the `siteConfigPath` or add the path to the Nginx config file to the `deployFiles` list. Zerops will deploy the file to the runtime container(s).

6. [Trigger](/nginx/how-to/trigger-pipeline) the build & deploy pipeline.

## SEO & Prerender Support

Single Page Applications and JavaScript-heavy sites render content client-side, which most crawlers can't process—they see an empty page instead of your content. This affects traditional search engines, social media platforms, and AI tools like ChatGPT, Perplexity, and Claude.

### Built-in Prerender.io Integration

The default Nginx configuration includes automatic [Prerender.io](https://prerender.io) support. When enabled, it detects crawler requests (including AI crawlers) and serves them pre-rendered HTML while your users get the full interactive experience.

### Setup

To enable prerender support:

1. Set the `PRERENDER_TOKEN` environment variable with your Prerender.io token (see [environment variables](/nginx/how-to/env-variables#prerenderio-support))
2. Optionally set `PRERENDER_HOST` if using a custom prerender server

The Nginx configuration will automatically handle the rest—no additional configuration needed.

----------------------------------------

# Nginx > How To > Deploy Process



----------------------------------------

# Nginx > How To > Env Variables


## Prerender.io Support

Zerops provides built-in prerender.io support for SEO optimization. Configure it using these environment variables:

<table className="w-fit my-1.5">
  <thead>
    <tr className="text-center rounded-lg">
      <th className="w-fit"><strong>Variable</strong></th>
      <th className="w-fit"><strong>Required</strong></th>
      <th className="w-fit"><strong>Description</strong></th>
      <th className="w-fit"><strong>Default</strong></th>
    </tr>
  </thead>
  <tbody>
    <tr className="text-center">
      <td className="w-fit">PRERENDER_TOKEN</td>
      <td className="w-fit">Yes</td>
      <td className="w-fit">Your prerender.io service token</td>
      <td className="w-fit">-</td>
    </tr>
    <tr className="text-center">
      <td className="w-fit">PRERENDER_HOST</td>
      <td className="w-fit">No</td>
      <td className="w-fit">Prerender service host</td>
      <td className="w-fit">service.prerender.io</td>
    </tr>
  </tbody>
</table>

:::tip
Set `PRERENDER_TOKEN` as a secret environment variable in Zerops GUI for security.
:::

Example in zerops.yaml:
```yaml
zerops:
  - setup: app
    run:
      envVariables:
        PRERENDER_HOST: "custom.prerender.host"
```

----------------------------------------

# Nginx > How To > Filebrowser



----------------------------------------

# Nginx > How To > Logs



----------------------------------------

# Nginx > How To > Scaling



----------------------------------------

# Nginx > How To > Shared Storage



----------------------------------------

# Nginx > How To > Trigger Pipeline



----------------------------------------

# Nginx > How To > Upgrade



----------------------------------------

# Nginx > Overview


The Nginx static service contains the [Nginx ↗](https://nginx.org/) web server optimized for your static content.

## How to start

- [Care for details?](/nginx/how-to/create) — Dive in all Zerops has to offer for your Nginx application.

## Feature Highlights

- [Create Nginx static service](/nginx/how-to/create) — Start with creating a Nginx static service using GUI or zCLI.
- [zerops.yaml](/nginx/how-to/build-pipeline#add-zeropsyaml-to-your-repository) — See a full example of zerops.yaml file to create your own app.
- [Scaling configuration](/nginx/how-to/scaling) — Set up scaling of your Nginx application so that it runs smoothly while using only necessary resources.
- [SEO Optimization](/nginx/how-to/env-variables#prerenderio-support) — Built-in prerender.io support for better SEO.

{" "}

- [Customize build environment](/nginx/how-to/create)
- [Customize runtime environment](/nginx/how-to/customize-runtime)

## When in doubt, reach out

Don't know how to start or got stuck during the process? You might not be the first one, visit the FAQ section to find out.

In case you haven't found an answer (and also if you have), we and our community are looking forward to hearing from you on Discord.

Have you build something that others might find useful? Don't hesitate to share your knowledge!

- [FAQ](/nginx/faq) — Most common questions in one place.
- [Discord](https://discord.com/invite/WDvCZ54) — Join our core team and Zerops community on Discord. Ask questions and share your tips with other members.

## Popular Guides

- [zCLI](/references/cli) — Get even more out of Zerops with the zCLI command line tool.
- [Zerops VPN](/references/networking/vpn) — Connect to your services easily with Zerops VPN.


----------------------------------------

# Nodejs > Faq


  **Question: Why is my Node.js build timing out or hanging on interactive prompts?**

If your build process seems to be hanging or timing out, check your logs for interactive prompts that are waiting for input, such as:
    ```
    ? The modules directory at "/build/source/node_modules" will be removed and reinstalled from scratch. Proceed? (Y/n) ‣ true
    ```

    Set the environment variable `CI: true` to resolve the problem. This allows the installation to proceed automatically without requiring manual confirmation.


----------------------------------------

# Nodejs > How To > Build Pipeline


Zerops provides a customizable build and runtime environment for your Node.js application.

## Add zerops.yaml to your repository

Start by adding `zerops.yaml` file to the **root of your repository** and modify it to fit your application:

```yaml
zerops:
  # define hostname of your service
  - setup: app
    # ==== how to build your application ====
    build:
      # REQUIRED. Set the base technology for the build environment:
      base: nodejs@latest

      # OPTIONAL. Set the operating system for the build environment.
      # os: ubuntu

      # OPTIONAL. Customize the build environment by installing additional packages
      # or tools to the base build environment.
      # prepareCommands:
      #   - sudo apt-get something
      #   - curl something else

      # OPTIONAL. Build your application
      buildCommands:
        - npm i
        - npm run build

      # REQUIRED. Select which files / folders to deploy after
      # the build has successfully finished
      deployFiles:
        - dist
        - package.json
        - node_modules

      # OPTIONAL. Which files / folders you want to cache for the next build.
      # Next builds will be faster when the cache is used.
      cache: node_modules

    # ==== how to run your application ====
    run:
      # OPTIONAL. Sets the base technology for the runtime environment:
      base: nodejs@latest

      # OPTIONAL. Sets the internal port(s) your app listens on:
      ports:
        # port number
        - port: 3000

      # OPTIONAL. Customize the runtime Node.js environment by installing additional
      # dependencies to the base Node.js runtime environment.
      # prepareCommands:
      #   - sudo apt-get something
      #   - curl something else

      # OPTIONAL. Run one or more commands each time a new runtime container
      # is started or restarted. These commands are triggered before
      # your Node.js application is started.
      # initCommands:
      #  - rm -rf ./cache

      # REQUIRED. Your Node.js application start command
      start: npm start
```

The top-level element is always `zerops`.

### Setup

The first element `setup` contains the **hostname** of your service. A runtime service with the same hostname must exist in Zerops.
Zerops supports the definition of multiple runtime services in a single `zerops.yaml`. This is useful when you use a monorepo. Just add multiple setup elements in your `zerops.yaml`:

```yaml
zerops:
  # definition for app service
  - setup: app
    # optional
    build: ...
    # optional
    deploy: ...
    # required
    run: ...

  # definition for api service
  - setup: api
    # optional
    build: ...
    # optional
    deploy: ...
    # required
    run: ...
```

Each service configuration contains at least the `run` section. Optional `build` and `deploy` sections can be added to further customize your process.

## Build pipeline configuration

### base

_REQUIRED._ Sets the base technology for the build environment.

Following options are available for Node.js builds:

- `nodejs@24`, `nodejs@latest`
- `nodejs@22`
- `nodejs@20`
- `nodejs@18`

```yaml
zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build:
      # REQUIRED. Sets the base technology for the build environment:
      base: nodejs@latest
      ...
```

<p>
  The base build environment contains {data.alpine.default}, the selected
  major version of Node.js, [Zerops command line tool](/references/cli), `npm`, `yarn`, `git` and `npx` tools.
</p>

:::info
You can change the base environment when you need to. Just simply modify the `zerops.yaml` in your repository.
:::

If you need to install more technologies to the build environment, set multiple values as a yaml array. For example:

```yaml
zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build:
      # REQUIRED. Sets the base technology for the build environment:
      base:
        - nodejs@latest
      prepareCommands:
        - zsc add go@latest
      ...
```

See the full list of supported [build base environments](/zerops-yaml/base-list#runtime-services).

To customize your build environment use the [prepareCommands](#preparecommands) attribute.

:::note
Modifying the base technology will invalidate your build cache. See our [Build Cache Documentation](/features/build-cache) for more details about cache invalidation.
:::

### os

_OPTIONAL._ Sets the operating system for the build environment.

Following options are available:

- `alpine`
- `ubuntu`

Default value is `alpine`.

We are currently using following os version:

- <span>{data.alpine.default}</span>
- <span>{data.ubuntu.default}</span>

:::caution
The os version is fixed and cannot be customized.
:::

:::note
Changing the OS setting will invalidate your build cache. See our [Build Cache Documentation](/features/build-cache) for details about cache behavior.
:::

### prepareCommands

_OPTIONAL._ Customizes the build environment by installing additional dependencies or tools to the base build environment.

The base build environment contains:

- <span>{data.alpine.default}</span>
- selected version of Node.js defined in the [base](#base) attribute
- [Zerops command line tool](/references/cli)
- `npm`, `yarn`, `git` and `npx` tools

To install additional packages or tools add one or more prepare commands:

```yaml
zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build:
      # REQUIRED. Set the base technology for the build environment:
      base: nodejs@latest

      # OPTIONAL. Customize the build environment by installing additional packages
      # or tools to the base build environment.
      prepareCommands:
        - sudo apt-get something
        - curl something else
      ...
```

When the first build is triggered, Zerops will

1. create a build container
2. download your application code from your repository
3. run the prepare commands in the defined order

The application code is available in `/build/source` before the prepare commands are triggered, so you can use any file from your repository in your prepare commands (e.g. a configuration file). The commands themselves run in the `/home/zerops` directory.

:::note
These commands are skipped when using cached environment. Modifying `prepareCommands` will invalidate your build cache. See our [Build Cache Documentation](/features/build-cache) for details about cache invalidation.
:::

#### Command exit code

If any command fails, it returns an exit code other than 0 and the build is canceled. Read the [build log](/nodejs/how-to/logs#build-log) to troubleshoot the error. If the command ends successfully, it returns the exit code 0 and Zerops triggers the following command. When all prepare commands are finished, your custom build environment is ready for the build phase.

#### Single or separated shell instances

You can configure your prepare commands to be run in a single shell instance or multiple shell instances. The format is identical to [build commands](#buildcommands).

### buildCommands

_OPTIONAL._ Defines build commands.

```yaml
zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build:
      # REQUIRED. Set the base technology for the build environment:
      base: nodejs@latest

      # OPTIONAL. Build your application
      buildCommands:
        - npm i
        - npm run build
      ...
```

Build commands are optional. Zerops triggers each command in the defined order in a dedicated build container, running from the `/build/source` directory.

Before the build commands are triggered the build container contains:

1. base environment defined by the [base](#base) attribute
2. optional customisation of the base environment defined in the [prepareCommands](#preparecommands) attribute
3. your application code

#### Run build commands as a single shell instance

Use following syntax to run all commands in the same environment context. For example, if one command changes the current directory, the next command continues in that directory. When one command creates an environment variable, the next command can access it.

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

#### Run build commands as a separate shell instances

When the following syntax is used, each command is triggered in a separate environment context. For example, each shell instance starts in the home directory again. When one command creates an environment variable, it won't be available for the next command.

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

#### Command exit code

If any command fails, it returns an exit code other than 0 and the build is canceled. Read the [build log](/nodejs/how-to/logs#build-log) to troubleshoot the error. If the error log doesn't contain any specific error message, try to run your build with the --verbose option.

```yaml
buildCommands:
  - npm i --verbose
  - npm run build
```

If the command ends successfully, it returns the exit code 0 and Zerops triggers the following command. When all `buildCommands` are finished, the application build is completed and ready for the deploy phase.

### deployFiles

_REQUIRED._ Selects which files or folders will be deployed after the build has successfully finished. To filter out specific files or folders, use [`.deployignore`](#deployignore) file.

```yaml
# REQUIRED. Select which files / folders to deploy after
# the build has successfully finished
deployFiles:
  - dist
  - package.json
  - node_modules
```

Determines files or folders produced by your build, which should be deployed to your runtime service containers.

The path starts from the **root directory** of your project (the location of `zerops.yaml`). You must enclose the name in quotes if the folder or the file name contains a space.

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

#### Examples

Deploys a folder, and a file from the project root directory:

```yaml
deployFiles:
  - dist
  - package.json
```

Deploys the whole content of the build container:

```yaml
deployFiles: .
```

Deploys a folder, and a file in a defined path:

```yaml
deployFiles:
  - ./path/to/file.txt
  - ./path/to/dir/
```

#### How to use a wildcard in the path

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

Deploys all folders that are located in any path that begins with `/path/to/`

```yaml
deployFiles: ./path/to/~/
```

Deploys all folders that are located in any path that begins with `/path/` and ends with `/to/`

```yaml
deployFiles: ./path/~/to/
```

:::note Example
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 will be cached for the next build.

```yaml
# OPTIONAL. Which files / folders you want to cache for the next build.
# Next builds will be faster when the cache is used.
cache: file.txt
```

The cache attribute helps optimize build times by preserving specified files between builds.

The cache attribute supports the [~ wildcard character](#how-to-use-a-wildcard-in-the-path).

Learn more about the [build cache system](/features/build-cache) in Zerops.

### envVariables

_OPTIONAL._ Defines the environment variables for the build environment.

Enter one or more env variables in following format:

```yaml
zerops:
  # define hostname of your service
  - setup: app
    # ==== how to build your application ====
    build:
      base: nodejs@latest
        …

      # OPTIONAL. Defines the env variables for the build environment:
      envVariables:
        NODE_ENV: production
        DB_NAME: db
        DB_HOST: db
        DB_USER: db
        DB_PASS: ${db_password}
```

Read more about [environment variables](/nodejs/how-to/env-variables) in Zerops.

## Runtime configuration

### base

_OPTIONAL._ Sets the base technology for the runtime environment.
If you don't specify the `run.base` attribute, Zerops keeps the current Node.js version for your runtime.

Following options are available for Node.js builds:

- `nodejs@24`, `nodejs@latest`
- `nodejs@22`
- `nodejs@20`
- `nodejs@18`

```yaml
zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build:
      # REQUIRED. Sets the base technology for the build environment:
      base: nodejs@latest
      ...

    # ==== how to run your application ====
    run:
      # OPTIONAL. Sets the base technology for the runtime environment:
        base: nodejs@latest
      ...
```

<p>
  The base runtime environment contains {data.alpine.default}, the
  selected major version of Node.js, Zerops command line tool, `npm`, `yarn`, `git` and `npx` tools.
</p>

:::info
You can change the base environment when you need to. Just simply modify the `zerops.yaml` in your repository.
:::

If you need to install more technologies to the runtime environment, set multiple values as a yaml array. For example:

```yaml
zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build:
      # REQUIRED. Sets the base technology for the build environment:
      base: nodejs@latest
      ...

    # ==== how to run your application ====
    run:
      # OPTIONAL. Sets the base technology for the runtime environment:
      base:
        - nodejs@latest
      prepareCommands:
        - zsc add go@latest
      ...
```

See the full list of supported [run base environments](/zerops-yaml/base-list).

To customize your build environment use the `prepareCommands` attribute.

### os

_OPTIONAL._ Sets the operating system for the runtime environment.

Following options are available:

- `alpine`
- `ubuntu`

Default value is `alpine`.

We are currently using following os version:

- <span>{data.alpine.default}</span>
- <span>{data.ubuntu.default}</span>

:::caution
The os version is fixed and cannot be customized.
:::

### ports

_OPTIONAL._ Specifies one or more internal ports on which your application will listen.

Projects in Zerops represent a group of one or more services. Services can be of different types (runtime services, databases, message brokers, object storage, etc.). All services of the same project share a **dedicated private network**. To connect to a service within the same project, just use the service hostname and its internal port.

For example, to connect to a Node.js service with hostname = "app" and port = 3000 from another service of the same project, simply use `app:3000`. Read more about [how to access a Node.js service](/references/networking/internal-access#basic-service-communication).

Each port has following attributes:

<table className="w-full my-1.5">
  <thead>
    <tr>
      <th className="w-fit"><strong>Parameter</strong></th>
      <th className="w-fit"><strong>Description</strong></th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td className="w-fit">port</td>
      <td className="w-fit">Defines the port number. You can set any port number between <em>10</em> and <em>65435</em>. Ports outside this interval are reserved for internal Zerops systems.</td>
    </tr>
    <tr>
      <td className="w-fit">protocol</td>
      <td className="w-fit"><strong>Optional.</strong> Defines the protocol. Allowed values are <code>TCP</code> or <code>UDP</code>. Default value is <code>TCP</code>.</td>
    </tr>
    <tr>
      <td className="w-fit">httpSupport</td>
      <td className="w-fit"><strong>Optional.</strong> <code>httpSupport = true</code> is the default setting for TCP protocol. Set <code>httpSupport = false</code> if a web server isn't running on the port. Zerops uses this information for the configuration of [public access](/features/access). <code>httpSupport = true</code> is available only in combination with the TCP protocol.</td>
    </tr>
  </tbody>
</table>

### prepareCommands

_OPTIONAL._ Customises the Node.js runtime environment by installing additional dependencies or tools to the runtime base environment.

<p>
  The base Node.js environment contains {data.alpine.current} the selected
  major version of Node.js, [Zerops command line tool](/references/cli) and `npm`, `yarn`, `git` and `npx` tools. To install
  additional packages or tools add one or more prepare commands:
</p>

```yaml
zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build:
      ...

    # ==== how to run your application ====
    run:
      # OPTIONAL. Customise the runtime environment by installing additional packages
      # or tools to the base Node.js runtime environment.
      prepareCommands:
        - sudo apt-get something
        - curl something else
      ...
```

When the first deploy with a defined prepare attribute is triggered, Zerops will

1. create a prepare runtime container
2. optionally: [copy selected folders or files from your build container](#copy-folders-or-files-from-your-build-container)
3. run the `prepareCommands` commands in the defined order

:::note
`run.prepareCommands` run in the `/home/zerops` directory.
:::

#### Command exit code

If any command fails, it returns an exit code other than 0 and the deploy is canceled. Read the [prepare runtime log](/nodejs/how-to/logs#prepare-runtime-log) to troubleshoot the error. If the command ends successfully, it returns the exit code 0 and Zerops triggers the following command. When all `prepareCommands` commands are finished, your custom runtime environment is ready for the deploy phase.

#### Cache of your custom runtime environment

Some packages or tools can take a long time to install. Therefore, Zerops caches your custom runtime environment after the installation of your custom packages or tools is completed. When the second or following deploy is triggered, Zerops will use the custom runtime cache from the previous deploy if following conditions are met:

1. Content of the [build.addToRunPrepare](#copy-folders-or-files-from-your-build-container) and `run.prepareCommands` attributes didn't change from the previous deploy
2. The custom runtime cache wasn't invalidated in the Zerops GUI.

To invalidate the Zerops runtime cache go to your service detail in Zerops GUI, choose **Service dashboard & runtime containers** from the left menu and click on the **Open pipeline detail** button. Then click on the **Clear runtime prepare cache** button.

When the custom runtime cache is used, Zerops doesn't create a prepare runtime container and executes the deployment of your application directly.

#### Single or separated shell instances

You can configure your prepare commands to be run in a single shell instance or multiple shell instances. The format is identical to [build commands](#buildcommands).

### Copy folders or files from your build container

<p>
  The prepare runtime container contains {data.alpine.current}, the
  selected major version of Node.js, [Zerops command line tool](/references/cli) and `npm`, `yarn`, `git` and `npx` tools.
</p>

The prepare runtime container does not contain your application code nor the built application. If you need to copy some folders or files from the build container to the runtime container (e.g. a configuration file) use the `addToRunPrepare` attribute in the [build section](#build-pipeline-configuration).

```yaml
zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build:
      ...
      addToRunPrepare: ./runtime-config.yaml

    # ==== how to run your application ====
    run:
      # OPTIONAL. Customise the runtime environment by installing additional packages
      # or tools to the base Node.js runtime environment.
      prepareCommands:
        - sudo apt-get something
        - curl something else
      ...
```

In the example above Zerops will copy the `runtime-config.yaml` file from your build container **after the build has finished** into the new **prepare runtime** container. The copied files and folders will be available in the `/home/zerops` folder in the new prepare runtime container before the prepare commands are triggered.

### initCommands

_OPTIONAL._ Defines one or more commands to be run each time a new runtime container is started or a container is restarted.

```yaml
zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build: ...

    # ==== how to run your application ====
    run:
      # OPTIONAL. Run one or more commands each time a new runtime container
      # is started or restarted. These commands are triggered before
      # your Node.js application is started.
      initCommands:
        - rm -rf ./cache
```

These commands are triggered in the runtime container before your Node.js application is started via the [start command](#start).

:::note
`run.initCommands` run in the `/var/www` directory.
:::

Use init commands to clean or initialise your application cache or similar operations.

:::caution
The init commands will delay the start of your application each time a new runtime container is started (including the horizontal [scaling](/nodejs/how-to/scaling) or when a runtime container is restarted).

Do not use the init commands for customising your runtime environment. Use the [run:prepareCommands](#preparecommands-1) attribute instead.
:::

#### Command exit code

If any of the `initCommands` fails, it returns an exit code other than 0, but deploy is **not** canceled. After all init commands are finished, regardless of the status code, the application is started. Read the [runtime log](/nodejs/how-to/logs#runtime-log) to troubleshoot the error.

#### Single or separated shell instances

You can configure your `initCommands` to be run in a single shell instance or multiple shell instances. The format is identical to [build commands](#buildcommands).

### envVariables

_OPTIONAL._ Defines the environment variables for the runtime environment.

Enter one or more env variables in following format:

```yaml
zerops:
  # define hostname of your service
  - setup: app
    # ==== how to run your application ====
    run:
      # OPTIONAL. Defines the env variables for the runtime environment:
      envVariables:
        NODE_ENV: production
        DB_NAME: db
        DB_HOST: db
        DB_USER: db
        DB_PASS: ${db_password}
```

Read more about [environment variables](/nodejs/how-to/env-variables) in Zerops.

### start

_REQUIRED._ Defines the start command for your Node.js application.

```yaml
zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build: ...

    # ==== how to run your application ====
    run:
      # REQUIRED. Your Node.js application start command
      start: npm start
```

We recommend starting your Node.js application using `npm start`.

### health check

_OPTIONAL._ Defines a health check.

`healthCheck` requires either one `httpGet` object or one `exec` object.

#### httpGet

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

Following attributes are available:

<table className="w-full my-1.5">
  <thead>
    <tr>
      <th className="w-fit whitespace-nowrap">Parameter</th>
      <th className="w-fit whitespace-nowrap">Description</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td className="w-fit whitespace-nowrap font-semibold">port</td>
      <td>Defines the port of the HTTP GET request.
The readiness check will trigger a GET request on <code>{'http://127.0.0.1:{port}/{path}'}</code></td>
    </tr>
    <tr>
      <td className="w-fit whitespace-nowrap font-semibold">path</td>
      <td>Defines the URL path of the HTTP GET request.
The readiness check will trigger a GET request on <code>{'http://127.0.0.1:{port}/{path}'}</code></td>
    </tr>
    <tr>
      <td className="w-fit whitespace-nowrap font-semibold">host</td>
      <td><strong>Optional.</strong> The readiness check is triggered from inside of your runtime container so it always uses the localhost <code>127.0.0.1</code>. If you need to add a <code>host</code> to the request header, specify it in the <code>host</code> attribute.</td>
    </tr>
    <tr>
      <td className="w-fit whitespace-nowrap font-semibold">scheme</td>
      <td><strong>Optional.</strong> The readiness check is triggered from inside of your runtime container so no https is required.
If your application requires a https request, set <code>scheme: https</code></td>
    </tr>
  </tbody>
</table>

**Example:**

```yaml
zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build: ...

    # ==== how to run your application ====
    run:
      # REQUIRED. Your Node.js application start command
      start: npm start

      # OPTIONAL. Define a health check with a HTTP GET request option.
      # Configures the check on http://127.0.0.1:80/status
      healthCheck:
        httpGet:
          port: 80
          path: /status
```

#### exec

Configures the health check to run a local command.
Following attributes are available:

<table className="w-full my-1.5">
  <thead>
    <tr>
      <th className="w-fit"><strong>Parameter</strong></th>
      <th className="w-fit"><strong>Description</strong></th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td className="w-fit"><strong>command</strong></td>
      <td className="w-fit">
        Defines a local command to be run.

        The command has access to the same [environment variables](/nodejs/how-to/create#set-secret-environment-variables) as your Node.js application.

        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 below.
      </td>
    </tr>
  </tbody>
</table>

**Example:**

```yaml
zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build: ...

    # ==== how to run your application ====
    run:
      # REQUIRED. Your Node.js application start command
      start: npm start

      # OPTIONAL. Define a health check with a shell command.
      healthCheck:
        exec:
          command: |
            touch grass
            rm -rf life
            mv /outside/user /home/user
```

### crontab

_OPTIONAL._ Defines cron jobs.

Setup cron jobs in the following format:

```yaml
zerops:
  # define hostname of your service
  - setup: app

    # ==== how to run your application ====
    run:
      crontab:
        # REQUIRED. Sets the command to execute:
        - command: ""
        # REQUIRED. Sets the interval time to execute:
          timing: "0 * * * *"
```

Read more about setting up [cron](/zerops-yaml/cron) in Zerops.

## Deploy configuration

### readiness check

_OPTIONAL._ Defines a readiness check. Read more about how the [readiness check works](/nodejs/how-to/deploy-process#readiness-checks) in Zerops.

`readinessCheck` requires either one `httpGet` object or one `exec` object.

#### httpGet

Configures the readiness check to request a local URL using a http GET method.

Following attributes are available:

<table className="w-full my-1.5">
  <thead>
    <tr>
      <th className="w-fit whitespace-nowrap">Parameter</th>
      <th className="w-fit whitespace-nowrap">Description</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td className="w-fit whitespace-nowrap font-semibold">port</td>
      <td>Defines the port of the HTTP GET request.
The readiness check will trigger a GET request on <code>{'http://127.0.0.1:{port}/{path}'}</code></td>
    </tr>
    <tr>
      <td className="w-fit whitespace-nowrap font-semibold">path</td>
      <td>Defines the URL path of the HTTP GET request.
The readiness check will trigger a GET request on <code>{'http://127.0.0.1:{port}/{path}'}</code></td>
    </tr>
    <tr>
      <td className="w-fit whitespace-nowrap font-semibold">host</td>
      <td><strong>Optional.</strong> The readiness check is triggered from inside of your runtime container so it always uses the localhost <code>127.0.0.1</code>. If you need to add a <code>host</code> to the request header, specify it in the <code>host</code> attribute.</td>
    </tr>
    <tr>
      <td className="w-fit whitespace-nowrap font-semibold">scheme</td>
      <td><strong>Optional.</strong> The readiness check is triggered from inside of your runtime container so no https is required.
If your application requires a https request, set <code>scheme: https</code></td>
    </tr>
  </tbody>
</table>

**Example:**

```yaml
zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build: ...

    # ==== how to deploy your application ====
    deploy:
      # OPTIONAL. Define a readiness check with a HTTP GET request option.
      # Configures the check on http://127.0.0.1:80/status
      readinessCheck:
        httpGet:
          port: 80
          path: /status

    # ==== how to run your application ====
    run: ...
```

Read more about how the [readiness check works](/nodejs/how-to/deploy-process#readiness-checks) in Zerops.

#### exec

Configures the readiness check to run a local command.
Following attributes are available:

<table className="w-full my-1.5">
  <thead>
    <tr>
      <th className="w-fit"><strong>Parameter</strong></th>
      <th className="w-fit"><strong>Description</strong></th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td className="w-fit"><strong>command</strong></td>
      <td className="w-fit">
        Defines a local command to be run.

        The command has access to the same [environment variables](/nodejs/how-to/create#set-secret-environment-variables) as your Node.js application.

        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 below.
      </td>
    </tr>
  </tbody>
</table>

**Example:**

```yaml
zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build: ...

    # ==== how to deploy your application ====
    deploy:
      # OPTIONAL. Define a readiness check with a HTTP GET request option.
      # Configures the check on http://127.0.0.1:80/status
      readinessCheck:
        exec:
          command: |
            touch grass
            rm -rf life
            mv /outside/user /home/user
```

Read more about how the [readiness check works](/nodejs/how-to/deploy-process#readiness-checks) in Zerops.


----------------------------------------

# Nodejs > How To > Build Process



----------------------------------------

# Nodejs > How To > Controls



----------------------------------------

# Nodejs > How To > Create


Zerops provides a powerful Node.js runtime service with extensive build support. The Node.js runtime is highly scalable and customizable to suit your development and production needs. With just a few clicks or commands, you can have a production-ready Node.js environment up and running in no time.

## Create a Node.js service using Zerops GUI

First, set up a project in the Zerops GUI. Then go to the project dashboard page and choose **Add new service** in the left menu under the **Services** section. From there, you can add a new Node.js service:

[Video: /vids/services/nodejs.webm](/vids/services/nodejs.webm)

### Choose a Node.js version

Zerops supports the following Node.js versions:

:::info
You can easily [upgrade](/nodejs/how-to/upgrade) the major version at any time later.
:::

### Set a hostname

Enter a unique service identifier like "app", "cache", "gui", etc. Duplicate services with the same name within the same project are not allowed.

#### Limitations:

- Maximum 25 characters
- Must contain only lowercase ASCII letters (a-z) or numbers (0-9)

:::caution
The hostname is fixed after the service is created and cannot be changed later.
:::

### Set secret environment variables

Add environment variables with sensitive data, such as passwords, tokens, salts, certificates, etc. These will be securely saved inside Zerops and added to your runtime service upon start.

Setting secret environment variables is optional. You can always set them later in the Zerops GUI.

Read more about the [different types of environment variables](/nodejs/how-to/env-variables#service-env-variables) in Zerops.

## Create a Node.js service using zCLI

zCLI is the Zerops command-line tool. To create a new Node.js service via the command line, follow these steps:

1. [Install & setup zCLI](/references/cli)
2. [Create a project description file](/nodejs/how-to/create#create-a-project-description-file)
3. [Create a project with a Node.js and PostgreSQL service](#full-example)

### Create a project description file

Zerops uses a YAML format to describe the project infrastructure.

#### Basic example:

Create a directory called `my-project`. Inside the `my-project` directory, create a `description.yaml` file with the following content:
```yaml
# basic project data
project:
  # project name
  name: my-project
# array of project services
services:
  - # service name
    hostname: app
    # service type and version number in nodejs@{version} format
    type: nodejs@latest
    # defines the minimum number of containers for horizontal autoscaling
    minContainers: 1
    # defines the maximum number of containers for horizontal autoscaling. Max value = 6.
    maxContainers: 6
    # optional: create env variables
    envSecrets:
      S3_ACCESS_KEY_ID: 'P8cX1vVVb'
      S3_ACCESS_SECRET: 'ogFthuiLYki8XoL73opSCQ'
```

The yaml file describes your future project infrastructure. The project will contain one Node.js version 20 service with default [auto scaling](/nodejs/how-to/scaling) configuration. Hostname will be set to "app", the internal port(s) the service listens on will be defined later in the [zerops.yaml](/nodejs/how-to/build-pipeline#ports). Following secret env variables will be configured:

```env
S3_ACCESS_KEY_ID="P8cX1vVVb"
S3_ACCESS_SECRET="ogFthuiLYki8XoL73opSCQ"
```

#### Full example:

Create a directory my-project. Create an description.yaml file inside the my-project directory with following content:

```yaml
# basic project data
project:
  # project name
  name: my-project
  # optional: project description
  description: A project with a Node.js and PostgreSQL database
  # optional: project tags
  tags:
    - DEMO
    - ZEROPS
# array of project services
services:
  - # service name
    hostname: app
    # service type and version number in nodejs@{version} format
    type: nodejs@latest
    # optional: vertical auto scaling customization
    verticalAutoscaling:
      cpuMode: DEDICATED
      minCpu: 2
      maxCpu: 5
      minRam: 2
      maxRam: 24
      minDisk: 6
      maxDisk: 50
      startCpuCoreCount: 3
      minFreeRamGB: 0.5
      minFreeRamPercent: 20
    # defines the minimum number of containers for horizontal autoscaling. Max value = 6.
    minContainers: 2
    # defines the maximum number of containers for horizontal autoscaling. Max value = 6.
    maxContainers: 4
    # optional: create env variables
    envSecrets:
      S3_ACCESS_KEY_ID: 'P8cX1vVVb'
      S3_ACCESS_SECRET: 'ogFthuiLYki8XoL73opSCQ'
  - # second service hostname
    hostname: db
    # service type and version number in postgresql@{version} format
    type: postgresql@12
    # mode of operation "HA"/"non_HA"
    mode: NON_HA
```

The yaml file describes your future project infrastructure. The project will contain a Node.js service and a [PostgreSQL](/postgresql/overview) service.

Node.js service with "app" hostname, the internal port(s) the service listens on will be defined later in the [zerops.yaml](/nodejs/how-to/build-pipeline#ports). Node.js service will run on version 20 with a custom vertical and horizontal scaling. Following secret env variables will be configured:

```env
S3_ACCESS_KEY_ID="P8cX1vVVb"
S3_ACCESS_SECRET="ogFthuiLYki8XoL73opSCQ"
```

The hostname of the PostgreSQL service will be set to "db". The [single container](/features/scaling#single-container-mode)(/features/scaling#deployment-modes-databases-and-shared-storage) mode will be chosen and the default auto [scaling configuration](/postgresql/how-to/scale#configure-scaling) will be set.

#### Description of description.yaml parameters

The `project:` section is required. Only one project can be defined.

<table className="w-full my-1.5">
  <thead>
    <tr>
      <th className="w-fit"><strong>Parameter</strong></th>
      <th className="w-fit"><strong>Description</strong></th>
      <th className="w-fit"><strong>Limitations</strong></th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td className="w-fit"><strong>name</strong></td>
      <td className="w-fit">The name of the new project. Duplicates are allowed.</td>
      <td className="w-fit"></td>
    </tr>
    <tr>
      <td className="w-fit"><strong>description</strong></td>
      <td className="w-fit"><strong>Optional.</strong> Description of the new project.</td>
      <td className="w-fit">Maximum 255 characters.</td>
    </tr>
    <tr>
      <td className="w-fit"><strong>tags</strong></td>
      <td className="w-fit"><strong>Optional.</strong> One or more string tags. Tags do not have a functional meaning, they only provide better orientation in projects.</td>
      <td className="w-fit"></td>
    </tr>
  </tbody>
</table>

At least one service in `services:` section is required. You can create a project with multiple services. The example above contains Node.js and PostgreSQL services but you can create a `description.yaml` with your own combination of [services](/features/infrastructure).

<table className="w-full my-1.5">
  <thead>
    <tr>
      <th className="w-fit"><strong>Parameter</strong></th>
      <th className="w-fit"><strong>Description</strong></th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td className="w-fit"><strong>hostname</strong></td>
      <td className="w-fit">
        The unique service identifier.

        The hostname of the new database will be set to the `hostname` value.

        <strong>Limitations:</strong>
        <ul>
        <li>duplicate services with the same name in the same project are forbidden</li>
        <li>maximum 25 characters</li>
        <li>must contain only lowercase ASCII letters (a-z) or numbers (0-9)</li>
        </ul>
      </td>
    </tr>
    <tr>
      <td className="w-fit"><strong>type</strong></td>
      <td className="w-fit">
        Specifies the service type and version.

        See what [Node.js service types](/references/import-yaml/type-list#runtime-services) are currently supported.
      </td>
    </tr>
    <tr>
      <td className="w-fit"><strong>verticalAutoscaling</strong></td>
      <td className="w-fit">
        <strong>Optional.</strong> Defines [custom vertical auto scaling parameters](/nodejs/how-to/create#set-auto-scaling-configuration).

        All verticalAutoscaling attributes are optional. Not specified attributes will be set to their default values.
      </td>
    </tr>
    <tr>
      <td className="w-fit"><strong>- cpuMode</strong></td>
      <td className="w-fit">
        <strong>Optional.</strong> Accepts `SHARED`, `DEDICATED` values. Default is `SHARED`
      </td>
    </tr>
    <tr>
      <td className="w-fit"><strong>- minCpu/maxCpu</strong></td>
      <td className="w-fit">
        <strong>Optional.</strong> Set the minCpu or maxCpu in CPU cores (integer).
      </td>
    </tr>
    <tr>
      <td className="w-fit"><strong>- minRam/maxRam</strong></td>
      <td className="w-fit">
        <strong>Optional.</strong> Set the minRam or maxRam in GB (float).
      </td>
    </tr>
    <tr>
      <td className="w-fit"><strong>- minDisk/maxDisk</strong></td>
      <td className="w-fit">
        <strong>Optional.</strong> Set the minDisk or maxDisk in GB (float).
      </td>
    </tr>
    <tr>
      <td className="w-fit"><strong>minContainers</strong></td>
      <td className="w-fit">
        <strong>Optional.</strong> Default = 1. Defines the minimum number of containers for [horizontal autoscaling](/nodejs/how-to/create#horizontal-auto-scaling).

        <strong>Limitations:</strong>

        Current maximum value = 10.
      </td>
    </tr>
    <tr>
      <td className="w-fit"><strong>maxContainers</strong></td>
      <td className="w-fit">
        Defines the maximum number of containers for [horizontal autoscaling](/nodejs/how-to/create#horizontal-auto-scaling).

        <strong>Limitations:</strong>

        Current maximum value = 10.
      </td>
    </tr>
    <tr>
      <td className="w-fit"><strong>envSecrets</strong></td>
      <td className="w-fit">
        <strong>Optional.</strong> Defines one or more secret env variables as a key value map. See env variable [restrictions](/nodejs/how-to/env-variables#env-variable-restrictions).
      </td>
    </tr>
  </tbody>
</table>

### Create a project based on the description.yaml

When you have your `description.yaml` ready, use the `zcli project project-import` command to create a new project and the service infrastructure.

```sh
Usage:
  zcli project project-import importYamlPath [flags]

Flags:
  -h, --help                Help for the project import command.
      --org-id string        If you have access to more than one organization, you must specify the org ID for which the
                            project is to be created.
      --working-dir string   Sets a custom working directory. Default working directory is the current directory. (default "./")
```

Zerops will create a project and one or more services based on the `description.yaml` content.

Maximum size of the `description.yaml` file is 100 kB.

You don't specify the project name in the `zcli project project-import` command, because the project name is defined in the `description.yaml`.

If you have access to more than one client, you must specify the client ID for which the project is to be created. The `clientID` is located in the Zerops GUI under the client name on the project dashboard page.

### Add Node.js service to an existing project

#### Example:

Create a directory `my-project` if it doesn't exist. Create an `import.yaml` file inside the `my-project` directory with following content:

```yaml
# basic project data
project:
  # project name
  name: my-project
# array of project services
services:
  - # service name
    hostname: app
    # service type and version number in nodejs@{version} format
    type: nodejs@latest
    # defines the minimum number of containers for horizontal autoscaling
    minContainers: 1
    # defines the maximum number of containers for horizontal autoscaling. Max value = 6.
    maxContainers: 6
    # optional: create env variables
    envSecrets:
      S3_ACCESS_KEY_ID: 'P8cX1vVVb'
      S3_ACCESS_SECRET: 'ogFthuiLYki8XoL73opSCQ'
```

The yaml file describes the list of one or more services that you want to add to your existing project. In the example above, one Node.js service version 20 with default [auto scaling](/nodejs/how-to/scaling) configuration will be added to your project. Hostname of the new service will be set to `app`. Following secret env variables will be configured:

```env
S3_ACCESS_KEY_ID="P8cX1vVVb"
S3_ACCESS_SECRET="ogFthuiLYki8XoL73opSCQ"
```

The content of the `services:` section of `import.yaml` is identical to the project description file. The `import.yaml` never contains the `project:` section because the project already exists.

When you have your `import.yaml` ready, use the `zcli project service-import` command to add one or more services to your existing Zerops project.

```sh
Usage:
  zcli project service-import importYamlPath [flags]

Flags:
  -h, --help                Help for the project service import command.
  -P, --project-id string   If you have access to more than one project, you must specify the project ID for which the
                           command is to be executed.
```

zCLI commands are interactive, when you press enter after `zcli project service-import importYamlPath`, you will be given a list of your projects to choose from.

Maximum size of the import.yaml file is 100 kB.


----------------------------------------

# Nodejs > How To > Customize Runtime



----------------------------------------

# Nodejs > How To > Deploy Process



----------------------------------------

# Nodejs > How To > Env Variables



----------------------------------------

# Nodejs > How To > Filebrowser



----------------------------------------

# Nodejs > How To > Logs



----------------------------------------

# Nodejs > How To > Scaling



----------------------------------------

# Nodejs > How To > Shared Storage



----------------------------------------

# Nodejs > How To > Trigger Pipeline



----------------------------------------

# Nodejs > How To > Upgrade



----------------------------------------

# Nodejs > Overview


[Node.js ↗](https://nodejs.org/en) is an asynchronous event-driven JavaScript runtime, which is designed to build scalable network applications.

As said, there is no need for coding yet, we have created a [Github repository ↗](https://github.com/zeropsio/recipe-nodejs), a **_recipe_**, containing the most simple Node.js web application. The repo will be used as a source from which the app will be built.

### 🚀 Feel free to deploy the recipe yourself

This is the most bare-bones example of Node.js app running in Zerops — as few libraries as possible,
  just a simple endpoint with connect, read and write to a Zerops PostgreSQL database.

  [Deploy "node-js" recipe on Zerops](https://app.zerops.io/recipe/?lf=node-js)

1. Log in/sign up to [Zerops GUI ↗](https://app.zerops.io)

2. In the **Projects** box click on **Import a project** and paste in the following YAML config ([source ↗](https://github.com/zeropsio/recipe-nodejs/blob/main/zerops-project-import.yaml)):

```yaml
project:
  name: recipe-nodejs
  tags:
    - zerops-recipe

services:
  - hostname: api
    type: nodejs@20
    enableSubdomainAccess: true
    buildFromGit: https://github.com/zeropsio/recipe-nodejs

  - hostname: db
    type: postgresql@16
    mode: NON_HA
    priority: 1
```

3. Click on **Import project** and wait until all pipelines have finished.

**That's it, your application is now up and running! :star: Let's check it works:**

1. A _subdomain_ should have been enabled and visible in the project's **IP addressed & Public Routing Overview** box. Its format should look similar to this `https://helloworld-24-8080.prg1.zerops.app`.
2. Click or the `subdomain` URL to open it in a browser and you should see

```
Hello, World!
```

:::tip
Do you have any questions? Check the step-by-step tutorial, browse the documentation and join our **[Discord](https://discord.com/invite/WDvCZ54)** community to get help from our team and other members.
:::

## How to start

It doesn't matter whether it's your first curious introduction to Zerops, you have already mastered the basics and are looking for a tiny detail or inspiration. Below, choose a section that fits your needs:

- [Care for details?](/nodejs/how-to/create) — Dive in all Zerops has to offer for your Node.js application.
- [Node.js recipes](https://github.com/zeropsio?q=nodejs&type=all&language=&sort=) — Get inspired by already existing repositories, ready to be imported to Zerops.

## Feature Highlights

- [Create Node.js service](/nodejs/how-to/create) — Start with creating a Node.js service using GUI or zCLI.
- [zerops.yaml](/nodejs/how-to/build-pipeline#add-zeropsyaml-to-your-repository) — See a full example of zerops.yaml file to create your own app.
- [Scaling configuration](/nodejs/how-to/scaling) — Set up scaling of your Node.js application so that it runs smoothly while using only necessary resources.

{" "}

- [Customize build environment](/nodejs/how-to/build-process#customize-build-environment)
- [Customize runtime environment](/nodejs/how-to/customize-runtime)

## When in doubt, reach out

Don't know how to start or got stuck during the process? You might not be the first one, visit the FAQ section to find out.

In case you haven't found an answer (and also if you have), we and our community are looking forward to hearing from you on Discord.

Have you build something that others might find useful? Don't hesitate to share your knowledge!

- [FAQ](/nodejs/faq) — Most common questions in one place.
- [Discord](https://discord.com/invite/WDvCZ54) — Join our core team and Zerops community on Discord. Ask questions and share your tips with other members.

## Popular Guides

- [zCLI](/references/cli) — Get even more out of Zerops with the zCLI command line tool.
- [Zerops VPN](/references/networking/vpn) — Connect to your services easily with Zerops VPN.


----------------------------------------

# Object Storage > How To > Access


Zerops Object storage is powered by [MinIO](https://min,io), a high-performance, S3 compatible object store. Object storage services are operated on an independent infrastructure separated from your other project services. You can access the object storage from any service hosted in Zerops or remotely over the internet.

## Object storage bucket

Zerops creates one bucket automatically for each new Object storage service.

:::note
Each Object storage service can only contain one bucket. If your application needs multiple buckets, add more Object storage services.
:::

#### Name

Bucket is created with a name based on the selected service name and a random prefix. The name of the bucket cannot be changed later.

#### Access policy

The bucket's access policy was defined when the Object storage service was created. You can [change it] later in Zerops GUI.

#### Quota

The bucket quota size was defined when the Object storage service was created. You can [change it] later in Zerops GUI.

## Copy access details from Zerops GUI

You will find the Object storage access details under the **Access details** button in the project dashboard page.

The same information is available in the service detail page under the **Access & bucket details** menu.

### Object storage access parameters

<table className="w-full my-1.5">
  <thead>
    <tr>
      <th className="w-fit whitespace-nowrap">Parameter</th>
      <th className="w-fit whitespace-nowrap">Description</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td className="w-fit whitespace-nowrap font-semibold">API URL</td>
      <td>URL of the Object storage service</td>
    </tr>
    <tr>
      <td className="w-fit whitespace-nowrap font-semibold">Bucket Name</td>
      <td>Bucket is created with a name based on the selected service name and a random prefix. The name of the bucket is fixed and cannot be changed later.</td>
    </tr>
    <tr>
      <td className="w-fit whitespace-nowrap font-semibold">Access Key ID</td>
      <td>The S3 Access Key ID</td>
    </tr>
    <tr>
      <td className="w-fit whitespace-nowrap font-semibold">Secret Key</td>
      <td>The S3 Secret Key</td>
    </tr>
  </tbody>
</table>

## Use Object storage environment variables

Zerops creates default environment variables for each Object storage service to help you with connection from any runtime services in the same project. To avoid the need to copy Object storage access parameters manually, use environment variables in your runtime service.

### Prefix the environment variable key

All services of the same project can reference environment variables from other services. To use an environment variable from one service in another service in the same project, you must prefix the environment variable key with the service name and underscore.

#### Example

To access the `bucketName` env variable of the `upload` service, use `upload_bucketName` as the env variable key. To access the `secretAccessKey` env variable of the `storage` service, use `storage_secretAccessKey` as the env variable key.

### Object storage environment variables

List of service environment variables is available in Zerops GUI. Go to an Object storage service detail and choose **Environment variables** in the left menu.

Zerops creates following environment variables when the Object storage service is created:

<table className="w-full my-1.5">
  <thead>
    <tr>
      <th className="w-fit whitespace-nowrap">Variable</th>
      <th className="w-fit whitespace-nowrap">Description</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td className="w-fit whitespace-nowrap font-semibold">apiUrl</td>
      <td>URL of the Object storage service</td>
    </tr>
    <tr>
      <td className="w-fit whitespace-nowrap font-semibold">accessKeyId</td>
      <td>The S3 Access Key ID</td>
    </tr>
    <tr>
      <td className="w-fit whitespace-nowrap font-semibold">secretAccessKey</td>
      <td>The S3 Secret Key</td>
    </tr>
    <tr>
      <td className="w-fit whitespace-nowrap font-semibold">bucketName</td>
      <td>Bucket is created with a name based on the selected service name and a random prefix. The name of the bucket is fixed and cannot be changed later.</td>
    </tr>
    <tr>
      <td className="w-fit whitespace-nowrap font-semibold">quotaGBytes</td>
      <td>The bucket quota in GB.</td>
    </tr>
    <tr>
      <td className="w-fit whitespace-nowrap font-semibold">projectId</td>
      <td>ID of the project. Generated by Zerops.</td>
    </tr>
    <tr>
      <td className="w-fit whitespace-nowrap font-semibold">serviceId</td>
      <td>ID of the Object storage service. Generated by Zerops.</td>
    </tr>
    <tr>
      <td className="w-fit whitespace-nowrap font-semibold">hostname</td>
      <td>The name of the Object storage service.</td>
    </tr>
  </tbody>
</table>


----------------------------------------

# Object Storage > How To > Controls



----------------------------------------

# Object Storage > How To > Create


Zerops provides a S3 compatible Object storage service to store your files. Zerops Object storage is powered by [MinIO](https://min.io), a high-performance, S3 compatible object store. MinIO is built for large scale AI/ML, data lake and database workloads.

## Create Object storage service using Zerops GUI

First, set up a project in Zerops GUI and add a runtime service. Then go to the project dashboard page and choose **Add new service** in the left menu in the **Services** block. Then add a new Object storage service:

[Video: /vids/services/object-storage.webm](/vids/services/object-storage.webm)

### Set a name

Enter a unique service identifier like `storage`,`s3` etc. Duplicate services with the same name in the same project are forbidden.

#### Limitations:

maximum 25 characters
must contain only lowercase ASCII letters (a-z) or numbers (0-9)

:::note
The name is fixed after the service is created. It can't be changed later.
:::

### Object storage bucket

Zerops creates one bucket automatically for each new Object storage service.

:::note
Each Object storage service can only contain one bucket. If your application needs multiple buckets, add more Object storage services.
:::

#### Name

Bucket will be created with a name based on the given service name and a random prefix. The name of the bucket cannot be changed later.

#### Access policy

Select one of the basic policy templates:

<table className="w-full my-1.5">
  <thead>
    <tr>
      <th className="w-fit"><strong>Template</strong></th>
      <th className="w-fit"><strong>Description</strong></th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td className="w-fit"><strong>Public read</strong></td>
      <td className="w-fit">
        Allows anyone:
        <ul>
          <li>to read the bucket's location `(s3:GetBucketLocation)`</li>
          <li>to list all bucket's objects `(s3:ListBucket)`</li>
          <li>to get any object of the bucket `(s3:GetObject)`</li>
        </ul>
      </td>
    </tr>
    <tr>
      <td className="w-fit"><strong>Public objects read</strong></td>
      <td className="w-fit">
        Allows anyone:
        <ul>
          <li>to read the bucket's location `(s3:GetBucketLocation)`</li>
          <li>to get any object of the bucket `(s3:GetObject)`</li>
        </ul>
      </td>
    </tr>
    <tr>
      <td className="w-fit"><strong>Public read write</strong></td>
      <td className="w-fit">
        Allows anyone:
        <ul>
          <li>to read the bucket's location `(s3:GetBucketLocation)`</li>
          <li>to list all bucket's objects `(s3:ListBucket)`</li>
          <li>to get any object of the bucket `(s3:GetObject)`</li>
          <li>to create a new object in the bucket `(s3:PutObject,s3:ListMultipartUploadParts, s3:AbortMultipartUpload, s3:ListBucketMultipartUploads)`</li>
          <li>to delete any object of the bucket `(s3:DeleteObject)`</li>
        </ul>
      </td>
    </tr>
    <tr>
      <td className="w-fit"><strong>Public write</strong></td>
      <td className="w-fit">Allows anyone to create objects in the bucket `(PutObject action)`</td>
    </tr>
    <tr>
      <td className="w-fit"><strong>Private</strong></td>
      <td className="w-fit">Denies the access to unauthenticated users.</td>
    </tr>
  </tbody>
</table>

Or you can set your own access policy in the [IAM Policy JSON format](https://min.io/docs/minio/linux/administration/identity-access-management/policy-based-access-control.html#policy-document-structure).

#### Example:

```yaml
{
  'Version': '2012-10-17',
  'Statement':
    [
      {
        'Effect': 'Allow',
        'Principal': { 'AWS': ['*'] },
        'Action': ['s3:GetBucketLocation', 's3:ListBucket'],
        'Resource': ['arn:aws:s3:::{{.BucketName}}'],
      },
      {
        'Effect': 'Allow',
        'Principal': { 'AWS': ['*'] },
        'Action': ['s3:GetObject'],
        'Resource': ['arn:aws:s3:::{{.BucketName}}/*'],
      },
    ],
}
```

:::tip
The `{{ .BucketName }}` variable will be replaced by the bucket name.
:::

The bucket's policy can be changed later in Zerops GUI.

#### Quota

Set the bucket quota size in GB. The quota must be set manually. It can be changed later in Zerops GUI. Zerops doesn't support Object storage autoscaling. You can set the bucket quota from 1 to 100 GB.

## Create Object storage using zCLI

zCLI is the Zerops command-line tool. To create a new Object storage service via the command-line, follow these steps:

1. [Install & setup zCLI](/references/cli)
2. [Create a project description file](#create-a-project-description-file)
3. Create a project and an Object storage service

### Create a project description file

Zerops uses a yaml format file to describe the project infrastructure.

#### Example

Create a directory `my-project`. Create a `description.yaml` file inside the directory with the following content:

```yaml
# basic project data
project:
  # project name
  name: my-project

  # optional: project description
  description: A project with an Object storage

  # optional: project tags
  tags:
    - DEMO
    - ZEROPS

# array of project services
services:
  - # service name
    hostname: upload

    # service type
    type: objectstorage

    # Object storage size in GB
    objectStorageSize: 73

    # Choose object storage policy from a predefined list
    objectStoragePolicy: public-write

    # Or define a custom policy
    objectStorageRawPolicy:
```

The yaml file describes your future project infrastructure. The project will contain one Object storage service named `upload`. The bucket quota will be set to 73 GB and the bucket access policy will be set to `public-write`.

#### Description of description.yaml parameters

The `project:` section is required. Only one project can be defined.

<table className="w-full my-1.5">
  <thead>
    <tr>
      <th className="w-fit"><strong>Parameter</strong></th>
      <th className="w-fit"><strong>Description</strong></th>
      <th className="w-fit"><strong>Limitations</strong></th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td className="w-fit"><strong>name</strong></td>
      <td className="w-fit">The name of the new project. Duplicates are allowed.</td>
      <td className="w-fit">Maximum 255 characters</td>
    </tr>
    <tr>
      <td className="w-fit"><strong>description</strong></td>
      <td className="w-fit"><strong>Optional.</strong> Description of the new project.</td>
      <td className="w-fit"></td>
    </tr>
    <tr>
      <td className="w-fit"><strong>tags</strong></td>
      <td className="w-fit"><strong>Optional.</strong> One or more string tags. Tags do not have a functional meaning, they only provide better orientation in projects.</td>
      <td className="w-fit"></td>
    </tr>
  </tbody>
</table>

At least one service in `services:` section is required. You can create a project with multiple services. The example above contains only Object storage service but you can create a description.yaml with different types of services.

<table className="w-full my-1.5">
  <thead>
    <tr>
      <th className="w-fit"><strong>Parameter</strong></th>
      <th className="w-fit"><strong>Description</strong></th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td className="w-fit"><strong>hostname</strong></td>
      <td className="w-fit">
        The unique service identifier.

        <strong>Limitations:</strong>
        <ul>
        <li>duplicate services with the same name in the same project are forbidden</li>
        <li>maximum 25 characters</li>
        <li>must contain only lowercase ASCII letters (a-z) or numbers (0-9)</li>
        </ul>
      </td>
    </tr>
    <tr>
      <td className="w-fit"><strong>type</strong></td>
      <td className="w-fit">
        Specifies the Object storage type objectstorage and version.

        Set type: `objectstorage`

        <strong>Limitations:</strong>

        Currently `objectstorage` or `object-storage` is available.
      </td>
    </tr>
    <tr>
      <td className="w-fit"><strong>objectStorageSize</strong></td>
      <td className="w-fit">
        The size of the bucket quota in GB.

        <strong>Limitations:</strong>

        Set a whole number between 1 and 100.
      </td>
    </tr>
    <tr>
      <td className="w-fit"><strong>objectStoragePolicy</strong></td>
      <td className="w-fit">
        <strong>Optional.</strong> Either `objectStoragePolicy` or `objectStorageRawPolicy` is required.

        Set one of allowed values:
        <ul>
          <li>`public-read`</li>
          <li>`public-objects-read`</li>
          <li>`public-read-write`</li>
          <li>`public-write`</li>
          <li>`private`</li>
        </ul>
        Read more about [the basic policy templates](#access-policy).
      </td>
    </tr>
    <tr>
      <td className="w-fit"><strong>objectStorageRawPolicy</strong></td>
      <td className="w-fit">
        <strong>Optional.</strong> Either `objectStoragePolicy` or `objectStorageRawPolicy` is required.

        Set your own access policy in the [IAM Policy JSON format](https://min.io/docs/minio/linux/administration/identity-access-management/policy-based-access-control.html#policy-document-structure).

        The `{{ .BucketName }}` variable will be replaced by the bucket name.
      </td>
    </tr>
  </tbody>
</table>

Zerops creates one bucket automatically for each new Object storage service.

:::note
Each Object storage service can only contain one bucket. If your application needs multiple buckets, add more Object storage services.
:::

Bucket will be created with a name based on the given service name and a random prefix. The name of the bucket cannot be changed later.

### Create a project based on the description.yaml

When you have your `description.yaml` ready, use the `zcli project project-import` command to create a new project and the service infrastructure.

```sh
Usage:
  zcli project project-import importYamlPath [flags]

Flags:
  -h, --help                Help for the project import command.
      --org-id string        If you have access to more than one organization, you must specify the org ID for which the
                            project is to be created.
      --working-dir string   Sets a custom working directory. Default working directory is the current directory. (default "./")
```

Zerops will create a project and one or more services based on the `description.yaml` content.

Maximum size of the `description.yaml` file is 100 kB.

You don't specify the project name in the `zcli project project-import` command, because the project name is defined in the `description.yaml`.

If you have access to more than one client, you must specify the client ID for which the project is to be created. The `clientID` is located in the Zerops GUI under the client name on the project dashboard page.

### Add Object service to an existing project

Create a directory `my-project` if it doesn't exist. Create an `import.yaml` file inside the `my-project` directory with following content:

```yaml
# array of project services
services:
  - # service name
    hostname: upload

    # service type
    type: objectstorage

    # Object storage size in GB
    objectStorageSize: 73

    # Choose object storage policy from a predefined list
    objectStoragePolicy: public-write

    # Or define a custom policy
    objectStorageRawPolicy:
```

The yaml file describes the list of one or more services that you want to add to your existing project. In the example above, one Object storage service named upload will be created. The bucket quota will be set to 73 GB and the bucket access policy will be set to `public-write`.

The content of the `services:` section of `import.yaml` is identical to the [project description file]. The `import.yaml` never contains the `project:` section because the project already exists.

When you have your `import.yaml` ready, use the `zcli project service-import` command to add one or more services to your existing Zerops project.

```sh
Usage:
  zcli project service-import importYamlPath [flags]

Flags:
  -h, --help                Help for the project service import command.
  -P, --project-id string   If you have access to more than one project, you must specify the project ID for which the
                           command is to be executed.
```

zCLI commands are interactive, when you press enter after `zcli project service-import importYamlPath`, you will be given a list of your projects to choose from.

Maximum size of the `import.yaml` file is 100 kB.

#### Example

Create a directory `my-project` if it doesn't exist. Create an `import.yaml` file inside the `my-project` directory with following content:

```bash
# array of project services
services:
  -
    # service name
    hostname: storage
    # service type
    type: objectstorage
```

The yaml file describes the list of one or more services that you want to add to your existing project. In the example above, one Object storage service in the single container mode with default auto scaling configuration will be added to your project. Hostname of the new service will be set to `storage`.

The content of the `services:` section of `import.yaml` is identical to the [project description file](#create-a-project-description-file). The `import.yaml` never contains the `project:` section because the project already exists.


----------------------------------------

# Object Storage > How To > Curl File


This guide explains how to download a single file from a private Object Storage bucket using cURL and a bash script with Zerops object storage.

## Prerequisites

- Access to Zerops Object Storage
- Storage credentials (`ACCESS_KEY_ID` and `SECRET_ACCESS_KEY`)
- Bash environment
- OpenSSL and cURL installed

:::caution
Store your storage credentials securely and never commit them to version control.
:::

## Script

Save this script as `download-storage.sh`:

```bash
#!/bin/bash

server="${3:-storage-prg1.zerops.io}"
file_path=$2
bucket=$1
set -eu pipefail

contentType="application/octet-stream"
dateValue=`date -R`
signature_string="GET\n\n${contentType}\n${dateValue}\n/${bucket}/${file_path}"

signature_hash=`echo -en ${signature_string} | openssl sha1 -hmac ${SECRET_ACCESS_KEY} -binary | base64`

curl -sSo ${file_path} \
  -H "Date: ${dateValue}" \
  -H "Content-Type: ${contentType}" \
  -H "Authorization: AWS ${ACCESS_KEY_ID}:${signature_hash}" \
  "https://${server}/${bucket}/${file_path}"

```

## Usage

1. Make the script executable:
```bash
chmod +x download-storage.sh
```

2. Set your storage credentials as environment variables:
```bash
export ACCESS_KEY_ID=your-access-key
export SECRET_ACCESS_KEY=your-secret-key
```

3. Run the script:
```bash
./download-storage.sh my-bucket file.pdf
```

## Troubleshooting

- **Permission Denied**: Check your `ACCESS_KEY_ID` and `SECRET_ACCESS_KEY`
- **File Not Found**: Verify bucket name and file path
- **Script Error**: Ensure the script has execute permissions

----------------------------------------

# Object Storage > How To > Update Bucket


Zerops creates one bucket automatically for each new Object storage service.

:::note
Each Object storage service can only contain one bucket. If your application needs multiple buckets, add more Object storage services.
:::

To change the bucket size or the access policy, go to the **Access & bucket details** in the Object service detail in Zerops GUI, scroll down and click on the **Configure bucket quota size and access policy** button.

### Quota

Set the bucket quota size in GB. The quota must be set manually. It can be changed later in Zerops GUI. Zerops doesn't support Object storage autoscaling. You can set the bucket quota from 1 to 100 GB.

### Access policy

Zerops creates one bucket automatically for each new Object storage service.

:::note
Each Object storage service can only contain one bucket. If your application needs multiple buckets, add more Object storage services.
:::

#### Name

Bucket will be created with a name based on the given service name and a random prefix. The name of the bucket cannot be changed later.

#### Access policy

Select one of the basic policy templates:

| Template                   | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| <b>Public read</b>         | Allows anyone:<ul><li>to read the bucket's location `(s3:GetBucketLocation)`</li><li>to list all bucket's objects `(s3:ListBucket)`</li><li>to get any object of the bucket `(s3:GetObject)`</li></ul>                                                                                                                                                                                                                                        |
| <b>Public objects read</b> | Allows anyone:<ul><li>to read the bucket's location `(s3:GetBucketLocation)`</li><li>to get any object of the bucket `(s3:GetObject)`</li></ul>                                                                                                                                                                                                                                                                                                          |
| <b>Public read write</b>   | Allows anyone:<ul><li>to read the bucket's location `(s3:GetBucketLocation)`</li><li>to list all bucket's objects `(s3:ListBucket)`</li><li>to get any object of the bucket `(s3:GetObject)`</li><li>to create a new object in the bucket `(s3:PutObject,s3:ListMultipartUploadParts, s3:AbortMultipartUpload, s3:ListBucketMultipartUploads)`</li><li>to delete any object of the bucket `(s3:DeleteObject)`</li></ul> |
| <b>Public write</b>        | Allows anyone to create objects in the bucket `(PutObject action)`                                                                                                                                                                                                                                                                                                                                                                                                  |
| <b>Private</b>             | Denies the access to unauthenticated users.                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| <b>Private</b>             | Denies the access to unauthenticated users.                                                                                                                                                                                                                                                                                                                                                                                                                                    |

Or you can set your own access policy in the [IAM Policy JSON format](https://min.io/docs/minio/linux/administration/identity-access-management/policy-based-access-control.html#policy-document-structure).

#### Example:

```yaml
{
  'Version': '2012-10-17',
  'Statement':
    [
      {
        'Effect': 'Allow',
        'Principal': { 'AWS': ['*'] },
        'Action': ['s3:GetBucketLocation', 's3:ListBucket'],
        'Resource': ['arn:aws:s3:::{{.BucketName}}'],
      },
      {
        'Effect': 'Allow',
        'Principal': { 'AWS': ['*'] },
        'Action': ['s3:GetObject'],
        'Resource': ['arn:aws:s3:::{{.BucketName}}/*'],
      },
    ],
}
```

:::tip
The `{{ .BucketName }}` variable will be replaced by the bucket name.
:::


----------------------------------------

# Object Storage > Overview


Zerops Object storage is powered by [MinIO ↗](https://min.io/), a high-performance, open-source S3 compatible object store. MinIO is built for large scale AI/ML, data lake and database workloads.

## Feature Highlights

- [Create Object Storage](/object-storage/how-to/create) — Create your first storage bucket with our step-by-step guide.
- [Customize Object Storage buckets](/object-storage/how-to/update-bucket) — Configure Object Storage to meet your application needs.
- [Access Object storage](/object-storage/how-to/access#copy-access-details-from-zerops-gui) — Simplify configuration with environment variables.

## Popular Guides

- [zCLI](/references/cli) — Get even more out of Zerops with the zCLI command line tool.
- [Zerops VPN](/references/networking/vpn) — Connect to your services easily with Zerops VPN.

## When in doubt, reach out

Don't know how to start or got stuck during the process? You might not be the first one, visit the FAQ section to find out.

In case you haven't found an answer (and also if you have), we and our community are looking forward to hearing from you on Discord.

Have you build something that others might find useful? Don't hesitate to share your knowledge!

- [FAQ](/nodejs/faq) — Most common questions in one place.
- [Discord](https://discord.com/invite/WDvCZ54) — Join our core team and Zerops community on Discord. Ask questions and share your tips with other members.


----------------------------------------

# Php > How To > Build Pipeline


Zerops provides a customizable build and runtime environment for your PHP application.

## Add zerops.yaml to your repository

Start by adding `zerops.yaml` file to the **root of your repository** and modify it to fit your application:

```yaml
zerops:
  # define hostname of your service
  - setup: app
    # ==== how to build your application ====
    build:
      # REQUIRED. Set the base technology for the build environment:
      base: php-apache@latest

      # OPTIONAL. Set the operating system for the build environment.
      # os: ubuntu

      # OPTIONAL. Customize the build environment by installing additional packages
      # or tools to the base build environment.
      # prepareCommands:
      #   - sudo apt-get something
      #   - curl something else

      # OPTIONAL. Build your application
      buildCommands:
        - composer install

      # REQUIRED. Select which files / folders to deploy after
      # the build has successfully finished
      deployFiles:
        - vendor
        - public

      # OPTIONAL. Which files / folders you want to cache for the next build.
      # Next builds will be faster when the cache is used.
      # cache: vendor

    # ==== how to run your application ====
    run:
      # OPTIONAL. Sets the base technology for the runtime environment:
      base: php-apache@latest

      # OPTIONAL. Customize the runtime PHP environment by installing additional
      # dependencies to the base PHP runtime environment.
      # prepareCommands:
      #   - sudo apt-get something
      #   - curl something else

      # OPTIONAL. Run one or more commands each time a new runtime container
      # is started or restarted. These commands are triggered before
      # your PHP application is started.
      # initCommands:
      #  - rm -rf ./cache

      # OPTIONAL. Customize the folder that will be used as the root of the publicly
      # accessible web server content. Enter the path relative to the /var/www folder.
      documentRoot: public

      # OPTIONAL. Sets the custom Nginx or Apache configuration. The file must be deployed in
      # the runtime container. Enter the path to the file relative to the /var/www folder
      siteConfigPath: site_config.tmpl
```

The top-level element is always `zerops`.

### Setup

The first element `setup` contains the **hostname** of your service. A runtime service with the same hostname must exist in Zerops.
Zerops supports the definition of multiple runtime services in a single `zerops.yaml`. This is useful when you use a monorepo. Just add multiple setup elements in your `zerops.yaml`:

```yaml
zerops:
  # definition for app service
  - setup: app
    # optional
    build: ...
    # optional
    deploy: ...
    # required
    run: ...

  # definition for api service
  - setup: api
    # optional
    build: ...
    # optional
    deploy: ...
    # required
    run: ...
```

Each service configuration contains at least the `run` section. Optional `build` and `deploy` sections can be added to further customize your process.

## Build pipeline configuration

### base

_REQUIRED._ Sets the base technology for the build environment.

Following options are available for PHP builds:

- `php@8.5`, `php@latest`
- `php@8.4`
- `php@8.3`
- `php@8.1`

```yaml
zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build:
      # REQUIRED. Sets the base technology for the build environment:
      base: php-apache@latest
      ...
```

<p>
  The base build environment contains {data.alpine.default}, the selected
  major version of PHP, [Zerops command line tool](/references/cli), `composer`, `git` and `wget`.
</p>

:::info
You can change the base environment when you need to. Just simply modify the `zerops.yaml` in your repository.
:::

If you need to install more technologies to the build environment, set multiple values as a yaml array. For example:

```yaml
zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build:
      # REQUIRED. Sets the base technology for the build environment:
      base:
        - php-apache@latest
      prepareCommands:
        - zsc add go@latest
      ...
```

See the full list of supported [build base environments](/zerops-yaml/base-list#runtime-services).

To customise your build environment use the [prepareCommands](#preparecommands) attribute.

:::note
Modifying the base technology will invalidate your build cache. See our [Build Cache Documentation](/features/build-cache) for more details about cache invalidation.
:::

### os

_OPTIONAL._ Sets the operating system for the build environment.

Following options are available:

- `alpine`
- `ubuntu`

Default value is `alpine`.

We are currently using following os version:

- <span>{data.alpine.default}</span>
- <span>{data.ubuntu.default}</span>

:::caution
The os version is fixed and cannot be customised.
:::

:::note
Changing the OS setting will invalidate your build cache. See our [Build Cache Documentation](/features/build-cache) for details about cache behavior.
:::

### prepareCommands

_OPTIONAL._ Customises the build environment by installing additional dependencies or tools to the base build environment.

The base build environment contains:

- <span>{data.alpine.default}</span>
- selected version of PHP defined in the [base](#base) attribute
- [Zerops command line tool](/references/cli)
- `composer`, `git` and `wget`

To install additional packages or tools add one or more prepare commands:

```yaml
zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build:
      # REQUIRED. Set the base technology for the build environment:
      base: php-apache@latest

      # OPTIONAL. Customise the build environment by installing additional packages
      # or tools to the base build environment.
      prepareCommands:
        - sudo apt-get something
        - curl something else
      ...
```

When the first build is triggered, Zerops will

1. create a build container
2. download your application code from your repository
3. run the prepare commands in the defined order

The application code is available in `/build/source` before the prepare commands are triggered, so you can use any file from your repository in your prepare commands (e.g. a configuration file). The commands themselves run in the `/home/zerops` directory.

:::note
These commands are skipped when using cached environment. Modifying `prepareCommands` will invalidate your build cache. See our [Build Cache Documentation](/features/build-cache) for details about cache invalidation.
:::

#### Command exit code

If any command fails, it returns an exit code other than 0 and the build is canceled. Read the [build log](/php/how-to/logs#build-log) to troubleshoot the error. If the command ends successfully, it returns the exit code 0 and Zerops triggers the following command. When all prepare commands are finished, your custom build environment is ready for the build phase.

#### Single or separated shell instances

You can configure your prepare commands to be run in a single shell instance or multiple shell instances. The format is identical to [build commands](#buildcommands).

### buildCommands

_OPTIONAL._ Defines build commands.

```yaml
zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build:
      # REQUIRED. Set the base technology for the build environment:
      base: php-apache@latest

      # OPTIONAL. Build your application
      buildCommands:
        - composer install
      ...
```

Build commands are optional. Zerops triggers each command in the defined order in a dedicated build container, running from the `/build/source` directory.

Before the build commands are triggered the build container contains:

1. base environment defined by the [base](#base) attribute
2. optional customisation of the base environment defined in the [prepareCommands](#preparecommands) attribute
3. your application code

#### Run build commands as a single shell instance

Use following syntax to run all commands in the same environment context. For example, if one command changes the current directory, the next command continues in that directory. When one command creates an environment variable, the next command can access it.

```yaml
buildCommands:
  - |
    composer install --optimize-autoloader --no-dev
    php artisan env
```

#### Run build commands as a separate shell instances

When the following syntax is used, each command is triggered in a separate environment context. For example, each shell instance starts in the home directory again. When one command creates an environment variable, it won't be available for the next command.

```yaml
buildCommands:
  - composer install --optimize-autoloader --no-dev
  - php artisan env
```

#### Command exit code

If any command fails, it returns an exit code other than 0 and the build is canceled. Read the [build log](/php/how-to/logs#build-log) to troubleshoot the error. If the error log doesn't contain any specific error message, try to run your build with the verbose option.

```yaml
buildCommands:
  - composer install -v
```

If the command ends successfully, it returns the exit code 0 and Zerops triggers the following command. When all `buildCommands` are finished, the application build is completed and ready for the deploy phase.

### deployFiles

_REQUIRED._ Selects which files or folders will be deployed after the build has successfully finished. To filter out specific files or folders, use [`.deployignore`](#deployignore) file.

```yaml
# REQUIRED. Select which files / folders to deploy after
# the build has successfully finished
deployFiles:
  - vendor
  - public
```

Determines files or folders produced by your build, which should be deployed to your runtime service containers.

The path starts from the **root directory** of your project (the location of `zerops.yaml`). You must enclose the name in quotes if the folder or the file name contains a space.

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

#### Examples

Deploys a folder, and a file from the project root directory:

```yaml
deployFiles:
  - public
  - file.txt
```

Deploys the whole content of the build container:

```yaml
deployFiles: .
```

Deploys a folder, and a file in a defined path:

```yaml
deployFiles:
  - ./path/to/file.txt
  - ./path/to/dir/
```

#### How to use a wildcard in the path

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

Deploys all folders that are located in any path that begins with `/path/to/`

```yaml
deployFiles: ./path/to/~/
```

Deploys all folders that are located in any path that begins with `/path/` and ends with `/to/`

```yaml
deployFiles: ./path/~/to/
```

:::note Example
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 will be cached for the next build.

```yaml
# OPTIONAL. Which files / folders you want to cache for the next build.
# Next builds will be faster when the cache is used.
cache: file.txt
```

The cache attribute helps optimize build times by preserving specified files between builds.

The cache attribute supports the [~ wildcard character](#how-to-use-a-wildcard-in-the-path).

Learn more about the [build cache system](/features/build-cache) in Zerops.

### envVariables

_OPTIONAL._ Defines the environment variables for the build environment.

Enter one or more env variables in following format:

```yaml
zerops:
  # define hostname of your service
  - setup: app
    # ==== how to build your application ====
    build:
      base: php-apache@latest
        …

      # OPTIONAL. Defines the env variables for the build environment:
      envVariables:
        PHP_ENV: production
        DB_NAME: db
        DB_HOST: db
        DB_USER: db
        DB_PASS: ${db_password}
```

Read more about [environment variables](/php/how-to/env-variables) in Zerops.

## Runtime configuration

### base

_OPTIONAL._ Sets the base technology for the runtime environment.
If you don't specify the `run.base` attribute, Zerops keeps the current PHP version for your runtime.

Following options are available for PHP builds:

- `php-apache@8.5`, `php-apache@latest`
- `php-apache@8.4`
- `php-apache@8.3`
- `php-apache@8.1`

- `php-nginx@8.5`, `php-nginx@latest`
- `php-nginx@8.4`
- `php-nginx@8.3`
- `php-nginx@8.1`

```yaml
zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build:
      # REQUIRED. Sets the base technology for the build environment:
      base: php-apache@latest
      ...

    # ==== how to run your application ====
    run:
      # OPTIONAL. Sets the base technology for the runtime environment:
        base: php-apache@latest
      ...
```

<p>
  The base runtime environment contains {data.alpine.default}, the
  selected major version of PHP, [Zerops command line tool](/references/cli) and `composer`, `git` and `wget`.
</p>

:::info
You can change the base environment when you need to. Just simply modify the `zerops.yaml` in your repository.
:::

If you need to install more technologies to the runtime environment, set multiple values as a yaml array. For example:

```yaml
zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build:
      # REQUIRED. Sets the base technology for the build environment:
      base: php-apache@latest
      ...

    # ==== how to run your application ====
    run:
      # OPTIONAL. Sets the base technology for the runtime environment:
      base:
        - php-apache@latest
      prepareCommands:
        - zsc add go@latest
      ...
```

See the full list of supported [run base environments](/zerops-yaml/base-list).

To customise your build environment use the `prepareCommands` attribute.

### os

_OPTIONAL._ Sets the operating system for the runtime environment.

Following options are available:

- `alpine`
- `ubuntu`

Default value is `alpine`.

We are currently using following os version:

- <span>{data.alpine.default}</span>
- <span>{data.ubuntu.default}</span>

:::caution
The os version is fixed and cannot be customised.
:::

### ports

_OPTIONAL._ Specifies one or more internal ports on which your application will listen.

:::info
If no ports are specified, Zerops adds the port TCP 80 automatically.
:::

:::caution
If you want the web server to listen on other port(s) than `:80`, you must [customize](/php/how-to/customize-web-server) your web server configuration as well.
:::

Projects in Zerops represent a group of one or more services. Services can be of different types (runtime services, databases, message brokers, object storage, etc.). All services of the same project share a **dedicated private network**. To connect to a service within the same project, just use the service hostname and its internal port.

For example, to connect to a PHP service with hostname = "app" and port = 80 from another service of the same project, simply use `app:80`. Read more about [how to access a PHP service](/references/networking/internal-access#basic-service-communication).

:::info
Do not use the port **:443**. All the incoming traffic is terminated on the Zerops internal balancer where the SSL certificate is installed and the request is forwarded to your PHP+Nginx / PHP+Apache service as a **http://** on the port **:80**.
:::

Each port has following attributes:

<table className="w-full my-1.5">
  <thead>
    <tr>
      <th className="w-fit"><strong>Parameter</strong></th>
      <th className="w-fit"><strong>Description</strong></th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td className="w-fit">port</td>
      <td className="w-fit">Defines the port number. You can set any port number between <em>10</em> and <em>65435</em>. Ports outside this interval are reserved for internal Zerops systems.</td>
    </tr>
    <tr>
      <td className="w-fit">protocol</td>
      <td className="w-fit"><strong>Optional.</strong> Defines the protocol. Allowed values are <code>TCP</code> or <code>UDP</code>. Default value is <code>TCP</code>.</td>
    </tr>
    <tr>
      <td className="w-fit">httpSupport</td>
      <td className="w-fit"><strong>Optional.</strong> <code>httpSupport = true</code> is the default setting for TCP protocol. Set <code>httpSupport = false</code> if a web server isn't running on the port. Zerops uses this information for the configuration of [public access](/features/access). <code>httpSupport = true</code> is available only in combination with the TCP protocol.</td>
    </tr>
  </tbody>
</table>

### prepareCommands

_OPTIONAL._ Customises the PHP runtime environment by installing additional dependencies or tools to the runtime base environment.

<p>
  The base PHP environment contains {data.alpine.default}, the selected
  major version of PHP, [Zerops command line tool](/references/cli) and `composer`, `git` and `wget`. To install
  additional packages or tools add one or more prepare commands:
</p>

```yaml
zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build:
      ...

    # ==== how to run your application ====
    run:
      # OPTIONAL. Customise the runtime environment by installing additional packages
      # or tools to the base PHP runtime environment.
      prepareCommands:
        - sudo apt-get something
        - curl something else
      ...
```

When the first deploy with a defined prepare attribute is triggered, Zerops will

1. create a prepare runtime container
2. optionally: [copy selected folders or files from your build container](#copy-folders-or-files-from-your-build-container)
3. run the `prepareCommands` commands in the defined order

:::note
`run.prepareCommands` run in the `/home/zerops` directory.
:::

#### Command exit code

If any command fails, it returns an exit code other than 0 and the deploy is canceled. Read the [prepare runtime log](/php/how-to/logs#prepare-runtime-log) to troubleshoot the error. If the command ends successfully, it returns the exit code 0 and Zerops triggers the following command. When all `prepareCommands` commands are finished, your custom runtime environment is ready for the deploy phase.

#### Cache of your custom runtime environment

Some packages or tools can take a long time to install. Therefore, Zerops caches your custom runtime environment after the installation of your custom packages or tools is completed. When the second or following deploy is triggered, Zerops will use the custom runtime cache from the previous deploy if following conditions are met:

1. Content of the [build.addToRunPrepare](#copy-folders-or-files-from-your-build-container) and `run.prepareCommands` attributes didn't change from the previous deploy
2. The custom runtime cache wasn't invalidated in the Zerops GUI.

To invalidate the Zerops runtime cache go to your service detail in Zerops GUI, choose **Service dashboard & runtime containers** from the left menu and click on the **Open pipeline detail** button. Then click on the **Clear runtime prepare cache** button.

When the prepare cache is used, Zerops doesn't create a prepare runtime container and executes the deployment of your application directly.

#### Single or separated shell instances

You can configure your prepare commands to be run in a single shell instance or multiple shell instances. The format is identical to [build commands](#buildcommands).

### Copy folders or files from your build container

<p>
  The prepare runtime container contains {data.alpine.default}, the
  selected major version of PHP, [Zerops command line tool](/references/cli) and `composer`, `git` and `wget`.
</p>

The prepare runtime container does not contain your application code nor the built application. If you need to copy some folders or files from the build container to the runtime container (e.g. a configuration file) use the `addToRunPrepare` attribute in the [build section](#build-pipeline-configuration).

```yaml
zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build:
      ...
      addToRunPrepare: ./runtime-config.yaml

    # ==== how to run your application ====
    run:
      # OPTIONAL. Customise the runtime environment by installing additional packages
      # or tools to the base PHP runtime environment.
      prepareCommands:
        - sudo apt-get something
        - curl something else
      ...
```

In the example above Zerops will copy the `runtime-config.yaml` file from your build container **after the build has finished** into the new **prepare runtime** container. The copied files and folders will be available in the `/home/zerops` folder in the new prepare runtime container before the prepare commands are triggered.

### initCommands

_OPTIONAL._ Defines one or more commands to be run each time a new runtime container is started or a container is restarted.

```yaml
zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build: ...

    # ==== how to run your application ====
    run:
      # OPTIONAL. Run one or more commands each time a new runtime container
      # is started or restarted. These commands are triggered before
      # your PHP application is started.
      initCommands:
        - rm -rf ./cache
```

These commands are triggered in the runtime container before your PHP application is started.

:::note
`run.initCommands` run in the `/var/www` directory.
:::

Use init commands to clean or initialise your application cache or similar operations.

:::caution
The init commands will delay the start of your application each time a new runtime container is started (including the horizontal [scaling](/php/how-to/scaling) or when a runtime container is restarted).

Do not use the init commands for customising your runtime environment. Use the [run:prepareCommands](#preparecommands-1) attribute instead.
:::

#### Command exit code

If any of the `initCommands` fails, it returns an exit code other than 0, but deploy is **not** canceled. After all init commands are finished, regardless of the status code, the application is started. Read the [runtime log](/php/how-to/logs#runtime-log) to troubleshoot the error.

#### Single or separated shell instances

You can configure your `initCommands` to be run in a single shell instance or multiple shell instances. The format is identical to [build commands](#buildcommands).

### documentRoot

_OPTIONAL._ Customizes the folder that will be used as the root of the publicly accessible web server content.

:::info
By default, the document root is configured to `/var/www`.
:::

Customize the folder that will be used as the root of the publicly accessible web server content. Enter the path relative to the `/var/www` folder.
E.g. `documentRoot: public` will set the web server document root to `/var/www/public`.

```yaml
zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build: ...

    # ==== how to run your application ====
    run:
      # OPTIONAL. Customise the folder that will be used as the root of the publicly
      # accessible web server content. Enter the path relative to the /var/www folder.
      documentRoot: public
```

### siteConfigPath

_OPTIONAL._ Sets the custom Nginx or Apache configuration.

:::info
By default, the default [nginx](/php/how-to/customize-web-server#default-nginx-configuration) or [Apache](/php/how-to/customize-web-server#default-apache-configuration) web server configuration is set.
:::

The file must be deployed in the runtime container. Enter the path to the file relative to the `/var/www` folder.
Read more about the [web server customization](/php/how-to/customize-web-server).

### envVariables

_OPTIONAL._ Defines the environment variables for the runtime environment.

Enter one or more env variables in following format:

```yaml
zerops:
  # define hostname of your service
  - setup: app
    # ==== how to run your application ====
    run:
      # OPTIONAL. Defines the env variables for the runtime environment:
      envVariables:
        PHP_ENV: production
        DB_NAME: db
        DB_HOST: db
        DB_USER: db
        DB_PASS: ${db_password}
```

Read more about [environment variables](/php/how-to/env-variables) in Zerops.

### health check

_OPTIONAL._ Defines a health check.

`healthCheck` requires either one `httpGet` object or one `exec` object.

#### httpGet

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

Following attributes are available:

<table className="w-full my-1.5">
  <thead>
    <tr>
      <th className="w-fit whitespace-nowrap">Parameter</th>
      <th className="w-fit whitespace-nowrap">Description</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td className="w-fit whitespace-nowrap font-semibold">port</td>
      <td>Defines the port of the HTTP GET request.
The readiness check will trigger a GET request on <code>{'http://127.0.0.1:{port}/{path}'}</code></td>
    </tr>
    <tr>
      <td className="w-fit whitespace-nowrap font-semibold">path</td>
      <td>Defines the URL path of the HTTP GET request.
The readiness check will trigger a GET request on <code>{'http://127.0.0.1:{port}/{path}'}</code></td>
    </tr>
    <tr>
      <td className="w-fit whitespace-nowrap font-semibold">host</td>
      <td><strong>Optional.</strong> The readiness check is triggered from inside of your runtime container so it always uses the localhost <code>127.0.0.1</code>. If you need to add a <code>host</code> to the request header, specify it in the <code>host</code> attribute.</td>
    </tr>
    <tr>
      <td className="w-fit whitespace-nowrap font-semibold">scheme</td>
      <td><strong>Optional.</strong> The readiness check is triggered from inside of your runtime container so no https is required.
If your application requires a https request, set <code>scheme: https</code></td>
    </tr>
  </tbody>
</table>

**Example:**

```yaml
zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build: ...

    # ==== how to run your application ====
    run:
      # OPTIONAL. Customise the folder that will be used as the root of the publicly
      # accessible web server content. Enter the path relative to the /var/www folder.
      documentRoot: public

      # OPTIONAL. Define a health check with a HTTP GET request option.
      # Configures the check on http://127.0.0.1:80/status
      healthCheck:
        httpGet:
          port: 80
          path: /status
```

#### exec

Configures the health check to run a local command.
Following attributes are available:

<table className="w-full my-1.5">
  <thead>
    <tr>
      <th className="w-fit"><strong>Parameter</strong></th>
      <th className="w-fit"><strong>Description</strong></th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td className="w-fit"><strong>command</strong></td>
      <td className="w-fit">
        Defines a local command to be run.

        The command has access to the same [environment variables](/php/how-to/create#set-secret-environment-variables) as your PHP application.

        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 below.
      </td>
    </tr>
  </tbody>
</table>

**Example:**

```yaml
zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build: ...

    # ==== how to run your application ====
    run:
      # OPTIONAL. Customise the folder that will be used as the root of the publicly
      # accessible web server content. Enter the path relative to the /var/www folder.
      documentRoot: public

      # OPTIONAL. Define a health check with a shell command.
      healthCheck:
        exec:
          command: |
            touch grass
            rm -rf life
            mv /outside/user /home/user
```

### crontab

_OPTIONAL._ Defines cron jobs.

Setup cron jobs in the following format:

```yaml
zerops:
  # define hostname of your service
  - setup: app

    # ==== how to run your application ====
    run:
      crontab:
        # REQUIRED. Sets the command to execute:
        - command: ""
        # REQUIRED. Sets the interval time to execute:
          timing: "0 * * * *"
```

Read more about setting up [cron](/zerops-yaml/cron) in Zerops.

## Deploy configuration

### readiness check

_OPTIONAL._ Defines a readiness check. Read more about how the [readiness check works](/php/how-to/deploy-process#readiness-checks) in Zerops.

`readinessCheck` requires either one `httpGet` object or one `exec` object.

#### httpGet

Configures the readiness check to request a local URL using a http GET method.

Following attributes are available:

<table className="w-full my-1.5">
  <thead>
    <tr>
      <th className="w-fit whitespace-nowrap">Parameter</th>
      <th className="w-fit whitespace-nowrap">Description</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td className="w-fit whitespace-nowrap font-semibold">port</td>
      <td>Defines the port of the HTTP GET request.
The readiness check will trigger a GET request on <code>{'http://127.0.0.1:{port}/{path}'}</code></td>
    </tr>
    <tr>
      <td className="w-fit whitespace-nowrap font-semibold">path</td>
      <td>Defines the URL path of the HTTP GET request.
The readiness check will trigger a GET request on <code>{'http://127.0.0.1:{port}/{path}'}</code></td>
    </tr>
    <tr>
      <td className="w-fit whitespace-nowrap font-semibold">host</td>
      <td><strong>Optional.</strong> The readiness check is triggered from inside of your runtime container so it always uses the localhost <code>127.0.0.1</code>. If you need to add a <code>host</code> to the request header, specify it in the <code>host</code> attribute.</td>
    </tr>
    <tr>
      <td className="w-fit whitespace-nowrap font-semibold">scheme</td>
      <td><strong>Optional.</strong> The readiness check is triggered from inside of your runtime container so no https is required.
If your application requires a https request, set <code>scheme: https</code></td>
    </tr>
  </tbody>
</table>

**Example:**

```yaml
zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build: ...

    # ==== how to deploy your application ====
    deploy:
      # OPTIONAL. Define a readiness check with a HTTP GET request option.
      # Configures the check on http://127.0.0.1:80/status
      readinessCheck:
        httpGet:
          port: 80
          path: /status

    # ==== how to run your application ====
    run: ...
```

Read more about how the [readiness check works](/php/how-to/deploy-process#readiness-checks) in Zerops.

#### exec

Configures the readiness check to run a local command.
Following attributes are available:

<table className="w-full my-1.5">
  <thead>
    <tr>
      <th className="w-fit"><strong>Parameter</strong></th>
      <th className="w-fit"><strong>Description</strong></th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td className="w-fit"><strong>command</strong></td>
      <td className="w-fit">
        Defines a local command to be run.

        The command has access to the same [environment variables](/php/how-to/create#set-secret-environment-variables) as your PHP application.

        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 below.
      </td>
    </tr>
  </tbody>
</table>

**Example:**

```yaml
zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build: ...

    # ==== how to deploy your application ====
    deploy:
      # OPTIONAL. Define a readiness check with a HTTP GET request option.
      # Configures the check on http://127.0.0.1:80/status
      readinessCheck:
        exec:
          command: |
            touch grass
            rm -rf life
            mv /outside/user /home/user
```

Read more about how the [readiness check works](/php/how-to/deploy-process#readiness-checks) in Zerops.


----------------------------------------

# Php > How To > Build Process



----------------------------------------

# Php > How To > Controls



----------------------------------------

# Php > How To > Create


Zerops provides 2 PHP services with an included web server: **PHP+Nginx** and **PHP+Apache**. PHP runtime is highly scalable and customisable to suit both development and production.

## Create PHP service using Zerops GUI

First, set up a project in Zerops GUI. Then go to the project dashboard page and choose **Add new service** in the left menu in the **Services** block. Then add a new PHP service:

### Choose PHP version

Following PHP versions are currently supported:

:::info
You can [change](/php/how-to/upgrade) the major version at any time later.
:::

### Set a hostname

Enter a unique service identifier like "app","cache", "gui" etc. Duplicate services with the same name in the same project are forbidden.

#### Limitations:

- maximum 25 characters
- must contain only lowercase ASCII letters (a-z) or numbers (0-9)

:::caution
The hostname is fixed after the service is created. It can't be changed later.
:::

### Set secret environment variables

Add environment variables with sensitive data, such as password, tokens, salts, certificates etc. These will be securely saved inside Zerops and added to your runtime service upon start.

Setting the secret environment variables is optional. You can set them later in Zerops GUI.

Read more about [different types of env variables](/php/how-to/env-variables#service-env-variables) in Zerops.

## Create PHP service using zCLI

zCLI is the Zerops command-line tool. To create a new PHP service via the command-line, follow these steps:

1. [Install & setup zCLI](/references/cli)
2. [Create a project description file](/php/how-to/create#create-a-project-description-file)
3. [Create a project with a PHP and PostgreSQL service](#full-example)

### Create a project description file

Zerops uses a yaml format to describe the project infrastructure.

#### Basic example:

Create a directory `my-project`. Create an `description.yaml` file inside the `my-project` directory with following content:

```yaml
# basic project data
project:
  # project name
  name: my-project
# array of project services
services:
  - # service name
    hostname: app
    # service type and version number in php-apache@{version} or php-nginx@{version} format
    type: php-nginx@latest
    # defines the minimum number of containers for horizontal autoscaling
    minContainers: 1
    # defines the maximum number of containers for horizontal autoscaling. Max value = 6.
    maxContainers: 6
    # optional: create env variables
    envSecrets:
      S3_ACCESS_KEY_ID: 'P8cX1vVVb'
      S3_ACCESS_SECRET: 'ogFthuiLYki8XoL73opSCQ'
```

The yaml file describes your future project infrastructure. The project will contain one PHP version 8.1 service with default [auto scaling](/php/how-to/scaling) configuration. Hostname will be set to "app", the internal port(s) the service listens on will be defined later in the [zerops.yaml](/php/how-to/build-pipeline#ports). Following secret env variables will be configured:

```env
S3_ACCESS_KEY_ID="P8cX1vVVb"
S3_ACCESS_SECRET="ogFthuiLYki8XoL73opSCQ"
```

#### Full example:

Create a directory my-project. Create an description.yaml file inside the my-project directory with following content:

```yaml
# basic project data
project:
  # project name
  name: my-project
  # optional: project description
  description: A project with a PHP and PostgreSQL database
  # optional: project tags
  tags:
    - DEMO
    - ZEROPS
# array of project services
services:
  - # service name
    hostname: app
    # service type and version number in php-apache@{version} or php-nginx@{version} format
    type: php-nginx@latest
    # optional: vertical auto scaling customization
    verticalAutoscaling:
      cpuMode: DEDICATED
      minCpu: 2
      maxCpu: 5
      minRam: 2
      maxRam: 24
      minDisk: 6
      maxDisk: 50
      startCpuCoreCount: 3
      minFreeRamGB: 0.5
      minFreeRamPercent: 20
    # defines the minimum number of containers for horizontal autoscaling. Max value = 6.
    minContainers: 2
    # defines the maximum number of containers for horizontal autoscaling. Max value = 6.
    maxContainers: 4
    # optional: create secret env variables
    envSecrets:
      S3_ACCESS_KEY_ID: 'P8cX1vVVb'
      S3_ACCESS_SECRET: 'ogFthuiLYki8XoL73opSCQ'
  - # second service hostname
    hostname: db
    # service type and version number in postgresql@{version} format
    type: postgresql@12
    # mode of operation "HA"/"non_HA"
    mode: NON_HA
```

The yaml file describes your future project infrastructure. The project will contain a PHP service and a [PostgreSQL](/postgresql/overview) service.

PHP service with "app" hostname, the internal port(s) the service listens on will be defined later in the [zerops.yaml](/php/how-to/build-pipeline#ports). PHP service will run on version 8.1 with a custom vertical and horizontal scaling. Following secret env variables will be configured:

```env
S3_ACCESS_KEY_ID="P8cX1vVVb"
S3_ACCESS_SECRET="ogFthuiLYki8XoL73opSCQ"
```

The hostname of the PostgreSQL service will be set to "db". The [single container](/features/scaling#single-container-mode)(/features/scaling#deployment-modes-databases-and-shared-storage) mode will be chosen and the default auto [scaling configuration](/postgresql/how-to/scale#configure-scaling) will be set.

#### Description of description.yaml parameters

The `project:` section is required. Only one project can be defined.

<table className="w-full my-1.5">
  <thead>
    <tr>
      <th className="w-fit"><strong>Parameter</strong></th>
      <th className="w-fit"><strong>Description</strong></th>
      <th className="w-fit"><strong>Limitations</strong></th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td className="w-fit"><strong>name</strong></td>
      <td className="w-fit">The name of the new project. Duplicates are allowed.</td>
      <td className="w-fit"></td>
    </tr>
    <tr>
      <td className="w-fit"><strong>description</strong></td>
      <td className="w-fit"><strong>Optional.</strong> Description of the new project.</td>
      <td className="w-fit">Maximum 255 characters.</td>
    </tr>
    <tr>
      <td className="w-fit"><strong>tags</strong></td>
      <td className="w-fit"><strong>Optional.</strong> One or more string tags. Tags do not have a functional meaning, they only provide better orientation in projects.</td>
      <td className="w-fit"></td>
    </tr>
  </tbody>
</table>

At least one service in `services:` section is required. You can create a project with multiple services. The example above contains PHP and PostgreSQL services but you can create a `description.yaml` with your own combination of [services](/features/infrastructure).

<table className="w-full my-1.5">
  <thead>
    <tr>
      <th className="w-fit"><strong>Parameter</strong></th>
      <th className="w-fit"><strong>Description</strong></th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td className="w-fit"><strong>hostname</strong></td>
      <td className="w-fit">
        The unique service identifier.

        The hostname of the new service will be set to the `hostname` value.

        <strong>Limitations:</strong>
        <ul>
        <li>duplicate services with the same name in the same project are forbidden</li>
        <li>maximum 25 characters</li>
        <li>must contain only lowercase ASCII letters (a-z) or numbers (0-9)</li>
        </ul>
      </td>
    </tr>
    <tr>
      <td className="w-fit"><strong>type</strong></td>
      <td className="w-fit">
        Specifies the service type and version.

        See what [PHP service types](/references/import-yaml/type-list#runtime-services) are currently supported.
      </td>
    </tr>
    <tr>
      <td className="w-fit"><strong>verticalAutoscaling</strong></td>
      <td className="w-fit">
        <strong>Optional.</strong> Defines [custom vertical auto scaling parameters](/php/how-to/create#set-auto-scaling-configuration).

        All verticalAutoscaling attributes are optional. Not specified attributes will be set to their default values.
      </td>
    </tr>
    <tr>
      <td className="w-fit"><strong>- cpuMode</strong></td>
      <td className="w-fit">
        <strong>Optional.</strong> Accepts `SHARED`, `DEDICATED` values. Default is `SHARED`
      </td>
    </tr>
    <tr>
      <td className="w-fit"><strong>- minCpu/maxCpu</strong></td>
      <td className="w-fit">
        <strong>Optional.</strong> Set the minCpu or maxCpu in CPU cores (integer).
      </td>
    </tr>
    <tr>
      <td className="w-fit"><strong>- minRam/maxRam</strong></td>
      <td className="w-fit">
        <strong>Optional.</strong> Set the minRam or maxRam in GB (float).
      </td>
    </tr>
    <tr>
      <td className="w-fit"><strong>- minDisk/maxDisk</strong></td>
      <td className="w-fit">
        <strong>Optional.</strong> Set the minDisk or maxDisk in GB (float).
      </td>
    </tr>
    <tr>
      <td className="w-fit"><strong>minContainers</strong></td>
      <td className="w-fit">
        <strong>Optional.</strong> Default = 1. Defines the minimum number of containers for [horizontal autoscaling](/php/how-to/create#horizontal-auto-scaling).

        <strong>Limitations:</strong>

        Current maximum value = 10.
      </td>
    </tr>
    <tr>
      <td className="w-fit"><strong>maxContainers</strong></td>
      <td className="w-fit">
        Defines the maximum number of containers for [horizontal autoscaling](/php/how-to/create#horizontal-auto-scaling).

        <strong>Limitations:</strong>

        Current maximum value = 10.
      </td>
    </tr>
    <tr>
      <td className="w-fit"><strong>envSecrets</strong></td>
      <td className="w-fit">
        <strong>Optional.</strong> Defines one or more secret env variables as a key value map. See env variable [restrictions](/php/how-to/env-variables#env-variable-restrictions).
      </td>
    </tr>
  </tbody>
</table>

### Create a project based on the description.yaml

When you have your `description.yaml` ready, use the `zcli project project-import` command to create a new project and the service infrastructure.

```sh
Usage:
  zcli project project-import importYamlPath [flags]

Flags:
  -h, --help                Help for the project import command.
      --org-id string        If you have access to more than one organization, you must specify the org ID for which the
                            project is to be created.
      --working-dir string   Sets a custom working directory. Default working directory is the current directory. (default "./")
```

Zerops will create a project and one or more services based on the `description.yaml` content.

Maximum size of the `description.yaml` file is 100 kB.

You don't specify the project name in the `zcli project project-import` command, because the project name is defined in the `description.yaml`.

If you have access to more than one client, you must specify the client ID for which the project is to be created. The `clientID` is located in the Zerops GUI under the client name on the project dashboard page.

### Add PHP service to an existing project

#### Example:

Create a directory `my-project` if it doesn't exist. Create an `import.yaml` file inside the `my-project` directory with following content:

```yaml
# basic project data
project:
  # project name
  name: my-project
# array of project services
services:
  - # service name
    hostname: app
    # service type and version number in php-apache@{version} or php-nginx@{version} format
    type: php-nginx@latest
    # defines the minimum number of containers for horizontal autoscaling
    minContainers: 1
    # defines the maximum number of containers for horizontal autoscaling. Max value = 6.
    maxContainers: 6
    # optional: create env variables
    envSecrets:
      S3_ACCESS_KEY_ID: 'P8cX1vVVb'
      S3_ACCESS_SECRET: 'ogFthuiLYki8XoL73opSCQ'
```

The yaml file describes the list of one or more services that you want to add to your existing project. In the example above, one PHP service version 8.1 with default [auto scaling](/php/how-to/scaling) configuration will be added to your project. Hostname of the new service will be set to `app`. Following secret env variables will be configured:

```env
S3_ACCESS_KEY_ID="P8cX1vVVb"
S3_ACCESS_SECRET="ogFthuiLYki8XoL73opSCQ"
```

The content of the `services:` section of `import.yaml` is identical to the project description file. The `import.yaml` never contains the `project:` section because the project already exists.

When you have your `import.yaml` ready, use the `zcli project service-import` command to add one or more services to your existing Zerops project.

```sh
Usage:
  zcli project service-import importYamlPath [flags]

Flags:
  -h, --help                Help for the project service import command.
  -P, --project-id string   If you have access to more than one project, you must specify the project ID for which the
                           command is to be executed.
```

zCLI commands are interactive, when you press enter after `zcli project service-import importYamlPath`, you will be given a list of your projects to choose from.

Maximum size of the import.yaml file is 100 kB.


----------------------------------------

# Php > How To > Customize Runtime


## Overwrite php.ini files

You can override PHP configuration directives by setting environment variables in your `zerops.yaml` file.

Here's an example of how to adjust PHP's `post_max_size` directive:
```yaml
zerops:
  # define hostname of your service
  - setup: app
    # ==== how to run your application ====
    run:
      # REQUIRED. Sets the base technology for the runtime environment:
      base: php-nginx@8.3

      # OPTIONAL. Defines the env variables for the runtime:
      envVariables:
        PHP_INI_post_max_size: 10M
```

:::info
After updating PHP-FPM configuration in your `zerops.yaml` file, you need to restart or reload the app for the changes to take effect.
:::

## PHP-FPM

### Default PHP-FPM configuration

PHP-FPM (FastCGI Process Manager) uses the **dynamic** process management mode by default. In this mode, the system automatically adjusts the number of PHP processes based on current load.

The default PHP-FPM configuration uses these values:

- `PHP_FPM_PM` = `dynamic`
- `PHP_FPM_PM_MAX_CHILDREN` = `20`
- `PHP_FPM_PM_START_SERVERS` = `2`
- `PHP_FPM_PM_MIN_SPARE_SERVERS` = `1`
- `PHP_FPM_PM_MAX_SPARE_SERVERS` = `3`
- `PHP_FPM_PM_MAX_SPAWN_RATE` = `32`
- `PHP_FPM_PM_MAX_REQUESTS` = `500`

### Dynamic mode

To adjust the dynamic mode settings, add the desired environment variables to the run section:
```yaml
zerops:
  # define hostname of your service
  - setup: app
    # ==== how to run your application ====
    run:
      # OPTIONAL. Defines the env variables for the runtime:
      envVariables:
        PHP_FPM_PM_MAX_CHILDREN: 30
        PHP_FPM_PM_START_SERVERS: 5
        PHP_FPM_PM_MIN_SPARE_SERVERS: 2
        PHP_FPM_PM_MAX_SPARE_SERVERS: 10
        PHP_FPM_PM_MAX_REQUESTS: 1000
```

### Ondemand mode

The **ondemand** mode is ideal for applications with lower traffic, where processes are created only when requests arrive. To enable ondemand mode:
```yaml
zerops:
  # define hostname of your service
  - setup: app
    # ==== how to run your application ====
    run:
      # OPTIONAL. Defines the env variables for the runtime:
      envVariables:
        PHP_FPM_PM: ondemand
        PHP_FPM_PM_MAX_CHILDREN: 20
        PHP_FPM_PM_PROCESS_IDLE_TIMEOUT: 60s
        PHP_FPM_PM_MAX_REQUESTS: 500
```

**Available parameters for ondemand mode:**

- `PHP_FPM_PM_MAX_CHILDREN` – maximum number of child processes
- `PHP_FPM_PM_PROCESS_IDLE_TIMEOUT` – time after which idle processes are terminated (default: `60s`)
- `PHP_FPM_PM_MAX_REQUESTS` – number of requests each process handles before being recycled (default: `500`)

:::info
After updating PHP-FPM configuration in your `zerops.yaml` file, you need to restart or reload the app for the changes to take effect.
:::

----------------------------------------

# Php > How To > Customize Web Server


## PHP + Nginx

### Default Nginx configuration

The default PHP+Nginx service has following Nginx configuration:

```
server {
    listen 80;
    listen [::]:80;

    server_name _;

    # Be sure that you set up the correct document root!
    root {{.DocumentRoot}};

    location ~ \.php {
        try_files _ @backend;
    }

    location / {
        # use this for pretty url
        try_files $uri /$uri /index.html /index.php$is_args$args;
    }

    location @backend {
        fastcgi_pass unix:{{.PhpSocket}};
        fastcgi_split_path_info ^(.+\.php)(/.*)$;
        include fastcgi_params;

        fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;
        fastcgi_param DOCUMENT_ROOT $realpath_root;
        internal;
    }

    access_log syslog:server=unix:/dev/log,facility=local1,tag=nginx,severity=info default_short;
    error_log syslog:server=unix:/dev/log,facility=local1,tag=nginx,severity=error;
}
```

The configuration contains 2 variables:

- **`{{.DocumentRoot}}`** is replaced by the [`run.documentRoot`](/php/how-to/build-pipeline#documentroot) attribute from the `zerops.yaml`. If the attribute is not specified, the default value `/var/www` is used.

- **`{{.PhpSocket}}`** is replaced by a path to the PHP socket based on the PHP version.

### Customize Nginx configuration

Follow these steps to customize the Nginx configuration in PHP+Nginx service:

1. Create a **.tmpl** file with the Apache configuration in your repository.

2. Optionally use following variables:

- **`{{.DocumentRoot}}`** is replaced by the [`run.documentRoot`](/php/how-to/build-pipeline#documentroot) attribute from the `zerops.yaml`. If the attribute is not specified, the default value `/var/www` is used.

Example:

```
root {{.DocumentRoot}};
```

- **`{{.PhpSocket}}`** is replaced by a path to the PHP socket based on the PHP version.

Example:

```
fastcgi_pass unix:{{.PhpSocket}};
```

- **`{{.Environment.ENV_NAME}}`** is replaced by the [env variable](/php/how-to/env-variables) value. The env variable must be either defined in [run.envVariables](/php/how-to/build-pipeline#envvariables-1) in `zerops.yaml` or set as a [secret](/php/how-to/env-variables#set-secret-env-variables-in-zerops-gui) or [generated](/php/how-to/env-variables#generated-env-variables) env variable in Zerops GUI.

:::caution
Use the **.tmpl** file extension to make Zerops interpret the file as a template. Zerops will replace the supported variables listed above.
:::

3. Check that your Nginx configuration is consistent with Zerops requirements:

- Do not use IP addresses in the `listen` directive
- If you use other ports than `:80` in the `listen` directive, add them to the [`run.ports`](/php/how-to/build-pipeline#ports) in your `zerops.yaml` as well.
- Do not use the port **:443**. All the incoming `https://` traffic is terminated on the Zerops internal balancer where the SSL certificate is installed and the request is forwarded to your PHP+Nginx service as a **http://** on the port **:80**.

4. Add the [`siteConfigPath`](/php/how-to/build-pipeline#siteconfigpath) to the run section of your `zerops.yaml`

```yaml
zerops:
  # define hostname of your service
  - setup: app
    # ==== how to build your application ====
    build:
      # REQUIRED. Set the base technology for the build environment:
      base: php-nginx@latest

      # REQUIRED. Select which files / folders to deploy after
      # the build has successfully finished
      deployFiles:
        - vendor
        - public

    # ==== how to run your application ====
    run:
      documentRoot: public

      # OPTIONAL. Sets the custom Nginx or Apache configuration. The file must be deployed in the runtime container. Enter the path to the file relative to the /var/www folder
      siteConfigPath: site_config.tmpl
```

5. Ensure that the [`build.deployFiles`](/php/how-to/build-pipeline#deployfiles) contains the folder with the `siteConfigPath` or add the path to the Nginx config file to the `deployFiles` list. Zerops will deploy the file to the runtime container(s).

6. [Trigger](/php/how-to/trigger-pipeline) the build & deploy pipeline.

## PHP + Apache

### Default Apache configuration

The default PHP+Apache service has following Apache configuration:

```

    </FilesMatch>

    ErrorLog  "| /usr/bin/logger -tapache -plocal1.err"
    CustomLog "| /usr/bin/logger -tapache -plocal1.notice" combined
</VirtualHost>
```

The configuration contains 2 variables:

- **`{{.DocumentRoot}}`** is replaced by the [`run.documentRoot`](/php/how-to/build-pipeline#documentroot) attribute from the `zerops.yaml`. If the attribute is not specified, the default value `/var/www` is used.

- **`{{.PhpSocket}}`** is replaced by a path to the PHP socket based on the PHP version.

### Customize Apache configuration

Follow these steps to customize the Apache configuration in PHP+Apache service:

1. Create a **.tmpl** file with the Nginx configuration in your repository.

2. Optionally use following variables:

- **`{{.DocumentRoot}}`** is replaced by the [`run.documentRoot`](/php/how-to/build-pipeline#documentroot) attribute from the `zerops.yaml`. If the attribute is not specified, the default value `/var/www` is used.

Example:

```
DocumentRoot {{.DocumentRoot}};
```

- **`{{.PhpSocket}}`** is replaced by a path to the PHP socket based on the PHP version.

Example:

```

```

- **`{{.Environment.ENV_NAME}}`** is replaced by the [env variable](/php/how-to/env-variables) value. The env variable must be either defined in [run.envVariables](/php/how-to/build-pipeline#envvariables-1) in `zerops.yaml` or set as a [secret](/php/how-to/env-variables#set-secret-env-variables-in-zerops-gui) or [generated](/php/how-to/env-variables#generated-env-variables) env variable in Zerops GUI.

:::caution
Use the **.tmpl** file extension to make Zerops interpret the file as a template. Zerops will replace the supported variables listed above.
:::

3. Check that your Apache configuration is consistent with Zerops requirements:

- Do not use IP addresses in the `<VirtualHost>` directive
- If you use other ports than `:80` in the `<VirtualHost>` directive, add them to the [`run.ports`](/php/how-to/build-pipeline#ports) in your `zerops.yaml` as well.
  Do not use the port **:443**. All the incoming `https://` traffic is terminated on the Zerops internal balancer where the SSL certificate is installed and the request is forwarded to your PHP+Apache service as a **http://** on the port **:80**.

4. Add the [`siteConfigPath`](/php/how-to/build-pipeline#siteconfigpath) to the run section of your `zerops.yaml`.

```yaml
zerops:
  # define hostname of your service
  - setup: app
    # ==== how to build your application ====
    build:
      # REQUIRED. Set the base technology for the build environment:
      base: php-apache@latest

      # REQUIRED. Select which files / folders to deploy after
      # the build has successfully finished
      deployFiles:
        - vendor
        - public

    # ==== how to run your application ====
    run:
      documentRoot: public

      # OPTIONAL. Sets the custom Nginx or Apache configuration. The file must be deployed in the runtime container. Enter the path to the file relative to the /var/www folder
      siteConfigPath: site_config.tmpl
```

5. Ensure that the [`build.deployFiles`](/php/how-to/build-pipeline#deployfiles) contains the folder with the `siteConfigPath` or add the path to the Apache config file to the `deployFiles` list. Zerops will deploy the file to the runtime container(s).

6. [Trigger](/php/how-to/trigger-pipeline) the build & deploy pipeline.


----------------------------------------

# Php > How To > Deploy Process



----------------------------------------

# Php > How To > Env Variables



----------------------------------------

# Php > How To > Filebrowser



----------------------------------------

# Php > How To > Logs



----------------------------------------

# Php > How To > Scaling



----------------------------------------

# Php > How To > Shared Storage



----------------------------------------

# Php > How To > Trigger Pipeline



----------------------------------------

# Php > How To > Upgrade



----------------------------------------

# Php > Overview


[PHP ↗](https://www.php.net/), a popular general-purpose scripting language that is especially suited to web development.

As said, there is no need for coding yet, we have created a [Github repository ↗](https://github.com/zeropsio/recipe-php-hello-world), a **_recipe_**, containing the most simple PHP web application. The repo will be used as a source from which the app will be built.

### 🚀 Feel free to deploy the recipe yourself

This is the most bare-bones example of PHP running in Zerops — as few libraries as possible,
  just a simple endpoint with connect, read and write to a Zerops PostgreSQL database.

  [Deploy "php" recipe on Zerops](https://app.zerops.io/recipe/?lf=php)

1. Log in/sign up to [Zerops GUI ↗](https://app.zerops.io)
2. In the **Projects** box click on **Import a project** and paste in the following YAML config ([source ↗](https://github.com/zeropsio/recipe-php-hello-world/blob/main/import-project/description.yaml)):

```yaml
project:
  name: my-first-project
services:
  - hostname: helloworld
    type: php-apache@8.1+2.4
    minContainers: 1
    maxContainers: 3
    buildFromGit: https://github.com/zeropsio/recipe-php-hello-world@main
    enableSubdomainAccess: true
```

3. Click on **Import project** and wait until all pipelines have finished.

**That's it, your application is now up and running! :star: Let's check it works:**

1. A _subdomain_ should have been enabled and visible in the project's **IP addressed & Public Routing Overview** box. Its format should look similar to this `https://helloworld-24-8080.prg1.zerops.app`.
2. Click or the `subdomain` URL to open it in a browser and you should see

```
Hello, World!
```

:::tip
Do you have any questions? Check the step-by-step tutorial, browse the documentation and join our **[Discord](https://discord.com/invite/WDvCZ54)** community to get help from our team and other members.
:::

## How to start

- [Care for details?](/php/how-to/create) — Dive in all Zerops has to offer for your PHP application.

## Feature Highlights

- [Create PHP service](/php/how-to/create) — Start with creating a PHP service using GUI or zCLI.
- [zerops.yaml](/php/how-to/build-pipeline#add-zeropsyaml-to-your-repository) — See a full example of zerops.yaml file to create your own app.
- [Scaling configuration](/php/how-to/scaling) — Set up scaling of your PHP application so that it runs smoothly while using only necessary resources.

{" "}

- [Customize build environment](/php/how-to/build-process#customize-build-environment)
- [Customize runtime environment](/php/how-to/customize-runtime)

## When in doubt, reach out

Don't know how to start or got stuck during the process? You might not be the first one, visit the FAQ section to find out.

In case you haven't found an answer (and also if you have), we and our community are looking forward to hearing from you on Discord.

Have you build something that others might find useful? Don't hesitate to share your knowledge!

- [FAQ](/php/faq) — Most common questions in one place.
- [Discord](https://discord.com/invite/WDvCZ54) — Join our core team and Zerops community on Discord. Ask questions and share your tips with other members.

## Popular Guides

- [zCLI](/references/cli) — Get even more out of Zerops with the zCLI command line tool.
- [Zerops VPN](/references/networking/vpn) — Connect to your services easily with Zerops VPN.


----------------------------------------

# Postgresql > How To > Connect


This guide covers everything about reaching your PostgreSQL database in Zerops: connection details, ports and TLS, connection pooling, connecting from other services or from your workstation, and the database tools you can use.

## Connection options at a glance

- **Internal**: between services in the same project, over the private network.
- **Remote**: from outside Zerops, either through the [VPN](#connect-via-zerops-vpn) (your machine joins the private network) or through [public IP access](#connect-via-public-ip) (TLS through pgBouncer).

## Connection details

Find your connection details in the service detail page under **Peek access details** (hostname, port, user, password, connection string). The full list of connection-related environment variables lives under **Environment variables** in the same service detail.

### Connection parameters

<table className="w-full my-1.5">
  <thead>
    <tr>
      <th className="w-fit">Parameter</th>
      <th className="w-fit">Internal</th>
      <th className="w-fit">Public IP (TLS)</th>
      <th className="w-fit">Env Variable</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td className="w-fit font-semibold whitespace-nowrap">Hostname</td>
      <td className="w-fit">Service hostname</td>
      <td className="w-fit">Public IP address</td>
      <td className="w-fit">`hostname`</td>
    </tr>
    <tr>
      <td className="w-fit font-semibold whitespace-nowrap">Port (primary)</td>
      <td className="w-fit">5432</td>
      <td className="w-fit">6432 (via pgBouncer)</td>
      <td className="w-fit">`port` / `portTls`</td>
    </tr>
    <tr>
      <td className="w-fit font-semibold whitespace-nowrap">Port (replicas, HA only)</td>
      <td className="w-fit">5433</td>
      <td className="w-fit">N/A</td>
      <td className="w-fit">`portReplicas`</td>
    </tr>
    <tr>
      <td className="w-fit font-semibold whitespace-nowrap">User</td>
      <td className="w-fit">`db` (default)</td>
      <td className="w-fit">Same as internal</td>
      <td className="w-fit">`user`</td>
    </tr>
    <tr>
      <td className="w-fit font-semibold whitespace-nowrap">Password</td>
      <td className="w-fit">Generated at creation</td>
      <td className="w-fit">Same as internal</td>
      <td className="w-fit">`password`</td>
    </tr>
    <tr>
      <td className="w-fit font-semibold whitespace-nowrap">Connection string (primary)</td>
      <td className="w-fit">`postgresql://${user}:${password}@${hostname}:5432/${dbName}`</td>
      <td className="w-fit">Same format with TLS port</td>
      <td className="w-fit">`connectionString` / `connectionTlsString`</td>
    </tr>
    <tr>
      <td className="w-fit font-semibold whitespace-nowrap">Connection string (replicas, HA only)</td>
      <td className="w-fit">`postgresql://${user}:${password}@${hostname}:5433/${dbName}`</td>
      <td className="w-fit">N/A</td>
      <td className="w-fit">`connectionStringReplicas`</td>
    </tr>
    <tr>
      <td className="w-fit font-semibold whitespace-nowrap">Database name</td>
      <td className="w-fit">`db` (default)</td>
      <td className="w-fit">Same as internal</td>
      <td className="w-fit">`dbName`</td>
    </tr>
  </tbody>
</table>

:::warning
Zerops creates a system user named `zps` with full privileges for maintenance. Do not delete it, change its password, or remove its privileges, as doing so disrupts Zerops' ability to maintain the database cluster.
:::

## Connection ports and TLS

PostgreSQL on Zerops exposes three ports, each for a different purpose:

<table className="w-full my-1.5">
  <thead>
    <tr>
      <th className="w-fit">Port</th>
      <th className="w-fit">Purpose</th>
      <th className="w-fit" style={{ minWidth: '105px' }}>TLS</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td className="w-fit"><code>5432</code></td>
      <td className="w-fit">Primary node (read and write)</td>
      <td className="w-fit">Not supported (plaintext)</td>
    </tr>
    <tr>
      <td className="w-fit"><code>5433</code></td>
      <td className="w-fit">Read-only replicas, distributing reads (HA mode only)</td>
      <td className="w-fit">Not supported (plaintext)</td>
    </tr>
    <tr>
      <td className="w-fit"><code>6432</code></td>
      <td className="w-fit">pgBouncer connection pooler</td>
      <td className="w-fit"><b>Required</b></td>
    </tr>
  </tbody>
</table>

- **Ports `5432` and `5433` do not support TLS.** Connect with `sslmode=disable`. Inside a project these ports are reachable only on the private network, and over the [VPN](#connect-via-zerops-vpn) the tunnel already encrypts the traffic, so requesting TLS on them fails the handshake.
- **Port `6432` (pgBouncer) requires TLS.** Connect with at least `sslmode=require`; the connection is always encrypted. pgBouncer presents a certificate signed by the [Zerops CA](/references/networking/zerops-ca) but does not force the client to validate it, so `sslmode=require` is enough. If you want to verify the server's identity, use `sslmode=verify-full` together with the Zerops CA. This holds whether you reach `6432` from inside the project or over a public IP.

## Connection pooling with pgBouncer

Port `6432` puts [pgBouncer](https://www.pgbouncer.org/) in front of PostgreSQL and multiplexes many client connections onto a small pool of server connections. This is valuable for applications that open many short-lived connections (serverless functions, PHP-FPM, or anything with high connection churn), and **we recommend connecting through `6432` rather than `5432` for these workloads, including for internal service-to-service connections.**

A few things to know:

- **Transaction pooling.** A server connection is returned to the pool after each transaction, not when the client disconnects. Prepared statements are supported (cached per server connection), but session-scoped features that span transactions (session-level `SET`, advisory locks held across statements, `LISTEN`/`NOTIFY`) won't behave as expected. Use a direct `5432` connection for those.
- **TLS is required** on `6432` (see [above](#connection-ports-and-tls)), even for internal connections.
- **HA mode.** pgBouncer pools connections to the primary (writes). Read routing across replicas on port `5433` is separate and is not pooled.

## Connect from services in the same project

All services in a project share a private network, so other services reach PostgreSQL directly by its hostname. There are two ways to wire it up.

### Direct connection parameters

Use the parameters from **Peek access details**:

```ini
host = db          # your PostgreSQL service hostname
port = 5432        # 5433 for read-only replicas in HA mode
user = db          # default user
password = **********
```

### Environment variables (recommended)

Zerops generates connection environment variables for every PostgreSQL service. To use one service's variables from another, prefix the variable name with the service hostname and an underscore. For example, to read the `connectionString` of service `db`, reference `db_connectionString`.

For read-only connections (HA mode only), use `connectionStringReplicas` instead.

See the [Environment Variables](/features/env-variables) documentation for details and for adding your own variables.

:::caution Important notes
- When changing a password, update both the database user and the environment variable, since they don't synchronize automatically.
- Zerops uses the `postgresql://` URI scheme. If your software requires the shorter `postgres://`, create a custom environment variable with that format.
- Internal connections on `5432`/`5433` don't use SSL/TLS. Security comes from the private network. For TLS-encrypted [connection pooling](#connection-pooling-with-pgbouncer), connect to pgBouncer on `6432`.
:::

## Connect remotely

There are two ways to reach PostgreSQL from outside Zerops: the VPN (recommended for development) and public IP access (for external applications).

### Connect via Zerops VPN

The VPN puts your workstation on the project's private network, so you connect exactly as an internal service would.

1. [Install & set up zCLI](/references/cli)
2. [Start the Zerops VPN](/references/networking/vpn#start-vpn)
3. Use the connection details from **Peek access details** in the service detail
4. When finished, [stop the Zerops VPN](/references/networking/vpn#stop-vpn)

:::warning Important notes
* Connect to `5432`/`5433` without SSL/TLS over the VPN, since the tunnel already encrypts the traffic.
* Environment variables are **not** available over the VPN; copy the access details from the GUI.
* If a connection doesn't work, try the `.zerops` suffix on the hostname (e.g. `db.zerops`). See the [VPN troubleshooting page](/references/networking/vpn#troubleshooting).
:::

### Connect via public IP

Public access always goes through pgBouncer on port `6432` over TLS (see [Connection ports and TLS](#connection-ports-and-tls)), which also pools your connections. The read-only replica port (`5433`) is **not** exposed publicly. Route reads through your application logic instead.

:::tip Trusting the TLS certificate
The certificate on `6432` is signed by the Zerops Certificate Authority. To verify it from outside Zerops, download and trust the [Zerops CA](/references/networking/zerops-ca), for example `psql "... sslmode=verify-full sslrootcert=./zerops-ca.pem"`.
:::

To enable public access:

1. Open your PostgreSQL service in the GUI and go to **Public Access through IP Addresses**
2. Choose IPv6 (available by default) or IPv4 (requires the [unique IPv4](/references/networking/public-access#ipv4-configuration) add-on)
3. Open one or more ports pointing to your service (routed through pgBouncer):
   - Any port from 10–65435 (except 80 and 443)
   - Each public port can map to any internal port; multiple public ports can share one internal port
   - IPv4 and IPv6 can be configured independently
4. Optionally enable firewall protection
5. Click **Publish X IP access change(s)** to apply

## Database management tools

You can use any PostgreSQL-compatible tool to administer your database. For a zero-setup option, Zerops provides a ready-to-use recipe for [Adminer](https://www.adminer.org), a lightweight, full-featured web-based tool that supports PostgreSQL.

### Install Adminer

In the GUI, open your project, select **Import services**, and paste:

```yaml title="zerops-import.yaml"
services:
  - hostname: adminer
    type: php-apache@8.5
    maxContainers: 1
    enableSubdomainAccess: true
    buildFromGit: https://github.com/zeropsio/recipe-adminer
```

Then [start the VPN](/references/networking/vpn) and open `http://adminer` in your browser (try `http://adminer.zerops` if it doesn't resolve).

:::caution
Do not use `https` when reaching management tools over the VPN.
:::

### Desktop tools and psql

Popular desktop clients (pgAdmin, DBeaver, DataGrip, or any PostgreSQL-compatible tool) work with Zerops over the VPN:

1. [Start the Zerops VPN](/references/networking/vpn) to open an encrypted tunnel to your project
2. Copy the [connection details](#connection-details) from the GUI (environment variables aren't available over the VPN)
3. Connect without SSL/TLS on `5432`/`5433`, since the tunnel already encrypts the connection

For the `psql` command-line client:

```sh
psql -h [hostname] -U [user] -d [database_name]
```

`psql` has no password flag, so it prompts you. To pass the password non-interactively, use `PGPASSWORD`:

```sh
PGPASSWORD=[password] psql -h [hostname] -U [user] -d [database_name]
```

:::tip
Try `[hostname].zerops` instead of `[hostname]` if you hit connection issues over the VPN.
:::

To move data in and out with these tools, see [Export & import data](/postgresql/how-to/manage#export--import-data).


----------------------------------------

# Postgresql > How To > Control



----------------------------------------

# Postgresql > How To > Create


Create a PostgreSQL service in the [GUI](#create-in-the-gui), or describe it in YAML and [import](#import-with-yaml) it through the GUI or zCLI. Both paths configure the same things; the YAML route is repeatable and versionable.

## Create in the GUI

Go to your project dashboard and choose **Add new service** in the **Services** block:

[Video: /vids/services/postgres.webm](/vids/services/postgres.webm)

The wizard asks for four things:

### Version

### Hostname

A unique service identifier, like `db`, `sql`, or `postgresql`. Maximum 25 characters, lowercase ASCII letters (a-z) and numbers (0-9) only, unique within the project.

### Deployment mode

**Highly Available** (a 3-node cluster, recommended for production) or **Single container** (lower cost, no redundancy). See [Deployment modes](/postgresql/overview#deployment-modes) for the comparison.

### Scaling profile and resources

Pick a [scaling profile](/postgresql/how-to/scale#scaling-profiles) matched to your workload (OLTP, OLAP, or write-heavy). The profile sets the autoscaling defaults and tunes the PostgreSQL configuration; on top of it you can set the CPU mode (shared or dedicated) and minimum/maximum limits for CPU, RAM, and disk. See [Scale & profiles](/postgresql/how-to/scale) for details.

:::caution
The **hostname** and **deployment mode** are fixed once the service is created. The scaling **profile** and resource limits can be changed at any time.
:::

## Import with YAML

Zerops uses a YAML file to describe services declaratively. You can paste it in the GUI (**Import services** in the left menu of your project) or import it with the [zCLI](/references/cli).

### Add a service to an existing project

```yaml title="zerops-import.yaml"
services:
  - hostname: db
    # postgresql:{single|ha}@{version}
    type: postgresql:single@18
    # optional: autoscaling profile, see Scale & profiles
    profile: oltp-staging
```

With zCLI:

```sh
zcli project service-import zerops-import.yaml
```

The command is interactive: it lists your projects and lets you pick which one to import into. You can also pass the project ID directly with `-P`:

```sh
Usage:
  zcli project service-import importYamlPath [flags]

Flags:
  -h, --help                Help for the project service import command.
  -P, --project-id string   If you have access to more than one project, you must specify the project ID for which the
                           command will be executed.
```

### Create a new project

A project import additionally contains the `project:` section:

```yaml title="zerops-import.yaml"
project:
  name: my-project
  # optional: project description and tags
  description: A project with a PostgreSQL database
  tags:
    - DEMO
    - ZEROPS

services:
  - hostname: db
    type: postgresql:ha@18
    profile: oltp-production
    # optional: override the profile's autoscaling defaults
    verticalAutoscaling:
      cpuMode: DEDICATED
      minCpu: 2
      maxCpu: 5
      minRam: 2
      maxRam: 24
      minDisk: 6
      maxDisk: 50
      startCpuCoreCount: 3
      minFreeRamGB: 0.5
      minFreeRamPercent: 20
  - hostname: dbstaging
    type: postgresql:single@18
    profile: oltp-staging
```

```sh
zcli project project-import zerops-import.yaml
```

The project name comes from the YAML, so the command doesn't take one. If you are a member of more than one organization (called *client* in the GUI), pass the ID with `--org-id`; you'll find it under the client name on the project dashboard.

```sh
Usage:
  zcli project project-import importYamlPath [flags]

Flags:
  -h, --help                Help for the project import command.
      --org-id string        If you have access to more than one organization, you must specify the org ID for which the
                            project will be created.
      --working-dir string   Sets a custom working directory. The default working directory is the current directory. (default "./")
```

:::note
The maximum size of an import YAML is 100 kB. A project import can mix PostgreSQL with [any other service type](/references/import-yaml/type-list).
:::

### Project parameters

The `project:` section is required for a project import. Only one project can be defined.

<table className="w-full my-1.5">
  <thead>
    <tr>
      <th className="w-fit" style={{ minWidth: '130px' }}>Parameter</th>
      <th className="w-fit">Description</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td className="w-fit"><b>name</b></td>
      <td className="w-fit">The name of the new project. Duplicates are allowed.</td>
    </tr>
    <tr>
      <td className="w-fit"><b>description</b></td>
      <td className="w-fit"><b>Optional.</b> Description of the new project. Maximum 255 characters.</td>
    </tr>
    <tr>
      <td className="w-fit"><b>tags</b></td>
      <td className="w-fit"><b>Optional.</b> One or more string tags. Tags have no functional meaning, they only provide better orientation in projects.</td>
    </tr>
  </tbody>
</table>

### Service parameters

At least one service in the `services:` section is required.

<table className="w-full my-1.5">
  <thead>
    <tr>
      <th className="w-fit" style={{ minWidth: '160px' }}>Parameter</th>
      <th className="w-fit">Description</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td className="w-fit"><b>hostname</b></td>
      <td className="w-fit">
        The unique service identifier; becomes the database hostname on the project's private network. Maximum 25 characters, lowercase ASCII letters (a-z) and numbers (0-9) only, unique within the project. <b>Fixed after creation.</b>
      </td>
    </tr>
    <tr>
      <td className="w-fit"><b>type</b></td>
      <td className="w-fit">
        The service type, deployment mode, and version in <code>postgresql:&#123;single|ha&#125;@&#123;version&#125;</code> format. The <code>:single</code>/<code>:ha</code> part selects the [deployment mode](/postgresql/overview#deployment-modes) and is <b>fixed after creation</b>; the standalone <code>mode</code> field is deprecated. See the [list of supported types](/references/import-yaml/type-list#database-services).
      </td>
    </tr>
    <tr>
      <td className="w-fit"><b>profile</b></td>
      <td className="w-fit">
        <b>Optional.</b> The [autoscaling profile](/postgresql/how-to/scale#scaling-profiles): sets the autoscaling envelope and tunes the PostgreSQL configuration for your workload. Defaults to <code>oltp-staging</code> (single) or <code>oltp-production</code> (HA). Can be changed at any time in the GUI.
      </td>
    </tr>
    <tr>
      <td className="w-fit"><b>profileOverrides</b></td>
      <td className="w-fit">
        <b>Optional.</b> Only valid with <code>profile: custom</code>; overrides individual PostgreSQL configuration values. See [Custom profile](/postgresql/how-to/scale#custom-profile) for the overridable keys and their units.
      </td>
    </tr>
    <tr>
      <td className="w-fit"><b>verticalAutoscaling</b></td>
      <td className="w-fit">
        <b>Optional.</b> Overrides the profile's autoscaling defaults. All attributes are optional: <code>cpuMode</code> (<code>SHARED</code>/<code>DEDICATED</code>), <code>minCpu</code>/<code>maxCpu</code> (cores), <code>minRam</code>/<code>maxRam</code> (GB), <code>minDisk</code>/<code>maxDisk</code> (GB), <code>startCpuCoreCount</code>, <code>minFreeRamGB</code>, <code>minFreeRamPercent</code>. See [Configure scaling](/postgresql/how-to/scale#configure-scaling).
      </td>
    </tr>
  </tbody>
</table>


----------------------------------------

# Postgresql > How To > Manage


This guide covers the default database setup, installing extensions, backups, and moving data in and out. For connecting and management tools, see [Connect](/postgresql/how-to/connect).

## Default database and user

Zerops creates a default database and user automatically when a PostgreSQL service is [created](/postgresql/how-to/create).

- **Database name**: `db`
- **User**: `db`
- **Password**: randomly generated
- **Encoding**: `UTF8` (locale `C.UTF-8`)

Both names are fixed; they don't follow the service hostname. Besides the `db` user, Zerops also creates a `postgres` superuser for you (see [Extensions](#extensions)).

:::info
For connection methods, ports, and environment variables, see [Connect to PostgreSQL](/postgresql/how-to/connect).
:::

## Extensions

### List available extensions

Any user can list the extensions available to install (superuser not required):

```sql
SELECT * FROM pg_available_extensions ORDER BY name;
```

### Install an extension (requires superuser)

1. **Connect as the superuser.** Use the `superUser` (user `postgres`) and `superUserPassword` environment variables from your service.
2. **Switch to your service database.** As the superuser you start in the `postgres` database, not your service database.
3. **Create the extensions** you need:

   ```sql
   CREATE EXTENSION pg_stat_statements;
   CREATE EXTENSION vector;
   CREATE EXTENSION postgis;
   ```

:::warning
You can only install extensions already listed in `pg_available_extensions`; new extensions cannot be added.
:::

When configuring text search dictionaries, reference the correct `stop`, `dict`, and `affix` files. Zerops PostgreSQL ships the following:

#### Available dictionary files

**Stop word files**, used to remove common words that don't add significant meaning:
```
czech.stop
danish.stop
dutch.stop
english.stop
finnish.stop
french.stop
german.stop
hungarian.stop
italian.stop
nepali.stop
norwegian.stop
polish.stop
portuguese.stop
russian.stop
slovak.stop
spanish.stop
swedish.stop
turkish.stop
```
**Dictionary and affix files**, used for stemming and word normalization:
```
cs_CZ.affix
cs_CZ.dict
en_US.affix
en_US.dict
pl_PL.affix
pl_PL.dict
sk_SK.affix
sk_SK.dict
```
**Special rules file:**
```
unaccent.rules
```

See the [PostgreSQL text search documentation](https://www.postgresql.org/docs/current/textsearch-dictionaries.html) for more.

## Backups

Zerops automatically backs up PostgreSQL services with full encryption. For scheduling, retention, tagging, storage quotas, and manual backups (and the CLI tools), see [Zerops Backups](/features/backup). This section covers the PostgreSQL specifics.

### Backup format

- **Format**: `.zip` containing per-schema `.dump` files
- **Tooling**: `pg_dump`, custom format (`-Fc`), files named `schemaName.dump`
- **Storage**: encrypted, in isolated object storage

### Restore a backup

1. **Download** the backup `.zip` from the GUI
2. **Extract** it to get the per-schema `.dump` files
3. **Prepare** the target (clean existing data, or use a fresh instance)
4. **Restore** each schema with `pg_restore`. The dumps are custom format (`-Fc`), so plain `psql` can't read them:

   ```sh
   pg_restore -d [database_name] schemaName.dump
   ```

   See the [official PostgreSQL backup documentation](https://www.postgresql.org/docs/current/backup-dump.html) for restore options. To use a web UI like [Adminer](/postgresql/how-to/connect#database-management-tools), first convert a dump to plain SQL with `pg_restore -f schema.sql schemaName.dump` and import that SQL file.

### High availability

For HA services:
- Backups run on a randomly selected healthy node
- Other nodes stay operational during the backup
- Manual backups typically run on the primary node

### Best practices

- Take a manual backup with a protected tag before migrations or major schema changes
- Test your restore process periodically in a non-production environment
- Monitor backup storage usage in the Project Overview
- Use descriptive tags like `pre-migration-v2`
- Mind schema dependency order when restoring

## Export & import data

To move data in and out, first connect to your database, either over the [VPN](/postgresql/how-to/connect#connect-via-zerops-vpn) for a local tool or via [Adminer](/postgresql/how-to/connect#database-management-tools) in the browser.

### With Adminer or a desktop tool

Once connected, use the tool's built-in export/import functions. See [Database management tools](/postgresql/how-to/connect#database-management-tools) and [Desktop tools and psql](/postgresql/how-to/connect#desktop-tools-and-psql).

### With the command line

Export data and schema with [pg_dump](https://www.postgresql.org/docs/current/app-pgdump.html):

```sh
pg_dump [database_name] > dump.sql
```

Import a plain SQL dump with `psql`:

```sh
psql [database_name] < dump.sql
```

For a custom-format dump (`pg_dump -Fc`, the format Zerops backups use), use [pg_restore](https://www.postgresql.org/docs/current/app-pgrestore.html):

```sh
pg_restore -d [database_name] dump.dump
```

See [Desktop tools and psql](/postgresql/how-to/connect#desktop-tools-and-psql) for how to reach the database and pass the password with `PGPASSWORD`.


----------------------------------------

# Postgresql > How To > Scale


Zerops automatically scales your PostgreSQL service based on actual database usage. When your database needs more power, resources increase. When demand drops, resources scale down to reduce costs.

:::tip Read More
For complete scaling details across all services, see [Automatic Scaling and High Availability](/features/scaling).
:::

## How PostgreSQL scaling works

PostgreSQL services use **vertical scaling** to adjust CPU, RAM, and disk resources within containers based on usage patterns. Unlike runtime services, PostgreSQL does not use horizontal scaling (adding/removing containers). Instead, PostgreSQL services use deployment modes for high availability.

:::danger Scaling can briefly interrupt the service
When scaling changes the service's resources, Zerops regenerates the PostgreSQL configuration and applies it with an automatic **reload**. If the new values require it, the service is **restarted** instead: rolling through the cluster in HA mode, a short outage in single mode.

A restart is only needed when the granted RAM crosses a memory step: `256 MiB`, `512 MiB`, `1 GiB`, `2 GiB`, `4 GiB`, then multiples of `8 GiB`. Scaling within a step reloads only; to rule out restarts entirely, keep `minRam` and `maxRam` within one step.
:::

## Scaling profiles

A **scaling profile** is the starting point for a PostgreSQL service. Each profile sets two things at once:

1. **The autoscaling envelope**: the default minimum/maximum CPU, RAM, and disk, plus the free-resource headroom that controls how eagerly the autoscaler reacts.
2. **The PostgreSQL configuration**: memory, WAL, planner, autovacuum, and replication settings tuned for a specific workload shape.

A profile name combines a **workload type** with a **tier**, e.g. `oltp-production`.

### Workload types

<table className="w-full my-1.5">
  <thead>
    <tr>
      <th className="w-fit" style={{ minWidth: '105px' }}>Type</th>
      <th className="w-fit">Tuned for</th>
      <th className="w-fit">Notes</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td className="w-fit"><b>OLTP</b></td>
      <td className="w-fit">Transactional workloads like web apps, APIs, order processing, and auth. Short transactions and point lookups.</td>
      <td className="w-fit">The default and most general-purpose type. Synchronous replication in HA.</td>
    </tr>
    <tr>
      <td className="w-fit"><b>OLAP</b></td>
      <td className="w-fit">Analytical workloads like reporting, dashboards, and large aggregations.</td>
      <td className="w-fit">Larger sort/hash memory, aggressive query parallelism, higher-resolution planner statistics. <b>Asynchronous</b> replication in HA (synchronous commits would throttle bulk loads).</td>
    </tr>
    <tr>
      <td className="w-fit"><b>WriteHeavy</b></td>
      <td className="w-fit">High-volume ingestion like IoT telemetry, event logging, and metrics.</td>
      <td className="w-fit">Commit batching, WAL compression, and aggressive autovacuum to keep up with write volume. Synchronous replication in HA.</td>
    </tr>
  </tbody>
</table>

### Available profiles

The tier part of the name sets the size of the autoscaling envelope (and, in HA, the replication topology). Which profiles you can pick depends on the deployment mode:

<table className="w-full my-1.5">
  <thead>
    <tr>
      <th className="w-fit" style={{ minWidth: '165px' }}>Profile</th>
      <th className="w-fit">Mode</th>
      <th className="w-fit">Use it for</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td className="w-fit"><code>oltp-hobby</code></td>
      <td className="w-fit">Single</td>
      <td className="w-fit">Side projects, prototypes, learning. Runs hot with minimal headroom to keep costs low.</td>
    </tr>
    <tr>
      <td className="w-fit"><code>oltp-staging</code></td>
      <td className="w-fit">Single / HA</td>
      <td className="w-fit">Staging, internal tools, early-stage apps. Moderate headroom. <b>Default for single.</b></td>
    </tr>
    <tr>
      <td className="w-fit"><code>oltp-production</code></td>
      <td className="w-fit">Single / HA</td>
      <td className="w-fit">Business-critical transactional workloads. Generous headroom for traffic spikes. <b>Default for HA.</b></td>
    </tr>
    <tr>
      <td className="w-fit"><code>oltp-enterprise</code></td>
      <td className="w-fit">HA only</td>
      <td className="w-fit">High-throughput OLTP at scale. Highest connection limits and the most aggressive headroom.</td>
    </tr>
    <tr>
      <td className="w-fit"><code>olap-production</code></td>
      <td className="w-fit">Single / HA</td>
      <td className="w-fit">Analytical / warehouse workloads.</td>
    </tr>
    <tr>
      <td className="w-fit"><code>writeheavy-production</code></td>
      <td className="w-fit">Single / HA</td>
      <td className="w-fit">Ingestion pipelines and write-heavy workloads.</td>
    </tr>
    <tr>
      <td className="w-fit"><code>custom</code></td>
      <td className="w-fit">Single / HA</td>
      <td className="w-fit">OLTP-based profile that lets you override individual PostgreSQL settings. See [Custom profile](#custom-profile).</td>
    </tr>
  </tbody>
</table>

:::note
In **HA** mode the OLTP and WriteHeavy profiles run with two synchronous standbys, so an acknowledged `COMMIT` survives a node failure. OLAP runs with asynchronous standbys, trading a small potential window of recent writes for ingest speed.
:::

### Setting a profile

Set the profile when you create the service in the GUI, or with the `profile` field in your [import YAML](/postgresql/how-to/create#import-with-yaml):

```yaml title="zerops-import.yaml"
services:
  - hostname: db
    type: postgresql:ha@18
    profile: oltp-production
```

If you don't set one, the default is used (`oltp-staging` for single, `oltp-production` for HA). **The profile can be changed at any time** in the GUI.

### Overriding the autoscaling envelope

The resource limits a profile sets are defaults. You can override any of them (CPU mode, min/max CPU/RAM/disk, and the free-resource thresholds) **without switching to the custom profile**, using the [`verticalAutoscaling`](/postgresql/how-to/create#service-parameters) block in your import YAML or the **Automatic scaling configuration** in the GUI. These overrides apply on top of any profile.

### Custom profile

The `custom` profile uses the **OLTP** tuning as its base and additionally lets you override individual PostgreSQL configuration values through `profileOverrides`:

```yaml title="zerops-import.yaml"
services:
  - hostname: db
    type: postgresql:single@18
    profile: custom
    profileOverrides:
      random_page_cost: 1.1
      default_statistics_target: 200
      autovacuum_max_workers: 5
      work_mem: 67108864           # bytes (64 MiB)
      autovacuum_naptime: 120000000000  # nanoseconds (2 minutes)
```

Settings that Zerops derives from the container's resources or that are required for the managed cluster to operate (`shared_buffers`, `max_connections`, JIT on/off, the pooler limits, and the replication/Patroni settings) are managed automatically and **cannot** be overridden.

Refer to the [PostgreSQL configuration documentation](https://www.postgresql.org/docs/current/runtime-config.html) for the meaning and valid range of each parameter, but **mind the units**: override values are plain numbers, with memory/disk sizes given in **bytes** and durations in **nanoseconds**. This differs from PostgreSQL's own conventions (kB, milliseconds, seconds). The table below shows which unit each key takes.

#### Overridable configuration keys

<table className="w-full my-1.5">
  <thead>
    <tr>
      <th className="w-fit">Key</th>
      <th className="w-fit" style={{ minWidth: '115px' }}>Type / unit</th>
      <th className="w-fit">Description</th>
    </tr>
  </thead>
  <tbody>
    <tr><td className="w-fit"><code>work_mem</code></td><td className="w-fit">bytes</td><td className="w-fit">Memory per sort/hash operation before spilling to disk</td></tr>
    <tr><td className="w-fit"><code>hash_mem_multiplier</code></td><td className="w-fit">integer</td><td className="w-fit">Multiplier applied to work_mem for hash-based operations</td></tr>
    <tr><td className="w-fit"><code>maintenance_work_mem</code></td><td className="w-fit">bytes</td><td className="w-fit">Memory for maintenance operations (VACUUM, CREATE INDEX, REINDEX)</td></tr>
    <tr><td className="w-fit"><code>autovacuum_work_mem</code></td><td className="w-fit">bytes</td><td className="w-fit">Memory used by each autovacuum worker</td></tr>
    <tr><td className="w-fit"><code>temp_buffers</code></td><td className="w-fit">bytes</td><td className="w-fit">Per-session memory for accessing temporary tables</td></tr>
    <tr><td className="w-fit"><code>temp_file_limit</code></td><td className="w-fit">bytes</td><td className="w-fit">Maximum total disk space a session may use for temporary files</td></tr>
    <tr><td className="w-fit"><code>effective_cache_size</code></td><td className="w-fit">bytes</td><td className="w-fit">Planner's assumption of total cache available (shared_buffers + OS cache)</td></tr>
    <tr><td className="w-fit"><code>effective_io_concurrency</code></td><td className="w-fit">integer</td><td className="w-fit">Estimated number of concurrent disk I/O operations the storage can handle</td></tr>
    <tr><td className="w-fit"><code>maintenance_io_concurrency</code></td><td className="w-fit">integer</td><td className="w-fit">Concurrent disk I/O operations for maintenance (VACUUM, prefetch)</td></tr>
    <tr><td className="w-fit"><code>random_page_cost</code></td><td className="w-fit">number</td><td className="w-fit">Planner's estimated cost of a non-sequential page fetch</td></tr>
    <tr><td className="w-fit"><code>default_statistics_target</code></td><td className="w-fit">integer</td><td className="w-fit">Default number of samples used by ANALYZE for column statistics</td></tr>
    <tr><td className="w-fit"><code>jit_above_cost</code></td><td className="w-fit">number</td><td className="w-fit">Query plan cost above which JIT compilation is considered</td></tr>
    <tr><td className="w-fit"><code>max_worker_processes</code></td><td className="w-fit">integer</td><td className="w-fit">Maximum number of background worker processes</td></tr>
    <tr><td className="w-fit"><code>max_parallel_workers</code></td><td className="w-fit">integer</td><td className="w-fit">Maximum parallel workers that can be active at one time cluster-wide</td></tr>
    <tr><td className="w-fit"><code>max_parallel_workers_per_gather</code></td><td className="w-fit">integer</td><td className="w-fit">Maximum parallel workers a single Gather node can start</td></tr>
    <tr><td className="w-fit"><code>max_parallel_maintenance_workers</code></td><td className="w-fit">integer</td><td className="w-fit">Maximum parallel workers for maintenance (CREATE INDEX, VACUUM)</td></tr>
    <tr><td className="w-fit"><code>wal_compression</code></td><td className="w-fit">string</td><td className="w-fit">Compression algorithm for full-page WAL images (off/pglz/lz4/zstd)</td></tr>
    <tr><td className="w-fit"><code>wal_buffers</code></td><td className="w-fit">bytes</td><td className="w-fit">Shared memory used to buffer WAL data not yet written to disk</td></tr>
    <tr><td className="w-fit"><code>wal_writer_delay</code></td><td className="w-fit">nanoseconds</td><td className="w-fit">Interval at which the WAL writer flushes WAL to disk</td></tr>
    <tr><td className="w-fit"><code>wal_writer_flush_after</code></td><td className="w-fit">bytes</td><td className="w-fit">WAL bytes written before the WAL writer triggers a flush</td></tr>
    <tr><td className="w-fit"><code>commit_delay</code></td><td className="w-fit">nanoseconds</td><td className="w-fit">Artificial delay before a WAL flush during commit to batch concurrent commits</td></tr>
    <tr><td className="w-fit"><code>commit_siblings</code></td><td className="w-fit">integer</td><td className="w-fit">Minimum number of concurrent open transactions required for commit_delay to apply</td></tr>
    <tr><td className="w-fit"><code>max_wal_size</code></td><td className="w-fit">bytes</td><td className="w-fit">Soft upper limit on WAL size that triggers a checkpoint</td></tr>
    <tr><td className="w-fit"><code>min_wal_size</code></td><td className="w-fit">bytes</td><td className="w-fit">Minimum WAL size kept for future reuse before recycling segments</td></tr>
    <tr><td className="w-fit"><code>autovacuum_max_workers</code></td><td className="w-fit">integer</td><td className="w-fit">Maximum autovacuum worker processes running concurrently</td></tr>
    <tr><td className="w-fit"><code>autovacuum_naptime</code></td><td className="w-fit">nanoseconds</td><td className="w-fit">Delay between autovacuum runs on any given database</td></tr>
    <tr><td className="w-fit"><code>autovacuum_vacuum_scale_factor</code></td><td className="w-fit">number</td><td className="w-fit">Fraction of table size added to the autovacuum threshold</td></tr>
    <tr><td className="w-fit"><code>autovacuum_analyze_scale_factor</code></td><td className="w-fit">number</td><td className="w-fit">Fraction of table size added to the auto-analyze threshold</td></tr>
    <tr><td className="w-fit"><code>autovacuum_vacuum_cost_delay</code></td><td className="w-fit">nanoseconds</td><td className="w-fit">Cost-based delay inserted by autovacuum between I/O operations</td></tr>
    <tr><td className="w-fit"><code>autovacuum_vacuum_cost_limit</code></td><td className="w-fit">integer</td><td className="w-fit">Accumulated vacuum cost at which an autovacuum worker sleeps</td></tr>
    <tr><td className="w-fit"><code>vacuum_cost_delay</code></td><td className="w-fit">nanoseconds</td><td className="w-fit">Cost-based delay inserted by manual VACUUM between I/O operations (0 disables)</td></tr>
    <tr><td className="w-fit"><code>idle_in_transaction_session_timeout</code></td><td className="w-fit">nanoseconds</td><td className="w-fit">Terminate sessions that stay idle in a transaction longer than this</td></tr>
  </tbody>
</table>

## Configure scaling

You can configure scaling settings:

- **During service creation** - Set initial scaling parameters when [creating](/postgresql/how-to/create) your PostgreSQL service
- **During import** - Define scaling configuration in your YAML import file using `verticalAutoscaling` parameters
- **After service creation** - Navigate to your PostgreSQL service and select **Automatic scaling configuration** to modify settings

### Basic settings

**CPU Mode**: Choose between shared (cost-effective, variable performance) or dedicated (consistent performance, higher cost). You can change CPU mode once per hour. See [pricing](https://zerops.io/#pricing) for costs.

**Resource limits**: Configure minimum and maximum resources for your PostgreSQL service:

- **Lower the maximum** to control costs and prevent over-scaling
- **Raise the minimum** when you need guaranteed baseline performance
- **Set minimum = maximum** to disable automatic scaling for that specific resource

**Deployment mode** (single container vs. highly available) is chosen when the service is created and cannot be changed later. See [Deployment modes](/postgresql/overview#deployment-modes).

### High availability

In HA mode, Zerops runs a 3-node cluster across separate physical machines, fronted by two database proxy containers (free of charge) that route traffic. When a container fails, Zerops automatically replaces it on a different machine and synchronizes data from the healthy copies.

A dedicated **read-replica port (`5433`)** lets you route read-only queries to the replicas, taking load off the primary and improving throughput. See [Connection parameters](/postgresql/how-to/connect#connection-parameters) and [Connection ports and TLS](/postgresql/how-to/connect#connection-ports-and-tls).

### Advanced settings

**Start CPU cores**: Determines how many CPU cores are allocated during database startup. Increase this value if your PostgreSQL service starts slowly or requires more processing power during initialization.

**RAM thresholds**: Help prevent out-of-memory crashes by maintaining buffer space:

- **Absolute (GB)**: Maintains this amount of free RAM at all times
- **Percentage**: Keeps this percentage of total RAM free

Consider increasing these values if your database experiences memory-related issues.

:::info Read More
For detailed technical parameters and scaling behavior, see [Automatic Scaling and High Availability](/features/scaling#resource-scaling-behavior).
:::

## Monitor usage

Navigate to your PostgreSQL service and select **Service containers & Overview** to view:
- CPU, RAM, and disk usage over time
- Historical scaling events
- Container health status

## Technical details

Zerops monitors database usage and automatically adjusts resources based on predefined thresholds and timing parameters. The scaling behavior follows the same principles as other services on the platform.

For complete technical specifications including:
- Resource monitoring intervals and thresholds
- Scale-up and scale-down timing parameters
- Scaling increments and steps
- Detailed scaling behavior patterns

See [Resource Scaling Behavior](/features/scaling#resource-scaling-behavior) in the general scaling documentation.

## Common issues

**Out of memory errors**
- Increase minimum free RAM settings in your scaling configuration
- Consider raising the minimum RAM allocation
- Check for memory-intensive queries or operations

**Higher than expected costs**
- Consider lowering your maximum resource limits
- Review scaling patterns in the monitoring dashboard

**Slow database startup**
- Increase the "Start CPU cores" setting
- Consider switching to dedicated CPU mode for consistent performance

**Not utilizing HA mode effectively**
- Use port `5432` for write operations (INSERT, UPDATE, DELETE)
- Use port `5433` for read operations (SELECT) to distribute load across replicas
- See [Connection Parameters](/postgresql/how-to/connect#connection-parameters) for details

*Need help? Join our [Discord community](https://discord.gg/zerops) for assistance!*


----------------------------------------

# Postgresql > Overview


[PostgreSQL ↗](https://www.postgresql.org/) is a powerful, open-source object-relational database with a 35-year track record for reliability, robustness, and performance. On Zerops it runs as a **fully managed service**: automated encrypted backups, vertical autoscaling, optional high availability with automatic failover, and a configuration tuned to your workload, with no server to administer.

## Quick start

Add a PostgreSQL service to your project with a `zerops-import.yaml`:

```yaml title="zerops-import.yaml"
services:
  - hostname: db
    # type is postgresql:{mode}@{version}
    type: postgresql:single@18
    # workload-tuned autoscaling profile
    profile: oltp-staging
```

Import it with the zCLI:

```bash
zcli project service-import zerops-import.yaml
```

The moment the container boots you have a working database. See [Create & import](/postgresql/how-to/create) for the GUI flow and the full configuration reference.

## What you get out of the box

- **A default database and user**, both named `db` (encoding `UTF8`, locale `C.UTF-8`), with a randomly generated password.
- **Connection details and environment variables**, including hostname, ports, and ready-made connection strings. See [Connect](/postgresql/how-to/connect).
- **Workload-tuned configuration** via the [scaling profile](/postgresql/how-to/scale#scaling-profiles) you choose (OLTP, OLAP, or write-heavy).
- **Automated, encrypted backups** stored in isolated object storage. See [Manage & data](/postgresql/how-to/manage#backups).
- **Vertical autoscaling** that grows and shrinks CPU, RAM, and disk with real usage.

### Supported versions

## Deployment modes

Choose the reliability model when you create the service. It is set through the service `type` and is **fixed for the life of the service**.

<table className="w-full my-1.5">
  <thead>
    <tr>
      <th className="w-fit" style={{ minWidth: '75px' }}>Mode</th>
      <th className="w-fit" style={{ minWidth: '200px' }}>type</th>
      <th className="w-fit">What it is</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td className="w-fit"><b>Highly Available</b></td>
      <td className="w-fit"><code>postgresql:ha@N</code></td>
      <td className="w-fit">A 3-node cluster spread across separate physical machines, with data stored redundantly, automatic failover, and a read-replica port. Recommended for production.</td>
    </tr>
    <tr>
      <td className="w-fit"><b>Single container</b></td>
      <td className="w-fit"><code>postgresql:single@N</code></td>
      <td className="w-fit">One container, so lower cost but no redundancy. Data since the last backup is lost if it fails. Good for development and non-critical workloads.</td>
    </tr>
  </tbody>
</table>

:::tip
In HA mode, route read-only queries to the replica port (`5433`) to take load off the primary. See [Scale &amp; profiles](/postgresql/how-to/scale#high-availability) and [Connection ports and TLS](/postgresql/how-to/connect#connection-ports-and-tls).
:::

## Next steps

- [Create & import](/postgresql/how-to/create) — Create a service in the GUI or with zerops-import.yaml.
- [Connect](/postgresql/how-to/connect) — Ports, TLS, pooling, env vars, VPN, and management tools.
- [Scale & profiles](/postgresql/how-to/scale) — Autoscaling, workload profiles, and high availability.
- [Manage & data](/postgresql/how-to/manage) — Users, extensions, backups, and export/import.

## Need help?

Stuck, or want to share what you built? Our core team and community are on Discord.

- [Discord](https://discord.com/invite/WDvCZ54) — Join the Zerops community on Discord. Ask questions and share your tips.
- [zCLI](/references/cli) — Get more out of Zerops with the command-line tool.


----------------------------------------

# Python > How To > Build Pipeline


Zerops provides a customizable build and runtime environment for your Python application.

## Add zerops.yaml to your repository

Start by adding `zerops.yaml` file to the **root of your repository** and modify it to fit your application:

```yaml
zerops:
  # define hostname of your service
  - setup: app
    # ==== how to build your application ====
    build:
      # REQUIRED. Set the base technology for the build environment:
      base: python@latest

      # OPTIONAL. Set the operating system for the build environment.
      # os: ubuntu

      # OPTIONAL. Customize the build environment by installing additional packages
      # or tools to the base build environment.
      # prepareCommands:
      #   - sudo apt-get something
      #   - curl something else

      # REQUIRED. Select which files / folders to deploy after
      # the build has successfully finished
      deployFiles:
        - app.py

      # OPTIONAL. Copy files from build container to runtime container.
      addToRunPrepare:
        - requirements.txt

      # OPTIONAL. Which files / folders you want to cache for the next build.
      # Next builds will be faster when the cache is used.
      # cache: file.txt

    # ==== how to run your application ====
    run:
      # OPTIONAL. Sets the base technology for the runtime environment:
      base: python@latest

      # OPTIONAL. Sets the internal port(s) your app listens on:
      ports:
        # port number
        - port: 8000

      # OPTIONAL. Customize the runtime Python environment by installing additional
      # dependencies to the base Python runtime environment.
      # prepareCommands:
      #   - python3 -m pip install --ignore-installed -r requirements.txt

      # OPTIONAL. Run one or more commands each time a new runtime container
      # is started or restarted. These commands are triggered before
      # your Python application is started.
      # initCommands:
      #  - rm -rf ./cache

      # REQUIRED. Your Python application start command
      start: python3 app.py
```

The top-level element is always `zerops`.

### Setup

The first element `setup` contains the **hostname** of your service. A runtime service with the same hostname must exist in Zerops.
Zerops supports the definition of multiple runtime services in a single `zerops.yaml`. This is useful when you use a monorepo. Just add multiple setup elements in your `zerops.yaml`:

```yaml
zerops:
  # definition for app service
  - setup: app
    # optional
    build: ...
    # optional
    deploy: ...
    # required
    run: ...

  # definition for api service
  - setup: api
    # optional
    build: ...
    # optional
    deploy: ...
    # required
    run: ...
```

Each service configuration contains at least the `run` section. Optional `build` and `deploy` sections can be added to further customize your process.

## Build pipeline configuration

### base

_REQUIRED._ Sets the base technology for the build environment.

Following options are available for Python builds:

- `python@3.14 (Ubuntu only)`, `python@latest`
- `python@3.12`
- `python@3.11`

```yaml
zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build:
      # REQUIRED. Sets the base technology for the build environment:
      base: python@latest
      ...
```

<p>
  The base build environment contains {data.alpine.default}, the selected
  major version of Python, [Zerops command line tool](/references/cli), `pip` and `git`.
</p>

:::info
You can change the base environment when you need to. Just simply modify the `zerops.yaml` in your repository.
:::

If you need to install more technologies to the build environment, set multiple values as a yaml array. For example:

```yaml
zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build:
      # REQUIRED. Sets the base technology for the build environment:
      base:
        - python@latest
      prepareCommands:
        - zsc add go@latest
      ...
```

See the full list of supported [build base environments](/zerops-yaml/base-list#runtime-services).

To customize your build environment use the [prepareCommands](#preparecommands) attribute.

:::note
Modifying the base technology will invalidate your build cache. See our [Build Cache Documentation](/features/build-cache) for more details about cache invalidation.
:::

### os

_OPTIONAL._ Sets the operating system for the build environment.

Following options are available:

- `alpine`
- `ubuntu`

Default value is `alpine`.

We are currently using following os version:

- <span>{data.alpine.default}</span>
- <span>{data.ubuntu.default}</span>

:::caution
The os version is fixed and cannot be customized.
:::

:::note
Changing the OS setting will invalidate your build cache. See our [Build Cache Documentation](/features/build-cache) for details about cache behavior.
:::

### prepareCommands

_OPTIONAL._ Customizes the build environment by installing additional dependencies or tools to the base build environment.

The base build environment contains:

- <span>{data.alpine.default}</span>
- selected version of Python defined in the [base](#base) attribute
- [Zerops command line tool](/references/cli)
- `pip` and `git`

To install additional packages or tools add one or more prepare commands:

```yaml
zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build:
      # REQUIRED. Set the base technology for the build environment:
      base: python@latest

      # OPTIONAL. Customize the build environment by installing additional packages
      # or tools to the base build environment.
      prepareCommands:
        - sudo apt install python3-pip # already installed for Python services
      ...
```

When the first build is triggered, Zerops will

1. create a build container
2. download your application code from your repository
3. run the prepare commands in the defined order

The application code is available in `/build/source` before the prepare commands are triggered, so you can use any file from your repository in your prepare commands (e.g. a configuration file). The commands themselves run in the `/home/zerops` directory.

:::note
These commands are skipped when using cached environment. Modifying `prepareCommands` will invalidate your build cache. See our [Build Cache Documentation](/features/build-cache) for details about cache invalidation.
:::

#### Command exit code

If any command fails, it returns an exit code other than 0 and the build is canceled. Read the [build log](/python/how-to/logs#build-log) to troubleshoot the error. If the command ends successfully, it returns the exit code 0 and Zerops triggers the following command. When all prepare commands are finished, your custom build environment is ready for the build phase.

#### Run prepare commands as a single shell instance

Use following syntax to run all commands in the same environment context. For example, if one command changes the current directory, the next command continues in that directory. When one command creates an environment variable, the next command can access it.

```yaml
prepareCommands:
  - |
    sudo apt update
    sudo apt install python3-pip # already installed for Python services
```

#### Run prepare commands as a separate shell instances

When the following syntax is used, each command is triggered in a separate environment context. For example, each shell instance starts in the home directory again. When one command creates an environment variable, it won't be available for the next command.

```yaml
prepareCommands:
  - sudo apt update
  - sudo apt install python3-pip # already installed for Python services
```

### deployFiles

_REQUIRED._ Selects which files or folders will be deployed after the build has successfully finished. To filter out specific files or folders, use [`.deployignore`](#deployignore) file.

```yaml
# REQUIRED. Select which files / folders to deploy after
# the build has successfully finished
deployFiles:
  - app.py
```

Determines files or folders produced by your build, which should be deployed to your runtime service containers.

The path starts from the **root directory** of your project (the location of `zerops.yaml`). You must enclose the name in quotes if the folder or the file name contains a space.

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

#### Examples

Deploys a folder, and a file from the project root directory:

```yaml
deployFiles:
  - app.py
```

Deploys the whole content of the build container:

```yaml
deployFiles: .
```

Deploys a folder, and a file in a defined path:

```yaml
deployFiles:
  - ./path/to/file.txt
  - ./path/to/dir/
```

#### How to use a wildcard in the path

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

Deploys all folders that are located in any path that begins with `/path/to/`

```yaml
deployFiles: ./path/to/~/
```

Deploys all folders that are located in any path that begins with `/path/` and ends with `/to/`

```yaml
deployFiles: ./path/~/to/
```

:::note Example
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 will be cached for the next build.

```yaml
# OPTIONAL. Which files / folders you want to cache for the next build.
# Next builds will be faster when the cache is used.
cache: file.txt
```

The cache attribute helps optimize build times by preserving specified files between builds.

The cache attribute supports the [~ wildcard character](#how-to-use-a-wildcard-in-the-path).

Learn more about the [build cache system](/features/build-cache) in Zerops.

### envVariables

_OPTIONAL._ Defines the environment variables for the build environment.

Enter one or more env variables in following format:

```yaml
zerops:
  # define hostname of your service
  - setup: app
    # ==== how to build your application ====
    build:
      base: python@latest
        …

      # OPTIONAL. Defines the env variables for the build environment:
      envVariables:
        PYTHON_ENV: production
        DB_NAME: db
        DB_HOST: db
        DB_USER: db
        DB_PASS: ${db_password}
```

Read more about [environment variables](/python/how-to/env-variables) in Zerops.

## Runtime configuration

### base

_OPTIONAL._ Sets the base technology for the runtime environment.
If you don't specify the `run.base` attribute, Zerops keeps the current Python version for your runtime.

Following options are available for Python builds:

- `python@3.14 (Ubuntu only)`, `python@latest`
- `python@3.12`
- `python@3.11`

```yaml
zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build:
      # REQUIRED. Sets the base technology for the build environment:
      base: python@latest
      ...

    # ==== how to run your application ====
    run:
      # OPTIONAL. Sets the base technology for the runtime environment:
        base: python@latest
      ...
```

<p>
  The base runtime environment contains {data.alpine.default}, the
  selected major version of Python, [Zerops command line tool](/references/cli), `pip` and `git`.
</p>

:::info
You can change the base environment when you need to. Just simply modify the `zerops.yaml` in your repository.
:::

If you need to install more technologies to the runtime environment, set multiple values as a yaml array. For example:

```yaml
zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build:
      # REQUIRED. Sets the base technology for the build environment:
      base: python@latest
      ...

    # ==== how to run your application ====
    run:
      # OPTIONAL. Sets the base technology for the runtime environment:
      base:
        - python@latest
      prepareCommands:
        - zsc add go@latest
      ...
```

See the full list of supported [run base environments](/zerops-yaml/base-list).

To customize your build environment use the `prepareCommands` attribute.

### os

_OPTIONAL._ Sets the operating system for the runtime environment.

Following options are available:

- `alpine`
- `ubuntu`

Default value is `alpine`.

We are currently using following os version:

- <span>{data.alpine.default}</span>
- <span>{data.ubuntu.default}</span>

:::caution
The os version is fixed and cannot be customised.
:::

### ports

_OPTIONAL._ Specifies one or more internal ports on which your application will listen.

Projects in Zerops represent a group of one or more services. Services can be of different types (runtime services, databases, message brokers, object storage, etc.). All services of the same project share a **dedicated private network**. To connect to a service within the same project, just use the service hostname and its internal port.

For example, to connect to a Python service with hostname = "app" and port = 8000 from another service of the same project, simply use `app:8000`. Read more about [how to access a Python service](/references/networking/internal-access#basic-service-communication).

Each port has following attributes:

<table className="w-full my-1.5">
  <thead>
    <tr>
      <th className="w-fit"><strong>Parameter</strong></th>
      <th className="w-fit"><strong>Description</strong></th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td className="w-fit">port</td>
      <td className="w-fit">Defines the port number. You can set any port number between <em>10</em> and <em>65435</em>. Ports outside this interval are reserved for internal Zerops systems.</td>
    </tr>
    <tr>
      <td className="w-fit">protocol</td>
      <td className="w-fit"><strong>Optional.</strong> Defines the protocol. Allowed values are <code>TCP</code> or <code>UDP</code>. Default value is <code>TCP</code>.</td>
    </tr>
    <tr>
      <td className="w-fit">httpSupport</td>
      <td className="w-fit"><strong>Optional.</strong> <code>httpSupport = true</code> is the default setting for TCP protocol. Set <code>httpSupport = false</code> if a web server isn't running on the port. Zerops uses this information for the configuration of [public access](/features/access). <code>httpSupport = true</code> is available only in combination with the TCP protocol.</td>
    </tr>
  </tbody>
</table>

### prepareCommands

_OPTIONAL._ Customises the Python runtime environment by installing additional dependencies or tools to the runtime base environment.

<p>
  The base Python environment contains {data.alpine.default}, the selected
  major version of Python, [Zerops command line tool](/references/cli), `pip` and `git`. To install additional packages or tools add one or more
  prepare commands:
</p>

```yaml
zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build:
      ...

    # ==== how to run your application ====
    run:
      # OPTIONAL. Customise the runtime environment by installing additional packages
      # or tools to the base Python runtime environment.
      prepareCommands:
        - python3 -m pip install --ignore-installed -r requirements.txt
      ...
```

When the first deploy with a defined prepare attribute is triggered, Zerops will

1. create a prepare runtime container
2. optionally: [copy selected folders or files from your build container](#copy-folders-or-files-from-your-build-container)
3. run the `prepareCommands` commands in the defined order

:::note
`run.prepareCommands` run in the `/home/zerops` directory.
:::

#### Command exit code

If any command fails, it returns an exit code other than 0 and the deploy is canceled. Read the [prepare runtime log](/python/how-to/logs#prepare-runtime-log) to troubleshoot the error. If the command ends successfully, it returns the exit code 0 and Zerops triggers the following command. When all `prepareCommands` commands are finished, your custom runtime environment is ready for the deploy phase.

#### Cache of your custom runtime environment

Some packages or tools can take a long time to install. Therefore, Zerops caches your custom runtime environment after the installation of your custom packages or tools is completed. When the second or following deploy is triggered, Zerops will use the custom runtime cache from the previous deploy if following conditions are met:

1. Content of the [build.addToRunPrepare](#copy-folders-or-files-from-your-build-container) and `run.prepareCommands` attributes didn't change from the previous deploy
2. The custom runtime cache wasn't invalidated in the Zerops GUI.

To invalidate the Zerops runtime cache go to your service detail in Zerops GUI, choose **Service dashboard & runtime containers** from the left menu and click on the **Open pipeline detail** button. Then click on the **Clear runtime prepare cache** button.

When the prepare cache is used, Zerops doesn't create a prepare runtime container and executes the deployment of your application directly.

#### Single or separated shell instances

You can configure your prepare commands to be run in a single shell instance or multiple shell instances. The format is identical to [build:prepareCommands](#preparecommands).

### Copy folders or files from your build container

<p>
  The prepare runtime container contains {data.alpine.default} the
  selected major version of Python, [Zerops command line tool](/references/cli), `pip` and `git`.
</p>

The prepare runtime container does not contain your application code nor the built application. If you need to copy some folders or files from the build container to the runtime container (e.g. a configuration file) use the `addToRunPrepare` attribute in the [build section](#build-pipeline-configuration).

```yaml
zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build:
      ...
      addToRunPrepare:
        - requirements.txt

    # ==== how to run your application ====
    run:
      # OPTIONAL. Customise the runtime environment by installing additional packages
      # or tools to the base Python runtime environment.
      prepareCommands:
        - python3 -m pip install --ignore-installed -r requirements.txt
      ...
```

In the example above Zerops will copy the `runtime-config.yaml` file from your build container **after the build has finished** into the new **prepare runtime** container. The copied files and folders will be available in the `/home/zerops` folder in the new prepare runtime container before the prepare commands are triggered.

### initCommands

_OPTIONAL._ Defines one or more commands to be run each time a new runtime container is started or a container is restarted.

```yaml
zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build: ...

    # ==== how to run your application ====
    run:
      # OPTIONAL. Run one or more commands each time a new runtime container
      # is started or restarted. These commands are triggered before
      # your Python application is started.
      initCommands:
        - rm -rf ./cache
```

These commands are triggered in the runtime container before your Python application is started via the [start command](#start).

:::note
`run.initCommands` run in the `/var/www` directory.
:::

Use init commands to clean or initialise your application cache or similar operations.

:::caution
The init commands will delay the start of your application each time a new runtime container is started (including the horizontal [scaling](/python/how-to/scaling) or when a runtime container is restarted).

Do not use the init commands for customising your runtime environment. Use the [run:prepareCommands](#preparecommands-1) attribute instead.
:::

#### Command exit code

If any of the `initCommands` fails, it returns an exit code other than 0, but deploy is **not** canceled. After all init commands are finished, regardless of the status code, the application is started. Read the [runtime log](/python/how-to/logs#runtime-log) to troubleshoot the error.

#### Single or separated shell instances

You can configure your `initCommands` to be run in a single shell instance or multiple shell instances. The format is identical to [build:prepareCommands](#preparecommands).

### envVariables

_OPTIONAL._ Defines the environment variables for the runtime environment.

Enter one or more env variables in following format:

```yaml
zerops:
  # define hostname of your service
  - setup: app
    # ==== how to run your application ====
    run:
      # OPTIONAL. Defines the env variables for the runtime environment:
      envVariables:
        PYTHON_ENV: production
        DB_NAME: db
        DB_HOST: db
        DB_USER: db
        DB_PASS: ${db_password}
```

Read more about [environment variables](/python/how-to/env-variables) in Zerops.

### start

_REQUIRED._ Defines the start command for your Python application.

```yaml
zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build: ...

    # ==== how to run your application ====
    run:
      # REQUIRED. Your Python application start command
      start: app.py
```

### health check

_OPTIONAL._ Defines a health check.

`healthCheck` requires either one `httpGet` object or one `exec` object.

#### httpGet

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

Following attributes are available:

<table className="w-full my-1.5">
  <thead>
    <tr>
      <th className="w-fit whitespace-nowrap">Parameter</th>
      <th className="w-fit whitespace-nowrap">Description</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td className="w-fit whitespace-nowrap font-semibold">port</td>
      <td>Defines the port of the HTTP GET request.
The readiness check will trigger a GET request on <code>{'http://127.0.0.1:{port}/{path}'}</code></td>
    </tr>
    <tr>
      <td className="w-fit whitespace-nowrap font-semibold">path</td>
      <td>Defines the URL path of the HTTP GET request.
The readiness check will trigger a GET request on <code>{'http://127.0.0.1:{port}/{path}'}</code></td>
    </tr>
    <tr>
      <td className="w-fit whitespace-nowrap font-semibold">host</td>
      <td><strong>Optional.</strong> The readiness check is triggered from inside of your runtime container so it always uses the localhost <code>127.0.0.1</code>. If you need to add a <code>host</code> to the request header, specify it in the <code>host</code> attribute.</td>
    </tr>
    <tr>
      <td className="w-fit whitespace-nowrap font-semibold">scheme</td>
      <td><strong>Optional.</strong> The readiness check is triggered from inside of your runtime container so no https is required.
If your application requires a https request, set <code>scheme: https</code></td>
    </tr>
  </tbody>
</table>

**Example:**

```yaml
zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build: ...

    # ==== how to run your application ====
    run:
      # REQUIRED. Your Python application start command
      start: app.py

      # OPTIONAL. Define a health check with a HTTP GET request option.
      # Configures the check on http://127.0.0.1:80/status
      healthCheck:
        httpGet:
          port: 80
          path: /status
```

#### exec

Configures the health check to run a local command.
Following attributes are available:

<table className="w-full my-1.5">
  <thead>
    <tr>
      <th className="w-fit"><strong>Parameter</strong></th>
      <th className="w-fit"><strong>Description</strong></th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td className="w-fit"><strong>command</strong></td>
      <td className="w-fit">
        Defines a local command to be run.

        The command has access to the same [environment variables](/python/how-to/create#set-secret-environment-variables) as your Python application.

        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 below.
      </td>
    </tr>
  </tbody>
</table>

**Example:**

```yaml
zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build: ...

    # ==== how to run your application ====
    run:
      # REQUIRED. Your Python application start command
      start: app.py

      # OPTIONAL. Define a health check with a shell command.
      healthCheck:
        exec:
          command: |
            touch grass
            rm -rf life
            mv /outside/user /home/user
```

### crontab

_OPTIONAL._ Defines cron jobs.

Setup cron jobs in the following format:

```yaml
zerops:
  # define hostname of your service
  - setup: app

    # ==== how to run your application ====
    run:
      crontab:
        # REQUIRED. Sets the command to execute:
        - command: ""
        # REQUIRED. Sets the interval time to execute:
          timing: "0 * * * *"
```

Read more about setting up [cron](/zerops-yaml/cron) in Zerops.

## Deploy configuration

### readiness check

_OPTIONAL._ Defines a readiness check. Read more about how the [readiness check works](/python/how-to/deploy-process#readiness-checks) in Zerops.

`readinessCheck` requires either one `httpGet` object or one `exec` object.

#### httpGet

Configures the readiness check to request a local URL using a http GET method.

Following attributes are available:

<table className="w-full my-1.5">
  <thead>
    <tr>
      <th className="w-fit whitespace-nowrap">Parameter</th>
      <th className="w-fit whitespace-nowrap">Description</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td className="w-fit whitespace-nowrap font-semibold">port</td>
      <td>Defines the port of the HTTP GET request.
The readiness check will trigger a GET request on <code>{'http://127.0.0.1:{port}/{path}'}</code></td>
    </tr>
    <tr>
      <td className="w-fit whitespace-nowrap font-semibold">path</td>
      <td>Defines the URL path of the HTTP GET request.
The readiness check will trigger a GET request on <code>{'http://127.0.0.1:{port}/{path}'}</code></td>
    </tr>
    <tr>
      <td className="w-fit whitespace-nowrap font-semibold">host</td>
      <td><strong>Optional.</strong> The readiness check is triggered from inside of your runtime container so it always uses the localhost <code>127.0.0.1</code>. If you need to add a <code>host</code> to the request header, specify it in the <code>host</code> attribute.</td>
    </tr>
    <tr>
      <td className="w-fit whitespace-nowrap font-semibold">scheme</td>
      <td><strong>Optional.</strong> The readiness check is triggered from inside of your runtime container so no https is required.
If your application requires a https request, set <code>scheme: https</code></td>
    </tr>
  </tbody>
</table>

**Example:**

```yaml
zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build: ...

    # ==== how to deploy your application ====
    deploy:
      # OPTIONAL. Define a readiness check with a HTTP GET request option.
      # Configures the check on http://127.0.0.1:80/status
      readinessCheck:
        httpGet:
          port: 80
          path: /status

    # ==== how to run your application ====
    run: ...
```

Read more about how the [readiness check works](/python/how-to/deploy-process#readiness-checks) in Zerops.

#### exec

Configures the readiness check to run a local command.
Following attributes are available:

<table className="w-full my-1.5">
  <thead>
    <tr>
      <th className="w-fit"><strong>Parameter</strong></th>
      <th className="w-fit"><strong>Description</strong></th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td className="w-fit"><strong>command</strong></td>
      <td className="w-fit">
        Defines a local command to be run.

        The command has access to the same [environment variables](/python/how-to/create#set-secret-environment-variables) as your Python application.

        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 below.
      </td>
    </tr>
  </tbody>
</table>

**Example:**

```yaml
zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build: ...

    # ==== how to deploy your application ====
    deploy:
      # OPTIONAL. Define a readiness check with a HTTP GET request option.
      # Configures the check on http://127.0.0.1:80/status
      readinessCheck:
        exec:
          command: |
            touch grass
            rm -rf life
            mv /outside/user /home/user
```

Read more about how the [readiness check works](/python/how-to/deploy-process#readiness-checks) in Zerops.


----------------------------------------

# Python > How To > Build Process



----------------------------------------

# Python > How To > Controls



----------------------------------------

# Python > How To > Create


Zerops provides a Python runtime service with extensive build support. Python runtime is highly scalable and customisable to suit both development and production.

## Create Python service using Zerops GUI

First, set up a project in Zerops GUI. Then go to the project dashboard page and choose **Add new service** in the left menu in the **Services** block. Then add a new Python service:

[Video: /vids/services/python.webm](/vids/services/python.webm)

### Choose Python version

Following Python versions are currently supported:

:::info
You can [change](/python/how-to/upgrade) the major version at any time later.
:::

### Set a hostname

Enter a unique service identifier like "app","cache", "gui" etc. Duplicate services with the same name in the same project are forbidden.

#### Limitations:

- maximum 25 characters
- must contain only lowercase ASCII letters (a-z) or numbers (0-9)

:::caution
The hostname is fixed after the service is created. It can't be changed later.
:::

### Set secret environment variables

Add environment variables with sensitive data, such as password, tokens, salts, certificates etc. These will be securely saved inside Zerops and added to your runtime service upon start.

Setting the secret environment variables is optional. You can set them later in Zerops GUI.

Read more about [different types of env variables](/python/how-to/env-variables#service-env-variables) in Zerops.

## Create Python service using zCLI

zCLI is the Zerops command-line tool. To create a new Python service via the command-line, follow these steps:

1. [Install & setup zCLI](/references/cli)
2. [Create a project description file](/python/how-to/create#create-a-project-description-file)
3. [Create a project with a Python and PostgreSQL service](#full-example)

### Create a project description file

Zerops uses a yaml format to describe the project infrastructure.

#### Basic example:

Create a directory `my-project`. Create an `description.yaml` file inside the `my-project` directory with following content:

```yaml
# basic project data
project:
  # project name
  name: my-project
# array of project services
services:
  - # service name
    hostname: app
    # service type and version number in python@{version} format
    type: python@latest
    # defines the minimum number of containers for horizontal autoscaling
    minContainers: 1
    # defines the maximum number of containers for horizontal autoscaling. Max value = 6.
    maxContainers: 6
    # optional: create env variables
    envSecrets:
      S3_ACCESS_KEY_ID: 'P8cX1vVVb'
      S3_ACCESS_SECRET: 'ogFthuiLYki8XoL73opSCQ'
```

The yaml file describes your future project infrastructure. The project will contain one Python version 3.12 service with default [auto scaling](/python/how-to/scaling) configuration. Hostname will be set to "app", the internal port(s) the service listens on will be defined later in the [zerops.yaml](/python/how-to/build-pipeline#ports). Following secret env variables will be configured:

```env
S3_ACCESS_KEY_ID="P8cX1vVVb"
S3_ACCESS_SECRET="ogFthuiLYki8XoL73opSCQ"
```

#### Full example:

Create a directory my-project. Create an description.yaml file inside the my-project directory with following content:

```yaml
# basic project data
project:
  # project name
  name: my-project
  # optional: project description
  description: A project with a Python and PostgreSQL database
  # optional: project tags
  tags:
    - DEMO
    - ZEROPS
# array of project services
services:
  - # service name
    hostname: app
    # service type and version number in python@{version} format
    type: python@latest
    # optional: vertical auto scaling customization
    verticalAutoscaling:
      cpuMode: DEDICATED
      minCpu: 2
      maxCpu: 5
      minRam: 2
      maxRam: 24
      minDisk: 6
      maxDisk: 50
      startCpuCoreCount: 3
      minFreeRamGB: 0.5
      minFreeRamPercent: 20
    # defines the minimum number of containers for horizontal autoscaling. Max value = 6.
    minContainers: 2
    # defines the maximum number of containers for horizontal autoscaling. Max value = 6.
    maxContainers: 4
    # optional: create secret env variables
    envSecrets:
      S3_ACCESS_KEY_ID: 'P8cX1vVVb'
      S3_ACCESS_SECRET: 'ogFthuiLYki8XoL73opSCQ'
  - # second service hostname
    hostname: db
    # service type and version number in postgresql@{version} format
    type: postgresql@12
    # mode of operation "HA"/"non_HA"
    mode: NON_HA
```

The yaml file describes your future project infrastructure. The project will contain a Python service and a [PostgreSQL](/postgresql/overview) service.

Python service with "app" hostname, the internal port(s) the service listens on will be defined later in the zerops.yaml. Python service will run on version 3.12 with a custom vertical and horizontal scaling. Following secret env variables will be configured:

```env
S3_ACCESS_KEY_ID="P8cX1vVVb"
S3_ACCESS_SECRET="ogFthuiLYki8XoL73opSCQ"
```

The hostname of the PostgreSQL service will be set to "db". The [single container](/features/scaling#single-container-mode)(/features/scaling#deployment-modes-databases-and-shared-storage) mode will be chosen and the default auto [scaling configuration](/postgresql/how-to/scale#configure-scaling) will be set.

#### Description of description.yaml parameters

The `project:` section is required. Only one project can be defined.

<table className="w-full my-1.5">
  <thead>
    <tr>
      <th className="w-fit"><strong>Parameter</strong></th>
      <th className="w-fit"><strong>Description</strong></th>
      <th className="w-fit"><strong>Limitations</strong></th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td className="w-fit"><strong>name</strong></td>
      <td className="w-fit">The name of the new project. Duplicates are allowed.</td>
      <td className="w-fit"></td>
    </tr>
    <tr>
      <td className="w-fit"><strong>description</strong></td>
      <td className="w-fit"><strong>Optional.</strong> Description of the new project.</td>
      <td className="w-fit">Maximum 255 characters.</td>
    </tr>
    <tr>
      <td className="w-fit"><strong>tags</strong></td>
      <td className="w-fit"><strong>Optional.</strong> One or more string tags. Tags do not have a functional meaning, they only provide better orientation in projects.</td>
      <td className="w-fit"></td>
    </tr>
  </tbody>
</table>

At least one service in `services:` section is required. You can create a project with multiple services. The example above contains Python and PostgreSQL services but you can create a `description.yaml` with your own combination of [services](/features/infrastructure).

<table className="w-full my-1.5">
  <thead>
    <tr>
      <th className="w-fit"><strong>Parameter</strong></th>
      <th className="w-fit"><strong>Description</strong></th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td className="w-fit"><strong>hostname</strong></td>
      <td className="w-fit">
        The unique service identifier.

        The hostname of the new service will be set to the `hostname` value.

        <strong>Limitations:</strong>
        <ul>
        <li>duplicate services with the same name in the same project are forbidden</li>
        <li>maximum 25 characters</li>
        <li>must contain only lowercase ASCII letters (a-z) or numbers (0-9)</li>
        </ul>
      </td>
    </tr>
    <tr>
      <td className="w-fit"><strong>type</strong></td>
      <td className="w-fit">
        Specifies the service type and version.

        See what [Python service types](/references/import-yaml/type-list#runtime-services) are currently supported.
      </td>
    </tr>
    <tr>
      <td className="w-fit"><strong>verticalAutoscaling</strong></td>
      <td className="w-fit">
        <strong>Optional.</strong> Defines [custom vertical auto scaling parameters](/python/how-to/create#set-auto-scaling-configuration).

        All verticalAutoscaling attributes are optional. Not specified attributes will be set to their default values.
      </td>
    </tr>
    <tr>
      <td className="w-fit"><strong>- cpuMode</strong></td>
      <td className="w-fit">
        <strong>Optional.</strong> Accepts `SHARED`, `DEDICATED` values. Default is `SHARED`
      </td>
    </tr>
    <tr>
      <td className="w-fit"><strong>- minCpu/maxCpu</strong></td>
      <td className="w-fit">
        <strong>Optional.</strong> Set the minCpu or maxCpu in CPU cores (integer).
      </td>
    </tr>
    <tr>
      <td className="w-fit"><strong>- minRam/maxRam</strong></td>
      <td className="w-fit">
        <strong>Optional.</strong> Set the minRam or maxRam in GB (float).
      </td>
    </tr>
    <tr>
      <td className="w-fit"><strong>- minDisk/maxDisk</strong></td>
      <td className="w-fit">
        <strong>Optional.</strong> Set the minDisk or maxDisk in GB (float).
      </td>
    </tr>
    <tr>
      <td className="w-fit"><strong>minContainers</strong></td>
      <td className="w-fit">
        <strong>Optional.</strong> Default = 1. Defines the minimum number of containers for [horizontal autoscaling](/python/how-to/create#horizontal-auto-scaling).

        <strong>Limitations:</strong>

        Current maximum value = 10.
      </td>
    </tr>
    <tr>
      <td className="w-fit"><strong>maxContainers</strong></td>
      <td className="w-fit">
        Defines the maximum number of containers for [horizontal autoscaling](/python/how-to/create#horizontal-auto-scaling).

        <strong>Limitations:</strong>

        Current maximum value = 10.
      </td>
    </tr>
    <tr>
      <td className="w-fit"><strong>envSecrets</strong></td>
      <td className="w-fit">
        <strong>Optional.</strong> Defines one or more secret env variables as a key value map. See env variable [restrictions](/python/how-to/env-variables#env-variable-restrictions).
      </td>
    </tr>
  </tbody>
</table>

### Create a project based on the description.yaml

When you have your `description.yaml` ready, use the `zcli project project-import` command to create a new project and the service infrastructure.

```sh
Usage:
  zcli project project-import importYamlPath [flags]

Flags:
  -h, --help                Help for the project import command.
      --org-id string        If you have access to more than one organization, you must specify the org ID for which the
                            project is to be created.
      --working-dir string   Sets a custom working directory. Default working directory is the current directory. (default "./")
```

Zerops will create a project and one or more services based on the `description.yaml` content.

Maximum size of the `description.yaml` file is 100 kB.

You don't specify the project name in the `zcli project project-import` command, because the project name is defined in the `description.yaml`.

If you have access to more than one client, you must specify the client ID for which the project is to be created. The `clientID` is located in the Zerops GUI under the client name on the project dashboard page.

### Add Python service to an existing project

#### Example:

Create a directory `my-project` if it doesn't exist. Create an `import.yaml` file inside the `my-project` directory with following content:

```yaml
# basic project data
project:
  # project name
  name: my-project
# array of project services
services:
  - # service name
    hostname: app
    # service type and version number in python@{version} format
    type: python@latest
    # defines the minimum number of containers for horizontal autoscaling
    minContainers: 1
    # defines the maximum number of containers for horizontal autoscaling. Max value = 6.
    maxContainers: 6
    # optional: create env variables
    envSecrets:
      S3_ACCESS_KEY_ID: 'P8cX1vVVb'
      S3_ACCESS_SECRET: 'ogFthuiLYki8XoL73opSCQ'
```

The yaml file describes the list of one or more services that you want to add to your existing project. In the example above, one Python service version 3.12 with default [auto scaling](/python/how-to/scaling) configuration will be added to your project. Hostname of the new service will be set to `app`. Following secret env variables will be configured:

```env
S3_ACCESS_KEY_ID="P8cX1vVVb"
S3_ACCESS_SECRET="ogFthuiLYki8XoL73opSCQ"
```

The content of the `services:` section of `import.yaml` is identical to the project description file. The `import.yaml` never contains the `project:` section because the project already exists.

When you have your `import.yaml` ready, use the `zcli project service-import` command to add one or more services to your existing Zerops project.

```sh
Usage:
  zcli project service-import importYamlPath [flags]

Flags:
  -h, --help                Help for the project service import command.
  -P, --project-id string   If you have access to more than one project, you must specify the project ID for which the
                           command is to be executed.
```

zCLI commands are interactive, when you press enter after `zcli project service-import importYamlPath`, you will be given a list of your projects to choose from.

Maximum size of the import.yaml file is 100 kB.


----------------------------------------

# Python > How To > Customize Runtime



----------------------------------------

# Python > How To > Deploy Process



----------------------------------------

# Python > How To > Env Variables



----------------------------------------

# Python > How To > Filebrowser



----------------------------------------

# Python > How To > Logs



----------------------------------------

# Python > How To > Scaling



----------------------------------------

# Python > How To > Shared Storage



----------------------------------------

# Python > How To > Trigger Pipeline



----------------------------------------

# Python > How To > Upgrade



----------------------------------------

# Python > Overview


[Python ↗](https://www.python.org/) is a programming language that lets you work quickly and integrate systems more effectively..

As said, there is no need for coding yet, we have created a [Github repository ↗](https://github.com/zeropsio/recipe-python-hello-world), a **_recipe_**, containing the most simple Python web application. The repo will be used as a source from which the app will be built.

### 🚀 Feel free to deploy the recipe yourself

This is the most bare-bones example of Python running in Zerops — as few libraries as possible,
  just a simple endpoint with connect, read and write to a Zerops PostgreSQL database.

  [Deploy "python" recipe on Zerops](https://app.zerops.io/recipe/?lf=python)

1. Log in/sign up to [Zerops GUI ↗](https://app.zerops.io)
2. In the **Projects** box click on **Import a project** and paste in the following YAML config ([source ↗](https://github.com/zeropsio/recipe-python-hello-world/blob/main/import-project/description.yaml)):

```yaml
project:
  name: my-first-project
services:
  - hostname: helloworld
    type: python@latest
    minContainers: 1
    maxContainers: 3
    buildFromGit: https://github.com/zeropsio/recipe-python-hello-world@main
    enableSubdomainAccess: true
```

3. Click on **Import project** and wait until all pipelines have finished.

**That's it, your application is now up and running! :star: Let's check it works:**

1. A _subdomain_ should have been enabled and visible in the project's **IP addressed & Public Routing Overview** box. Its format should look similar to this `https://helloworld-24-8080.prg1.zerops.app`.
2. Click or the `subdomain` URL to open it in a browser and you should see

```
Hello, World!
```

:::tip
Do you have any questions? Check the step-by-step tutorial, browse the documentation and join our **[Discord](https://discord.com/invite/WDvCZ54)** community to get help from our team and other members.
:::

## How to start

- [Care for details?](/python/how-to/create) — Dive in all Zerops has to offer for your Python application.

## Feature Highlights

- [Create Python service](/python/how-to/create) — Start with creating a Python service using GUI or zCLI.
- [zerops.yaml](/python/how-to/build-pipeline#add-zeropsyaml-to-your-repository) — See a full example of zerops.yaml file to create your own app.
- [Scaling configuration](/python/how-to/scaling) — Set up scaling of your Python application so that it runs smoothly while using only necessary resources.

{" "}

- [Customize build environment](/python/how-to/build-process#customize-build-environment)
- [Customize runtime environment](/python/how-to/customize-runtime)

## When in doubt, reach out

Don't know how to start or got stuck during the process? You might not be the first one, visit the FAQ section to find out.

In case you haven't found an answer (and also if you have), we and our community are looking forward to hearing from you on Discord.

Have you build something that others might find useful? Don't hesitate to share your knowledge!

- [FAQ](/python/faq) — Most common questions in one place.
- [Discord](https://discord.com/invite/WDvCZ54) — Join our core team and Zerops community on Discord. Ask questions and share your tips with other members.

## Popular Guides

- [zCLI](/references/cli) — Get even more out of Zerops with the zCLI command line tool.
- [Zerops VPN](/references/networking/vpn) — Connect to your services easily with Zerops VPN.


----------------------------------------

# Qdrant > Overview


[Qdrant](https://qdrant.tech/) in Zerops provides a fully managed vector database solution designed for AI applications. Focus on building vector search features while we handle infrastructure maintenance, high availability, and data protection.

## Supported Versions

Currently supported Qdrant versions:

Import configuration version:

- `qdrant@1.12`
- `qdrant@1.10`

## Deployment Modes

#### Non-HA Mode
- Single node setup ideal for development and non-production projects
- Simple deployment and management

#### HA Cluster
- Automatically configured with 3 nodes
- Recommended for production environments
- Built-in data replication across nodes
- By default (`automaticClusterReplication=true`), automatically creates replicas of all shards across all three nodes
  - Can be disabled by setting `automaticClusterReplication` to `false`
- Automatic cluster recovery and node replacement in case of failures

## Data Backup

Qdrant backups are created using native snapshotting:

- **Format**: `.snapshot` (compressed)
- **Tooling**: Native snapshotting
- **Source**: Taken from the primary node (leader in HA clusters)

For backup configuration, scheduling, retention policies, and management options, see the [Zerops Backups](/features/backup) documentation.

### Restoring Backups

To restore a Qdrant backup:

1. **Download** the backup file (`.snapshot`) from the Zerops UI
2. **Prepare** your target environment (clean existing collections or use a new instance)
3. **Restore** using the Qdrant API. Use the snapshot restore endpoint to import the snapshot file. Follow the [official Qdrant documentation](https://qdrant.tech/documentation/database-tutorials/create-snapshot/#restore-from-snapshot) for detailed snapshot restore procedures.

For assistance with the restoration process, contact Zerops support.

## Network Architecture & Access

Qdrant can be accessed only from services within the same project, public access is not available.

### API Keys
API key authentication is required for both HTTP and gRPC API calls. Include the key in your request headers. The keys are automatically generated when the Qdrant service is created and can be found in the service's environment variables:

- **`apiKey`:** Full access API key for administrative operations (creating collections, indexing)
- **`readOnlyApiKey`:** Restricted API key for search operations

#### HTTP API
- **Port:** `6333`
- **Connection String:** Available as `connectionString` environment variable or construct using `http://${hostname}:${port}`

#### gRPC API
- **Port:** `6334`
- **gRPC Connection String:** Available as `grpcConnectionString` environment variable or construct using `tcp://${hostname}:${grpcPort}`

## Support

For advanced configurations or custom requirements:
- Join our [Discord community](https://discord.gg/zeropsio)
- Contact support via [email](mailto:support@zerops.io)

----------------------------------------

# Quickstart > Quickstart Going Further

---
title: Deploy Your First App
description: Swap the recipe for your own code, deploy the feedback app, and connect GitHub for auto-deploy.
sidebar_label: Deploy Your First App
slug: /quickstart/deploy-your-first-app

custom_edit_url: null
---

You've got a live app running on Zerops. Now let's make it actually yours.

This page walks you through deploying the feedback app we showed you at the top of the quickstart - a Node.js app with a PostgreSQL database, auto-deploy on every git push, and a wall of everyone who's made it through. If you'd rather skip straight to your own code, there's a note at the bottom for that.

### Deploy the feedback app

Start from the recipe template. Click the link below, pick a name for your repo, and hit **Create repository**:

**[github.com/new?template_name=recipe-nodejs&template_owner=zeropsio](https://github.com/new?template_name=recipe-nodejs&template_owner=zeropsio)**

Then clone your new repo and install dependencies:

```bash
git clone https://github.com/your-username/your-repo.git
cd your-repo
npm install
```

The repo uses TypeScript. You only need to touch two files: `src/app.ts` and `src/db.ts`. Leave `src/index.ts` and `src/config.ts` exactly as they are.

**Replace `src/db.ts`** with this:

```ts

export const connectDB = async () => {
  const client = new Client({
    host: config.db.host,
    port: config.db.port,
    user: config.db.username,
    password: config.db.password,
    database: config.db.database,
  });

  await client.connect();

  await client.query(`
    CREATE TABLE IF NOT EXISTS clicks (
      id SERIAL PRIMARY KEY,
      seed INTEGER NOT NULL,
      clicked_at TIMESTAMPTZ DEFAULT NOW()
    )
  `);

  return client;
};
```

**Replace `src/app.ts`** with this:

```ts

const app = express();

app.use(express.static(path.join(__dirname, '../public')));

app.get('/count', async (_, res) => {
  const client = await connectDB();
  const result = await client.query(
    'SELECT seed FROM clicks ORDER BY id ASC LIMIT 20'
  );
  const countResult = await client.query('SELECT COUNT(*) FROM clicks');
  await client.end();
  res.json({
    count: parseInt(countResult.rows[0].count),
    seeds: result.rows.map((r) => r.seed),
  });
});

app.post('/click', async (_, res) => {
  const client = await connectDB();
  const seed = Math.floor(Math.random() * 1000000);
  await client.query('INSERT INTO clicks (seed) VALUES ($1)', [seed]);
  const countResult = await client.query('SELECT COUNT(*) FROM clicks');
  await client.end();
  res.json({ count: parseInt(countResult.rows[0].count), seed });
});

app.get('/status', (_, res) => {
  res.status(200).send({ status: 'UP' });
});

export default app;
```

**Create a `public/` folder** at the repo root and add `public/index.html`:

<div style={{maxHeight: '400px', overflowY: 'auto', borderRadius: '8px'}}>

```html
<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Zerops Quickstart</title>
    <style>
      * {
        box-sizing: border-box;
        margin: 0;
        padding: 0;
      }
      body {
        font-family: sans-serif;
        background: #ffffff;
        display: flex;
        flex-direction: column;
        align-items: center;
        justify-content: center;
        min-height: 100vh;
        padding: 3rem 1.5rem;
      }
      .logo {
        display: flex;
        align-items: center;
        gap: 7px;
        margin-bottom: 2.5rem;
        opacity: 0.45;
      }
      .logo-dot {
        width: 18px;
        height: 18px;
        background: #3bbdb2;
        border-radius: 4px;
      }
      .logo-text {
        font-size: 13px;
        color: #1a1a1a;
        letter-spacing: 0.06em;
        font-weight: 600;
      }
      h1 {
        font-size: 1.6rem;
        font-weight: 500;
        color: #111;
        text-align: center;
        margin-bottom: 0.6rem;
        line-height: 1.3;
      }
      .subtitle {
        font-size: 0.9rem;
        color: #777;
        text-align: center;
        max-width: 360px;
        line-height: 1.6;
        margin-bottom: 2.5rem;
      }
      button {
        background: #3bbdb2;
        color: #fff;
        border: none;
        border-radius: 8px;
        padding: 0.85rem 1.8rem;
        font-size: 0.95rem;
        font-weight: 600;
        cursor: pointer;
        transition:
          transform 0.1s,
          background 0.15s;
        font-family: sans-serif;
      }
      button:hover {
        background: #2ea39a;
      }
      button:active {
        transform: scale(0.97);
      }
      button:disabled {
        opacity: 0.5;
        cursor: default;
      }
      .count {
        margin-top: 1.1rem;
        font-size: 0.82rem;
        color: #aaa;
        text-align: center;
      }
      .count-num {
        color: #3bbdb2;
        font-weight: 700;
      }
      .avatars {
        display: flex;
        flex-wrap: wrap;
        justify-content: center;
        gap: 7px;
        margin-top: 1.8rem;
        max-width: 400px;
      }
      .avatar {
        width: 34px;
        height: 34px;
        border-radius: 50%;
        display: flex;
        align-items: center;
        justify-content: center;
        font-size: 10px;
        font-weight: 700;
        color: #fff;
        opacity: 0;
        transform: scale(0.5);
        transition:
          opacity 0.3s,
          transform 0.3s;
      }
      .avatar.visible {
        opacity: 1;
        transform: scale(1);
      }
      .divider {
        width: 40px;
        height: 1px;
        background: #ddd;
        margin: 2rem 0 1.2rem;
      }
      .stack-pills {
        display: flex;
        gap: 6px;
        flex-wrap: wrap;
        justify-content: center;
      }
      .pill {
        font-size: 11px;
        padding: 3px 10px;
        border-radius: 20px;
        border: 0.5px solid #d0cec8;
        color: #999;
        background: #fff;
      }
    </style>
  </head>
  <body>
    <div class="logo">
      <div class="logo-dot"></div>
      <span class="logo-text">zerops</span>
    </div>
    <h1>You made it. 🎉</h1>
    <p class="subtitle">
      You just deployed a real app: managed database, private network,
      auto-deploy. Let us know you made it through.
    </p>
    <button id="btn">👋 I followed the Zerops quickstart</button>
    <p class="count">
      <span class="count-num" id="count">...</span>
      <span id="count-label"></span>
    </p>
    <div class="avatars" id="avatars"></div>
    <div class="divider"></div>
    <div class="stack-pills">
      <span class="pill">Node.js 20</span>
      <span class="pill">PostgreSQL 16</span>
      <span class="pill">Zerops</span>
    </div>

    <script>
      const colors = [
        '#3BBDB2',
        '#0891b2',
        '#7c3aed',
        '#db2777',
        '#d97706',
        '#3BBDB2',
        '#2563eb',
        '#9333ea',
      ];
      const letters = 'ABCDEFGHJKLMNPRSTUVWXYZ';
      const btn = document.getElementById('btn');
      const countEl = document.getElementById('count');
      const countLabel = document.getElementById('count-label');
      const avatarsEl = document.getElementById('avatars');

      function initials(seed) {
        return (
          letters[(seed * 7) % letters.length] +
          letters[(seed * 13 + 5) % letters.length]
        );
      }

      function addAvatar(seed, animate) {
        if (seed === undefined || seed === null || Number.isNaN(seed)) return;

        const av = document.createElement('div');
        av.className = 'avatar';
        av.style.background = colors[seed % colors.length];
        av.textContent = initials(seed);
        av.title = 'builder_' + (1000 + (seed % 1000));
        avatarsEl.appendChild(av);

        if (animate) {
          void av.offsetWidth;
          requestAnimationFrame(() => {
            av.classList.add('visible');
          });
        } else {
          av.classList.add('visible');
        }
      }

      async function loadCount() {
        const res = await fetch('/count');
        const { count, seeds } = await res.json();
        countEl.textContent = count;
        countLabel.textContent = `developer${count === 1 ? '' : 's'} deployed this`;
        (seeds || []).forEach((seed) => addAvatar(seed, false));
      }

      btn.addEventListener('click', async () => {
        btn.disabled = true;
        const res = await fetch('/click', { method: 'POST' });
        const { count, seed } = await res.json();
        countEl.textContent = count;
        countLabel.textContent = `developer${count === 1 ? '' : 's'} deployed this`;
        btn.textContent = "🎉 You're in!";
        addAvatar(seed, true);
      });

      loadCount();
    </script>
  </body>
</html>
```

</div>

The `zerops.yml` already exists in the repo. Update `deployFiles` to include the `public` folder:

```yaml
zerops:
  - setup: app
    build:
      base: nodejs@20
      prepareCommands:
        - npm install -g typescript
      buildCommands:
        - npm i
        - npm run build
      deployFiles:
        - ./dist
        - ./node_modules
        - ./public
        - ./package.json
    run:
      base: nodejs@20
      ports:
        - port: 3000
          httpSupport: true
      envVariables:
        NODE_ENV: production
        DB_NAME: db
        DB_HOST: ${db_hostname}
        DB_USER: ${db_user}
        DB_PASSWORD: ${db_password}
        # or use the full connection string:
        # DB_CONNECTION_STRING: ${db_connectionString}
      start: npm run start:prod
      healthCheck:
        httpGet:
          port: 3000
          path: /status
```

:::tip How Zerops env variables work
Zerops automatically generates credentials for every managed service. The variable names are derived from the service hostname — so if your database service is named `db`, the variables are `${db_hostname}`, `${db_user}`, `${db_password}`, and `${db_connectionString}`. If you named it `postgres` instead, they'd be `${postgres_hostname}`, `${postgres_password}`, and so on.
:::

Push to your repo and connect GitHub in the next section.

```bash
git add .
git commit -m "add feedback app"
git push
```

:::note Want to build something else instead?
Skip the feedback app. Pick the recipe matching your stack from [app.zerops.io/recipes](https://app.zerops.io/recipes), add a `zerops.yaml` to your repo root copying the structure from the recipe, and adjust `buildCommands`, `deployFiles`, and `start` for your stack. The database env variables (`${db_hostname}`, `${db_user}`, `${db_password}`) stay the same regardless of what you're building.
:::

### Connect GitHub and auto-deploy

1. Click into your **app** service
2. Scroll down to **Pipelines & CI/CD settings**
3. Click **GitHub** to connect your repo
4. Select your repo and set **Trigger on** to **Push to Branch**, pick `main`
5. In the **"Which `setup` from zerops.yml to use"** field, type `app`
6. Click **Activate pipeline trigger**

That's it. Every push to main now builds and deploys automatically. Zero downtime, Zerops runs the new version alongside the old one, waits for a health check, then switches traffic over.

You can also trigger deploys manually with the Zerops CLI: `zcli push`.

### Add yourself to the list

Deployed the feedback app? Open your live app URL and click **"I followed the Zerops quickstart"**. You'll show up alongside everyone else who's made it through.

Check out everyone who's already made it: [app-25be-3000.prg1.zerops.app](https://app-25be-3000.prg1.zerops.app/)

### If something breaks

Got a 502 or an app crash on startup? Start here.

**Check the runtime logs first.** Dashboard, click your app service, click the three-dot menu, then **Runtime log**. The error will be there, usually in the last few lines.

Two things come up most often on a first deploy:

:::tip Debug locally with VPN
Install zcli first (see [CLI reference](/references/cli)), then run `zcli vpn up [your-project-id]` and your machine joins the project's private network. You can connect to `db:5432` directly from your local machine using TablePlus, psql, or any database client. You can disable SSL when connecting over VPN - the tunnel itself handles security either way. If `db` doesn't resolve, try `db.zerops` instead.
:::

### What's next

- **[SSH into your container](/references/networking/ssh)**: `zcli service shell [service-name]` for full Linux access
- **[Custom domain](/references/networking/public-access)**: add your domain, SSL is automatic
- **[Autoscaling](/features/scaling)**: set min and max CPU and RAM, Zerops scales within that range automatically
- **[Add more services](/features/infrastructure)**: queues, search engines, object storage, just add them to your project
- **[Try ZCP](/zcp/quickstart)**: Zerops' AI agent that can deploy, debug, and operate your project

:::note Stuck?
Jump into the [Zerops Discord](https://docs.zerops.io/discord). The community is active and the team is there.
:::


----------------------------------------

# Quickstart > Quickstart


In the next 5 minutes, we'll go from zero to a live app: a managed database, a public URL, and auto-deploy on every git push, all set up for you.

Here's what we're building together: a page with a button that says **"I followed the Zerops quickstart"**. Every developer who finishes this guide and clicks it gets added to the wall. It's a real app, Express backend, PostgreSQL database, static frontend, running entirely on **Zerops**.

Curious what you'll end up with? Here it is, live: [app-25be-3000.prg1.zerops.app](https://app-25be-3000.prg1.zerops.app/)

[Video: /vids/quickstart-app.webm](/vids/quickstart-app.webm)

:::tip Before we start
Sign up at [app.zerops.io](https://app.zerops.io). You get $15 in promo credits on signup, no credit card needed. Verify your account with a $10 payment and get an additional $50, bringing your total to $65 in credits. A simple app with a database costs roughly $3-5/month, so credits go a long way.
:::

---

## 1. Deploy the recipe

Go to [app.zerops.io/recipes](https://app.zerops.io/recipes). No account needed, the recipes page works even when you're not logged in.

For this guide, find and click **Node.js**. You'll see **Node.js Hello World**, a Node.js app with Express connected to a PostgreSQL database.

Hit **Deploy nodejs-hello-world-small-prod**. If you're not signed in yet, Zerops creates your account and kicks off the deploy in the same step.

:::info What's a recipe?
A recipe is a working app with infrastructure already configured: managed database, environment variables, `zerops.yaml`, everything connected. It's a correct starting point, not a finished product.
:::

---

## 2. Watch it build

After hitting Deploy, you'll land on the dashboard. On the right side you'll see a pipeline already running.

It goes through these steps in real time:

1. Initializing build container
2. Running build commands from `zerops.yaml`
3. Creating app version and upgrading service
4. Done

:::tip Good to know
The build container is **temporary and free**. Zerops spins it up, runs your build, saves the output, and deletes it. You're only billed for the running app.
:::

Once the pipeline finishes, your app is live.

---

## 3. See what got created

Click into your new project. You'll see:

- **app**: your Node.js service, already running
- **db**: a managed PostgreSQL database, already running
- **Project core**: load balancer, firewall, logger, all managed by Zerops

All of these are already talking to each other on a private network. Nothing to configure.

---

## 4. Open your live app

The Zerops subdomain is already enabled when you deploy from a recipe. Click into your **app** service and open the URL.

The default recipe app will be there.

When you're ready for production, point a custom domain at your app. Zerops handles the SSL certificate automatically.

---

## You're live 🎉

Here's what's running:

- A real app on production infrastructure
- A managed PostgreSQL database, ready to use
- All services on a private network, secure by default
- Full Linux containers for your app — SSH in anytime, install anything

None of the infrastructure needed manual configuration.

:::note Stuck?
Jump into the [Zerops Discord](https://docs.zerops.io/discord). The community is active and the team is there.
:::

---

Your app is live and the infrastructure is running.

**Next up:** Swap the recipe for the feedback app we showed you, connect GitHub for auto-deploy, and add yourself to the wall. [Deploy your first app →](/quickstart/deploy-your-first-app)


----------------------------------------

# References > Api


The Zerops REST API allows you to programmatically interact with Zerops platform by providing access to resources like projects, services, users, billing, and configurations.

## Base URL

All API requests should be made to:
```
https://api.app-prg1.zerops.io/api/rest/public
```

## Authentication

The API uses Bearer token authentication. You can obtain your Personal access token from the **Access Token management** section in the Zerops GUI.

Include the token in the Authorization header:
```
Authorization: Bearer <your-token>
```

## API Resources

:::note
Some resource groups have non-obvious naming:
- `/service-stack` endpoints handle services management
- `/user-data` endpoints handle environment variables management
:::

View the [full Swagger documentation](https://api.app-prg1.zerops.io/api/rest/public/swagger) or jump to a specific resource group:

<table className="w-full">
  <thead className="rounded-lg">
    <tr>
      <th className="w-auto"><strong>Group</strong></th>
      <th className="w-full"><strong>Description</strong></th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td className="w-fit whitespace-nowrap"><strong>[/app-version](https://api.app-prg1.zerops.io/api/rest/public/swagger/#/PublicAppVersion)</strong></td>
      <td className="w-fit">Manage application versions, builds, and deployments</td>
    </tr>
    <tr>
      <td className="w-fit whitespace-nowrap"><strong>[/auth](https://api.app-prg1.zerops.io/api/rest/public/swagger/#/PublicAuth)</strong></td>
      <td className="w-fit">Authentication and token management</td>
    </tr>
    <tr>
      <td className="w-fit whitespace-nowrap"><strong>[/billing](https://api.app-prg1.zerops.io/api/rest/public/swagger/#/PublicBilling)</strong></td>
      <td className="w-fit">Billing operations and payment management</td>
    </tr>
    <tr>
      <td className="w-fit whitespace-nowrap"><strong>[/client](https://api.app-prg1.zerops.io/api/rest/public/swagger/#/PublicClient)</strong></td>
      <td className="w-fit">Client account management</td>
    </tr>
    <tr>
      <td className="w-fit whitespace-nowrap"><strong>[/client-user](https://api.app-prg1.zerops.io/api/rest/public/swagger/#/PublicClientUser)</strong></td>
      <td className="w-fit">User management within client accounts</td>
    </tr>
    <tr>
      <td className="w-fit whitespace-nowrap"><strong>[/github](https://api.app-prg1.zerops.io/api/rest/public/swagger/#/PublicGithub)</strong></td>
      <td className="w-fit">GitHub repository connections and authorization</td>
    </tr>
    <tr>
      <td className="w-fit whitespace-nowrap"><strong>[/gitlab](https://api.app-prg1.zerops.io/api/rest/public/swagger/#/PublicGitlab)</strong></td>
      <td className="w-fit">GitLab repository connections and authorization</td>
    </tr>
    <tr>
      <td className="w-fit whitespace-nowrap"><strong>[/project](https://api.app-prg1.zerops.io/api/rest/public/swagger/#/PublicProject)</strong></td>
      <td className="w-fit">Project management operations</td>
    </tr>
    <tr>
      <td className="w-fit whitespace-nowrap"><strong>[/project-env](https://api.app-prg1.zerops.io/api/rest/public/swagger/#/PublicProjectEnv)</strong></td>
      <td className="w-fit">Project environment variables management</td>
    </tr>
    <tr>
      <td className="w-fit whitespace-nowrap"><strong>[/public-http-routing](https://api.app-prg1.zerops.io/api/rest/public/swagger/#/PublicPublicHttpRouting)</strong></td>
      <td className="w-fit">HTTP routing configuration</td>
    </tr>
    <tr>
      <td className="w-fit whitespace-nowrap"><strong>[/public-port-routing](https://api.app-prg1.zerops.io/api/rest/public/swagger/#/PublicPublicPortRouting)</strong></td>
      <td className="w-fit">Port routing and firewall rules configuration</td>
    </tr>
    <tr>
      <td className="w-fit whitespace-nowrap"><strong>[/service-stack](https://api.app-prg1.zerops.io/api/rest/public/swagger/#/PublicServiceStack)</strong></td>
      <td className="w-fit">Service stack operations and configuration</td>
    </tr>
    <tr>
      <td className="w-fit"><strong>[/settings](https://api.app-prg1.zerops.io/api/rest/public/swagger/#/PublicSettings)</strong></td>
      <td className="w-fit">System settings and configurations</td>
    </tr>
    <tr>
      <td className="w-fit whitespace-nowrap"><strong>[/user](https://api.app-prg1.zerops.io/api/rest/public/swagger/#/PublicUser)</strong></td>
      <td className="w-fit">User account management</td>
    </tr>
    <tr>
      <td className="w-fit whitespace-nowrap"><strong>[/user-data](https://api.app-prg1.zerops.io/api/rest/public/swagger/#/PublicUserData)</strong></td>
      <td className="w-fit">Environment variables management</td>
    </tr>
    <tr>
      <td className="w-fit whitespace-nowrap"><strong>[/user-notification](https://api.app-prg1.zerops.io/api/rest/public/swagger/#/PublicUserNotification)</strong></td>
      <td className="w-fit">User notifications management</td>
    </tr>
    <tr>
      <td className="w-fit whitespace-nowrap"><strong>[/user-token](https://api.app-prg1.zerops.io/api/rest/public/swagger/#/PublicUserToken)</strong></td>
      <td className="w-fit">Personal access tokens management</td>
    </tr>
  </tbody>
</table>

----------------------------------------

# References > Cli


zCLI is the command-line tool for Zerops that allows users to manage services, simplify interactions, and configure infrastructure directly from the terminal.

For detailed information, see the [Configuration](/references/zcli/configuration) and [Commands Reference](/references/zcli/commands) pages.

## Platforms

zCLI currently supports:

- Linux (x86 & x64)
- macOS (x86-64 & ARM64)
- Windows (x64)

## Get started

### Manual Installation

To download the zCLI directly, get the [latest release](https://github.com/zeropsio/zcli/releases) from GitHub.

### Linux/MacOS

```sh
curl -L https://zerops.io/zcli/install.sh | sh
```

zCLI will be installed inside `/usr/bin` or `/usr/local/bin`.

### Windows

Execute following command in PowerShell:

```powershell
irm https://zerops.io/zcli/install.ps1 | iex
```

zCLI will be installed inside `C:\Users\<user>\.zerops\zcli.exe`.

### Using Package Managers

You can also install zCLI using package managers:

```sh
npm i -g @zerops/zcli
```

```sh
yarn global add @zerops/zcli
```

### NixOS

:::note
Make sure `nix-command` and flakes are enabled, if not. You can also use `--extra-experimental-features 'nix-command flakes'` with `nix`.
:::

Clone the [zCLI repository](https://github.com/zeropsio/zcli) and build the binary.

```
git clone https://github.com/zeropsio/zcli
```

```
cd zcli
```

```
nix develop
```

```
nix build
```

You can find zCLI binary inside `result/bin`.

## Personal access tokens

Personal tokens allow you to securely access Zerops directly. You can create one or more personal tokens and manage them in [Zerops GUI](https://app.zerops.io).

### Managing your access tokens

To create a new personal access token, go to [Access Tokens management](https://app.zerops.io/settings/token-management) and click "Generate a new access token".

You may delete an access token anytime.

### Using access tokens

You may use an access token to access Zerops using this command:

```sh
zcli login <token>
```

----------------------------------------

# References > Github Integration


Discover how to seamlessly integrate your GitHub repository with Zerops for automated builds and deployments.

You can choose between two powerful integration approaches: direct integration through the Zerops GUI for straightforward setup, or GitHub Actions for more customized deployment workflows.

This guide walks you through both integration methods, helping you choose and implement the approach that best fits your team's needs.

---

## Prerequisites

Before starting the integration process, ensure your repository contains a valid `zerops.yaml` configuration file located in the root directory. This file is essential for defining the build, deploy, and run processes.
For detailed information on how to create or modify this file, refer to the [Zerops YAML configuration](/zerops-yaml/specification) guide.

---

## Integration via Zerops GUI

Follow these steps to connect your GitHub repository directly with Zerops:

1. **Access Service Settings**

   - Log into the [**Zerops GUI**](https://app.zerops.io/)
   - Select the relevant service from your dashboard.
   - In the left-hand menu, navigate to **Build, Deploy, Run Pipeline Settings**.

2. **Connect to GitHub**

   - Click **Connect with a GitHub repository**
   - You'll be prompted to authorize Zerops to access your GitHub account.
   - Grant the necessary permissions for Zerops to manage webhooks and fetch your code.

:::note
Zerops requires full access to your repository in order to configure webhooks and pull the latest code changes. However, Zerops does not store your source code unless explicitly specified by you.
:::

3. **Select Repository and Trigger**

   - Choose the GitHub repository you'd like to integrate with Zerops.
   - Configure the trigger that will initiate a build:
     - **New tag**: Builds are triggered whenever a new tag is created. This is the recommended option for production deployments.
       - You can optionally add a regular expression (regex) to filter specific tags.
     - **Push to branch**: Builds are triggered on every push to a specified branch, such as `main` or `develop`.

4. **Finalize Setup**

   - Review and confirm your settings to complete the integration process.
   - Your GitHub repository is now connected, and builds will be triggered based on the configured triggers.

---

### Skip the automatic pipeline once

To ensure that a pipeline is not triggered by a specific commit, add `[ci skip]` or `[skip ci]` to the commit message. It is case insensitive.

:::note
You will still see a successful delivery of a webhook in your GitHub repository as a webhook is actually triggered, but with no action.
:::

---

### Disconnecting Your Repository

To disconnect your GitHub repository from Zerops:

1. Navigate to the **Service Details** page for the relevant service
1. Select **Build, Deploy, Run Pipeline Settings** from the menu.
1. Click **Stop automatic build trigger**

**This action will remove the GitHub webhook and delete the associated integration configuration, effectively halting automated builds from this repository.**

### Authorizing Access to Organizations

If you want to authorize Zerops to access a specific organization, you can do so by clicking on the **Grant** from [GitHub Applications Settings](https://github.com/settings/connections/applications/4408deded6c1fed7193c).

---

## GitHub Workflow Integration

As an alternative to direct integration, you can use GitHub Actions to manage your deployments. This approach gives you more control over your deployment workflow and allows integration with other CI/CD processes.

### GitHub Workflow using Zerops Actions

1. **Create Workflow Configuration**

   Create a new file at `.github/workflows/deploy.yaml` in your repository:

   Basic example:

   ```yaml
   name: Deploy to Zerops

   on:
     push:
       branches:
         - main

   jobs:
     deploy:
       runs-on: ubuntu-latest

       steps:
         - name: Checkout code
           uses: actions/checkout@v7

         - name: Deploy with Zerops
           uses: zeropsio/actions@main
           with:
             access-token: ${{ secrets.ZEROPS_TOKEN }}
             service-id: your-service-id
   ```

   Example with tag matching:

   ```yaml
   name: Deploy to Zerops on Tag

   on:
     push:
       tags:
         - 'v[0-9]+\.[0-9]+\.[0-9]+' # Example: v1.0.0, v2.3.4

   jobs:
     deploy:
       runs-on: ubuntu-latest

       steps:
         - name: Checkout code
           uses: actions/checkout@v7

         - name: Deploy with Zerops
           uses: zeropsio/actions@main
           with:
             access-token: ${{ secrets.ZEROPS_TOKEN }}
             service-id: your-service-id
   ```

2. **Generate Access Token**

   - Navigate to [**Settings > Access Token Management**](https://app.zerops.io/settings/token-management) in your Zerops dashboard
   - Generate a new access token with appropriate permissions
   - Copy this token for use in GitHub secrets

3. **Locate Service ID**

   - Go to your service dashboard and click the three dots menu → **Copy Service ID**
   - Alternatively, find it in your service URL: `https://app.zerops.io/service-stack/<your-service-id>/dashboard`

4. **Configure GitHub Secrets**

   - Go to your GitHub repository settings
   - Navigate to **Settings** > **Secrets and variables** > **Actions** > **Repository secrets**
   - Add a new secret named `ZEROPS_TOKEN` with your access token value

:::note
Keep your access token secure and never commit it directly to your repository. The token provides administrative access to your Zerops resources.
:::

For more information about GitHub Actions, refer to the [official GitHub Actions documentation](https://docs.github.com/en/actions).

---

## Advanced: Full Lifecycle Automation

:::tip Reference repository
A complete, working example of this pattern is available at [zerops-showcase-deploy](https://github.com/zeropsio/zerops-showcase-deploy), a deployment orchestrator built entirely on GitHub Actions and the Zerops API, no Zerops CLI required. Clone it as a starting point for your own multi-environment pipeline.
:::

The workflow above deploys a single service on push to one branch. This reference repo extends that into a full lifecycle: every feature branch gets its own isolated environment, every PR gets a preview, and stage and prod stay permanent with their data intact across deploys.

### What it sets up

| You do this                 | Pipeline creates                                   | Lifetime                    |
| --------------------------- | -------------------------------------------------- | --------------------------- |
| Push to a feature branch    | A full isolated environment                        | Until the branch is deleted |
| Open/update a PR to `stage` | A full isolated preview environment                | Until the PR is closed      |
| Merge a PR into `stage`     | Redeploys app code to the shared stage environment | Permanent, data preserved   |
| Push/merge to `main`        | Redeploys app code to production                   | Permanent, data preserved   |
| Push/merge to `main`        | Redeploys app code to production                   | Permanent, data preserved   |

Permanent environments keep their databases, caches, queues, and storage across every deploy, only the application code gets updated. Ephemeral environments are created from scratch and torn down automatically when no longer needed, so every developer gets their own isolated copy of the full stack without manual cleanup.

PR previews require a `stage` branch as the pull request target; the repo's setup guide covers creating it.

### How it differs from the basic workflow above

The basic GitHub Actions setup deploys one service to one Zerops project. This pattern manages entire **projects** programmatically instead: it checks whether a project for a given branch or PR already exists, creates one from an import template if not, and deploys to it. The key safeguard is that it never deletes or recreates infrastructure on permanent environments, only ephemeral ones get torn down. This is a reference implementation, not a Zerops-managed service, so you own the repo, the GitHub Actions minutes, and the Zerops API calls it makes on your behalf.

:::tip Full setup guide
Required secrets, customizing the project template for your own services, and the complete workflow reference are all covered in the [repo's README](https://github.com/zeropsio/zerops-showcase-deploy#readme).
:::


----------------------------------------

# References > Gitlab Integration


Discover how to seamlessly integrate your GitLab repository with Zerops for automated builds and deployments.

This guide walks you through the step-by-step process to link your repository, configure triggers, and manage your integrations efficiently.

---

## Prerequisites

Before starting the integration process, ensure your repository contains a valid `zerops.yaml` configuration file located in the root directory. This file is essential for defining the build, deploy, and run processes.
For detailed information on how to create or modify this file, refer to the [Zerops YAML configuration](/zerops-yaml/specification) guide.

---

## Integration Steps

Follow these steps to connect your Gitlab repository with Zerops:

1. **Access Service Settings**

   - Log into the [**Zerops GUI**](https://app.zerops.io/)
   - Select the relevant service from your dashboard.
   - In the left-hand menu, navigate to **Build, Deploy, Run Pipeline Settings**.

2. **Connect to GitLab**

   - Click **Connect with a GitLab repository**
   - You'll be prompted to authorize Zerops to access your GitLab account.
   - Grant the necessary permissions for Zerops to manage webhooks and fetch your code.

:::note
Zerops requires full access to configure webhooks and download your code. Your source code is not stored after the build process.
:::

3. **Select Repository and Trigger**

   - Choose the repository to integrate
   - Select a trigger method:
     - **New tag**: Builds trigger on new tags
       - Optionally add a regex to filter tags
     - **Push to branch**: Builds trigger on pushes to a specific branch

4. **Finalize Setup**
   - Confirm your settings to complete the integration

---

### Skip the automatic pipeline once

To ensure that a pipeline is not triggered by a specific commit, add `[ci skip]` or `[skip ci]` to the commit message. It is case insensitive.

:::note
You will still see a successful delivery of a webhook in your GitLab repository as a webhook is actually triggered, but with no action.
:::

---

## Disconnecting Your Repository

To disconnect your GitLab repository from Zerops:

1. Navigate to the **Service Details** page for the relevant service
1. Select **Build, Deploy, Run Pipeline Settings** from the menu.
1. Click **Stop automatic build trigger**

**This action will remove the GitLab webhook and delete the associated integration configuration, effectively halting automated builds from this repository.**


----------------------------------------

# References > Import Yaml > Pre Processor


The `yamlPreprocessor` option in your project & service import YAML allows you to generate random secret values, passwords, and public/private key pairs for your secret environment variables.

---

## How does it work?

The `yamlPreprocessor=on` is required as the first line in your import YAML to enable the preprocessor.

```yaml
#yamlPreprocessor=on
project:
  name: project
services:
  - hostname: app
    type: nodejs@latest
    buildFromGit: https://github.com/example/app
    enableSubdomainAccess: true
    envSecrets:
      # yamlPreprocessor feat: generates a random 64 char and stores it
      SECRET_KEY: <@generateRandomString(<64>)>

  - hostname: db
    type: postgresql@16
    mode: HA
```

After you've added the `yamlPreprocessor=on` line, the preprocessor will be enabled and you can now utilize the functions.

---

### How Preprocessing Works

The YAML script processing happens in two sequential steps. During the first turn (preprocessing), the system scans for Zerops import functions and modifiers, evaluates them, and replaces function calls with their results. All this data is stored in memory.

The second turn handles standard processing, where the system creates the imported project, instantiates all required services, and handles environment variables, including setting up any new ones as needed.

### Syntax Reference

<table className="w-full my-1.5 ">
  <thead>
    <tr className="">
      <th className="w-fit">Sequence</th>
      <th className="w-fit">Description</th>
    </tr>
  </thead>
  <tbody className="">
    <tr>
      <td className="w-fit">`<@`</td>
      <td className="w-fit ">The identifier of the beginning of a function expression syntax.</td>
    </tr>
    <tr>
      <td className="w-fit">`(`</td>
      <td className="w-fit">The identifier of the beginning of the function parameters.</td>
    </tr>
    <tr>
      <td className="w-fit">`)`</td>
      <td className="w-fit">The identifier of the end of the function parameters.</td>
    </tr>
    <tr>
      <td className="w-fit">`,`</td>
      <td className="w-fit">A function parameters delimiter.</td>
    </tr>
    <tr>
      <td className="w-fit">`<`</td>
      <td className="w-fit">Identifier of the beginning of a string expression (without @).</td>
    </tr>
    <tr>
      <td className="w-fit">`>`</td>
      <td className="w-fit">The identifier of the end of a string expression or a function expression syntax.</td>
    </tr>
    <tr>
      <td className="w-fit">`|`</td>
      <td className="w-fit">The separator between a string or a function expression content and a modifier name.</td>
    </tr>
    <tr>
      <td className="w-fit">`\`</td>
      <td className="w-fit">Escaping character.</td>
    </tr>
    <tr>
      <td className="w-fit">`\<>|`</td>
      <td className="w-fit">Characters that need to be escaped to print them out.</td>
    </tr>
  </tbody>
</table>

:::note
All functions in the preprocessor return values as strings, regardless of the operation performed. This includes numeric operations, random generation, and variable manipulation.
:::

---

## Parameter Data Types

Functions generally support 2 types of parameters.

### String expressions

- Value is enclosed in `<` and `>` characters.
- Spaces between `<` and `>` are NOT trimmed.
- When the value is passed as a function parameter, it's always a string.

```yaml
# String expression: <16>
SECRET_KEY: <@generateRandomString(<16>)>
# String expressions: <1> and <100>
RANDOM_RANGE: <@generateRandomInt(<1>, <100>)>
# String expressions: <red>, <green>, <blue>
PICK_VALUE: <@pickRandom(<red>, <green>, <blue>)>
```

### Variable reference names

Variables are used to store and reuse values across your configuration. They can be created using functions like `setVar` and retrieved using `getVar`.

- Variable references are NOT enclosed in `<` and `>` when used with `getVar`
- Variable names are case-sensitive
- Spaces before and after the reference name are trimmed
- Returns an error if the variable doesn't exist

```yaml
# Stores a value in myPassword variable
PASSWORD: <@setVar(<myPassword>, <@generateRandomString(<30>)>)>

# Retrieves the stored value (myPassword)
HASHED_PASSWORD: <@getVar(myPassword)|sha256>
# Reuses the stored value (myPassword)
SAME_PASSWORD_AGAIN: <@getVar(myPassword)>
```

:::tip Internal processing of function parameters
All parameters are handled as strings internally. For functions that expect numbers (like `generateRandomString`), the string values are automatically converted to numbers during processing.
:::

---

## Nested Expressions

The preprocessor supports nested function and string expressions, allowing you to:
- Combine multiple functions
- Use function outputs as inputs for other functions
- Nest string expressions within other strings
- Create complex, multi-level expressions

### Examples of Nesting with Environment Variables

```yaml
#yamlPreprocessor=on
services:
- hostname: app
  type: nodejs@20
  envSecrets:
    NESTED_STRINGS: <Base and <Nested> content>
    NESTED_FUNCTIONS: <@generateRandomString(<@generateRandomInt(<20>, <50>)>)>
    EVEN_MORE_NESTING: <@setVar(<refVarName>, <@generateRandomString(<@generateRandomInt(<20>, <30>)>)>)>
```

### Outputs of Nesting with Environment Variables

```yaml
#yamlPreprocessor=on
services:
- hostname: app
  type: nodejs@20
  envSecrets:
    NESTED_STRINGS: "Base and Nested content"
    NESTED_FUNCTIONS: "58580f0ad377a8e4c0dccc1622e2d3812b90"
    EVEN_MORE_NESTING: "73bcd2b647293dd04674cdecc"
```

### Escaping to Print Reserved Characters

Reserved characters `\<>|` have to be escaped using the `\` backslash to print them out. It's mandatory to escape the `\` character itself.

:::caution
The YAML processing happens in two sequential phases:
1. **Preprocessing Phase**: Evaluates functions, modifiers, and replaces them with results
2. **YAML Processing Phase**: Creates project, services, and handles environment variables

Each phase processes escape characters, so backslashes need to be escaped twice:

- If you want to output a single backslash `\`, you need to use four backslashes `\\\\`
- Example:

Input: `FILE_PATH: value\\\\with\\\\backslashes`

Output: `FILE_PATH: value\with\backslashes`

It means that if `DIR: <\\\\>` is used, the final value stored in the environment variable will be just `\`. The same is true for any value with backslashes, like `SERVER: True\\\\False`, where the stored result will be `True\False`.
:::

### Examples of Correct Function Expressions

```yaml
# Function will receive one parameter as the string constant value of: 30
<@generateRandomString(<30>)>
# Function will receive two parameters as the string constant values of: 200 and 1000
<@generateRandomInt(<200>, <1000>)>
# It's possible to nest functions one into the other.
<@generateRandomString(<@generateRandomInt(<200>, <1000>)>)>
# Using commas inside a string constant passed as the parameter is possible.
# The passed value is stored as internal variable under the name: commentValue
<@setVar(<commentValue>, <By the way, this is the text passed over as a value.>)>
# Function will receive one parameter as the internal variable reference: commentValue
# Its value is returned as a string if such an internal variable exists. If not, an error returns.
<@getVar(commentValue)>
# Examples of function expressions with escaped characters:
\<@generateRandomString(30)\>               # Output: <@generateRandomString(30)>
\<@generateRandomString(\<30\>)\>           # Output: <@generateRandomString(<30>)>
\<@generateRandomInt(\<30\>, \<80\>)\>      # Output: <@generateRandomInt(<30>, <80>)>
\<@generateRandomInt(\<30\>\, \<80\>)\>     # Output: <@generateRandomInt(<30>, <80>)>
\<@generateRandomInt(<30>, <80>)\>          # Output: <@generateRandomInt(30, 80)>
```

---

:::tip What happens with environment variable references
Environment variable reference might need to be used as a part of string expressions. From the parsing point of view on the pre-processing level, they have not been recognized as something special but just a regular string, and they will be transparently passed without any modification. The second standard parsing turn only evaluates them.
:::

```yaml

# The part ` {ITEM_VALUE` is taken as a regular text when storing a string value as an internal variable.
<@setVar(<commentValue>, <By the way, this ${ITEM_VALUE} is text passed over as a value.>)>
# The returned value will be exactly the same when retrieving the previously stored value.
<@getVar(<commentValue>)>
# The returned value will be: By the way, this  {ITEM_VALUE} is text passed over as a value.

```

---

## List of import functions

:::caution Important reminder
If you don't use the `yamlPreprocessor=on` line at the beginning of your import YAML script, the preprocessor will not be enabled and the functions will not work.

The `type: nodejs@latest` is just an example. The functions are available for all runtime types.
:::

---

### generateRandomString (length)

This function generates a random string of specified length using alphanumeric characters and some special characters (`_`, `-`, `.`). It's useful for creating random passwords, API keys, or any other secret values that needs to be unique and unpredictable.

<table className="w-full my-1.5">
  <thead>
    <tr>
      <th className="w-fit">Field</th>
      <th className="w-fit">Details</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td className="w-fit font-semibold">Syntax:</td>
      <td className="w-fit">`<@generateRandomString(<10>)>`</td>
    </tr>
    <tr>
      <td className="w-fit font-semibold">Limitation:</td>
      <td className="w-fit">Length of the string should be an *integer* between `1` and `1024` characters. eg. `<10>`, `<512>`, `<1024>`.</td>
    </tr>
    <tr>
      <td className="w-fit font-semibold">Output:</td>
      <td className="w-fit">hR5hS79H4p</td>
    </tr>
  </tbody>
</table>

#### Usage in import YAML

```yaml
#yamlPreprocessor=on
services:
- hostname: app
  type: nodejs@20
  envSecrets:
    RANDOM_STRING: <@generateRandomString(<10>)>
```

#### Output of import YAML

```yaml
RANDOM_STRING: 58580f0ad377a8e4c0dccc1622e2d3812b90
```

---

### generateRandomBytes (length)

This function generates requested amount of cryptographically random bytes. It is useful for creating random passwords, API keys, or any other secret values that needs to be unique and unpredictable.

<table className="w-full my-1.5">
  <thead>
    <tr>
      <th className="w-fit">Field</th>
      <th className="w-fit">Details</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td className="w-fit font-semibold">Syntax:</td>
      <td className="w-fit">`<@generateRandomBytes(<10>)>`</td>
    </tr>
    <tr>
      <td className="w-fit font-semibold">Limitation:</td>
      <td className="w-fit">Length of the string should be an *integer* between `1` and `1024` characters. eg. `<10>`, `<512>`, `<1024>`.</td>
    </tr>
    <tr>
      <td className="w-fit font-semibold">Output:</td>
      <td className="w-fit">hR5hS79H4p</td>
    </tr>
  </tbody>
</table>

#### Usage in import YAML

```yaml
#yamlPreprocessor=on
services:
- hostname: app
  type: nodejs@20
  envSecrets:
    RANDOM_STRING: <@generateRandomString(<10>)>
```

#### Output of import YAML

```yaml
RANDOM_STRING: 58580f0ad377a8e4c0dccc1622e2d3812b90
```

---

### generateRandomInt (min, max)

This function generates a random integer within a specified range (inclusive). It's particularly useful when you need random numeric values, like ports, timeouts, or any other configuration that requires random numbers within specific bounds.

<table className="w-full my-1.5 ">
  <thead>
    <tr>
      <th className="w-fit">Field</th>
      <th className="w-fit">Details</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td className="w-fit font-semibold">Syntax:</td>
      <td className="w-fit">`<@generateRandomInt(<200>, <1000>)>`</td>
    </tr>
    <tr>
      <td className="w-fit font-semibold">Minimum:</td>
      <td className="w-fit">Required minimum (inclusive) as a signed integer (from -4,611,686,018,427,387,903 to 4,611,686,018,427,387,903).</td>
    </tr>
    <tr>
      <td className="w-fit font-semibold">Maximum:</td>
      <td className="w-fit">Required maximum (inclusive) as a signed integer (from -4,611,686,018,427,387,903 to 4,611,686,018,427,387,903).</td>
    </tr>
    <tr>
      <td className="w-fit font-semibold">Output:</td>
      <td className="w-fit">823</td>
    </tr>
  </tbody>
</table>

#### Usage in import YAML

```yaml
#yamlPreprocessor=on
services:
- hostname: app
  type: nodejs@20
  envSecrets:
    RANDOM_INT: <@generateRandomInt(<200>, <1000>)>
```

#### Output of import YAML

```yaml
RANDOM_INT: 823
```

---

### pickRandom (...param)

<table className="w-full my-1.5 ">
  <thead>
    <tr>
      <th className="w-fit">Field</th>
      <th className="w-full">Details</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td className="w-fit font-semibold">Syntax:</td>
      <td className="w-fit">`<@pickRandom(<640>, <800>, <1024>, <1280>, <1440>, <1920>)>`</td>
    </tr>
    <tr>
      <td className="w-fit font-semibold">Parameters:</td>
      <td className="w-fit">The required parameters from which the selection will be made. eg. `<1101>`, `<800>`, `<1920>`, etc.</td>
    </tr>
    <tr>
      <td className="w-fit font-semibold">Output:</td>
      <td className="w-fit">1024</td>
    </tr>
  </tbody>
</table>

This function randomly selects one value from a list of provided options. It's helpful when you want to randomly assign values from a predefined set, such as screen resolutions, configuration options, or any other scenario where you need random selection from specific choices.

#### Usage in import YAML

```yaml
#yamlPreprocessor=on
services:
- hostname: app
  type: nodejs@20
  envSecrets:
    PICK_RANDOM: <@pickRandom(<640>, <800>, <1024>, <1280>, <1440>, <1920>)>
```

#### Output of import YAML

```yaml
PICK_RANDOM: 1024
```

---

### setVar (name, content)

This function stores a value in memory for later use and returns the stored value. It's particularly useful when you need to reuse the same generated value multiple times in your configuration, ensuring consistency across different environment variables.

<table className="w-full my-1.5 ">
  <thead>
    <tr>
      <th className="w-fit">Field</th>
      <th className="w-fit">Details</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td className="w-fit font-semibold">Syntax:</td>
      <td className="w-fit">`<@setVar(<plainPassword>, <@generateRandomString(<16>)>)>`</td>
    </tr>
    <tr>
      <td className="w-fit font-semibold">Variable:</td>
      <td className="w-fit">The required parameter of the internal variable name under which the provided content can be retrieved later using [getVar](#getvar) function. The chosen name is case-sensitive. eg. `<varName>`, `<plainPassword>`, etc</td>
    </tr>
    <tr>
      <td className="w-fit font-semibold">Content:</td>
      <td className="w-fit">Any text you want to be stored, including composition using functions. Already existing variable with the same name is overwritten.</td>
    </tr>
    <tr>
      <td className="w-fit font-semibold">Output:</td>
      <td className="w-fit">N4KdtM41WskS74wx</td>
    </tr>
  </tbody>
</table>

#### Usage in import YAML

```yaml
#yamlPreprocessor=on
services:
- hostname: app
  type: nodejs@20
  envSecrets:
    SET_VAR: <@setVar(<plainPassword>, <@generateRandomString(<16>)>)>
```

#### Output of import YAML

```yaml
SET_VAR: N4KdtM41WskS74wx
```

---

### getVar (name)

This function retrieves a previously stored value from memory. It works in conjunction with setVar and other storage functions to access values that were generated or stored earlier in the configuration process. eg. `plainPassword`

<table className="w-full my-1.5 ">
  <thead>
    <tr>
      <th className="w-fit">Field</th>
      <th className="w-fit">Details</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td className="w-fit font-semibold">Syntax:</td>
      <td className="w-fit">`<@getVar(plainPassword)>`</td>
    </tr>
    <tr>
      <td className="w-fit font-semibold">Variable:</td>
      <td className="w-fit">The required parameter of the internal variable name that is case-sensitive. The parameter is used as a reference, so it MUST NOT be enclosed in &lt; and &gt;. eg. `(plainPassword)`, `(varName)`, etc</td>
    </tr>
    <tr>
      <td className="w-fit font-semibold">Output:</td>
      <td className="w-fit">N4KdtM41WskS74wx</td>
    </tr>
  </tbody>
</table>

#### Usage in import YAML

```yaml
#yamlPreprocessor=on
services:
- hostname: app
  type: nodejs@20
  envSecrets:
    GET_VAR: <@getVar(plainPassword)>
```

#### Output of import YAML

```yaml
GET_VAR: N4KdtM41WskS74wx
```

---

### generateRandomStringVar (name, length)

This function combines the functionality of `generateRandomString` and `setVar`. It generates a random string and automatically stores it under a specified variable name for later use.

The output contains only a random combination of alphanumeric characters (`a-zA-Z0-9`) and select special characters (`_`, `-`, `.`).

<table className="w-full my-1.5 ">
  <thead>
    <tr>
      <th className="w-fit">Field</th>
      <th className="w-fit">Details</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td className="w-fit font-semibold">Syntax:</td>
      <td className="w-fit">`<@generateRandomStringVar(<plainPassword>, <10>)>`</td>
    </tr>
    <tr>
      <td className="w-fit font-semibold">Variable:</td>
      <td className="w-fit">The required parameter of the internal variable name under which the provided content can be retrieved later using [getVar](#getvar) function. The chosen name is case-sensitive. eg. `<plainPassword>`, `<varName>`, etc</td>
    </tr>
    <tr>
      <td className="w-fit font-semibold">Limitation:</td>
      <td className="w-fit">Required length of the string to be generated in characters (maximum allowed value is 1024).</td>
    </tr>
    <tr>
      <td className="w-fit font-semibold">Output:</td>
      <td className="w-fit">hR5hS79H4p</td>
    </tr>
  </tbody>
</table>

#### Usage in import YAML

```yaml
#yamlPreprocessor=on
services:
- hostname: app
  type: nodejs@20
  envSecrets:
    GENERATE_RANDOM_STRING_VAR: <@generateRandomStringVar(<plainPassword>, <10>)>
```

#### Output of import YAML

```yaml
GENERATE_RANDOM_STRING_VAR: hR5hS79H4p
```

---

### generateJWT (tokenSecret, jsonPayload)

This function generates a JWT (JSON Web Token) signed by HS256 algorithm using provided secret and payload. The payload MUST be a valid JSON value. Default values for `iss` and `iat` are set to `zerops` and current timestamp respectively.

<table className="w-full my-1.5 ">
  <thead>
    <tr>
      <th className="w-fit">Field</th>
      <th className="w-fit">Details</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td className="w-fit font-semibold">Syntax:</td>
      <td className="w-fit">`<@generateJWT(<tokenSecret>, <jsonPayload>)>`</td>
    </tr>
    <tr>
      <td className="w-fit font-semibold whitespace-nowrap">Token Secret:</td>
      <td className="w-fit">The required secret (`string`) used to sign your JWT.</td>
    </tr>
    <tr>
      <td className="w-fit font-semibold whitespace-nowrap">JSON Payload:</td>
      <td className="w-fit">The required payload part of the JWT (`string`) in JSON format.</td>
    </tr>
    <tr>
      <td className="w-fit font-semibold">Output:</td>
      <td className="w-fit">eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJyb2xlIjoiYWRtaW4iLCJpYXQiOjE3Mjkw
      Njk4NTcsImlzcyI6Inplcm9wcyJ9.xPrqHDtGhK5c7WMJliguwBeKI29qzAoD7KXrtACb
      jio</td>
    </tr>
  </tbody>
</table>

#### Usage in import YAML

```yaml
#yamlPreprocessor=on
services:
- hostname: app
  type: nodejs@20
  envSecrets:
    # Using a fixed secret string
    JWT_FIXED: <@generateJWT(<fixedSecretString>, <{"role":"admin","exp":1798761600}>)>

    # Using an empty payload
    JWT_EMPTY: <@generateJWT(<fixedSecretString>, <{}>)>

    # Generate and store a random secret, then use it
    JWT_RANDOM: <@generateJWT(<@generateRandomStringVar(<jwtSecretKey>, <32>)>, <{"role":"admin","exp":1798761600}>)>

    # Use a previously stored secret
    JWT_STORED: <@generateJWT(<@getVar(jwtSecretKeyVar)>, <{"role":"admin","exp":1798761600}>)>
```

#### Output of import YAML

```yaml
JWT_FIXED: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJyb2xlIjoiYWRtaW4iLCJleHAiOjE3OTg3NjE2MDAsImlhdCI6MTcyOTA2OTYzMiwiaXNzIjoiemVyb3BzIn0.xPrqHDtGhK5c7WMJliguwBeKI29qzAoD7KXrtACbjio

JWT_EMPTY: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3MjkwNjk4NTcsImlzcyI6Inplcm9wcyJ9.xPrqHDtGhK5c7WMJliguwBeKI29qzAoD7KXrtACbjio

JWT_RANDOM: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJyb2xlIjoiYWRtaW4iLCJleHAiOjE3OTg3NjE2MDAsImlhdCI6MTcyOTA2OTYzMiwiaXNzIjoiemVyb3BzIn0.ksbck_HQv44YXbqJk6lDrGFYTq3nmLydFIe0Xlejk5Q

JWT_STORED: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJyb2xlIjoiYWRtaW4iLCJleHAiOjE3OTg3NjE2MDAsImlhdCI6MTcyOTA2OTYzMiwiaXNzIjoiemVyb3BzIn0.O0RaXzGFwj2t8P2kc4nU4PfuI43-dAuAl2d0T1uUlEE
```

---

### getDateTime (format, [timezone])

This function returns the current date and time formatted according to your specifications. It's useful for timestamps, logging, and any scenario where you need the current time in a specific format and timezone.

Returns the current date and time in a [specified mask pattern](#masking) and a chosen timezone.

<table className="w-full my-1.5 ">
  <thead>
    <tr>
      <th className="w-fit">Field</th>
      <th className="w-fit">Details</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td className="w-fit font-semibold">Syntax:</td>
      <td className="w-fit">`<@getDatetime(<DD.MM.YYYY HH:mm:ss>, <CET>)>`</td>
    </tr>
    <tr>
      <td className="w-fit font-semibold">Mask:</td>
      <td className="w-fit">The required parameter of the chosen timezone.
      eg. `<DD.MM.YYYY HH:mm:ss>`</td>
    </tr>
    <tr>
      <td className="w-fit font-semibold">Timezone:</td>
      <td className="w-fit">
        The optional parameter of the chosen timezone. It's possible to select from three different formats: Abbreviation, Location, and POSIX. If not specified, the GMT timezone is set by default.

        You can see the complete listing of [all possible values](https://nodatime.org/TimeZones). POSIX format uses the opposite sign. Times to the west are positive, to the east negative.

        For Central European Time, you can use `CET`, `Europe/Prague`, `Etc/GMT-2` (summer), `Etc/GMT-1` (winter). Abbreviated and location formats return values with the currently valid DST.

        eg. `<CET>`, `<Europe/Prague>`, `<Etc/GMT-2>`
      </td>
    </tr>
    <tr>
      <td className="w-fit font-semibold">Output:</td>
      <td className="w-fit">11.12.2022 18:06:13</td>
    </tr>
  </tbody>
</table>

#### Usage in import YAML

```yaml
#yamlPreprocessor=on
services:
- hostname: app
  type: nodejs@20
  envSecrets:
    GET_DATETIME: <@getDatetime(<DD.MM.YYYY HH:mm:ss>, <CET>)>
```

#### Output of import YAML

```yaml
GET_DATETIME: 11.12.2022 18:06:13
```

#### Masking

#### Date and Time Format

When using the `getDateTime` function, you can customize the output format using various masks. Here's a comprehensive list of available format patterns:

    #### Year
    - `YYYY` - Full year (e.g., 2024)
    - `YY` - Two-digit year (e.g., 24)

    #### Month
    - `MMMM` - Full month name (e.g., January)
    - `MMM` - Short month name (e.g., Jan)
    - `MM` - Two-digit month (e.g., 01)
    - `M` - Single-digit month (e.g., 1)

    #### Day
    - `DDDD` - Day of year with leading zeros (e.g., 001, 002, ..., 365)
    - `DD` - Day of month with leading zeros (e.g., 01, 02, ..., 31)
    - `D` - Day of month without leading zeros (e.g., 1, 2, ..., 31)
    - `dddd` - Full weekday name (e.g., Monday)
    - `ddd` - Short weekday name (e.g., Mon)

    #### Time
    - `HH` - 24-hour format with leading zeros (e.g., 00, 01, ..., 23)
    - `hh` - 12-hour format with leading zeros (e.g., 01, 02, ..., 12)
    - `h` - 12-hour format without leading zeros (e.g., 1, 2, ..., 12)
    - `mm` - Minutes with leading zeros (e.g., 00, 01, ..., 59)
    - `m` - Minutes without leading zeros (e.g., 0, 1, ..., 59)
    - `ss` - Seconds with leading zeros (e.g., 00, 01, ..., 59)
    - `s` - Seconds without leading zeros (e.g., 0, 1, ..., 59)
    - `S` - Microseconds (e.g., 000000...999999)

    #### Period
    - `A` - Uppercase meridiem (AM, PM)
    - `a` - Lowercase meridiem (am, pm)

    #### Timezone
    - `ZZZ` - Timezone abbreviation (e.g., UTC, CET)
    - `zz` - Timezone offset with colon (e.g., +00:00, +01:00)
    - `Z` - Timezone offset without colon (e.g., +0000, +0100)

    #### Usage of different masks

    ```yaml
    #yamlPreprocessor=on
    services:
      - hostname: app
        type: nodejs@20
        envSecrets:
          TIMESTAMP: <@getDateTime(<YYYY-MM-DD HH:mm:ss>, <UTC>)>
          FRIENDLY_DATE: <@getDateTime(<dddd, MMM D, YYYY 'at' h:mma>, <UTC>)>
    ```

---

:::tip Example Usage for Environment Variables
- For Multiline Generation use:
```yaml
APP_PUBLIC_KEY: |
      <@getVar(KeyPublic)>
```

- For Single Value Generation use:
```yaml
APP_PUBLIC_KEY_SSH: <@getVar(KeyPublicSsh)>
```
:::

---

### generateED25519Key (name)

Generates public and private [ED25519](https://en.wikipedia.org/wiki/EdDSA) key pairs (including SSH) and stores them for later use as internal variables with names using the base name and variants.

<table className="w-full my-1.5 ">
  <thead>
    <tr>
      <th className="w-fit">Field</th>
      <th className="w-fit">Details</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td className="w-fit font-semibold">Syntax:</td>
      <td className="w-fit">`<@generateED25519Key(<Key>)>`</td>
    </tr>
    <tr>
      <td className="w-fit font-semibold">Variants:</td>
      <td className="w-fit">The base name parameter stores all generated key versions as internal variables, combined with the [Available Variants](#available-variants).</td>
    </tr>
  </tbody>
</table>

#### Available Variants

<table className="w-full my-1.5 ">
  <thead>
    <tr>
      <th className="w-fit">Variant</th>
      <th className="w-fit">Description</th>
      <th className="w-fit">Retrieving the value</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td className="w-fit">Public</td>
      <td className="w-fit">Public key version. This value is also returned by the called function.</td>
      <td className="w-fit">`<@getVar(KeyPublic)>`</td>
    </tr>
    <tr>
      <td className="w-fit">PublicSsh</td>
      <td className="w-fit">SSH formatted public key version. For use as the authorized key file.</td>
      <td className="w-fit">`<@getVar(KeyPublicSsh)>`</td>
    </tr>
    <tr>
      <td className="w-fit">Private</td>
      <td className="w-fit">Private key version in the standard format. Not usable for OpenSSH.</td>
      <td className="w-fit">`<@getVar(KeyPrivate)>`</td>
    </tr>
    <tr>
      <td className="w-fit">PrivateSsh</td>
      <td className="w-fit">Private key version in the OpenSSH format.</td>
      <td className="w-fit">`<@getVar(KeyPrivateSsh)>`</td>
    </tr>
  </tbody>
</table>

#### Usage in import YAML

:::caution
  These Generated keys are formatted as multiline strings. That means using the `|` syntax is necessary in import YAML.
:::

```yaml
#yamlPreprocessor=on
services:
- hostname: app
  type: nodejs@20
  envSecrets:
    GENERATED_PUBLIC_KEY: |
      <@generateED25519Key(<Key>)>
    APP_PUBLIC_KEY: |
      <@getVar(KeyPublic)>
    APP_PUBLIC_KEY_SSH: <@getVar(KeyPublicSsh)>
    APP_PRIVATE_KEY: |
      <@getVar(KeyPrivate)>
    APP_PRIVATE_KEY_SSH: |
      <@getVar(KeyPrivateSsh)>
```

#### Output of import YAML

:::info
  You can clearly see the multiline strings and the `|` syntax in Output.
:::

#### GENERATED_PUBLIC_KEY

- Generated as a multiline value
    - The same value as in APP_PUBLIC_KEY.

    ```yaml
    GENERATED_PUBLIC_KEY: |
      -----BEGIN PUBLIC KEY-----
      MCowBQYDK2VwAyEAu0/gEIpNUbVdqA20lVl+ZD+5/zzfVK4exrgGLxgQQRU=
      -----END PUBLIC KEY-----
    ```

#### APP_PUBLIC_KEY

- Generated as a multiline value.
    - The same value as in GENERATED_PUBLIC_KEY.

    ```yaml
    APP_PUBLIC_KEY: |
      -----BEGIN PUBLIC KEY-----
      MCowBQYDK2VwAyEAu0/gEIpNUbVdqA20lVl+ZD+5/zzfVK4exrgGLxgQQRU=
      -----END PUBLIC KEY-----
    ```

#### APP_PUBLIC_KEY_SSH

- Generated as a single value

    ```yaml
    APP_PUBLIC_KEY_SSH: ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAILtP4BCKTVG1XagNtJVZfmQ/uf8831SuHsa4Bi8YEEEV
    ```

#### APP_PRIVATE_KEY

- Generated as a multiline value

    ```yaml
    APP_PRIVATE_KEY: |
      -----BEGIN PRIVATE KEY-----
      MC4CAQAwBQYDK2VwBCIEIFzW6uPLlMnse2Hqg4hlyTwtlWaPKHjyoaaBi/FfVxBQ
      -----END PRIVATE KEY-----
    ```

#### APP_PRIVATE_KEY_SSH

- Generated as a multiline value

    ```yaml
    APP_PRIVATE_KEY_SSH: |
      -----BEGIN OPENSSH PRIVATE KEY-----
      b3BlbnNzaC1rZXktdjEAAAAABG5vbmUAAAAEbm9uZQAAAAAAAAABAAAAMwAAAAtz
      c2gtZWQyNTUxOQAAACC7T+AQik1RtV2oDbSVWX5kP7n/PN9Urh7GuAYvGBBBFQAA
      AIiaywRCmssEQgAAAAtzc2gtZWQyNTUxOQAAACC7T+AQik1RtV2oDbSVWX5kP7n/
      PN9Urh7GuAYvGBBBFQAAAEBc1urjy5TJ7Hth6oOIZck8LZVmjyh48qGmgYvxX1cQ
      ULtP4BCKTVG1XagNtJVZfmQ/uf8831SuHsa4Bi8YEEEVAAAAAAECAwQF
      -----END OPENSSH PRIVATE KEY-----
    ```

---

### generateRSA2048Key (name)

This Generates public and private [RSA 2048bit](https://en.wikipedia.org/wiki/RSA_(cryptosystem)) key pairs (including SSH) and stores them for later use as internal variables with names using the base name and variants.

<table className="w-full my-1.5 ">
  <thead>
    <tr>
      <th className="w-fit">Field</th>
      <th className="w-fit">Details</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td className="w-fit font-semibold">Syntax:</td>
      <td className="w-fit">`<@generateRSA2048Key(<Key>)>`</td>
    </tr>
    <tr>
      <td className="w-fit font-semibold">Variants:</td>
      <td className="w-fit">The base name parameter stores all generated key versions as internal variables, combined with the [Available Variants](#available-variants).</td>
    </tr>
  </tbody>
</table>

#### Available Variants

<table className="w-full my-1.5 ">
  <thead>
    <tr>
      <th className="w-fit">Variant</th>
      <th className="w-fit">Description</th>
      <th className="w-fit">How to use with: `<@generateRSA2048Key(<Key>)>`</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td className="w-fit">Public</td>
      <td className="w-fit">Public key version. This value is also returned by the called function.</td>
      <td className="w-fit">`<@getVar(KeyPublic)>`</td>
    </tr>
    <tr>
      <td className="w-fit">PublicSsh</td>
      <td className="w-fit">SSH formatted public key version. For use as the authorized key file.</td>
      <td className="w-fit">`<@getVar(KeyPublicSsh)>`</td>
    </tr>
    <tr>
      <td className="w-fit">Private</td>
      <td className="w-fit">Private key version in the standard format.</td>
      <td className="w-fit">`<@getVar(KeyPrivate)>`</td>
    </tr>
  </tbody>
</table>

#### Usage in import YAML

:::caution
  These Generated keys are formatted as multiline strings. That means using the `|` syntax is necessary in import YAML.
:::

```yaml
#yamlPreprocessor=on
services:
- hostname: app
  type: nodejs@16
  minContainers: 1
  envSecrets:
    GENERATED_PUBLIC_KEY: |
      <@generateRSA2048Key(<Key>)>
    APP_PUBLIC_KEY: |
      <@getVar(KeyPublic)>
    APP_PUBLIC_KEY_SSH: <@getVar(KeyPublicSsh)>
    APP_PRIVATE_KEY: |
      <@getVar(KeyPrivate)>
```

#### Output of import YAML

:::info
  You can clearly see the multiline strings and the `|` syntax in Output.
:::

#### GENERATED_PUBLIC_KEY

- Generated as a multiline value
    - The same value as in APP_PUBLIC_KEY.

    ```yaml
    GENERATED_PUBLIC_KEY: |
      -----BEGIN PUBLIC KEY-----
      MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAyWMKx+vdEb/Ww19trV9D
      og7x6d4MCL4u576fVdDjBFhXjXYrK0Y0movvYNe72qtpggW8FnAiKbFNWMLr7mV1
      2u0JEdPzaqSOX/XKRKWq2q7wyZjGU0uVLJ3Rd2Y4yFyjg6zbvA0Hh5HRgbn7xoRM
      UbT3mt1lBP+DeHIi9exTvtiNfpO0Z1bidmLLvzLnakg1ei8YWnEAFJi83/MuRMhI
      WOA32h14WVbvg4SA7++STHF3uHL+kHJ7P/KeqACDBPbgcc9Sz7WsSTAO6Pdry3sr
      KCP60AMaT2PewB51AtuvFR8nP05WskMgd887KHXZjk9NhDU5E06vz4nf7a3t+it0
      UwIDAQAB
      -----END PUBLIC KEY-----
    ```

#### APP_PUBLIC_KEY

- Generated as a multiline value.
    - The same value as in GENERATED_PUBLIC_KEY.

    ```yaml
    APP_PUBLIC_KEY: |
      -----BEGIN PUBLIC KEY-----
      MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAyWMKx+vdEb/Ww19trV9D
      og7x6d4MCL4u576fVdDjBFhXjXYrK0Y0movvYNe72qtpggW8FnAiKbFNWMLr7mV1
      2u0JEdPzaqSOX/XKRKWq2q7wyZjGU0uVLJ3Rd2Y4yFyjg6zbvA0Hh5HRgbn7xoRM
      UbT3mt1lBP+DeHIi9exTvtiNfpO0Z1bidmLLvzLnakg1ei8YWnEAFJi83/MuRMhI
      WOA32h14WVbvg4SA7++STHF3uHL+kHJ7P/KeqACDBPbgcc9Sz7WsSTAO6Pdry3sr
      KCP60AMaT2PewB51AtuvFR8nP05WskMgd887KHXZjk9NhDU5E06vz4nf7a3t+it0
      UwIDAQAB
      -----END PUBLIC KEY-----
    ```

#### APP_PUBLIC_KEY_SSH

- Generated as a single value

    ```yaml
    APP_PUBLIC_KEY_SSH: ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDJYwrH690Rv9bDX22tX0OiDvHp3gwIvi7nvp9V0OMEWFeNdisrRjSai+9g17vaq2mCBbwWcCIpsU1YwuvuZXXa7QkR0/NqpI5f9cpEpararvDJmMZTS5UsndF3ZjjIXKODrNu8DQeHkdGBufvGhExRtPea3WUE/4N4ciL17FO+2I1+k7RnVuJ2Ysu/MudqSDV6LxhacQAUmLzf8y5EyEhY4DfaHXhZVu+DhIDv75JMcXe4cv6Qcns/8p6oAIME9uBxz1LPtaxJMA7o92vLeysoI/rQAxpPY97AHnUC268VHyc/TlayQyB3zzsoddmOT02ENTkTTq/Pid/tre36K3RT
    ```

#### APP_PRIVATE_KEY

- Generated as a multiline value

    ```yaml
    APP_PRIVATE_KEY: |
      -----BEGIN PRIVATE KEY-----
      MIIEvwIBADANBgkqhkiG9w0BAQEFAASCCS4wggkqAgEAAoICAQDWRgQntuMGJfME
      wj9wLrBqNyUd13k1nRuzHZ3x5VJodRrPjX19M9gFXuY95zTJti6VOG+pZftzuTkf
      +MlW9NwFEe/g0OomY6UwfKfPj4/ib3MPiASg2o4Ixqu0mv3IrLOsGmU25J38gAVQ
      I3oohW4+B7Vp+2+RnLQCx1FsweWpa8wR0ffQwl0LsWSEWyutfSxi+5pbYwWORBOK
      yESmGFqGBhMfl0KutBqNAGLt9IYS61bYIqnvfzHqE1uIH3/+ViNzMAr56xt8Lr5a
      +Y84Mmer1h1wnh6OHnOE6y2sw+876RO8OjMTnHq6v1HDnKHQyCNHxDvpqihy7hly
      RtCpC9fuCJC94lB0Gf65xgJC55Jx7gGRSbdLUhN2XZdQeAGPtdidz5KqC8S02fhi
      DKe0C78hpUGD8MZU4GqvqlyiHoouBhKugkba7F0NeSOLVC9GPLdKNjt5AyCi72pQ
      z8vXaBk8TIb7F+WeQ3NtLw8sgZj0XjXRtx/S6SSoTIOkIKB6hKsPV0k+Z7VaVJ+F
      pXPsr2CbwcH0iyCJC6A6hLQWnDnts26PLcFck7hE6UjE4BsBhXQhcyMTe5Yai3y4
      V5NWoHinkLO9NX2N2hBcpQWSSCbr0wSg33xAHROzcG1w5/n1fq46723CbWW3Gcsf
      naL/hPIt3MSsiz28RqjHlB7qXiWEBQIDAQABAoICAQCemAYdSv0voMkFfaysoLIM
      e7JqKwDY0OcepM4xq1VaYUqt0oDOOaArIXly2f01SzWhVrs2+3eoyLBiXKbRSLzM
      t+D/WkHklh4/DBS8yPprU6grF7atQ/aawkl2jL1IWaNGv+aoQYA50pucHBYfhdr5
      6IS649JJSV3nLJW01LLiuhm6Gtm8Vw+9RtgqKrziVOKUhLtT5q/HA9YfA2nkMeRW
      jIp8+Fzvp/h64o1WqITP3gZSRR3YWSGdqiQ2VXJL0n+8kxOctQqL2KEl/s6lfpFD
      G2CA6VeeQyWnfNY6qG8avcHQsJb7bfdc35xqFzWhrXCHftQFd98madrFvWpVpKF1
      fjSrQAWHShgyCBQuBteWhYWFlWMkYX3tab6MUS8vUR3LQuv3NGEWvQMgxA2eBzq2
      iPhTnCJ0EQIMgsBg+O6qW2JuJMdTwB2U+WlLJiJnSBQ5aWwDKjIIzoH17lYmDOvz
      ij0ZbzHUx01wU5w58z8mi//PppQheaxIT0jZkoGXOmbMsCTv/UcxlqnVHJ1ysA8d
      QgK+3L+7dyjl3k5IQNt9f49X/C5D0oPYGuzPuP37HzEZYZbYtz5CoICUf6nNFGBl
      aetSTGRs6ePVqHlo1cZQdk5fIQwX7yelehEb/Cpjk0mv5sk8cJcYviAnkQyUBjOE
      wujWkG9XTisPMl3c6pAkJQKCAQEA/5TAJKP/uGofwDxoFXg4zjyRsqWeWpIvny5E
      K9avHPdqFcU1DGAVwUfw6z5Grx8QzWZbnPFI5KMvdVoLpDMubw1XWQCY5X7AD3Iu
      C9C0cbE+vW8d0AKGEt2q4ERTMZ5dqJiAN/tGJ8wH9mQxOhoim1MPAb0PZJg6WHda
      4uN/wnZCuhEVnU86vbKhMJUZYotxEiV3qokZzV7zwsYOdCDw5iipm6McrRVrfdyE
      u4yIyorq9RB3JChhkgkKSLaFHpuG/YOSM0DQ3vizC57w3LpJ+i+d2FR7Z8fYPSSW
      BF/hUBUNZG4kk4wxH9dYk27ohBSI2u44n50zrQGST36vxETodwKCAQEA1p/uia4V
      cHilRd454sQMevtbZO2Zak/g7MzxIUIPI363CKCfjIu/t3iyJ5xohI6OVdqdvE0/
      hEiVJkv5YNXNLvQFnF7y7z5/HKjkEe72TrZuBwWSoQx69UP9QymzMuV+41f8aVpc
      c2Xe7XWXK+X56ZGRFND5sB8hd65G9D818Qi90kQyYlb43l8CyiylqYIYh8ldIqHU
      jAzNGk65kpW6CkL9v/qloKrpAWxErAinB40MHBvgZULj7LijCt2orHOPjOjC1f8n
      BDf9eBKT+gTLXifIggGBh0iBxen9d2S7/Wz4ySLX47ijDgH0aQO8d668z+c9As0t
      lz1HmEqLtyLSYwKCAQBH3Y/ZvbOeK1kaOOIbh16Rvz5IuYE5fnmdjOjmWsuKnZda
      38T24d28J3p661v8ygNzfiCslLwmbixeFx/G4A1idKHnCN/1SBrBPR3tfJYAkhJO
      OfxsDQmeLG5r+UpbXWiAi8Eh/KnRbvGeOrYM3GR2wHgryPmXE6b0UTthKQ83owFI
      SJ2HSkv+I0hn3MTyjLsSmy526W4z7UslrYNK7ChQz4ZBmS/rC2baUTOReQbNzRoc
      JrEZnbEx2xDlOU1dOeZPSrvFZahVyiCuV9bqegdrLhB4T+kTWYJYTv1P5ZX5arIF
      V2M5ieYWSftCGaGP4iZJSUrqts1dDGATsk/CJI4pAoIBAQCnIfYk2x6w7hJt/ScA
      swCxCGpchzYv9rJGVTX1WzbkwjmQi1yTmwQZwPCjLgaqK0UmEE9DIriyr78OCp3R
      Tc0xoi94XOw7aGSeEdtBJ+BA3YmDCFDt/wUFWAOyOJfmq5aLPao+9HIIHy1hp2+o
      bLeXrpbXKgE2qJdsVpfEfjDoWZFQW3EM6YN1z3EhtXDwNnIZ07ImVPVqdlGGCgYy
      40vzz8VAqdQu8MjwJbq4aSiBFdJ3VTICSPurDQFSZdiDKp5/8YZAFSjx/RPyXC1F
      xlQEJ2DZ9IhErC76y0NppVVLfX+jSfHq0I6RSu5klNdAMB+ymvUE6Hh3TO4i5vI0
      E/bXAoIBAQCEXLJhLE/imGPl1Fbqh4lnr2iRMzN3cPxb6DHiKoFXhY18/WWneXEI
      8DwK0D+n8spX67YyelFqBjWi4JrG2KhZmPSBF7p7lPypjPdbjkCnSJ0Qjrvdo5ns
      46CtmUH8d54SAdgRkXypc1y/3mOnVAhnSRUYm5mtDOtfG0dXdsfS/uDXVRZkTv7S
      xjdaHi3Ap+oxTMS+zWfKvYAx5g0gTdvb+FdsN89T9XRRx+7N5TmG9D+sUAqNEWkH
      7SG6By8x+JqhURZOF9T9n2TX7N9g/+c0y9J10Ol5r0rDFM4SSTX9A5NmqfNF6LO7
      A0bX/JM8kHjLlJNrtioxcT+dX4lL6/zT
      -----END PRIVATE KEY-----
    ```

---

### generateRSA4096Key (name)

This Function Generates public and private [RSA 4096bit](https://en.wikipedia.org/wiki/RSA_(cryptosystem)) key pairs (including SSH) and stores them for later use as internal variables with names using the base name and variants.

<table className="w-full my-1.5 ">
  <thead>
    <tr>
      <th className="w-fit">Field</th>
      <th className="w-fit">Details</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td className="w-fit font-semibold">Syntax:</td>
      <td className="w-fit">`<@generateRSA4096Key(<Key>)>`</td>
    </tr>
    <tr>
      <td className="w-fit font-semibold">Variants:</td>
      <td className="w-fit">The base name parameter stores all generated key versions as internal variables, combined with the [Available Variants](#available-variants).</td>
    </tr>
  </tbody>
</table>

#### Available Variants

<table className="w-full my-1.5 ">
  <thead>
    <tr>
      <th className="w-fit">Variant</th>
      <th className="w-fit">Description</th>
      <th className="w-fit">How to use with: `<@generateRSA4096Key(<Key>)>`</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td className="w-fit">Public</td>
      <td className="w-fit">Public key version. This value is also returned by the called function.</td>
      <td className="w-fit">`<@getVar(KeyPublic)>`</td>
    </tr>
    <tr>
      <td className="w-fit">PublicSsh</td>
      <td className="w-fit">SSH formatted public key version. For use as the authorized key file.</td>
      <td className="w-fit">`<@getVar(KeyPublicSsh)>`</td>
    </tr>
    <tr>
      <td className="w-fit">Private</td>
      <td className="w-fit">Private key version in the standard format.</td>
      <td className="w-fit">`<@getVar(KeyPrivate)>`</td>
    </tr>
  </tbody>
</table>

#### Usage in import YAML

:::caution
  These Generated keys are formatted as multiline strings. That means using the `|` syntax is necessary in import YAML.
:::

```yaml
#yamlPreprocessor=on
services:
- hostname: app
  type: nodejs@16
  envSecrets:
    GENERATED_PUBLIC_KEY: |
      <@generateRSA4096Key(<Key>)>
    APP_PUBLIC_KEY: |
      <@getVar(KeyPublic)>
    APP_PUBLIC_KEY_SSH: <@getVar(KeyPublicSsh)>
    APP_PRIVATE_KEY: |
      <@getVar(KeyPrivate)>
```

#### Output of import YAML

:::info
  You can clearly see the multiline strings and the `|` syntax in Output.
:::

#### GENERATED_PUBLIC_KEY

- Generated as a multiline value
    - The same value as in APP_PUBLIC_KEY.

    ```yaml
    GENERATED_PUBLIC_KEY: |
      -----BEGIN PUBLIC KEY-----
      MIICIjANBgkqhkiG9w0BAQEFAAOCAg8AMIICCgKCAgEA1kYEJ7bjBiXzBMI/cC6w
      ajclHdd5NZ0bsx2d8eVSaHUaz419fTPYBV7mPec0ybYulThvqWX7c7k5H/jJVvTc
      BRHv4NDqJmOlMHynz4+P4m9zD4gEoNqOCMartJr9yKyzrBplNuSd/IAFUCN6KIVu
      Pge1aftvkZy0AsdRbMHlqWvMEdH30MJdC7FkhFsrrX0sYvuaW2MFjkQTishEphha
      hgYTH5dCrrQajQBi7fSGEutW2CKp738x6hNbiB9//lYjczAK+esbfC6+WvmPODJn
      q9YdcJ4ejh5zhOstrMPvO+kTvDozE5x6ur9Rw5yh0MgjR8Q76aoocu4ZckbQqQvX
      7giQveJQdBn+ucYCQueSce4BkUm3S1ITdl2XUHgBj7XYnc+SqgvEtNn4YgyntAu/
      IaVBg/DGVOBqr6pcoh6KLgYSroJG2uxdDXkji1QvRjy3SjY7eQMgou9qUM/L12gZ
      PEyG+xflnkNzbS8PLIGY9F410bcf0ukkqEyDpCCgeoSrD1dJPme1WlSfhaVz7K9g
      m8HB9IsgiQugOoS0Fpw57bNujy3BXJO4ROlIxOAbAYV0IXMjE3uWGot8uFeTVqB4
      p5CzvTV9jdoQXKUFkkgm69MEoN98QB0Ts3BtcOf59X6uOu9twm1ltxnLH52i/4Ty
      LdzErIs9vEaox5Qe6l4lhAUCAwEAAQ==
      -----END PUBLIC KEY-----
      ```

#### APP_PUBLIC_KEY

- Generated as a multiline value.
    - The same value as in GENERATED_PUBLIC_KEY.

    ```yaml
    APP_PUBLIC_KEY: |
      -----BEGIN PUBLIC KEY-----
      MIICIjANBgkqhkiG9w0BAQEFAAOCAg8AMIICCgKCAgEA1kYEJ7bjBiXzBMI/cC6w
      ajclHdd5NZ0bsx2d8eVSaHUaz419fTPYBV7mPec0ybYulThvqWX7c7k5H/jJVvTc
      BRHv4NDqJmOlMHynz4+P4m9zD4gEoNqOCMartJr9yKyzrBplNuSd/IAFUCN6KIVu
      Pge1aftvkZy0AsdRbMHlqWvMEdH30MJdC7FkhFsrrX0sYvuaW2MFjkQTishEphha
      hgYTH5dCrrQajQBi7fSGEutW2CKp738x6hNbiB9//lYjczAK+esbfC6+WvmPODJn
      q9YdcJ4ejh5zhOstrMPvO+kTvDozE5x6ur9Rw5yh0MgjR8Q76aoocu4ZckbQqQvX
      7giQveJQdBn+ucYCQueSce4BkUm3S1ITdl2XUHgBj7XYnc+SqgvEtNn4YgyntAu/
      IaVBg/DGVOBqr6pcoh6KLgYSroJG2uxdDXkji1QvRjy3SjY7eQMgou9qUM/L12gZ
      PEyG+xflnkNzbS8PLIGY9F410bcf0ukkqEyDpCCgeoSrD1dJPme1WlSfhaVz7K9g
      m8HB9IsgiQugOoS0Fpw57bNujy3BXJO4ROlIxOAbAYV0IXMjE3uWGot8uFeTVqB4
      p5CzvTV9jdoQXKUFkkgm69MEoN98QB0Ts3BtcOf59X6uOu9twm1ltxnLH52i/4Ty
      LdzErIs9vEaox5Qe6l4lhAUCAwEAAQ==
      -----END PUBLIC KEY-----
    ```

#### APP_PUBLIC_KEY_SSH

- Generated as a single value

    ```yaml
    APP_PUBLIC_KEY_SSH: ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAACAQDWRgQntuMGJfMEwj9wLrBqNyUd13k1nRuzHZ3x5VJodRrPjX19M9gFXuY95zTJti6VOG+pZftzuTkf+MlW9NwFEe/g0OomY6UwfKfPj4/ib3MPiASg2o4Ixqu0mv3IrLOsGmU25J38gAVQI3oohW4+B7Vp+2+RnLQCx1FsweWpa8wR0ffQwl0LsWSEWyutfSxi+5pbYwWORBOKyESmGFqGBhMfl0KutBqNAGLt9IYS61bYIqnvfzHqE1uIH3/+ViNzMAr56xt8Lr5a+Y84Mmer1h1wnh6OHnOE6y2sw+876RO8OjMTnHq6v1HDnKHQyCNHxDvpqihy7hlyRtCpC9fuCJC94lB0Gf65xgJC55Jx7gGRSbdLUhN2XZdQeAGPtdidz5KqC8S02fhiDKe0C78hpUGD8MZU4GqvqlyiHoouBhKugkba7F0NeSOLVC9GPLdKNjt5AyCi72pQz8vXaBk8TIb7F+WeQ3NtLw8sgZj0XjXRtx/S6SSoTIOkIKB6hKsPV0k+Z7VaVJ+FpXPsr2CbwcH0iyCJC6A6hLQWnDnts26PLcFck7hE6UjE4BsBhXQhcyMTe5Yai3y4V5NWoHinkLO9NX2N2hBcpQWSSCbr0wSg33xAHROzcG1w5/n1fq46723CbWW3GcsfnaL/hPIt3MSsiz28RqjHlB7qXiWEBQ==
    ```

#### APP_PRIVATE_KEY

- Generated as a multiline value

    ```yaml
    APP_PRIVATE_KEY: |
      -----BEGIN PRIVATE KEY-----
      MIIJRAIBADANBgkqhkiG9w0BAQEFAASCCS4wggkqAgEAAoICAQDWRgQntuMGJfME
      wj9wLrBqNyUd13k1nRuzHZ3x5VJodRrPjX19M9gFXuY95zTJti6VOG+pZftzuTkf
      +MlW9NwFEe/g0OomY6UwfKfPj4/ib3MPiASg2o4Ixqu0mv3IrLOsGmU25J38gAVQ
      I3oohW4+B7Vp+2+RnLQCx1FsweWpa8wR0ffQwl0LsWSEWyutfSxi+5pbYwWORBOK
      yESmGFqGBhMfl0KutBqNAGLt9IYS61bYIqnvfzHqE1uIH3/+ViNzMAr56xt8Lr5a
      +Y84Mmer1h1wnh6OHnOE6y2sw+876RO8OjMTnHq6v1HDnKHQyCNHxDvpqihy7hly
      RtCpC9fuCJC94lB0Gf65xgJC55Jx7gGRSbdLUhN2XZdQeAGPtdidz5KqC8S02fhi
      DKe0C78hpUGD8MZU4GqvqlyiHoouBhKugkba7F0NeSOLVC9GPLdKNjt5AyCi72pQ
      z8vXaBk8TIb7F+WeQ3NtLw8sgZj0XjXRtx/S6SSoTIOkIKB6hKsPV0k+Z7VaVJ+F
      pXPsr2CbwcH0iyCJC6A6hLQWnDnts26PLcFck7hE6UjE4BsBhXQhcyMTe5Yai3y4
      V5NWoHinkLO9NX2N2hBcpQWSSCbr0wSg33xAHROzcG1w5/n1fq46723CbWW3Gcsf
      naL/hPIt3MSsiz28RqjHlB7qXiWEBQIDAQABAoICAQCemAYdSv0voMkFfaysoLIM
      e7JqKwDY0OcepM4xq1VaYUqt0oDOOaArIXly2f01SzWhVrs2+3eoyLBiXKbRSLzM
      t+D/WkHklh4/DBS8yPprU6grF7atQ/aawkl2jL1IWaNGv+aoQYA50pucHBYfhdr5
      6IS649JJSV3nLJW01LLiuhm6Gtm8Vw+9RtgqKrziVOKUhLtT5q/HA9YfA2nkMeRW
      jIp8+Fzvp/h64o1WqITP3gZSRR3YWSGdqiQ2VXJL0n+8kxOctQqL2KEl/s6lfpFD
      G2CA6VeeQyWnfNY6qG8avcHQsJb7bfdc35xqFzWhrXCHftQFd98madrFvWpVpKF1
      fjSrQAWHShgyCBQuBteWhYWFlWMkYX3tab6MUS8vUR3LQuv3NGEWvQMgxA2eBzq2
      iPhTnCJ0EQIMgsBg+O6qW2JuJMdTwB2U+WlLJiJnSBQ5aWwDKjIIzoH17lYmDOvz
      ij0ZbzHUx01wU5w58z8mi//PppQheaxIT0jZkoGXOmbMsCTv/UcxlqnVHJ1ysA8d
      QgK+3L+7dyjl3k5IQNt9f49X/C5D0oPYGuzPuP37HzEZYZbYtz5CoICUf6nNFGBl
      aetSTGRs6ePVqHlo1cZQdk5fIQwX7yelehEb/Cpjk0mv5sk8cJcYviAnkQyUBjOE
      wujWkG9XTisPMl3c6pAkJQKCAQEA/5TAJKP/uGofwDxoFXg4zjyRsqWeWpIvny5E
      K9avHPdqFcU1DGAVwUfw6z5Grx8QzWZbnPFI5KMvdVoLpDMubw1XWQCY5X7AD3Iu
      C9C0cbE+vW8d0AKGEt2q4ERTMZ5dqJiAN/tGJ8wH9mQxOhoim1MPAb0PZJg6WHda
      4uN/wnZCuhEVnU86vbKhMJUZYotxEiV3qokZzV7zwsYOdCDw5iipm6McrRVrfdyE
      u4yIyorq9RB3JChhkgkKSLaFHpuG/YOSM0DQ3vizC57w3LpJ+i+d2FR7Z8fYPSSW
      BF/hUBUNZG4kk4wxH9dYk27ohBSI2u44n50zrQGST36vxETodwKCAQEA1p/uia4V
      cHilRd454sQMevtbZO2Zak/g7MzxIUIPI363CKCfjIu/t3iyJ5xohI6OVdqdvE0/
      hEiVJkv5YNXNLvQFnF7y7z5/HKjkEe72TrZuBwWSoQx69UP9QymzMuV+41f8aVpc
      c2Xe7XWXK+X56ZGRFND5sB8hd65G9D818Qi90kQyYlb43l8CyiylqYIYh8ldIqHU
      jAzNGk65kpW6CkL9v/qloKrpAWxErAinB40MHBvgZULj7LijCt2orHOPjOjC1f8n
      BDf9eBKT+gTLXifIggGBh0iBxen9d2S7/Wz4ySLX47ijDgH0aQO8d668z+c9As0t
      lz1HmEqLtyLSYwKCAQBH3Y/ZvbOeK1kaOOIbh16Rvz5IuYE5fnmdjOjmWsuKnZda
      38T24d28J3p661v8ygNzfiCslLwmbixeFx/G4A1idKHnCN/1SBrBPR3tfJYAkhJO
      OfxsDQmeLG5r+UpbXWiAi8Eh/KnRbvGeOrYM3GR2wHgryPmXE6b0UTthKQ83owFI
      SJ2HSkv+I0hn3MTyjLsSmy526W4z7UslrYNK7ChQz4ZBmS/rC2baUTOReQbNzRoc
      JrEZnbEx2xDlOU1dOeZPSrvFZahVyiCuV9bqegdrLhB4T+kTWYJYTv1P5ZX5arIF
      V2M5ieYWSftCGaGP4iZJSUrqts1dDGATsk/CJI4pAoIBAQCnIfYk2x6w7hJt/ScA
      swCxCGpchzYv9rJGVTX1WzbkwjmQi1yTmwQZwPCjLgaqK0UmEE9DIriyr78OCp3R
      Tc0xoi94XOw7aGSeEdtBJ+BA3YmDCFDt/wUFWAOyOJfmq5aLPao+9HIIHy1hp2+o
      bLeXrpbXKgE2qJdsVpfEfjDoWZFQW3EM6YN1z3EhtXDwNnIZ07ImVPVqdlGGCgYy
      40vzz8VAqdQu8MjwJbq4aSiBFdJ3VTICSPurDQFSZdiDKp5/8YZAFSjx/RPyXC1F
      xlQEJ2DZ9IhErC76y0NppVVLfX+jSfHq0I6RSu5klNdAMB+ymvUE6Hh3TO4i5vI0
      E/bXAoIBAQCEXLJhLE/imGPl1Fbqh4lnr2iRMzN3cPxb6DHiKoFXhY18/WWneXEI
      8DwK0D+n8spX67YyelFqBjWi4JrG2KhZmPSBF7p7lPypjPdbjkCnSJ0Qjrvdo5ns
      46CtmUH8d54SAdgRkXypc1y/3mOnVAhnSRUYm5mtDOtfG0dXdsfS/uDXVRZkTv7S
      xjdaHi3Ap+oxTMS+zWfKvYAx5g0gTdvb+FdsN89T9XRRx+7N5TmG9D+sUAqNEWkH
      7SG6By8x+JqhURZOF9T9n2TX7N9g/+c0y9J10Ol5r0rDFM4SSTX9A5NmqfNF6LO7
      A0bX/JM8kHjLlJNrtioxcT+dX4lL6/zT
      -----END PRIVATE KEY-----
    ```

## Import modifiers

Modifiers provide a simpler way to transform values compared to using functions alone. You can chain multiple modifiers together using the `|` symbol, making it easy to apply several transformations in sequence. They work with both string and function expressions - just add them between the `<` and `>` markers, right before the closing `>`.

---

### List of import modifiers

<table className="w-full my-1.5 ">
  <thead>
    <tr>
      <th className="w-fit">Name</th>
      <th className="w-fit">Description</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td className="w-fit font-semibold">sha256</td>
      <td className="w-fit">Generate a hash of the incoming string using [sha256](https://en.wikipedia.org/wiki/SHA-2) algorithm.</td>
    </tr>
    <tr>
      <td className="w-fit font-semibold">sha512</td>
      <td className="w-fit">Generate a hash of the incoming string using [sha512](https://en.wikipedia.org/wiki/SHA-2) algorithm.</td>
    </tr>
    <tr>
      <td className="w-fit font-semibold">bcrypt</td>
      <td className="w-fit">
        Generate a hash of the incoming string using [bcrypt](https://en.wikipedia.org/wiki/Bcrypt) algorithm.

        Fixed configuration: Number of cycles = 11
      </td>
    </tr>
    <tr>
      <td className="w-fit font-semibold">argon2id</td>
      <td className="w-fit">
        Generate a hash of the incoming string using [argon2id](https://en.wikipedia.org/wiki/Argon2) algorithm.

        Fixed configuration: Memory = 64MiB, Iterations = 4, Parallelism = 4, SaltLen = 16B, KeyLength = 32B
      </td>
    </tr>
    <tr>
      <td className="w-fit font-semibold">toHex</td>
      <td className="w-fit">Encodes provided string/bytes into hexadecimal</td>
    </tr>
    <tr>
      <td className="w-fit font-semibold">toString</td>
      <td className="w-fit">Encodes provided string/bytes into string comprised of [a-zA-Z0-9_-.]</td>
    </tr>
    <tr>
      <td className="w-fit font-semibold">upper</td>
      <td className="w-fit">Maps all unicode letters to their upper case</td>
    </tr>
    <tr>
      <td className="w-fit font-semibold">lower</td>
      <td className="w-fit">Maps all unicode letters to their lower case</td>
    </tr>
    <tr>
      <td className="w-fit font-semibold">title</td>
      <td className="w-fit">Maps all words to title case (first letter upper case, rest lower case)</td>
    </tr>
    <tr>
      <td className="w-fit font-semibold">noop</td>
      <td className="w-fit">Does nothing - used in tests</td>
    </tr>
  </tbody>
</table>

---

### Examples of correctly using import modifiers

#### Generating a plain password and related hashes

- `<@generateRandomStringVar(<myPassword>, <30>)>` will output a random string of 30 characters:
    ```yaml
    7a14c8e74bc98a0d74253b1d1a4ef6
    ```

    - `<@getVar(<myPassword>)| sha256>` will output the sha256 hash of the `<myPassword>` variable:
    ```yaml
    081b91d6dff5036229a92e2442fb65d7c8124571d4e70a2ac4729aeb86957407
    ```

    - `<@getVar(<myPassword>)| sha512>` will output the sha512 hash of the `<myPassword>` variable:
    ```yaml
    89c05547de0aa4926512a958f95ab8bf4096ceec63ad5aad4266890bfa059e0cc98917c54276ba4cd61f1dde4c8efda948fc967885c9dd50558ed939722ca10c
    ```

    - `<@getVar(<myPassword>)| bcrypt>` will output the bcrypt hash of the `<myPassword>` variable:
    ```yaml
    $2a$10$CxKZX0yIxdc7ts6eI5aBu.g.heAsFcePdMDEpnlViTlo3vGc//PXe
    ```

    - `<@getVar(<myPassword>)| argon2id>` will output the argon2id hash of the `<myPassword>` variable:
    ```yaml
    $argon2id$v=19$m=98304,t=1,p=3$uWBpmoUT3sfckXHyRF9hlg$8bGtNffuHxaRIgN99zCmJeGEYJF5BY2J9TwzqmezP28
    ```

#### String Case Modification Examples

- Using upper case modifier:
    ```yaml
    Input:  <sTATic StrINg wiTH a mOdifIER| upper>
    Output: STATIC STRING WITH A MODIFIER
    ```

    - Using lower case modifier:
    ```yaml
    Input:  <sTATic StrINg wiTH a mOdifIER| lower>
    Output: static string with a modifier
    ```

    - Using title case modifier:
    ```yaml
    Input:  <sTATic StrINg wiTH a mOdifIER| title>
    Output: Static String With A Modifier
    ```

    - Chaining multiple modifiers:
    ```yaml
    Input:  <sTATic StrINg wiTH a mOdifIER| upper | lower>
    Output: static string with a modifier
    ```

    - Using modifiers with functions:
    ```yaml
    Input:  <@generateRandomString(<30>) | upper>
    Output: 7A14C8E74BC98A0D74253B1D1A4EF6

    Input:  <@setVar(<bucketName>, <@generateRandomString(<10>) | lower>)>
    Output: h73ep149sd
    ```

:::tip Using a space before the pipe separator
As you can see above, unlike the case of the string expression, using a space before the `|` separator in a function expression doesn't add an additional space character to the result.
:::


----------------------------------------

# References > Import Yaml > Type List


This is a list of all supported service types that can be used in import yaml configuration file.

:::note
Versions listed on the same line are aliases of the same underlying version.
:::

## Available service types

### Static Services

<table className="w-full my-1.5 whitespace-nowrap">
  <thead>
    <tr>
      <th className="">Service Type</th>
      <th className="w-full">Versions</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td className="w-fit">Nginx</td>
      <td className="w-fit">
- `nginx@1.22`, `nginx@latest`
</td>
    </tr>
    <tr>
      <td className="w-fit">Static</td>
      <td className="w-fit">
- `static`, `static@1.0`, `static@latest`
</td>
    </tr>
  </tbody>
</table>

### Containers and virtual machines

<table className="w-full my-1.5 whitespace-nowrap">
  <thead>
    <tr>
      <th className="">Service Type</th>
      <th className="w-full">Versions</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td className="w-fit">Alpine</td>
      <td className="w-fit">
- `alpine@3.23`
- `alpine@3.22`
- `alpine@3.21`
- `alpine@3.20`
- `alpine@3.19`
- `alpine@3.18`
- `alpine@3.17`
</td>
    </tr>
    <tr>
      <td className="w-fit">Ubuntu</td>
      <td className="w-fit">
- `ubuntu@24.04`
- `ubuntu@22.04`
</td>
    </tr>
  </tbody>
</table>

### Runtime services

<table className="w-full my-1.5">
  <thead>
    <tr>
      <th className="whitespace-nowrap">Service Type</th>
      <th className="w-full">Versions</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td className="w-fit">Bun</td>
      <td className="w-fit">
- `bun@1.3.9`, `bun@1.3`, `bun@latest`
- `bun@1.2.2`, `bun@1.2`
- `bun@nightly`
- `bun@canary`
- `bun@1.1.34`, `bun@1.1(Ubuntu only)`
</td>
    </tr>
    <tr>
      <td className="w-fit">Deno</td>
      <td className="w-fit">
- `deno@2.0.0`, `deno@2`, `deno@latest`
- `deno@1.45.5`, `deno@1`
</td>
    </tr>
    <tr>
      <td className="w-fit">.NET</td>
      <td className="w-fit">
- `dotnet@10`
- `dotnet@9`
- `dotnet@8`
- `dotnet@7`
- `dotnet@6`
</td>
    </tr>
    <tr>
      <td className="w-fit">Elixir</td>
      <td className="w-fit">
- `elixir@1`, `elixir@1.16`, `elixir@1.16.2`
</td>
    </tr>
    <tr>
      <td className="w-fit">Gleam</td>
      <td className="w-fit">
- `gleam@1`, `gleam@1.5`, `gleam@1.5.1`
</td>
    </tr>
    <tr>
      <td className="w-fit"><span class="anchor anchorWithStickyNavbar_------node_modules-@docusaurus-theme-classic-lib-theme-Heading-styles-module" id="go">Go</span></td>
      <td className="w-fit">
- `go@1.22`, `go@1`, `golang@1`, `golang@1.22`
</td>
    </tr>
    <tr>
      <td className="w-fit">Java</td>
      <td className="w-fit">
- `java@21`
- `java`, `java@17`, `java@latest`
</td>
    </tr>
    <tr>
      <td className="w-fit">Node.js</td>
      <td className="w-fit">
- `nodejs@24`
- `nodejs@22`
- `nodejs@20`
- `nodejs@18`
</td>
    </tr>
    <tr>
      <td className="w-fit">PHP & Apache</td>
      <td className="w-fit">
- `php-apache@8.5+2.4`, `php-apache@8.5`
- `php-apache@8.4+2.4`, `php-apache@8.4`
- `php-apache@8.3+2.4`, `php-apache@8.3`
- `php-apache@8.1+2.4`, `php-apache@8.1`
</td>
    </tr>
    <tr>
      <td className="w-fit">PHP & nginx</td>
      <td className="w-fit">
- `php-nginx@8.5+1.28`, `php-nginx@8.5`
- `php-nginx@8.4+1.22`, `php-nginx@8.4`
- `php-nginx@8.3+1.22`, `php-nginx@8.3`
- `php-nginx@8.1+1.22`, `php-nginx@8.1`
</td>
    </tr>
    <tr>
      <td className="w-fit">Python</td>
      <td className="w-fit">
- `python@3.14 (Ubuntu only)`
- `python@3.12`
- `python@3.11`
</td>
    </tr>
    <tr>
      <td className="w-fit">Rust</td>
      <td className="w-fit">
- `rust@1.86`, `rust@1`, `rust@stable`
- `rust@1.80`
- `rust@1.78`
- `rust@nightly`
</td>
    </tr>
  </tbody>
</table>

### Database services

<table className="w-full my-1.5 whitespace-nowrap">
  <thead>
    <tr>
      <th className="">Database Type</th>
      <th className="w-full">Versions</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td className="w-fit">KeyDB</td>
      <td className="w-fit">
- `keydb@6`
</td>
    </tr>
      <tr>
      <td className="w-fit">MariaDB</td>
      <td className="w-fit">
- `mariadb@10.6`
</td>
    </tr>
        <tr>
      <td className="w-fit">PostgreSQL</td>
      <td className="w-fit">
- `postgresql:single@18`, `postgresql:ha@18`
- `postgresql:single@17`, `postgresql:ha@17`
- `postgresql:single@16`, `postgresql:ha@16`
- `postgresql:single@14`, `postgresql:ha@14`
</td>
    </tr>
    <tr>
      <td className="w-fit">Qdrant</td>
      <td className="w-fit">
- `qdrant@1.12`
- `qdrant@1.10`
</td>
    </tr>
    <tr>
      <td className="w-fit">Valkey</td>
      <td className="w-fit">
- `valkey@7.2`
</td>
    </tr>
  </tbody>
</table>

### Search Engine

<table className="w-full my-1.5 whitespace-nowrap">
  <thead>
    <tr>
      <th className="">Search Engine</th>
      <th className="w-full">Versions</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td className="w-fit">Elasticsearch</td>
      <td className="w-fit">
- `elasticsearch@9.2`
- `elasticsearch@8.16`
</td>
    </tr>
    <tr>
      <td className="w-fit">Meilisearch</td>
      <td className="w-fit">
- `meilisearch@1.20`
- `meilisearch@1.10`
</td>
    </tr>
    <tr>
      <td className="w-fit">Typesense</td>
      <td className="w-fit">
- `typesense@27.1`
</td>
    </tr>
  </tbody>
</table>

### Message Broker

<table className="w-full my-1.5 whitespace-nowrap">
  <thead>
    <tr>
      <th className="">Message Broker</th>
      <th className="w-full">Versions</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td className="w-fit">Kafka</td>
      <td className="w-fit">
- `kafka@3.9`
- `kafka@3.8`
</td>
    </tr>
    <tr>
      <td className="w-fit">NATS</td>
      <td className="w-fit">
- `nats@2.12`
- `nats@2.10`
</td>
    </tr>
  </tbody>
</table>

### Storage Services

<table className="w-full my-1.5 whitespace-nowrap">
  <thead>
    <tr>
      <th className="">Database Type</th>
      <th className="w-full">Versions</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td className="w-fit">Object storage</td>
      <td className="w-fit">
- `object-storage`
</td>
    </tr>
    <tr>
      <td className="w-fit">Shared storage</td>
      <td className="w-fit">
- `shared-storage:single`, `shared-storage:ha`
</td>
    </tr>
  </tbody>
</table>


----------------------------------------

# References > Import


The Import YAML configuration provides powerful capabilities for both importing and exporting projects and services. This documentation covers how to define your infrastructure as code and move configurations between environments.

## YAML Configuration Basics

The Import YAML configuration can be used to create or replicate services in Zerops. You can import configurations in two ways:

- **Using the GUI**:
  - **For projects**: In the Zerops dashboard, click on **Import a project** in the Projects section
  - **For services**: Navigate to a project's details page and click **Import services** in the services section
- **Using the [CLI](/references/cli)**: Run `zcli project project-import` for projects or `zcli project service-import` for individual services

Both methods provide straightforward ways to migrate or replicate infrastructure as needed.

#### Comprehensive example of an import YAML configuration

This section provides a comprehensive example of an import YAML configuration file, allowing you to define and import a project and its services with environment variables.

```yaml
# ==== Define a project to import ====
project:
  # REQUIRED. Name of your project
  name: project0
  # Project description
  description: "This project is an example only"
  # Project core package - LIGHT/SERIOUS
  corePackage: SERIOUS
  # List of project tags for filtering
  tags:
    - test
    - dev
  # Project-level environment variables
  envVariables:
    LOG_LEVEL: info
    API_VERSION: v1
# ==== Define a list of services to import into the project ====
services:
  # REQUIRED. Name of your service
  - hostname: app
    # REQUIRED. Choose from list of supported technologies and their versions
    type: nodejs@22
    # HA or NON_HA mode
    mode: HA
    # Map of secret environment variables
    envSecrets:
      SECRET_KEY: <@generateRandomString(<32>)>
    # Environment variables defined in .env format (automatically creates secret envs)
    dotEnvSecrets: |
      APP_KEY=<@generateRandomString(<32>)>
      DB_PASSWORD=secure123
    # Object storage size in GB
    objectStorageSize: 2
    # Choose object storage policy from a predefined list
    objectStoragePolicy: public-read-write
    # Define additional policy
    objectStorageRawPolicy:
    # One time build git repository
    buildFromGit: https://github.com/myorg/myapp
    # true or false
    enableSubdomainAccess: true
    # The higher the sooner the service is created
    priority: 1
    # Vertical autoscaling configuration object
    verticalAutoscaling:
      minCpu: 1
      maxCpu: 3
      # Choose SHARED or DEDICATED
      cpuMode: DEDICATED
      minRam: 1
      maxRam: 4
      minDisk: 1
      maxDisk: 10
      startCpuCoreCount: 2
      minFreeCpuCores: 0.5
      minFreeCpuPercent: 20
      minFreeRamGB: 0.5
      minFreeRamPercent: 20
    # Minimum number of containers
    minContainers: 2
    # Maximum number of containers
    maxContainers: 6
    # List of shared storage services to connect to
    mount:
      - teststorage1
    # Full nginx config
    nginxConfig: |-
      server {
          listen 80 default_server;
          listen [::]:80 default_server;

          server_name _;
          root /var/www;

          location / {
              try_files $uri $uri/ /index.html;
          }

          access_log syslog:server=unix:/dev/log,facility=local1 default_short;
          error_log syslog:server=unix:/dev/log,facility=local1;
      }
    # Zerops.yaml configuration
    zeropsSetup: backendapi
    zeropsYaml:
      zerops:
        - setup: backendapi
          build:
            base: nodejs@22
            buildCommands:
              - npm ci
              - npm run build
            deployFiles: ./
            cache: node_modules
          run:
            initCommands:
              - npm run db:migrate
            start: npm start
    # When set to true, enables overriding an existing runtime service with the same hostname and triggers a redeploy
    override: false
  # REQUIRED. Name of your other service
  - hostname: teststorage1
    type: shared-storage:ha
    ...
```

:::note
The example above is a general guideline; not all keys are valid for every service type. For technology-specific details, refer to the **Create service** page in the **How To** section of the Zerops documentation.

- `REQUIRED.` If a parent object is defined, the key-value pair is required to be filled. All other key-value pairs are optional.
:::

## Project Configuration

The project configuration is used to define the project you want to import.

### Usage

<table className="w-full my-1.5">
  <thead>
    <tr>
      <th className="w-fit">Field</th>
      <th className="w-fit">Type</th>
      <th className="w-fit">Description</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td className="w-fit font-semibold">project</td>
      <td className="w-fit">object</td>
      <td className="w-fit">_REQUIRED, if a whole project is imported_
Only one project can be defined.</td>
    </tr>
    <tr>
      <td className="w-fit font-semibold">name</td>
      <td className="w-fit">string, REQUIRED</td>
      <td className="w-fit">The name of the new project. Duplicates are allowed.</td>
    </tr>
    <tr>
      <td className="w-fit font-semibold">description</td>
      <td className="w-fit">string</td>
      <td className="w-fit">Description of the new project.</td>
    </tr>
    <tr>
      <td className="w-fit font-semibold">corePackage</td>
      <td className="w-fit">string</td>
      <td className="w-fit">[Core package](/features/infrastructure#project-core-options) of the new project.
Values: <b>LIGHT</b>/<b>SERIOUS</b> (default LIGHT)</td>
    </tr>
    <tr>
      <td className="w-fit font-semibold">tags</td>
      <td className="w-fit">list of strings</td>
      <td className="w-fit">One or more string tags.
Tags provide better orientation in projects.</td>
    </tr>
    <tr>
      <td className="w-fit font-semibold">envVariables</td>
      <td className="w-fit">map[string]string</td>
      <td className="w-fit">[Project-level environment variables](/features/env-variables#project-variables) that are available to all services in the project.</td>
    </tr>
  </tbody>
</table>

:::important
The `corePackage` value can be upgraded later from Lightweight to Serious Core, but cannot be downgraded. Upgrades involve a brief service disruption and are partially destructive (logs/statistics are lost). Make sure to choose a suitable core package for your project. Learn more about [core upgrade process](/features/infrastructure#project-core-upgrade).
:::

This example will create a project named `project0` with [serious core](/features/infrastructure#serious-core) package and the description `This project is an example only`. The project will have two tags: `test` and `dev`, and two environment variables: `LOG_LEVEL` and `API_VERSION`:

```yaml
# ==== Define a project to import ====
project:
  # REQUIRED. Name of your project
  name: project0
  # Project description
  description: "This project is an example only"
  # Project core package
  corePackage: LIGHT
  # List of project tags for filtering
  tags:
    - test
    - dev
  # Project-level environment variables
  envVariables:
    LOG_LEVEL: info
    API_VERSION: v1
```

## Service Configuration

The service configuration defines one or more services to import into your project. Services are specified as an array under the `services` key, allowing you to configure multiple services in a single YAML file. You need at least one service and either an existing project to import into or a project defined in the YAML file.

The Service Configuration section is divided into multiple subsections for better organization:
- [**Service Basic Configuration**](#service-basic-configuration) - Core parameters like hostname, type, mode, and environment variables
- [**Service Vertical Autoscaling**](#service-vertical-autoscaling) - CPU, RAM, and disk scaling settings
- [**Service Horizontal Autoscaling**](#service-horizontal-autoscaling) - Container count scaling settings
- [**Service Mount Shared Storage**](#service-mount-shared-storage) - Connecting to shared storage services
- [**Service Nginx Configuration**](#service-nginx-configuration) - Custom web server settings
- [**Service zerops.yaml Configuration**](#service-zeropsyaml-configuration) - Build and run configurations

#### Complete Service Configuration Example

```yaml
#yamlPreprocessor=on
services:
  - hostname: app           # REQUIRED: Unique service identifier
    type: nodejs@22                 # REQUIRED: Service type and version
    mode: HA                        # HA or NON_HA mode (default: NON_HA)

    # Environment variables
    envSecrets:                     # Secret environment variables (blurred in GUI)
      SECRET_KEY: <@generateRandomString(<32>)>  # Generated random string
    dotEnvSecrets: |                # Environment vars in .env format
      APP_KEY=<@generateRandomString(<32>)>

    # Storage configuration
    objectStorageSize: 2            # Object storage size in GB
    objectStoragePolicy: public-read-write  # Predefined S3 bucket policy
    # Note: Typically you would use either objectStoragePolicy OR objectStorageRawPolicy, not both
    objectStorageRawPolicy: |       # Custom S3 bucket policy
      {
        "Version": "2012-10-17",
        "Statement": [
          {
            "Effect": "Allow",
            "Principal": "*",
            "Action": ["s3:GetObject"],
            "Resource": ["arn:aws:s3:::{{ .BucketName }}/*"]
          }
        ]
      }

    # Build and deployment
    buildFromGit: https://github.com/myorg/myapp  # Git repo for one-time build
    enableSubdomainAccess: true     # Enable public access via Zerops subdomain
    priority: 1                     # Higher priority services are created sooner
    override: true                  # When true, triggers redeploy of existing service

    # Vertical autoscaling
    verticalAutoscaling:
      minCpu: 1                     # Minimum number of virtual CPUs
      maxCpu: 3                     # Maximum number of virtual CPUs
      cpuMode: DEDICATED            # SHARED or DEDICATED CPU mode
      minRam: 1                     # Minimum RAM in GB
      maxRam: 4                     # Maximum RAM in GB
      minDisk: 1                    # Minimum disk space in GB
      maxDisk: 10                   # Maximum disk space in GB
      startCpuCoreCount: 2          # Initial CPU core count
      minFreeCpuCores: 0.5          # Min free CPU cores before scaling
      minFreeCpuPercent: 20         # Min free CPU percentage before scaling
      minFreeRamGB: 0.5             # Min free RAM in GB before scaling
      minFreeRamPercent: 20         # Min free RAM percentage before scaling

    # Horizontal autoscaling
    minContainers: 2                # Minimum number of containers (default: 1, max: 10)
    maxContainers: 6                # Maximum number of containers (max: 10)

    # Shared storage
    mount:                          # List of shared storage services to mount
      - teststorage1

    # Nginx configuration
    nginxConfig: |-                 # Custom nginx configuration
      server {
          listen 80 default_server;
          listen [::]:80 default_server;
          server_name _;
          root /var/www/public;

          location / {
              try_files $uri $uri/ /index.html;
          }

          access_log syslog:server=unix:/dev/log,facility=local1 default_short;
          error_log syslog:server=unix:/dev/log,facility=local1;
      }

    # Zerops.yaml configuration
    zeropsSetup: backendapi          # Service setup name from zeropsYaml or repo
    zeropsYaml:                     # Full zerops.yaml configuration
      zerops:
        - setup: backendapi
          build:
            base: nodejs@22
            buildCommands:
              - npm ci
              - npm run build
            deployFiles: ./
            cache: node_modules
          run:
            initCommands:
              - npm run db:migrate
            start: npm start

  # A second, simpler service example
  - hostname: teststorage1
    type: shared-storage:ha
```

This example includes all possible configuration options for Zerops services. Not all options are required or applicable to every service type. The example shows two services in the same YAML file: a fully configured Node.js API service and a simpler static frontend service.

### Service Basic Configuration

<table className="w-full my-1.5">
  <thead>
    <tr>
      <th className="w-fit">Field</th>
      <th className="w-fit">Type</th>
      <th className="w-fit">Description</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td className="w-fit font-semibold">services</td>
      <td className="w-fit">list of objects, REQUIRED</td>
      <td className="w-fit">At least one service is required.</td>
    </tr>
    <tr>
      <td className="w-fit font-semibold">hostname</td>
      <td className="w-fit">string, REQUIRED</td>
      <td className="w-fit">
        The unique service identifier.
        Limitations:
        - duplicates in the same project forbidden
        - maximum 25 characters, lowercase ASCII letters (a-z) or numbers (0-9) only
      </td>
    </tr>
    <tr>
      <td className="w-fit font-semibold">type</td>
      <td className="w-fit">enum, REQUIRED</td>
      <td className="w-fit">Specifies the service type and version. See [supported types](/references/import-yaml/type-list).</td>
    </tr>
    <tr>
      <td className="w-fit font-semibold">mode</td>
      <td className="w-fit">enum</td>
      <td className="w-fit">Values: <b>HA</b> / <b>NON_HA</b> (default NON_HA)
Defines the operation mode of the service.</td>
    </tr>
    <tr>
      <td className="w-fit font-semibold">envSecrets</td>
      <td className="w-fit">map[string]string</td>
      <td className="w-fit">Environment variables that are blurred by default in Zerops GUI. Can be edited or deleted in Zerops GUI.</td>
    </tr>
    <tr>
      <td className="w-fit font-semibold">dotEnvSecrets</td>
      <td className="w-fit">string (multiline)</td>
      <td className="w-fit">Environment variables in .env file format that are automatically created as secret envs.</td>
    </tr>
    <tr>
      <td className="w-fit font-semibold">objectStorageSize</td>
      <td className="w-fit">integer</td>
      <td className="w-fit">Object storage size in GB.</td>
    </tr>
    <tr>
      <td className="w-fit font-semibold">objectStoragePolicy</td>
      <td className="w-fit">enum</td>
      <td className="w-fit">
        Values: **private / public-read / public-objects-read / public-write / public-read-write / custom**
        Select a predefined AWS S3 bucket access policy.
      </td>
    </tr>
    <tr>
      <td className="w-fit font-semibold">objectStorageRawPolicy</td>
      <td className="w-fit">json</td>
      <td className="w-fit">
        Define your own AWS S3 bucket access policy. See [AWS docs](https://docs.aws.amazon.com/AmazonS3/latest/userguide/access-policy-language-overview.html) for details.
        Use `{{ .BucketName }}` placeholder if you need to use bucket name in your custom policy rules.
      </td>
    </tr>
    <tr>
      <td className="w-fit font-semibold">buildFromGit</td>
      <td className="w-fit">string (URL)</td>
      <td className="w-fit">
        A URL of a Github or Gitlab repository used for a one-time build of your service.
        The repository must be publicly accessible — a private repository fails at clone
        time (the build ends FAILED with no build log). Use the plain repository URL
        without a trailing `.git` suffix, which fails the same way.
      </td>
    </tr>
    <tr>
      <td className="w-fit font-semibold">startWithoutCode</td>
      <td className="w-fit">boolean</td>
      <td className="w-fit">
        Default: `false`

        Set `true` to start a runtime service's containers without waiting for a first
        deploy. Useful when the code arrives later (a subsequent pipeline run), or when
        you want a live container to [SSH](/references/networking/ssh) into and play
        around in — once your setup steps work, version them into
        [`run.prepareCommands`](/zerops-yaml/specification#preparecommands--1) so they
        persist across container replacements.
      </td>
    </tr>
    <tr>
      <td className="w-fit font-semibold">enableSubdomainAccess</td>
      <td className="w-fit">boolean</td>
      <td className="w-fit">
        Default: `false`

        Set `true`, if you want to enable a public access to your service via a Zerops subdomain. Not suitable for production.
      </td>
    </tr>
    <tr>
      <td className="w-fit font-semibold">priority</td>
      <td className="w-fit">integer</td>
      <td className="w-fit">
        Services are sorted before creation by priority in descending order, i.e. the higher the priority the sooner the service is created.
      </td>
    </tr>
    <tr>
      <td className="w-fit font-semibold">override</td>
      <td className="w-fit">boolean</td>
      <td className="w-fit">
        Default: `false`

        This only works for **runtime** services.

        The parameter allows you to replace an existing runtime service with the same hostname byt triggering a redeploy if the service already exists.
      </td>
    </tr>
  </tbody>
</table>

#### Service Basic Configuration Example

```yaml
#yamlPreprocessor=on
services:
# REQUIRED: Name of your service
- hostname: app
  # REQUIRED: Choose from list of supported technologies and their versions
  type: nodejs@22
  # High-Availability or Non-High-Availability mode
  mode: HA
  # Map of secret environment variables
  envSecrets:
    SECRET_KEY: <@generateRandomString(<32>)>
  # Environment variables in .env format
  dotEnvSecrets: |
    APP_KEY=<@generateRandomString(<32>)>
  # Object storage size in GB
  objectStorageSize: 2
  # Choose object storage policy from a predefined list
  objectStoragePolicy: public-read-write
  # Define additional policy
  objectStorageRawPolicy:
  # One time build git repository
  buildFromGit: https://github.com/myorg/myapp
  # Enables public access via zerops.app subdomain
  enableSubdomainAccess: true
  # The higher the sooner the service is created
  priority: 1
  # When set to true, triggers a redeploy of an existing runtime service with the same hostname
  override: false
```

This yaml will create a `nodejs@latest` service named `app` in `HA` (High-Availability) mode with the following configurations:
- Environment variables:
  - From `envSecrets`: `SECRET_KEY` (requires yamlPreprocessor)
  - From `dotEnvSecrets`: `APP_KEY` in .env format (requires yamlPreprocessor)
- Object storage: 2GB with `public-read-write` policy
- Git repository: `https://github.com/zeropsio/recipe-nodejs`
- Public access enabled via Zerops subdomain
- Priority: 1
- Override existing service: `false`

The `services` object allows you to define one or more services in the same yaml file.

:::caution
The `yamlPreprocessor` option in your project & service import YAML is required to generate random secret values, passwords, and public/private key pairs. For more information, see the [yamlPreprocessor](/references/import-yaml/pre-processor) page.
:::

### Service Vertical Autoscaling

The vertical autoscaling configuration defines how the service can scale its resources vertically.

<table className="w-full my-1.5">
  <thead>
    <tr>
      <th className="w-fit">Field</th>
      <th className="w-fit">Type</th>
      <th className="w-fit">Description</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td className="w-fit font-semibold">minCpu</td>
      <td className="w-fit">integer</td>
      <td className="w-fit">Minimum number of virtual CPUs</td>
    </tr>
    <tr>
      <td className="w-fit font-semibold">maxCpu</td>
      <td className="w-fit">integer</td>
      <td className="w-fit">Maximum number of virtual CPUs</td>
    </tr>
    <tr>
      <td className="w-fit font-semibold">cpuMode</td>
      <td className="w-fit">enum</td>
      <td className="w-fit">Values: **SHARED / DEDICATED**</td>
    </tr>
    <tr>
      <td className="w-fit font-semibold">minRam</td>
      <td className="w-fit">float</td>
      <td className="w-fit">
        Minimum RAM in GB that each container of the service can scale down to.
      </td>
    </tr>
    <tr>
      <td className="w-fit font-semibold">maxRam</td>
      <td className="w-fit">float</td>
      <td className="w-fit">
        Maximum RAM in GB that each container of the service can scale up to.
      </td>
    </tr>
    <tr>
      <td className="w-fit font-semibold">minDisk</td>
      <td className="w-fit">float</td>
      <td className="w-fit">
        Minimum disk space in GB that each container of the service can scale down to.
      </td>
    </tr>
    <tr>
      <td className="w-fit font-semibold">maxDisk</td>
      <td className="w-fit">float</td>
      <td className="w-fit">
        Maximum disk space in GB that each container of the service can scale up to.
      </td>
    </tr>
    <tr>
      <td className="w-fit font-semibold">startCpuCoreCount</td>
      <td className="w-fit">integer</td>
      <td className="w-fit">
        Number of CPU cores with which each container starts.
      </td>
    </tr>
    <tr>
      <td className="w-fit font-semibold">minFreeCpuCores</td>
      <td className="w-fit">float</td>
      <td className="w-fit">
        Minimum number of unused CPU cores before a container starts scaling.
      </td>
    </tr>
    <tr>
      <td className="w-fit font-semibold">minFreeCpuPercent</td>
      <td className="w-fit">float</td>
      <td className="w-fit">
        Minimum percentage of unused CPU cores before a container starts scaling.
      </td>
    </tr>
    <tr>
      <td className="w-fit font-semibold">minFreeRamGB</td>
      <td className="w-fit">float</td>
      <td className="w-fit">
        Minimum unused memory in GB before a container starts scaling.
      </td>
    </tr>
    <tr>
      <td className="w-fit font-semibold">minFreeRamPercent</td>
      <td className="w-fit">float</td>
      <td className="w-fit">
        Minimum percentage of unused memory before a container starts scaling.
      </td>
    </tr>
  </tbody>
</table>

#### Vertical Autoscaling Configuration Example

```yaml
services:
  - hostname: app
    type: nodejs@22
    buildFromGit: https://github.com/myorg/myapp
    enableSubdomainAccess: true
    verticalAutoscaling:
      minCpu: 1                     # Minimum number of virtual CPUs
      maxCpu: 3                     # Maximum number of virtual CPUs
      cpuMode: DEDICATED            # SHARED or DEDICATED CPU mode
      minRam: 1                     # Minimum RAM in GB
      maxRam: 4                     # Maximum RAM in GB
      minDisk: 1                    # Minimum disk space in GB
      maxDisk: 10                   # Maximum disk space in GB
      startCpuCoreCount: 2          # Initial CPU core count
      minFreeCpuCores: 0.5          # Min free CPU cores before scaling
      minFreeCpuPercent: 20         # Min free CPU percentage before scaling
      minFreeRamGB: 0.5             # Min free RAM in GB before scaling
      minFreeRamPercent: 20         # Min free RAM percentage before scaling
```

This yaml will create a service with the hostname `app` with `php-nginx@8.4` runtime with `HA` High-Availability mode for vertical autoscaling:

- CPU: `1-3` virtual CPUs in `DEDICATED` mode
- RAM: `1-4 GB`
- Disk Space: `1-10 GB`

### Service Horizontal Autoscaling

The horizontal autoscaling configuration is used to define the horizontal autoscaling settings for the service.

<table className="w-full my-1.5">
  <thead>
    <tr>
      <th className="w-fit">Field</th>
      <th className="w-fit">Type</th>
      <th className="w-fit">Description</th>
    </tr>
  </thead>
  <tbody>
<tr>
  <td className="w-fit font-semibold">minContainers</td>
  <td className="w-fit">integer</td>
  <td className="w-fit">Minimum number of containers of the service.
Default: 1, maximum value: 10</td>
</tr>
<tr>
  <td className="w-fit font-semibold">maxContainers</td>
  <td className="w-fit">integer</td>
  <td className="w-fit">Maximum number of containers of the service.
Maximum value: 10</td>
</tr>
</tbody>
</table>

```yaml
services:
  - hostname: app
    type: nodejs@22
    buildFromGit: https://github.com/zeropsio/recipe-php
    enableSubdomainAccess: true
    # Minimum number of containers
    minContainers: 2
    # Maximum number of containers
    maxContainers: 6
```

The `minContainers` and `maxContainers` parameters allow you to define the minimum and maximum number of containers for the service. The service will automatically scale between these values as needed.

### Service Mount Shared Storage

The mount shared storage configuration defines which shared storage services should be mounted to the service.

<table className="w-full my-1.5">
  <thead>
    <tr>
      <th className="w-fit">Field</th>
      <th className="w-fit">Type</th>
      <th className="w-fit">Description</th>
    </tr>
  </thead>
  <tbody>
  <tr>
    <td className="w-fit font-semibold">mount</td>
    <td className="w-fit">list of strings</td>
    <td className="w-fit">Mount shared storage to the service. `buildFromGit` must be filled.</td>
    </tr>
  </tbody>
</table>

```yaml
services:
  - hostname: app
    type: nodejs@22
    buildFromGit: https://github.com/myorg/myapp
    enableSubdomainAccess: true
    mount:
      - teststorage1
```

The `mount:` parameter allows you to mount a shared storage (which should be created inside the project) to the service.

The `buildFromGit` requirement exists because an import without it only creates an empty service shell with nothing deployed yet, so there is nothing to mount the storage into. With `buildFromGit`, the import also builds and deploys the repository, and the mount is applied to the deployed service. If you import a service without `buildFromGit`, deploy your application first and then connect the shared storage [in the GUI](/shared-storage/how-to/connect).

### Service Nginx Configuration

The nginx configuration defines the nginx settings for the service.

<table className="w-full my-1.5 whitespace-nowrap">
  <thead>
    <tr>
      <th className="w-fit">Field</th>
      <th className="w-fit">Type</th>
      <th className="w-fit">Description</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td className="w-fit font-semibold">nginxConfig</td>
      <td className="w-fit">string (multiline)</td>
      <td className="w-full">Insert full nginx config.</td>
    </tr>
   </tbody>
</table>

```yaml
#yamlPreprocessor=on
services:
  - hostname: app
    type: php-nginx@8.4
    enableSubdomainAccess: true
    nginxConfig: |-
      server {
          listen 80 default_server;
          listen [::]:80 default_server;

          server_name _;
          root /var/www;

          location / {
              try_files $uri $uri/ /index.html;
          }

          access_log syslog:server=unix:/dev/log,facility=local1 default_short;
          error_log syslog:server=unix:/dev/log,facility=local1;
      }
```

The `nginxConfig: |-` parameter allows you to specify a custom nginx configuration for the service.

### Service zerops.yaml Configuration

The `zeropsSetup` and `zeropsYaml` parameters provide flexibility in how you define and use your service configurations. Both parameters are optional and work together in the following ways:

<table className="w-full my-1.5">
  <thead>
    <tr>
      <th className="w-fit">Field</th>
      <th className="w-fit">Type</th>
      <th className="w-fit">Description</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td className="w-fit font-semibold">zeropsSetup</td>
      <td className="w-fit whitespace-nowrap">string</td>
      <td className="w-fit">Specifies which service setup to use. This should match a setup name found in either the `zeropsYaml` parameter (if provided) or the `zerops.yaml` file in the repository root. If not specified, defaults to the service hostname.</td>
    </tr>
    <tr>
      <td className="w-fit font-semibold">zeropsYaml</td>
      <td className="w-fit whitespace-nowrap">object</td>
      <td className="w-fit">Contains the full [zerops.yaml configuration](/zerops-yaml/specification). If provided, this will be used instead of looking for a `zerops.yaml` file in the repository.</td>
    </tr>
  </tbody>
</table>

```yaml
services:
  - hostname: app
    type: nodejs@22
    buildFromGit: https://github.com/myorg/myapp
    # Specify which setup to use from zerops.yaml
    zeropsSetup: backendapi
    # Full zerops.yaml configuration
    zeropsYaml:
      zerops:
        - setup: backendapi
          build:
            base: nodejs@18
            buildCommands:
              - npm ci
              - npm run build
            deployFiles: ./dist
            cache: node_modules
          run:
            initCommands:
              - npm run db:migrate
            start: npm start
```

#### How They Work Together

- **Neither parameter specified**:
  - The system looks for a `zerops.yaml` file in the repository root
  - It searches for a setup with a name that matches the service hostname
- **Only `zeropsSetup` specified**:
  - The system looks for a setup with the specified name in the `zerops.yaml` file in the repository root
- **Only `zeropsYaml` specified**:
  - The system uses the provided YAML configuration instead of looking for a file in the repository
  - It searches for a setup with a name that matches the service hostname
- **Both parameters specified**:
  - The system uses the provided `zeropsYaml` configuration
  - It specifically looks for the setup named in `zeropsSetup` within that YAML

If the specified `zeropsSetup` does not exist in the available YAML configuration (either provided in `zeropsYaml` or found in the repository), the import will fail.

## Export

Zerops provides the ability to export your existing projects and services as YAML configurations through the GUI. This feature is particularly useful for:
- Creating backups of your project configurations
- Replicating project or service setups across different environments
- Sharing project templates with team members
- Creating version-controlled infrastructure configurations

The exported YAML follows the same structure as the import YAML configuration detailed above. It will contain all the configuration parameters you've set for your project and services.

### How to Export

#### Exporting a Single Service
Navigate to your service dashboard in the Zerops GUI, click the three-dot menu (⋮) in the top-right corner of the service card, and choose **Export service as yaml**.

#### Exporting an Entire Project
In the Zerops GUI, go to the project dashboard, click the three-dot menu (⋮) in the top-right corner of the project card, and select **Export project as yaml**.

### Using Exported Configurations

The exported YAML files are compatible with:
- The Zerops GUI import functionality
- The `zcli project project-import` command
- The `zcli project service-import` command (for single service exports)

This allows you to easily move configurations between environments or create new instances of your infrastructure.

## Editor support (JSON Schema)

Zerops publishes an official [JSON Schema ↗](https://json-schema.org/) for the Import YAML:

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

With the schema attached, your editor gives you:

- **Autocomplete** for every key and nested field (project, services, autoscaling, nginx, embedded `zeropsYaml`, …)
- **Inline documentation** on hover
- **Validation** — typos, wrong types, and missing required fields are flagged as you type
- **Enum suggestions** for fields like `corePackage`, `mode`, `cpuMode`, service `type`, and more

### 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 matches:

- `zerops-import.yml`, `zerops-import.yaml`
- `zerops-*-import.yml`, `zerops-*-import.yaml` (e.g., `zerops-project-import.yaml`, `zerops-service-import.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/import-project-yml-json-schema.json
project:
  name: project0
services:
  - hostname: app
    type: nodejs@22
    # ...
```

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


----------------------------------------

# References > Log Forwarding


For more advanced [log](/references/logging) analysis and centralized logging, you can forward all your Zerops logs to external logging services. The Zerops logger service uses **syslog-ng** to enable this functionality.

## Ready-Made Configurations

Zerops provides pre-configured setups for popular logging services:

- **[Better Stack](https://betterstack.com/)**
- **[Papertrail](https://www.papertrail.com/)**
- **Self-hosted [ELK Stack](https://www.elastic.co/elastic-stack) (Logstash)**

To set up one of these integrations, go to your project detail, select **Advanced Observability**, choose your preferred service, and follow the guided steps in the interface.

## Self-Hosted Logstash

To collect logs in a self-hosted ELK stack, a Logstash instance (deployed as the `logstash` service) is required. Logstash listens for incoming UDP syslog packets and indexes them to Elasticsearch.

The one-click GUI integration setup is all you need to get started. After setup completes, logs will appear in Kibana's "Logs > Explorer" section. You can find access information in the **Advanced Observability** section of your project in the GUI.

:::warning
Setting up log forwarding to ELK will override any previously configured log forwarding.
:::

### What Happens Behind the Scenes

1. The `elkstorage`, `kibana`, and `logstash` services are deployed and configured in the target project (if not already present)
2. If logging is required across different projects, the `logstash` service is made publicly accessible through port routing with firewall whitelisting for source project IPs
3. Log forwarding is configured on source projects to forward logs to the target Logstash instance

:::tip
For the complete ELK stack setup including tracing capabilities, see the [Self-Hosted Observability](/references/metrics) guide.
:::

## Custom Log Forwarding Configuration

You can set up forwarding to any syslog-ng compatible software. To do this, navigate to your project detail's **Advanced Observability** section, and choose the "Setup forwarding to any syslog-ng compatible software" option.

When configuring your custom syslog-ng setup, note the following important details:

### Certificate Configuration
- Certificates are located in `/etc/ssl/certs`
- If your configuration references `/etc/syslog-ng/ca.d` or `/etc/syslog-ng/cert.d`, change these paths to `/etc/ssl/certs`
- For custom certificates, you can use: `ca-file("/etc/syslog-ng/user.crt")`
- You can combine custom certificates with standard certificates using: `ca-dir("/etc/ssl/certs")`
  (This will verify both your custom certificate and standard certificates like those from LetsEncrypt)

### Source Configuration
- Zerops uses `s_src` as the source configuration name
- This differs from Papertrail, which might instruct you to "replace 's_sys' with the name you found" - in Zerops, always use `s_src` instead

----------------------------------------

# References > Logging


Zerops automatically collects logs from all services in your project through a built-in logger service. These logs include runtime operations, database activities, build processes, and more.

## Project-Wide Logs

To view all project logs, navigate to your project detail and select the **Logs overview** section, where you'll find a consolidated view of all logging activity from all services with multiple filtering options.

Additionally, in the **Advanced Observability** section, you can set up [log forwarding](/references/log-forwarding) to external logging services for more advanced analysis and long-term storage.

## Service-Specific Logs

Zerops provides different log types depending on the service:

### Build Logs
Shows the output from your build process:
- **GUI**: Service detail → **Pipelines & CI/CD settings** section → Pipeline detail → Build log
- **CLI**: [`zcli service log --showBuildLogs`](/references/zcli/commands#service-log)

:::note
The build log button is available only when the [build pipeline](/features/pipeline#build-phase) was triggered for the selected deploy.
:::

### Prepare Runtime Logs
Documents the creation of a custom runtime image:
- **GUI**: Service detail → **Pipelines & CI/CD settings** section → Pipeline detail → Prepare runtime log
- **CLI**: *Not currently supported*

:::note
The prepare runtime log button is available only when the [prepare runtime phase](/features/pipeline#runtime-prepare-phase-optional) was triggered for the selected deploy.
:::

### Runtime/Database Logs
Contains the operational output from your service.

- **GUI**:
  - Runtime services: Service detail → **Runtime logs**
  - Database services: Service detail → **Database logs**
- **CLI**: [`zcli service log`](/references/zcli/commands#service-log)

:::note
Each container has its own log. For services with multiple containers, select the specific container in the header. You can filter logs by severity level or time period.

To view logs from all containers of a service combined, you can either use the Project logs view or click the **Go to full service log** button in the service detail page.
:::

:::important
For severity levels to work properly in Zerops, your application must log to syslog.
:::


----------------------------------------

# References > Metrics


Zerops Advanced Observability provides one-click, self-hosted, pre-configured deployments of the **[ELK stack](#elk-stack)** or **[Prometheus with Grafana](#prometheus-with-grafana)**. This enables comprehensive observability for your deployments while maintaining full control over your data and infrastructure.

## Deployment Modes

Both ELK and Prometheus can be deployed in two ways:

- **Local deployment**: Services are deployed within your target project
- **Global deployment**: A dedicated project is created specifically for observability

## ELK Stack

The ELK observability setup deploys and configures two base services:

- **Elasticsearch** (as `elkstorage`)
- **Kibana** (as `kibana`) - the observability access point

### Logging

For log collection with ELK, see the [Log Forwarding](/references/log-forwarding#self-hosted-logstash) guide which covers the Logstash setup and configuration.

### Tracing

To collect traces in the ELK stack, an APM Server instance (deployed as the `apmserver` service) is required. APM Server listens for incoming traces securely over HTTPS and indexes them to Elasticsearch.

First, follow the one-click GUI integration setup to deploy the required infrastructure. Then configure your application to send traces to APM Server.

#### Setting Up APM Agents

1. Update your code according to the [APM documentation](https://www.elastic.co/guide/en/apm/agent/index.html) for your application's language. See this [simple Go application](https://github.com/zerops-recipe-apps/go-hello-world-app/tree/with-apm-and-metrics) using APM libraries for reference.

2. Add the following environment variables to your application service (these are specific to the official Go APM Agent library and may differ for other agents):
```
ELASTIC_APM_ACTIVE=true
ELASTIC_APM_SERVICE_NAME=recipe-go
ELASTIC_APM_SERVER_URL=https://apmserver.url.copy.from.gui
ELASTIC_APM_SECRET_TOKEN=secret_token_copy_from_gui
```

:::note
The `ELASTIC_APM_ACTIVE` variable is set to `false` by default on Zerops, so you must explicitly set it to `true` to enable APM for the official Go APM agent.
:::

3. Restart or reload your application service.

You should start seeing traces appear in Kibana's "Applications > Traces" section.

#### What Happens Behind the Scenes

1. The `elkstorage`, `kibana`, and `apmserver` services are deployed and configured in the target project (if not already present)
2. The `apmserver` is made publicly accessible over HTTPS via a Zerops subdomain and configured with a secret token for secure access

Access information for both Kibana and APM Server can be found in the **Advanced Observability** section of your project in the GUI.

### Next Steps

- **Security**: Set up custom domains for Kibana and APM Server
- **Optimization**: Connect to APM Server locally via HTTP for improved performance
- **Customization**: Fork the [ELK recipe](https://github.com/zeropsio/recipe-elk), customize the Logstash configuration, and redeploy the `logstash` service via `zcli`

## Prometheus with Grafana

The full Prometheus setup consists of:

- **Prometheus** (as `prometheus`)
- **Grafana** (as `grafana`) - the observability access point
- **PostgreSQL database** (as `grafanadb`) - for Grafana data storage
- **S3 bucket** (as `prometheusbackups`) - for storing Prometheus backups

Metrics can be forwarded to the target project via a Prometheus exporter (single `prometheuslight` service configured [with remote write](https://grafana.com/docs/agent/latest/flow/reference/components/prometheus.remote_write/#prometheusremote_write)). When present in a source project, it collects metrics and forwards them to Prometheus in the target project.

Since Prometheus supports only filesystem storage and non-HA (single instance) setup, the `prometheus` service is configured to run a backup cron job that stores metric data snapshots in object storage.

### Metrics

After deploying the full or forwarder Prometheus setup, metrics are automatically scraped by Prometheus. After setup completes, log in to Grafana using the credentials found in the **Advanced Observability** section of your project in the GUI, then navigate to `/dashboards` to start exploring your metrics.

Zerops provides several metrics out of the box:

- Service scaling and resource metrics
- PostgreSQL database service metrics (with HAProxy balancer metrics in HA setups)
- MariaDB database service metrics
- Valkey database metrics

:::note
Some PostgreSQL database metrics are available only after enabling the `pg_stat_statements` extension. Run `CREATE EXTENSION IF NOT EXISTS pg_stat_statements;` as a superuser and restart the database service.
:::

You can also expose custom metrics from your applications.

#### Exposing Custom Metrics

1. Configure your application to expose an HTTP `/metrics` endpoint on an arbitrary port. See this [simple Go application using `promauto`](https://github.com/zerops-recipe-apps/go-hello-world-app/tree/with-apm-and-metrics) for reference.

   :::note
   Only the `/metrics` path is scraped and cannot currently be configured otherwise.
   :::

2. Add and commit the `ZEROPS_PROMETHEUS_PORT` environment variable to your application service with the port where you exposed the `/metrics` endpoint:
```
Single port:
9090

Multiple ports can be defined using commas:
9090,9091
```

For example: `ZEROPS_PROMETHEUS_PORT=9090`. After setting the environment variable, your service's ports will be automatically added to metrics discovery and scraped by Prometheus.

#### What Happens Behind the Scenes

**Full setup:**

1. The `prometheus`, `grafana`, `grafanadb`, and `prometheusbackups` services are deployed and configured (if not already present)
2. `grafana` is made publicly accessible over HTTPS, securely accessible via a generated password

After that, metrics are scraped and available for visualization in Grafana.

**Forwarder setup:**

1. The `prometheuslight` forwarder service is deployed in the source project
2. The `prometheus`, `grafana`, `grafanadb`, and `prometheusbackups` services are deployed and configured in the target project (if not already present)
3. `grafana` is made publicly accessible over HTTPS, securely accessible via a generated password
4. `prometheus` is made publicly accessible over HTTPS via a Zerops zone domain and secured with basic access authentication (username and password)
5. `prometheuslight` is configured to forward metrics to the target `prometheus` using the generated credentials over secure HTTPS

### Next Steps

- **Security**: Set up custom domains for Grafana and Prometheus
- **Customization**: Fork the [Prometheus recipe](https://github.com/zeropsio/recipe-prometheus), customize dashboards and alerting rules, and redeploy via `zcli`
- **Advanced monitoring**: Explore Grafana's alerting capabilities and create custom dashboards for your specific use cases

----------------------------------------

# References > Networking > Cloudflare


This guide provides step-by-step instructions for configuring Cloudflare to work with your Zerops applications, covering DNS records, proxy settings, SSL/TLS configuration, and common troubleshooting scenarios.

## Prerequisites

Before starting, ensure you have:
- A Cloudflare account
- A registered domain name
- Access to your Zerops project with [domain access configured](/references/networking/public-access#custom-domain-access)
- Your Zerops IP addresses (IPv4 and/or IPv6) from the Zerops GUI

## DNS Record Configuration

Configure your DNS records in Cloudflare using one of these approaches based on your needs:

### Using CNAME Records

CNAME can be used for non-apex domains (subdomains) or with DNS providers that support CNAME flattening at the apex (like Cloudflare). When you set up a CNAME in Zerops, it internally creates A and AAAA records pointing to your project.

To find your CNAME target value, go to your service in the Zerops GUI, navigate to **Public access & internal ports**, and select the **CNAME** option when adding a domain.
```bash
Type    Name              Content                         Proxy status       TTL
CNAME   <your-domain>     <your-project-cname-target>     Proxied/DNS Only   Auto
```

:::warning Cloudflare Proxy with Shared IPv4
When using Cloudflare's proxy with CNAME records, you **must exclude the shared IPv4**. Toggle off "Shared IPv4 included in the CNAME" in the Zerops GUI.

Zerops does a reverse lookup of the AAAA record of the domain for requests to our shared IPv4 address. If you use a shared IPv4 and also enable a proxy for the AAAA record, Zerops will not be able to correctly route the request.

This setting affects all domains in your project.
:::

### With Cloudflare Proxy

#### IPv6 only
```bash
Type    Name              Content                Proxy status   TTL
AAAA    <your-domain>     <your-project-ipv6>    Proxied        Auto
```

Cloudflare handles IPv4 to IPv6 translation, making your service accessible to both IPv4 and IPv6 users. Uses Zerops' free dedicated IPv6 address.

:::note
Do not add a proxied A record with shared IPv4 when using this setup, as it would prevent proper IPv4 traffic routing.
:::

#### Dedicated IPv4
```bash
Type    Name              Content                Proxy status   TTL
A       <your-domain>     <your-dedicated-ipv4>  Proxied        Auto
# Optional
AAAA    <your-domain>     <your-project-ipv6>    Proxied        Auto
```

Uses your dedicated IPv4 address with Cloudflare's proxy features.

:::tip
Adding the AAAA record allows visitors with IPv6 support to connect directly via IPv6.
:::

#### Shared IPv4 *(not recommended)*
```bash
Type    Name              Content                Proxy status  TTL
AAAA             DNS only      Auto
A               Proxied       Auto
```

:::tip Why Not?
Zerops does a reverse lookup of the AAAA record of the domain for requests to our shared IPv4 address. If you use a shared IPv4 and also enable a proxy for the AAAA record, Zerops will not be able to correctly route the request.

Consider using IPv6 only or dedicated IPv4 configurations instead.
:::

### DNS-Only Configuration (Without Cloudflare Proxy)

If you prefer direct connections without Cloudflare's proxy features:

#### Shared IPv4
```bash
Type    Name              Content                Proxy status   TTL
A       <your-domain>     <zerops-shared-ipv4>   DNS only       Auto
AAAA    <your-domain>     <your-project-ipv6>    DNS only       Auto
```

Uses Zerops' free shared IPv4.

:::note Both A + AAAA Required
Adding AAAA record is essential for shared IPv4 configuration as it serves as a [security measure](/references/networking/dns#understand-shared-ipv4) to prevent unauthorized domain claims.
:::

#### Dedicated IPv4
```bash
Type    Name              Content                Proxy status   TTL
A       <your-domain>     <your-dedicated-ipv4>  DNS only       Auto
# Optional
AAAA    <your-domain>     <your-project-ipv6>    DNS only       Auto
```

Uses your dedicated IPv4 address.
:::tip
Adding the AAAA record allows visitors with IPv6 support to connect directly via IPv6.
:::

#### IPv6 only
```bash
Type    Name              Content                Proxy status   TTL
AAAA    <your-domain>     <your-project-ipv6>    DNS only       Auto
```

Uses only Zerops' free dedicated IPv6.
:::note
This configuration will only work for users with IPv6 connectivity.
:::

## Wildcard Domain Configuration

Zerops supports wildcard domains (`*.<your-domain>`) that allow routing all subdomains to your project.

### DNS Records for Wildcards

Configure wildcard domains using either method:

#### Method A: Direct Wildcard Records
```bash
Type   Name              Content               Proxy status       TTL
A      *.<your-domain>   <your-ipv4-address>   DNS only/Proxied   Auto
AAAA   *.<your-domain>   <your-ipv6-address>   DNS only/Proxied   Auto
```

#### Method B: CNAME to Main Domain
First ensure your main domain has proper A/AAAA records, then add:
```bash
Type    Name              Content         Proxy status       TTL
CNAME   *.<your-domain>   <your-domain>   DNS only/Proxied   Auto
```

### Certificate Validation for Wildcards

To enable automatic SSL certificate issuance for wildcard domains:

```bash
Type    Name                            Content                     Proxy status   TTL
CNAME   _acme-challenge.<your-domain>   <your-domain>.zerops.zone   DNS only       Auto
```

This CNAME record allows Zerops to handle the DNS-01 challenge required for wildcard SSL certificates.

### Higher-Level Wildcard Subdomains

You can also set up higher-level wildcard subdomains like `*.<subdomain>.<your-domain>`:

#### Method A: Direct Configuration
```bash
Type   Name                          Content               Proxy status       TTL
A      *.<subdomain>.<your-domain>   <your-ipv4-address>   DNS only/Proxied   Auto
AAAA   *.<subdomain>.<your-domain>   <your-ipv6-address>   DNS only/Proxied   Auto
```

#### Method B: Using a CNAME Record
```bash
Type    Name                          Content                     Proxy status       TTL
CNAME   *.<subdomain>.<your-domain>   <subdomain>.<your-domain>   DNS only/Proxied   Auto
```
or
```bash
Type    Name                          Content         Proxy status       TTL
CNAME   *.<subdomain>.<your-domain>   <your-domain>   DNS only/Proxied   Auto
```

For certificate validation with higher-level wildcards:
```bash
Type    Name                                        Content                                 Proxy status   TTL
CNAME   _acme-challenge.<subdomain>.<your-domain>   <subdomain>.<your-domain>.zerops.zone   DNS only       Auto
```

### Combining Main Domain and Wildcard Domain

To use both `<your-domain>` and `*.<your-domain>`, specify both variants in your [Zerops configuration](/references/networking/public-access#http-routing-setup). Zerops automatically issues a single shared certificate for both the main domain and all its subdomains.

## Cloudflare SSL/TLS Configuration

### Essential SSL/TLS Settings

1. **Set Encryption Mode**
   - Navigate to **SSL/TLS** → **Overview** in your Cloudflare dashboard
   - Select **Full (strict)** for production or **Full** for testing
   - **Never use Flexible mode** - this will cause redirect loops

2. **Edge Certificates**
   - Go to **SSL/TLS** → **Edge Certificates**
   - Ensure **Always Use HTTPS** is enabled for production
   - Keep **Automatic HTTPS Rewrites** enabled

### Certificate Validation Configuration

For proper certificate issuance, especially with Let's Encrypt:

#### Option A: Simple Setup (Testing/Development)
- Temporarily disable **Always Use HTTPS** during initial certificate setup
- Re-enable after certificates are issued

#### Option B: Production Setup
Keep **Always Use HTTPS** enabled and create a Configuration Rule:

1. Go to **Rules** → **Configuration Rules**
2. Create a new rule with these settings:
   - **Rule name:** "Allow ACME Challenge"
   - **Field:** URI Path
   - **Operator:** starts with
   - **Value:** `/.well-known/acme-challenge/`
   - **Action:** Disable **Automatic HTTPS Rewrites**

This rule allows certificate validation to work while maintaining HTTPS enforcement for all other traffic.

## Validation and Testing

### DNS Resolution Testing
```bash
# Check IPv4 resolution
dig A <your-domain>

# Check IPv6 resolution
dig AAAA <your-domain>

# Check from specific DNS server
dig @1.1.1.1 <your-domain>
```

### Connectivity Testing
```bash
# Basic HTTPS test
curl -vI https://<your-domain>

# Test with specific subdomain (for wildcards)
curl -vI https://api.<your-domain>

# Test IPv4 specifically
curl -4 -v https://<your-domain>

# Test IPv6 specifically
curl -6 -v https://<your-domain>
```

### Cloudflare-Specific Checks

1. **Verify proxy status** in Cloudflare DNS dashboard (orange cloud = proxied)
2. **Check SSL/TLS mode** in SSL/TLS → Overview
3. **Confirm certificate issuance** in SSL/TLS → Edge Certificates
4. **Test redirect behavior** by accessing `http://` version of your domain

## Troubleshooting Common Issues

### SSL Certificate Problems

#### Too Many Redirects or SSL Errors

**Possible causes:**
- Incorrect SSL/TLS mode in Cloudflare
- Invalid or missing certificates
- Misconfigured HTTPS settings

**Solutions:**
1. Verify SSL/TLS mode is set to **Full** or **Full (strict)**, not **Flexible**
2. Check that both Zerops and Cloudflare have valid certificates
3. Ensure **Always Use HTTPS** is properly configured
4. For new domains, refresh the Cloudflare SSL/TLS page as settings may display incorrectly initially

#### Certificate Validation Fails for Wildcard Domains

**Possible causes:**
- Missing or incorrect `_acme-challenge` CNAME record
- DNS propagation not complete
- Incorrect CNAME target

**Solutions:**
1. Verify the `_acme-challenge` CNAME record is correctly configured
2. Ensure DNS propagation is complete (check with `dig` command)
3. Confirm the CNAME points to `<your-domain>.zerops.zone`

#### Domain Verification Failed (DNS Warning in Zerops)

**Possible causes:**
- Cloudflare's WAF or security features blocking the `/.well-known/acme-challenge/` path
- Let's Encrypt HTTP-01 validation being prevented

**Solutions:**

**Option 1: Create a WAF Skip Rule (Recommended)**

1. Navigate to **Security** → **WAF** → **Custom rules** in Cloudflare
2. Click **Create rule** and configure:
   - **Rule name:** "Allow ACME Challenge"
   - **Field:** URI Path
   - **Operator:** starts with
   - **Value:** `/.well-known/acme-challenge/`
   - **Choose action:** Skip
   - **Which rules to skip:** Select all WAF components
3. Move this rule to the **top** of your Custom rules list
4. Wait a few minutes and check if the warning disappears in Zerops

**Option 2: Modify Existing WAF Rules**

1. Edit your existing WAF rule
2. Add an additional condition:
   - **Field:** URI Path
   - **Operator:** does not start with
   - **Value:** `/.well-known/acme-challenge/`

:::tip CNAME Flattening and DNS Verification
Cloudflare uses CNAME flattening, which converts CNAME records to A/AAAA records in DNS responses. This is normal behavior and doesn't affect Zerops' domain verification. However, if WAF or other security features block the ACME challenge endpoint, Zerops cannot complete the HTTP-01 validation required for certificate issuance.
:::

### DNS Resolution Issues

#### Domain Not Resolving

**Possible causes:**
- Incorrect DNS record configuration
- DNS propagation delay
- Typos in IP addresses

**Solutions:**
1. Confirm DNS records are correctly configured in Cloudflare
2. Verify proxy status matches your intended setup (orange cloud = proxied)
3. Check for typos in IP addresses or CNAME targets
4. Wait for DNS propagation (typically 5-10 minutes, up to 24 hours globally)
5. Test resolution using: `dig @1.1.1.1 <your-domain>`

#### IPv4 Traffic Not Working with IPv6-Only Setup

**Possible causes:**
- Cloudflare proxy disabled
- Incorrect IPv6 address
- Conflicting DNS records

**Solutions:**
1. Ensure Cloudflare proxy is **enabled** (orange cloud icon)
2. Verify IPv6 address is correct in AAAA record
3. Confirm no conflicting A record with shared IPv4 exists
4. Test with: `curl -4 -v https://<your-domain>`

## Security Considerations

- Always use **Full (strict)** SSL mode for production
- Enable **HSTS (HTTP Strict Transport Security)** in Cloudflare
- Consider enabling **Bot Fight Mode** for additional protection
- Use Cloudflare's **Firewall Rules** to block malicious traffic
- Regularly monitor SSL certificate expiration dates

## Getting Help

If you encounter issues not covered in this guide:
- Check the [general DNS configuration guide](/references/networking/dns#technical-background) for additional context
- Review your Zerops service logs for error messages
- Verify your configuration against Cloudflare's documentation
- Test with simple curl commands to isolate the problem
- Contact Zerops support via [email](mailto:support@zerops.io) or reach out on [Discord](https://discord.gg/zeropsio)

----------------------------------------

# References > Networking > Dns


This guide will show you how to configure DNS records and proxy settings to work with your Zerops applications.

:::important Cloudflare
If you're using Cloudflare, check out our dedicated [Cloudflare DNS Configuration Guide](/references/networking/cloudflare) for step-by-step instructions specific to Cloudflare's interface and features.
:::

## DNS Configuration

DNS records for Zerops services can be configured in two main ways:
* **With Proxy**: Routes traffic through proxy services, providing additional security and performance features (recommended for DDoS protection)
* **Without Proxy (DNS Only)**: Direct connection to your Zerops service's IP address

DNS allows you to set two records based on IP address type:
* **A** record for **IPv4** - Zerops offers either a free **shared** IPv4 or a paid **dedicated** IPv4
* **AAAA** record for **IPv6** - Zerops provides a free **dedicated** IPv6

### Using CNAME Records

CNAME can be used for non-apex domains (subdomains) or with DNS providers that support CNAME flattening at the apex. When you set up a CNAME in Zerops, it internally creates A and AAAA records pointing to your project.

To find your CNAME target value, go to your service in the Zerops GUI, navigate to **Public access & internal ports**, and select the **CNAME** option when adding a domain.

```
Type    Name              Content                         Proxy status       TTL
CNAME   <your-domain>     <your-project-cname-target>     DNS only/Proxied   Auto
```

:::warning Using Proxy with Shared IPv4
When using any CDN or proxy service with CNAME records, you should **exclude the shared IPv4**. Toggle off "Shared IPv4 included in the CNAME" in the Zerops GUI.

Zerops does a reverse lookup of the AAAA record of the domain for requests to our shared IPv4 address. If you use a shared IPv4 and also enable a proxy for the AAAA record, Zerops will not be able to correctly route the request because it sees the proxy's IP instead of your project's IPv6.

This setting affects all domains in your project.
:::

### With Proxy

#### IPv6 only
```bash
Type    Name              Content                Proxy status   TTL
AAAA    <your-domain>     <your-project-ipv6>    Proxied        Auto
```

:::note
Make sure your proxy service supports IPv4 to IPv6 translation for this configuration to work for **both IPv4 and IPv6** users.

Do not add a proxied A record with shared IPv4 - doing so would prevent the proxy from properly routing IPv4 traffic to your service.
:::

#### Dedicated IPv4
```bash
Type    Name              Content                Proxy status   TTL
A       <your-domain>     <your-dedicated-ipv4>  Proxied        Auto
# Optional
AAAA    <your-domain>     <your-project-ipv6>    Proxied        Auto
```

:::tip
Adding also AAAA record can be beneficial as visitors with IPv6 support will connect directly via IPv6.
:::

#### Shared IPv4 *(not recommended)*
```bash
Type    Name              Content                Proxy status  TTL
AAAA    <your-domain>     <your-project-ipv6>    DNS only      Auto
A       <your-domain>     <zerops-shared-ipv4>   Proxied       Auto
```

:::tip Why Not?
Zerops does a reverse lookup of the AAAA record of the domain for requests to our shared IPv4 address. If you use a shared IPv4 and also enable a proxy for the AAAA record, Zerops will not be able to correctly route the request.

Use [IPv6 only](#ipv6-only) or dedicated IPv4 configurations instead.
:::

### Without Proxy

#### Shared IPv4
```bash
Type    Name              Content                Proxy status   TTL
AAAA    <your-domain>     <your-project-ipv6>    DNS only       Auto
A       <your-domain>     <zerops-shared-ipv4>   DNS only       Auto
```

:::note Both A + AAAA Required
Adding AAAA record is essential for shared IPv4 configuration as it serves as a [security measure](#understand-shared-ipv4) to prevent unauthorized domain claims.
:::

#### Dedicated IPv4
```bash
Type    Name              Content                Proxy status   TTL
A       <your-domain>     <your-dedicated-ipv4>  DNS only       Auto
# Optional
AAAA    <your-domain>     <your-project-ipv6>    DNS only       Auto
```

:::tip
Adding also AAAA record can be beneficial as visitors with IPv6 support will connect directly via IPv6.
:::

#### IPv6 only
```bash
Type    Name              Content                Proxy status   TTL
AAAA    <your-domain>     <your-project-ipv6>    DNS only       Auto
```

:::note
This configuration will only work for users with IPv6 connectivity, which may limit your service accessibility.
:::

## Wildcard Domain Configuration

Zerops supports wildcard domains (`*.<your-domain>`) that allow routing all subdomains to your project.

### DNS Configuration
#### Method A: Direct configuration of A and AAAA records
Configure wildcard DNS records following the same patterns described in the [DNS Configuration](#dns-configuration) section, using `*.<your-domain>` in the Name field:

```bash
Type   Name              Content               Proxy status       TTL
A      *.<your-domain>   <your-ipv4-address>   DNS only/Proxied   Auto
AAAA   *.<your-domain>   <your-ipv6-address>   DNS only/Proxied   Auto
```

#### Method B: Using a CNAME record
First configure A and AAAA records for your main domain (`<your-domain>`), then set up a CNAME record:

```bash
Type    Name              Content         Proxy status       TTL
CNAME   *.<your-domain>   <your-domain>   DNS only/Proxied   Auto
```

### Certificate Validation

For proper HTTPS certificate functionality with wildcard domains, configure:
```bash
Type    Name                            Content                     Proxy status   TTL
CNAME   _acme-challenge.<your-domain>   <your-domain>.zerops.zone   DNS only       Auto
```

This record enables Zerops to issue and verify a wildcard certificate for your domain.

### Higher-Level Wildcard Subdomains

You can also set up higher-level wildcard subdomains like `*.<subdomain>.<your-domain>`:

#### Method A: Direct configuration
```bash
Type   Name                          Content               Proxy status       TTL
A      *.<subdomain>.<your-domain>   <your-ipv4-address>   DNS only/Proxied   Auto
AAAA   *.<subdomain>.<your-domain>   <your-ipv6-address>   DNS only/Proxied   Auto
```

#### Method B: Using a CNAME record
```bash
Type    Name                          Content                     Proxy status       TTL
CNAME   *.<subdomain>.<your-domain>   <subdomain>.<your-domain>   DNS only/Proxied   Auto
```
or
```bash
Type    Name                          Content         Proxy status       TTL
CNAME   *.<subdomain>.<your-domain>   <your-domain>   DNS only/Proxied   Auto
```

For certificate validation:
```bash
Type    Name                                        Content                                 Proxy status   TTL
CNAME   _acme-challenge.<subdomain>.<your-domain>   <subdomain>.<your-domain>.zerops.zone   DNS only       Auto
```

### Combining Main Domain and Wildcard Domain

To use both `<your-domain>` and `*.<your-domain>`, specify both variants in your [Zerops configuration](/references/networking/public-access#http-routing-setup). Zerops automatically issues a single shared certificate for both the main domain and all its subdomains.

## Validation Steps

Test your configuration:
```bash
# Check DNS resolution
dig AAAA <your-domain>

# Verify connectivity
curl -vI https://<your-domain>

# Test IPv4 access
curl -4 -v https://<your-domain>

# Test IPv6 access
curl -6 -v https://<your-domain>
```

## Troubleshooting Guide

1. **DNS Resolution Issues**
   - Confirm correct record configuration
   - Verify proxy status settings
   - Check IPv6 address accuracy
   - Allow time for DNS propagation (typically 5-10 minutes)

2. **Connection Problems**
   - Test both IPv4 and IPv6 connectivity
   - Check proxy server status if applicable
   - Confirm port configurations

3. **Certificate Issues**
   - Verify proper _acme-challenge CNAME configuration for wildcard domains
   - Check that DNS records match the domains configured in Zerops
   - **Provider-specific certificate problems**: Consult your DNS provider's documentation for SSL/TLS configuration requirements

## Technical Background

### Understanding Shared IPv4 Addresses {#understand-shared-ipv4}

Shared IPv4 allows multiple Zerops projects to use the same IPv4 address while maintaining separate routing for each project. Here's how it works:

1. When a visitor makes a request, it first arrives at the shared IPv4 address
2. The system looks at the domain name in the request (using SNI - Server Name Indication)
3. For security, it checks if this domain properly resolves to your project's IPv6 address
4. Only if IPv6 address matches your project will the traffic be routed correctly

This is why configuring both A (IPv4) and AAAA (IPv6) records is crucial when using shared IPv4 addresses - the IPv6 record acts as a security key that helps prevent unauthorized use of the shared IPv4 address.

### Certificate Verification Methods

When issuing SSL/TLS certificates, different verification methods are used depending on the certificate type:

#### HTTP-01 vs DNS-01 Verification

- **Regular certificates** (for a single domain like `<your-domain>`) are typically issued using the **HTTP-01** challenge method. This verification checks that you control the domain by placing a specific file at a specific URL.

- **Wildcard certificates** (for domains like `*.<your-domain>`) must be issued using the **DNS-01** challenge method. This method requires creating specific TXT records in your DNS configuration.

### How Zerops Handles Wildcard Certificate Verification

Zerops simplifies the DNS-01 challenge process:

1. You create a CNAME record (e.g., `_acme-challenge.<your-domain> CNAME <your-domain>.zerops.zone`)
2. When a certificate needs to be issued or renewed, Zerops automatically creates the required TXT records on its `zerops.zone` domain
3. The certificate authority verifies these TXT records through the CNAME redirection
4. Once verified, the wildcard certificate is issued without requiring manual intervention

----------------------------------------

# References > Networking > Firewall


Zerops includes a comprehensive firewall system implemented using [nftables](https://en.wikipedia.org/wiki/Nftables) to ensure platform security.

The primary focus is on managing outbound communication to prevent potential platform misuse while maintaining the flexibility needed for legitimate applications.

## What is a Firewall?

A Firewall is a network security system that monitors and controls incoming and outgoing network traffic based on predetermined security rules.

At Zerops, we implemented a robust firewall system to protect our platform and your applications.

## Port Access Rules

### UDP Ports
*No restrictions*

### TCP Ports

#### **TCP ports 1-1024**
The following specific ports are allowed:

- **22** - SSH
- **53** - DNS
- **80** - HTTP
- **123** - NTP
- **443** - HTTPS
- **587** - SMTP (with STARTTLS)

*All other TCP ports in the range 1-1024 are **blocked** for security reasons, see below.*

#### **TCP ports 1025-65535**
*No restrictions*

## Security Measures

These firewall rules are strategically implemented to:

- Prevent unauthorized use of the Zerops infrastructure for spam or network attacks
- Protect Zerops and its users from potential security threats
- Maintain compliance with security best practices

## Common Use Cases

### Standard Web Applications (HTTP/HTTPS)
- Full access to HTTP/HTTPS communication (ports 80/443)
- Unrestricted DNS queries (port 53)
- Time synchronization via NTP (port 123)

### Email Services

- SMTP access through port 587 (with STARTTLS)
- For detailed SMTP configuration, see our [SMTP documentation](/references/smtp)

## Requesting Firewall Modifications

If your application requires access to additional ports:

1. Contact Zerops support at [support@zerops.io](mailto:support@zerops.io).
2. Include in your request:
   - Specific ports and protocols needed.
   - Detailed explanation of your use case.
   - Mention your Project ID and Organization ID from your Zerops Dashboard.


----------------------------------------

# References > Networking > Internal Access


This guide covers internal communication between services and methods for accessing your project's private network. For an overview of all access methods, see the [Access & Networking guide](/features/access).

## Internal Access Methods

Choose the access method that fits your needs:

- **[Service-to-Service Communication](#service-to-service-communication)** - Direct communication between services in the same project
- **[Environment Variables](#environment-variables)** - Share configuration and credentials between services
- **[External Access to Private Network](#external-access-to-private-network)** - Connect from outside the project using VPN or SSH

## Service-to-Service Communication

Every Zerops project includes a dedicated private network that automatically connects all services within the project.

### Network Architecture

**Automatic Service Discovery:**
- All services communicate directly using service hostnames
- No manual network configuration required
- Traffic stays isolated within your project's private network

### Basic Service Communication

Connect to any service within the same project using the service hostname and internal port, e.g.:

```bash
# Connect to 'api' service on port 3000
http://api:3000/health
```

:::note
Do not use `https://` when communicating between runtime services in the same project. The internal communication is done over a private network and is isolated from other projects.
:::

### Internal Ports Configuration

Services expose internal ports for communication within the project:

- **Define ports** in your service's `zerops.yaml` [configuration](/zerops-yaml/specification#ports-)
- **HTTP ports** are accessible for web traffic between services
- **TCP/UDP ports** support database connections and custom protocols
- **Multiple ports** can be exposed per service for different purposes

:::tip Connect from another project
To connect to a service from **another Zerops project**, you'll need to use [public access methods](/references/networking/public-access) since different projects don't share private networks.
:::

### Environment Variables

Zerops creates default environment variables for each service to help you with connection within the same project. To avoid the need to copy the access parameters manually, use generated environment variables of the service.

#### Generated Environment Variables

Each service automatically receives environment variables containing connection details for other services in the project:

```bash
# Database connection variables
DATABASE_HOST=postgres
DATABASE_PORT=5432
DATABASE_URL=postgresql://app_user:secure_password@postgres:5432/myapp
```

#### Prefix the environment variable key

All services of the same project can reference environment variables from other services. To use an environment variable from one service in another service in the same project, you must prefix the environment variable key with the service hostname and underscore.

**Example:**

To access the `API_TOKEN` env variable of the `app` service, use `app_API_TOKEN` as the env variable key.

:::tip Environment Variables Guide
For complete information on environment variable types, isolation, and management, see the [Environment Variables Reference](/features/env-variables).
:::

## External Access to Private Network

Access your project's private network from external locations for development and administration.

### VPN Access

You can securely connect to your application from your local workspace via Zerops VPN. Zerops VPN client is included into zCLI, the Zerops command-line tool.

#### Start VPN connection

To start a VPN connection to the selected Zerops project, follow these steps:

1. [Install & setup zCLI](/references/cli)
2. [Start the Zerops VPN](/references/networking/vpn#start-vpn)

#### Access application through VPN

Once the VPN session is established, you have the secured connection to the project's private network in Zerops. You can access all project services locally by using their hostname. The only difference is that no environment variables are available when connected through VPN. To connect to your application in Zerops set the hostname and internal port e.g. `http://app:3000`

:::info
Do not use `https://` when communicating over the VPN. The security is assured by the VPN. The internal communication is done over a private network and is isolated from other projects.
:::

:::tip VPN Setup
For complete VPN setup, configuration, and troubleshooting, see the [VPN Reference Guide](/references/networking/vpn).
:::

### SSH Access

Use [SSH](/references/networking/ssh) to connect to your service for debugging and system administration.

```bash
# Connect to a specific service
ssh <service-name>
```

**Important:** SSH access is temporary and changes are not persistent across deployments.

:::tip SSH Configuration
For complete SSH documentation, access control, and advanced usage, see the [SSH Reference Guide].
:::

:::note
When you're finished working with internal access over VPN, [stop the Zerops VPN](/references/networking/vpn#stop-vpn) in zCLI.
:::

## Next Steps

- **Public access configuration:** [Public Access Reference Guide](/references/networking/public-access)
- **Environment variables:** [Environment Variables Reference](/features/env-variables)
- **VPN setup:** [VPN Reference Guide](/references/networking/vpn)
- **SSH access:** [SSH Reference Guide](/references/networking/ssh)

----------------------------------------

# References > Networking > L7 Balancer Config


This guide provides comprehensive documentation for Zerops L7 HTTP balancer configuration and advanced routing features. For basic setup instructions, see the [Domain & Access Configuration](/features/access) guide.

The L7 HTTP Balancer handles all HTTP/HTTPS traffic and provides advanced application-layer capabilities:

**Functions:**
- SSL/TLS termination with automatic certificate management
- Domain routing and virtual host management
- Load balancing across multiple service instances
- Advanced routing features (redirects, access policies, rate limiting)
- Performance optimization through caching and compression

**Architecture:**
- Deployed in two containers for high availability
- Scales automatically based on traffic patterns
- Integrated with Let's Encrypt for SSL certificates
- Configurable through advanced balancer settings

## L7 HTTP Balancer Configuration

Access the advanced balancer configuration through your project's HTTP Balancer section → **Advanced balancer configuration**.

### Connection Handling

Configure how the balancer manages client connections:

<table className="w-full my-1.5">
  <thead>
    <tr>
      <th className="w-fit whitespace-nowrap">Setting</th>
      <th className="w-fit whitespace-nowrap">Default</th>
      <th className="w-fit whitespace-nowrap">Range</th>
      <th className="w-fit whitespace-nowrap">Parameter</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td className="w-fit font-semibold whitespace-nowrap">Maximum simultaneous connections per worker</td>
      <td className="w-fit whitespace-nowrap">4000</td>
      <td className="w-fit whitespace-nowrap">1024-65535</td>
      <td className="w-fit whitespace-nowrap">worker_connections</td>
    </tr>
    <tr>
      <td className="w-fit font-semibold whitespace-nowrap">Accept multiple connections at once</td>
      <td className="w-fit whitespace-nowrap">on</td>
      <td className="w-fit whitespace-nowrap">on/off</td>
      <td className="w-fit whitespace-nowrap">multi_accept</td>
    </tr>
    <tr>
      <td className="w-fit font-semibold whitespace-nowrap">How long to keep idle connections open</td>
      <td className="w-fit whitespace-nowrap">30s</td>
      <td className="w-fit whitespace-nowrap">1s-300s</td>
      <td className="w-fit whitespace-nowrap">keepalive_timeout</td>
    </tr>
    <tr>
      <td className="w-fit font-semibold whitespace-nowrap">Maximum number of requests per connection</td>
      <td className="w-fit whitespace-nowrap">100000</td>
      <td className="w-fit whitespace-nowrap">1-1000000</td>
      <td className="w-fit whitespace-nowrap">keepalive_requests</td>
    </tr>
  </tbody>
</table>

:::tip Recommendations
- **High-traffic websites**: Increase `worker_connections` to 8000 or higher
- **API services**: Adjust `keepalive_timeout` to 60 for longer connections
- **WebSocket applications**: Increase `keepalive_timeout` for persistent connections
:::

### Client Request Settings

Control how the balancer handles incoming requests:

<table className="w-full my-1.5">
  <thead>
    <tr>
      <th className="w-fit whitespace-nowrap">Setting</th>
      <th className="w-fit whitespace-nowrap">Default</th>
      <th className="w-fit whitespace-nowrap">Range</th>
      <th className="w-fit whitespace-nowrap">Parameter</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td className="w-fit font-semibold whitespace-nowrap">Timeout for receiving client request header</td>
      <td className="w-fit whitespace-nowrap">10s</td>
      <td className="w-fit whitespace-nowrap">1s-300s</td>
      <td className="w-fit whitespace-nowrap">client_header_timeout</td>
    </tr>
    <tr>
      <td className="w-fit font-semibold whitespace-nowrap">Timeout for receiving client request body</td>
      <td className="w-fit whitespace-nowrap">10s</td>
      <td className="w-fit whitespace-nowrap">1s-300s</td>
      <td className="w-fit whitespace-nowrap">client_body_timeout</td>
    </tr>
    <tr>
      <td className="w-fit font-semibold whitespace-nowrap">Maximum allowed size of client request body</td>
      <td className="w-fit whitespace-nowrap">512m</td>
      <td className="w-fit whitespace-nowrap">1k-2048m</td>
      <td className="w-fit whitespace-nowrap">client_max_body_size</td>
    </tr>
    <tr>
      <td className="w-fit font-semibold whitespace-nowrap">Reset connections that have timed out</td>
      <td className="w-fit whitespace-nowrap">on</td>
      <td className="w-fit whitespace-nowrap">on/off</td>
      <td className="w-fit whitespace-nowrap">reset_timedout_connection</td>
    </tr>
    <tr>
      <td className="w-fit font-semibold whitespace-nowrap">Timeout for transmitting response to client</td>
      <td className="w-fit whitespace-nowrap">2s</td>
      <td className="w-fit whitespace-nowrap">1s-300s</td>
      <td className="w-fit whitespace-nowrap">send_timeout</td>
    </tr>
  </tbody>
</table>

:::tip Recommendations
- **File upload services**: Increase `client_body_timeout` and `client_max_body_size` to accommodate large files
- **Slow clients**: Increase header and body timeouts
- **API endpoints**: Set `client_max_body_size` according to your API payload requirements
:::

### Buffer Settings

Optimize memory usage for request and response handling:

<table className="w-full my-1.5">
  <thead>
    <tr>
      <th className="w-fit whitespace-nowrap">Setting</th>
      <th className="w-fit whitespace-nowrap">Default</th>
      <th className="w-fit whitespace-nowrap">Range</th>
      <th className="w-fit whitespace-nowrap">Parameter</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td className="w-fit font-semibold whitespace-nowrap">Size of buffer for client request header</td>
      <td className="w-fit whitespace-nowrap">1k</td>
      <td className="w-fit whitespace-nowrap">1k-64k</td>
      <td className="w-fit whitespace-nowrap">client_header_buffer_size</td>
    </tr>
    <tr>
      <td className="w-fit font-semibold whitespace-nowrap">Number of buffers for large client headers</td>
      <td className="w-fit whitespace-nowrap">4</td>
      <td className="w-fit whitespace-nowrap">1-16</td>
      <td className="w-fit whitespace-nowrap">large_client_header_buffers_number</td>
    </tr>
    <tr>
      <td className="w-fit font-semibold whitespace-nowrap">Size of buffers for large client headers</td>
      <td className="w-fit whitespace-nowrap">8k</td>
      <td className="w-fit whitespace-nowrap">1k-64k</td>
      <td className="w-fit whitespace-nowrap">large_client_header_buffers_size</td>
    </tr>
    <tr>
      <td className="w-fit font-semibold whitespace-nowrap">Size of buffer for client request body</td>
      <td className="w-fit whitespace-nowrap">16k</td>
      <td className="w-fit whitespace-nowrap">1k-1m</td>
      <td className="w-fit whitespace-nowrap">client_body_buffer_size</td>
    </tr>
  </tbody>
</table>

:::tip Recommendations
- **Large headers**: Increase header buffer sizes for applications with extensive headers
- **File uploads**: Optimize `client_body_buffer_size` based on typical upload sizes
- **Memory optimization**: Tune based on available memory and connection patterns
:::

### Proxy Settings

Configure how the balancer communicates with backend services:

<table className="w-full my-1.5">
  <thead>
    <tr>
      <th className="w-fit whitespace-nowrap">Setting</th>
      <th className="w-fit whitespace-nowrap">Parameter</th>
      <th className="w-fit whitespace-nowrap">Default</th>
      <th className="w-fit whitespace-nowrap">Range</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td className="w-fit font-semibold whitespace-nowrap">Enable buffering of client request body</td>
      <td className="w-fit whitespace-nowrap">proxy_request_buffering</td>
      <td className="w-fit whitespace-nowrap">off</td>
      <td className="w-fit whitespace-nowrap">on/off</td>
    </tr>
    <tr>
      <td className="w-fit font-semibold whitespace-nowrap">Enable buffering of responses from proxied server</td>
      <td className="w-fit whitespace-nowrap">proxy_buffering</td>
      <td className="w-fit whitespace-nowrap">on</td>
      <td className="w-fit whitespace-nowrap">on/off</td>
    </tr>
    <tr>
      <td className="w-fit font-semibold whitespace-nowrap">Size of the buffer used for reading the first part of the response</td>
      <td className="w-fit whitespace-nowrap">proxy_buffer_size</td>
      <td className="w-fit whitespace-nowrap">32k</td>
      <td className="w-fit whitespace-nowrap">1k-256k</td>
    </tr>
    <tr>
      <td className="w-fit font-semibold whitespace-nowrap">Number of buffers used for reading a response from the proxied server</td>
      <td className="w-fit whitespace-nowrap">proxy_buffers_number</td>
      <td className="w-fit whitespace-nowrap">4</td>
      <td className="w-fit whitespace-nowrap">1-16</td>
    </tr>
    <tr>
      <td className="w-fit font-semibold whitespace-nowrap">Size of buffers for reading a response from the proxied server</td>
      <td className="w-fit whitespace-nowrap">proxy_buffers_size</td>
      <td className="w-fit whitespace-nowrap">256k</td>
      <td className="w-fit whitespace-nowrap">1k-1m</td>
    </tr>
    <tr>
      <td className="w-fit font-semibold whitespace-nowrap">Size of buffers that can be busy sending response to the client</td>
      <td className="w-fit whitespace-nowrap">proxy_busy_buffers_size</td>
      <td className="w-fit whitespace-nowrap">256k</td>
      <td className="w-fit whitespace-nowrap">1k-1m</td>
    </tr>
  </tbody>
</table>

:::tip Recommendations
- **Real-time APIs**: Set `proxy_buffering` to off for lower latency
- **Large responses**: Increase `proxy_buffer_size` for handling larger API responses
- **Multimedia streaming**: Increase `proxy_buffers_size` and `proxy_buffers_number` for larger content
:::

### Performance Optimization

Enable various performance enhancements:

<table className="w-full my-1.5">
  <thead>
    <tr>
      <th className="w-fit whitespace-nowrap">Setting</th>
      <th className="w-fit whitespace-nowrap">Default</th>
      <th className="w-fit whitespace-nowrap">Range</th>
      <th className="w-fit whitespace-nowrap">Parameter</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td className="w-fit font-semibold whitespace-nowrap">Use sendfile() for file transfers</td>
      <td className="w-fit whitespace-nowrap">on</td>
      <td className="w-fit whitespace-nowrap">on/off</td>
      <td className="w-fit whitespace-nowrap">sendfile</td>
    </tr>
    <tr>
      <td className="w-fit font-semibold whitespace-nowrap">Enable TCP_NOPUSH socket option</td>
      <td className="w-fit whitespace-nowrap">on</td>
      <td className="w-fit whitespace-nowrap">on/off</td>
      <td className="w-fit whitespace-nowrap">tcp_nopush</td>
    </tr>
    <tr>
      <td className="w-fit font-semibold whitespace-nowrap">Enable TCP_NODELAY socket option</td>
      <td className="w-fit whitespace-nowrap">on</td>
      <td className="w-fit whitespace-nowrap">on/off</td>
      <td className="w-fit whitespace-nowrap">tcp_nodelay</td>
    </tr>
    <tr>
      <td className="w-fit font-semibold whitespace-nowrap">Enable gzip compression</td>
      <td className="w-fit whitespace-nowrap">on</td>
      <td className="w-fit whitespace-nowrap">on/off</td>
      <td className="w-fit whitespace-nowrap">gzip</td>
    </tr>
    <tr>
      <td className="w-fit font-semibold whitespace-nowrap">Rate limit for response transmission (0 = no limit)</td>
      <td className="w-fit whitespace-nowrap">0</td>
      <td className="w-fit whitespace-nowrap">0-1000m</td>
      <td className="w-fit whitespace-nowrap">limit_rate</td>
    </tr>
  </tbody>
</table>

:::tip Recommendations
- **File serving**: Ensure `sendfile` and `tcp_nopush` are enabled for static content
- **Real-time applications**: Verify `tcp_nodelay` is enabled
- **Bandwidth control**: Use `limit_rate` for traffic shaping
- **Multimedia streaming**: Enable `sendfile` and `tcp_nopush` for optimal streaming performance
:::

### File Cache Settings

Optimize file system operations:

<table className="w-full my-1.5">
  <thead>
    <tr>
      <th className="w-fit whitespace-nowrap">Setting</th>
      <th className="w-fit whitespace-nowrap">Default</th>
      <th className="w-fit whitespace-nowrap">Range</th>
      <th className="w-fit whitespace-nowrap">Parameter</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td className="w-fit font-semibold whitespace-nowrap">Cache open file descriptors</td>
      <td className="w-fit whitespace-nowrap">on</td>
      <td className="w-fit whitespace-nowrap">on/off</td>
      <td className="w-fit whitespace-nowrap">open_file_cache</td>
    </tr>
    <tr>
      <td className="w-fit font-semibold whitespace-nowrap">Maximum number of elements in file cache</td>
      <td className="w-fit whitespace-nowrap">200000</td>
      <td className="w-fit whitespace-nowrap">1000-1000000</td>
      <td className="w-fit whitespace-nowrap">open_file_cache_max</td>
    </tr>
    <tr>
      <td className="w-fit font-semibold whitespace-nowrap">Time after which unused cache elements are removed</td>
      <td className="w-fit whitespace-nowrap">20s</td>
      <td className="w-fit whitespace-nowrap">1s-300s</td>
      <td className="w-fit whitespace-nowrap">open_file_cache_inactive</td>
    </tr>
    <tr>
      <td className="w-fit font-semibold whitespace-nowrap">Time interval for checking cached elements validity</td>
      <td className="w-fit whitespace-nowrap">30s</td>
      <td className="w-fit whitespace-nowrap">1s-300s</td>
      <td className="w-fit whitespace-nowrap">open_file_cache_valid</td>
    </tr>
    <tr>
      <td className="w-fit font-semibold whitespace-nowrap">Minimum file uses to remain in cache</td>
      <td className="w-fit whitespace-nowrap">2</td>
      <td className="w-fit whitespace-nowrap">1-100</td>
      <td className="w-fit whitespace-nowrap">open_file_cache_min_uses</td>
    </tr>
    <tr>
      <td className="w-fit font-semibold whitespace-nowrap">Cache file lookup errors</td>
      <td className="w-fit whitespace-nowrap">on</td>
      <td className="w-fit whitespace-nowrap">on/off</td>
      <td className="w-fit whitespace-nowrap">open_file_cache_errors</td>
    </tr>
  </tbody>
</table>

:::tip Recommendations
- **Static file serving**: Increase cache size and adjust timeouts
- **Development**: Reduce validation timeout for faster file updates
- **High I/O applications**: Optimize based on file access patterns
:::

### Security Settings

Configure security-related options:

<table className="w-full my-1.5">
  <thead>
    <tr>
      <th className="w-fit whitespace-nowrap">Setting</th>
      <th className="w-fit whitespace-nowrap">Default</th>
      <th className="w-fit whitespace-nowrap">Parameter</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td className="w-fit font-semibold whitespace-nowrap">Emit nginx version in error messages and headers</td>
      <td className="w-fit whitespace-nowrap">off</td>
      <td className="w-fit whitespace-nowrap">server_tokens</td>
    </tr>
  </tbody>
</table>

**Best Practice:** Keep `server_tokens` disabled to avoid revealing server information.

## Forwarded Headers

The balancer sets the following headers on every request proxied to your application. They are always set by the balancer itself, overwriting any values sent by the client, so your application can safely trust them:

<table className="w-full my-1.5">
  <thead>
    <tr>
      <th className="w-fit whitespace-nowrap">Header</th>
      <th className="w-fit">Value</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td className="w-fit font-semibold whitespace-nowrap">Host</td>
      <td className="w-fit">Host requested by the client</td>
    </tr>
    <tr>
      <td className="w-fit font-semibold whitespace-nowrap">X-Real-IP</td>
      <td className="w-fit">Client IP address</td>
    </tr>
    <tr>
      <td className="w-fit font-semibold whitespace-nowrap">X-Forwarded-For</td>
      <td className="w-fit">Client IP address appended to any existing chain</td>
    </tr>
    <tr>
      <td className="w-fit font-semibold whitespace-nowrap">X-Forwarded-Proto</td>
      <td className="w-fit">Protocol the client used (`http` or `https`)</td>
    </tr>
    <tr>
      <td className="w-fit font-semibold whitespace-nowrap">X-Forwarded-Host</td>
      <td className="w-fit">Host requested by the client</td>
    </tr>
    <tr>
      <td className="w-fit font-semibold whitespace-nowrap">X-Forwarded-Port</td>
      <td className="w-fit">Port the client connected to</td>
    </tr>
  </tbody>
</table>

:::note Security
The `Forwarded` (RFC 7239) and `Proxy` headers are stripped from incoming requests and never reach your application. Configure your framework to read the `X-Forwarded-*` headers above instead.
:::

## Advanced Routing Features

The L7 HTTP Balancer supports sophisticated routing beyond basic domain mapping.

Access the advanced location configuration through your project's HTTP Balancer section → click the **gear/settings icon** next to any domain location to open the **Advanced Location Configuration** dialog.

### Redirect Configuration

Redirect requests to different URLs with full control:

**Configuration Options:**
- **Redirect URL**: Destination for redirected requests
- **Redirect Code**: HTTP status code for redirection (e.g., 301, 302, 307, 308)
- **Preserve Path**: Keep original path in redirect URL
- **Preserve Query**: Keep original query parameters in redirect URL

### Access Policy Configuration

Implement IP-based access control. If the request fails the check, a 403 Forbidden error is returned:

**Policy Types:**
- **Default Policy**: `allow` or `deny`
- **CIDR Blocks**: List of IP addresses/ranges that will have the opposite policy than the default

**Supported Formats:**
- IPv4 address: `192.168.1.1`
- IPv4 range: `192.168.1.0/24`
- IPv6 address: `2001:db8::1`
- IPv6 range: `2001:db8::/32`

### Rate Limiting Configuration

Protect against abuse and ensure fair resource usage. When the rate limit is exceeded, requests are delayed (burst). If they cannot be processed in time, a 503 Service Temporarily Unavailable error is returned:

**Configuration Parameters:**
- **Rate Limit Key**: `binary_remote_addr` (per IP) or `server_name` (per domain)
- **Rate**: Requests per second to allow
- **Burst**: Number of requests to queue when rate exceeded
- **Zone Name**: Memory zone for storing rate limiting state
- **Zone Size**: Memory allocated for rate limiting data (in MB)

### Basic Authentication

Add HTTP Basic Authentication to protected resources:

**Configuration:**
- **Realm**: Authentication realm name
- **Users**: Username and password combinations

### Custom Content Responses

Return custom content for specific conditions:

**Configuration:**
- **HTTP Status Code**: Any valid status code (200, 404, 503, etc.)
- **Content**: Response body content
- **Content Type**: MIME type (default: text/plain)

*Need help? Join our [Discord community](https://discord.gg/zeropsio).*

----------------------------------------

# References > Networking > Public Access


This guide provides detailed configuration instructions for making your Zerops services publicly accessible from the internet. For an overview of all access methods, see the [Access & Networking guide](/features/access).

## Public Access Methods

Choose the access method that best fits your needs:

- **[Zerops Subdomain Access](#zerops-subdomain-access)** - Quick setup with `.zerops.app` domains, ideal for development and testing
- **[Custom Domain Access](#custom-domain-access)** - Production-ready access through your own domains with full SSL support
- **[Direct Port Access](#direct-port-access)** - Direct port routing for non-HTTP protocols and specialized applications

## Zerops Subdomain Access

Zerops subdomains provide quick public access through `.zerops.app` addresses, ideal for development and testing environments.

### Configuration

1. Navigate to your service detail page in Zerops GUI
2. Select **Subdomain & domain & IP access** from the left menu (for runtime services)
3. Toggle the **Zerops subdomain access** switch

Once enabled, Zerops assigns a unique subdomain for your application. If you've defined multiple [internal ports](/zerops-yaml/specification#ports-) with HTTP support in your `zerops.yaml`, each port receives its own unique `.zerops.app` subdomain.

### Technical Implementation

When using Zerops subdomains:
- Access your application using the `https://` protocol (Zerops automatically manages SSL certificates)
- Traffic flows through a central HTTP balancer that:
  - Terminates SSL connections
  - Forwards requests to your application via HTTP
  - Handles all security certificates

### Limitations

:::warning Production Considerations
- The central HTTPS balancer is shared across all Zerops projects, which creates a scalability bottleneck
- Maximum upload size is limited to 50MB
- Not recommended for production traffic due to scalability bottleneck
- Better suited for development and testing environments
:::

## Custom Domain Access

Custom domain access provides production-ready public access through your own domain names, offering better performance and full control over domain settings.

### IP Address Configuration

Before setting up domain access, you need to configure public IP addresses. Zerops offers the following options:

#### IPv4 Configuration

**Dedicated IPv4 Address ($3/30 days)**
- Dedicated to your project and shared across all project services
- One IPv4 address per project limit
- Protects against blacklisting risks associated with shared IPs
- Subscription automatically renews every 30 days *(cannot be purchased with promo credit)*
- Fee is non-refundable but address can be reused in another project until subscription ends
- **Recommended for production workloads**

**Shared IPv4 Address (Free)**
- Available at no cost
- Shared across all Zerops users and their projects
- Limitations:
  - For HTTP/HTTPS traffic only
  - Restricted number of open connections
  - Shorter connection timeouts
- **Not recommended for production use**

#### IPv6 Configuration

**IPv6 Address (Free)**
- Dedicated to your project and shared across all project services
- One IPv6 address per project limit
- Automatically activated with first domain setup
- Available for all projects at no additional cost

:::tip Dual Stack Recommendation
Since IPv6 support is not universal, using both IPv4 and IPv6 is recommended for maximum accessibility.
:::

### HTTP Routing Setup

To configure domain access:

1. Go to your service detail page in Zerops GUI and select **Subdomain & domain & IP access** (or access from project's **Project & Services Access Overview** section → **HTTP Balancer (L7) Configuration & Public Access Through Domains**)
   - For advanced L7 balancer settings (connection handling, buffers, performance optimization), click **Advanced balancer configuration**
2. Click **Setup first domain access**
3. Configure domain settings:
   - Enter domain names (e.g., `mydomain.com`, `app.mydomain.com`)
   - Add multiple domains if needed (useful for multi-language sites)
   - Choose SSL certificate management
4. Define routing rules:
   - **Source:** The public path (the part of URL after your domain)
   - **Destination:** Choose which application and internal port receives the traffic
   - Add multiple routing configurations as needed

:::tip Alternative Access
Domain configuration can also be accessed from individual service pages under **Subdomain & domain & IP access**.
:::

All settings can be modified later as your needs change.

[Video: /vids/routes.webm](/vids/routes.webm)

### DNS Configuration

After setting up domain access in Zerops, configure your DNS records with your domain registrar:

:::tip DNS Configuration Guides
- **Cloudflare users:** Follow the [Cloudflare DNS Configuration Guide](/references/networking/cloudflare) for step-by-step Cloudflare-specific instructions
- **Other providers:** Use the [DNS and Proxy Configuration Guide](/references/networking/dns) for universal DNS setup instructions
:::

### HTTPS & SSL Configuration

When using Let's Encrypt certificates (recommended):

**Certificate Management:**
- Zerops handles all certificate installation and renewal automatically
- Certificates are provided free of charge
- No manual certificate management required

**Traffic Flow:**
1. Traffic arrives at your public IPv4/IPv6 addresses
2. Requests route through your project's dedicated HTTPS balancer
3. SSL termination occurs at the balancer level
4. Internal traffic uses HTTP protocol for optimal performance

**Balancer Architecture:**
- Deployed in two containers for high availability
- Scales vertically based on traffic demands
- Cannot be directly modified by users
- Included free of charge with custom domain setup

**Load Balancing:**
- **Round-robin load balancing** across multiple service instances
- **Health checks** to route traffic only to healthy instances
- **Connection pooling** for improved performance

**Performance Considerations:**
- Use dedicated IPv4 addresses instead of shared ones for high-traffic applications
- Consider the [L7 Balancer advanced configuration options](/references/networking/l7-balancer-config) for production optimization

## Direct Port Access

Direct port access enables public access to specific ports on your services, supporting any protocol and specialized use cases beyond HTTP.

:::important Service Compatibility
Currently, direct public port access is only available for runtime services and PostgreSQL databases.
:::

### Port Configuration

1. Navigate to your service detail page in Zerops GUI:
   - For runtime services: Select **Subdomain & domain & IP access**
   - For PostgreSQL services: Select **Direct access through IP address**
   - Or access from project's **Project & Services Access Overview** section → **Direct IP Accesses to Services**
2. Configure port settings:
   - Either **Setup first access through IPv6** or activate **Unique IPv4 add-on** (if needed)
   - Choose any port from 10-65435 (ports 80 and 443 are reserved)
   - Select destination service and internal port
   - Each public port can be mapped to any internal service port
   - Multiple public ports can point to the same internal port if needed
   - Port configurations can be set independently for IPv4 and IPv6

:::tip Service-Level Access
For runtime services, you can also access port configuration from the service detail page under **Subdomain & domain & IP access**.
:::

### Firewall Configuration

Secure your public ports with optional firewall rules:

1. **Enable firewall** for specific ports
2. **Choose policy type:**
   - **Blacklist:** Block specific IPs/ranges (allow all others)
   - **Whitelist:** Allow only specific IPs/ranges (block all others)
3. **Configure IP rules:**
   - **Single IP format:** Affects only the specific IP address
   - **IP range format:** Affects all IPs in the specified CIDR range

For information about Zerops' platform-wide firewall and port restrictions, see the [Firewall Reference Guide](/references/networking/firewall).

### Protocol Support

Direct port access supports:
- **TCP protocols:** HTTP, HTTPS, database connections, custom TCP services
- **UDP protocols:** DNS, gaming protocols, custom UDP services
- **Any port-based protocol** your application requires

## Next Steps

- **DNS Configuration:** [DNS and Proxy Configuration Guide](/references/networking/dns) or [Cloudflare Guide](/references/networking/cloudflare)
- **Advanced Routing:** [L7 Balancer Configuration & Advanced Routing Guide](/references/networking/l7-balancer-config)
- **Wildcard Domains:** [Wildcard Domain Configuration](/references/networking/dns#wildcard-domain-configuration)
- **Internal Access:** [Internal Access Configuration Guide](/references/networking/internal-access)

*Need help? Join our [Discord community](https://discord.gg/zeropsio).*

----------------------------------------

# References > Networking > Ssh


:::important
SSH access is available only for runtime services and web servers.

Database services, message brokers, and object storage are **not accessible** via SSH.
:::

:::warning Non-Persistent Changes
SSH connections should not be used for making persistent changes to your service:

- In [HA mode](/features/scaling#horizontal-scaling-runtime-services-linux-containers-and-docker), changes via SSH affect only the current container
- Container replacements or scaling events will deploy the original application version
- For persistent changes across all containers, use:
  - [`run.prepareCommands`](/zerops-yaml/specification#preparecommands--1)
  - [`run.initCommands`](/zerops-yaml/specification#initcommands-)
:::

## Connection Methods

You can connect to your services using two methods:

### Web Terminal (Always Available)
For quick debugging and inspection, use the **Remote Web Terminal** available in each service's detail page. This browser-based terminal:
- **Always accessible** regardless of [SSH isolation](#ssh-access-control) settings
- Requires no VPN setup
- Provides instant access to your containers
- Perfect for quick debugging sessions and emergency access

### SSH via VPN (Full Access)
For full SSH capabilities and persistent connections, connect through the [Zerops VPN](/references/networking/vpn).

## Setting Up SSH Access

### 1. Configure VPN Connection (For SSH Access)

The [Zerops CLI (zCLI)](/references/cli) comes bundled with the [Zerops VPN](/references/networking/vpn) client. To connect to your [Zerops project](/features/infrastructure#projects):

1. [Install and configure zCLI](/references/cli)
2. [Initialize the Zerops VPN connection](/references/networking/vpn#start-vpn)

### 2. Establish SSH Connection via VPN

Once your VPN session is active, you can connect to any [service](/features/infrastructure#services) using its hostname via SSH:

```sh
ssh <service hostname>
```

Example:
```sh
ssh app
```

When connecting for the first time, you may receive this security prompt:

```sh title="bash"
The authenticity of host 'app (x.x.x.x)' can't be established.
RSA key fingerprint is SHA256:5wdgRcp/...
This key is not known by any other names
Are you sure you want to continue connecting (yes/no/[fingerprint])?
```

Type `yes` to trust the host and prevent future prompts.

#### Connecting to Specific Containers

To access a specific container instead of the service as a whole, use the container's hostname:

```sh
ssh <container hostname>
```

Example:
```sh
ssh node-id-1.runtime.app.zerops
```

:::note
When using [HA mode](/features/scaling#horizontal-scaling-runtime-services-linux-containers-and-docker), connecting to the service hostname will route you to a random container within that service.
:::

#### Container Naming Conventions

Each container in your project has a unique hostname following these patterns:

- Format 1: `node-id-<number>.runtime.app.zerops`
- Format 2: `node<number>.runtime.app.zerops`

When your application [scales horizontally](/features/scaling#horizontal-scaling-runtime-services-linux-containers-and-docker):
- New containers receive incremental hostnames
- Decommissioned container hostnames are not recycled
- You might see non-sequential container numbers (e.g., `node-id-5` and `node-id-12`)
- Container hostnames may change as your service scales

:::warning
Never connect to containers using their local IP addresses, as these addresses are dynamic and may change.
:::

## SSH Access Control

Zerops provides fine-grained control over SSH access through SSH Isolation. It is configured with the `sshIsolation` project variable. This security feature determines who can connect to your services via SSH, controlling both VPN connections and service-to-service SSH access.

### Default Behavior

By default, `sshIsolation` is set to `vpn`, which means:

- ✅ VPN users can SSH to any service
- ✅ **Web Terminal is always accessible** (unaffected by isolation settings)
- ❌ Services cannot SSH to each other

*This configuration maintains maximum security for production environments.*

### Configuring SSH Isolation

SSH isolation can be configured at two levels:

#### Project-Level Configuration

Set the `sshIsolation` project variable through:
- **GUI**: Navigate to **Project Environment Variables**
- **Import**: Add to your `import.yaml`:

```yaml title="import.yaml"
project:
  sshIsolation: "vpn project"
```

#### Service-Level Override

Individual services can override the project setting:

```yaml title="import.yaml"
services:
  - hostname: api
    sshIsolation: "vpn service@admin"
```

:::note
In import YAML, `sshIsolation` can be also defined in `envVariables`/`envSecrets`.  (If both are present, the nested version takes precedence).
:::

### Isolation Modes

#### Rule Types

**Allow Rules**: Grant SSH access
- `vpn` *(default)* - VPN SSH connections
- `project` - Any service in the project
- `service` - Containers within the same service
- `service@name` - Specific service named "name"

**Block Rules**: Deny SSH access (use `-` prefix)
- `-vpn` - Block VPN SSH connections
- `-project` - Block all services
- `-service` - Block all services
- `-service@name` - Block specific service named "name"

:::info
**Web Terminal access is never blocked** by these rules and remains available as an emergency access method.
:::

### Combining Rules

You can combine multiple rules using spaces. The system evaluates rules by checking the most specific matches first.

#### Rule Evaluation Order

The system checks SSH connection rules in this priority:
1. **Specific service rules**: `service@name` or `-service@name`
2. **General service rules**: `service` or `-service`
3. **Project rules**: `project` or `-project`
4. **VPN rules**: `vpn` or `-vpn`

:::note Important
- Block rules (`-`) always take priority over allow rules when both apply to the same source
- **Web Terminal access bypasses all these rules** and is always available
:::

When a service tries to connect, the system:

1. **Identifies the connecting source** (VPN user, Web Terminal, or specific service name)
2. **Checks for specific rules** first (like `service@admin` or `-service@api`)
3. **Falls back to general rules** (like `project` or `-service`)
4. **Allows or blocks** based on the first matching rule

#### Rule Evaluation Examples

#### Simple Rule

**Rule**: `project -service@untrusted`

1. When **Web Terminal** is used:
- Always allowed → **ALLOWED**
2. When **`untrusted` service** connects:
- Matches `-service@untrusted` rule → **BLOCKED**
3. When **any other service** connects:
- Matches `project` rule → **ALLOWED**

**Effective behavior**:
- ✅ All services can SSH to each other
- ✅ Web Terminal always accessible
- ❌ Except the `untrusted` service cannot SSH anywhere
- ❌ No VPN SSH access (no `vpn` rule present)

#### Complex Rule

**Rule**: `vpn project -service service@admin`

1. When **VPN user** connects via SSH:
  - Matches `vpn` rule → **ALLOWED**
2. When **Web Terminal** is used:
  - Always allowed regardless of rules → **ALLOWED**
3. When **`admin` service** connects:
- Matches `service@admin` rule → **ALLOWED**
4. When **any other service** (like `api`) connects:
- Matches `-service` rule → **BLOCKED**
- Never reaches the `project` rule

**Effective behavior**:
- ✅ VPN SSH connections can access all services
- ✅ Web Terminal always accessible
- ✅ Only the `admin` service can SSH to other services
- ❌ All other services are blocked from SSH connections

:::note
The `project` rule remains in the configuration but becomes unreachable for most services because they get blocked by `-service` first.
:::

#### Common Combinations

**Development Setup** *(ideal for microservices debugging)*:
```yaml
sshIsolation: "vpn project"
```
- ✅ VPN SSH connections can access all services
- ✅ Services can SSH to each other
- ✅ Web Terminal always accessible

**Gateway Pattern**:
```yaml
sshIsolation: "vpn service@gateway"
```
- ✅ VPN SSH connections can access all services
- ✅ Only the `gateway` service can SSH to other services
- ✅ Web Terminal always accessible
- ❌ Other services cannot SSH anywhere

**Selective Exclusion**:
```yaml
sshIsolation: "project -service@untrusted"
```
- ✅ All services can SSH to each other
- ✅ Web Terminal always accessible
- ❌ The `untrusted` service cannot SSH anywhere
- ❌ No VPN SSH access (not included in rules)

### Security Considerations

:::warning
Be careful with block rules - they can prevent expected SSH access even when allow rules are present.

**Example**: `project -service` would block all services from SSH, making the `project` rule ineffective for service-to-service connections.
:::

**Safety Mechanism**: Web Terminal access is never blocked by SSH isolation rules, ensuring you always have a way to access your containers for debugging or emergency fixes.

**Common Gotchas**:
- `service -service@api` blocks the `api` service from SSH but allows others within their own service
- `project -service` allows VPN SSH access but blocks all service-to-service SSH
- `-vpn -project -service` blocks all SSH connections but Web Terminal remains accessible
- Missing `vpn` in rules blocks VPN SSH access but Web Terminal still works

### Best Practices
- Start with `vpn` for production environments
- Use `vpn project` for development and debugging
- Test isolation changes in development environments first
- Be explicit about what you want to allow rather than relying on complex combinations
- Remember that Web Terminal provides emergency access when SSH rules are too restrictive
- Document your isolation strategy for team members

*Need help? Join our [Discord community](https://discord.gg/zeropsio).*

----------------------------------------

# References > Networking > Vpn


At Zerops, security is our core priority. We ensure everything stays within a private network with zero exposure to the internet.
Unlike typical consumer VPNs that focus on changing your public IP address, our WireGuard VPN implementation is specifically designed to give you secure access to your project's services.

## Prerequisites

Before getting started, ensure you have:

- [WireGuard](https://www.wireguard.com/install) installed on your system
- [zCLI](/references/cli) (serves as the WireGuard client)
- A Zerops project with at least one service

:::info Windows prerequisite
zCLI VPN relies on WireGuard, which requires the **Virtual Machine Platform**
feature to be enabled on Windows 11. Open `optionalfeatures.exe`, check
**Virtual Machine Platform**, then reboot.
:::

## Usage

You can interact with services within your project and even establish SSH connection to your services after connecting to project through VPN.

### Start VPN

Connects to the Zerops VPN.

```bash
zcli vpn up [project-id] [flags]
```

**Flags:**
- `--auto-disconnect` - Automatically disconnect from VPN if already connected
- `--help` - Display help for the vpn up command
- `--mtu int` - Set custom MTU value for Wireguard interface (default: 1420)
- `-P, --project-id string` - Required when you have access to multiple projects

To connect to a specific project without using the interactive mode, use the project ID from your Zerops dashboard:

```bash
zcli vpn up Evs8Je4NTvKeIkUqoUXp2w
```

:::info
First-time `zcli vpn up` usage requires installing the Zerops VPN daemon.
Confirm with `y` when prompted (administrator privileges may be required).
:::

Upon connection, you'll have secure access to your project's private network with the following characteristics:

- All services are accessible via their hostnames
- Only one project connection is possible at a time (new connections automatically close existing ones)
- The VPN daemon maintains connection stability with automatic reconnection
- Environment variables are not available through VPN connections

### Stop VPN

Disconnects from the Zerops VPN.

```bash
zcli vpn down [flags]
```

**Flags:**
- `--help` - Display help for the vpn down command

## Troubleshooting

#### 1. Interface Already Exists
**Problem**: When running `zcli vpn up`, you get an error like:
```
ERR /opt/homebrew/bin/wg-quick up /opt/homebrew/etc/wireguard/zerops.conf: [+] Interface for zerops is utun6 wg-quick: 'zerops' already exists as 'utun6'
```

**Solution**: Reset the VPN connection by running:
```bash
zcli vpn down
zcli vpn up
```

#### 2. Hostname Resolution
**Problem**: Even with VPN successfully connected, hostname resolution fails with errors like:
```
could not translate host name "hostname" to address: nodename nor servname provided, or not known
```

* The issue is known to happen rarely on Windows

**Solution**: Append `.zerops` to the hostname, even when VPN shows as connected:
```bash
# Instead of
psql -h [hostname] -U [user]

# Use
psql -h [hostname].zerops -U [user]
```

:::tip Windows OS tip
In the Advanced TCP/IP Settings dialog, navigate to the DNS tab and confirm that "zerops" appears in the "Append these DNS suffixes (in order)" list. If missing, add it using the Add button.
:::

#### 3. WSL2 VPN Connection
**Problem**: VPN not running in WSL2

**Solution**: This might occur because `systemd` is not running in WSL2 by default. To fix:
1. Run `sudo -e /etc/wsl.conf`
2. Add `system=true` to `[boot]` section
3. Comment out the first line `LABEL=cloudimg-rootfs / ext4 defaults 0 1`
4. In `cmd.exe/PowerShell` run `wsl --shutdown` to restart WSL2

#### 4. VPN Connection Conflicts
**Problem**: When another VPN connection is active concurrently with Zerops VPN, users may experience degraded network performance or connection timeouts due to packet fragmentation issues.

**Solution**: Run the VPN with a reduced MTU (Maximum Transmission Unit) size:
```bash
zcli vpn up --mtu 1350
```

This resolves packet size conflicts that can occur when multiple VPN connections are active simultaneously.

#### 5. wg-quick Issues on Ubuntu 25.*
**Problem**: VPN fails to start due to wg-quick errors on Ubuntu 25.* systems.

**Solution**: Install and configure AppArmor utilities:
```bash
sudo apt install apparmor-utils
sudo aa-complain wg-quick
```

## Enhanced Security with WireGuard

Zerops uses **WireGuard** to create secure VPN tunnel connections to your project's private network. This provides enhanced security compared to traditional **SSH** connections.

WireGuard eliminates the need for **passwords** or **IP address management** that SSH typically requires. As a free, lightweight, **open-source** communication protocol, WireGuard employs advanced **cryptography** to establish secure connections.

The system creates encrypted tunnels using **UDP** for traffic transmission and relies on **public/private key pairs** for user authorization.

Each Zerops project runs a **WireGuard server**, while the **zCLI** (Zerops Command Line Interface) functions as a **WireGuard client**. This architecture enables authorized users to securely interact with their Zerops projects through the command line interface.

----------------------------------------

# References > Networking > Zerops Ca


Zerops issues TLS certificates for its managed services (for example PostgreSQL via pgBouncer, or Valkey TLS ports) from its own internal Certificate Authority. When you connect to one of these endpoints over TLS from outside Zerops &mdash; your laptop, CI runner, or another piece of infrastructure &mdash; the client needs to trust the Zerops CA in order to verify the certificate and complete the handshake.

## Download the CA

The Zerops root CA is published as a single PEM file at:

```
https://app.zerops.io/ca
```

Fetch it directly:

```bash
curl -L -o zerops-ca.pem https://app.zerops.io/ca
```

The downloaded file is a standard PEM-encoded certificate. You can inspect it with `openssl`:

```bash
openssl x509 -in zerops-ca.pem -noout -subject -issuer -dates
```

## Inside Zerops

If your application or client runs **inside** a Zerops container, you do not need to download anything &mdash; the CA is already available on the local filesystem at:

```
/etc/zerops-zembed/ca.crt
```

Point your TLS client at that path the same way you would point it at a downloaded copy (`sslrootcert=/etc/zerops-zembed/ca.crt`, `--cacert /etc/zerops-zembed/ca.crt`, etc.). It is the same certificate that `https://app.zerops.io/ca` serves.

The Zerops CA is also pre-installed into the system trust store of **every Zerops container**, so most TLS libraries will verify Zerops-signed certificates without any explicit `--cacert` / `sslrootcert` configuration. You can confirm this in your own container with any of the following:

```bash
# 1) Subject hash → matching symlink in the system trust dir (Debian/Ubuntu)
ls -l "/etc/ssl/certs/$(openssl x509 -noout -subject_hash -in /etc/zerops-zembed/ca.crt).0"
# e.g. /etc/ssl/certs/59e8696a.0 -> service-intermediate.pem

# 2) Verify the CA file against the merged system bundle
openssl verify -CAfile /etc/ssl/certs/ca-certificates.crt /etc/zerops-zembed/ca.crt
# expected: /etc/zerops-zembed/ca.crt: OK

# 3) End-to-end: handshake against a Zerops-signed endpoint without -CAfile
openssl s_client -connect <service-hostname>:6380 -verify_return_error </dev/null
# look for: Verify return code: 0 (ok)
```

## When to use it

Use the Zerops CA whenever your client needs to verify a TLS certificate issued by Zerops. The most common cases are:

- Connecting to a [managed PostgreSQL](/postgresql/how-to/connect#connect-via-public-ip) over the public TLS port (`6432`, via pgBouncer)
- Connecting to [managed Valkey](/valkey/overview) on its TLS ports (`6380`, or `7001` in HA setups)
- Any other Zerops-signed TLS endpoint reached from outside the project's private network

The same CA also signs internal TLS endpoints, so it can be useful when verifying certificates from inside a Zerops project too.

:::note
You do **not** need the CA for HTTPS traffic on `.zerops.app` subdomains or on custom domains &mdash; those use publicly-trusted certificates (Let's Encrypt by default), which every operating system already trusts.
:::

## Usage examples

### psql (PostgreSQL)

Pass the CA via `sslrootcert` and require certificate verification with `sslmode=verify-full`:

```bash
psql "host=<public-ip> port=6432 user=<user> dbname=db \
      sslmode=verify-full sslrootcert=./zerops-ca.pem"
```

Or as a connection string:

```
postgresql://<user>:<password>@<public-ip>:6432/db?sslmode=verify-full&sslrootcert=./zerops-ca.pem
```

### redis-cli (Valkey)

```bash
redis-cli --tls --cacert ./zerops-ca.pem \
  -h <public-ip> -p 6380 -a <password>
```

### openssl s_client (debugging)

To confirm the TLS handshake and inspect the served certificate chain:

```bash
openssl s_client -connect <public-ip>:6432 \
  -CAfile ./zerops-ca.pem -servername <public-ip>
```

### System-wide trust

To trust the Zerops CA system-wide (so clients pick it up automatically without an explicit flag):

- **Debian/Ubuntu:** copy to `/usr/local/share/ca-certificates/zerops-ca.crt` and run `sudo update-ca-certificates`
- **macOS:** `sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain zerops-ca.pem`
- **Alpine:** copy to `/usr/local/share/ca-certificates/zerops-ca.crt` and run `update-ca-certificates`

:::tip
For application code, most TLS libraries accept a custom CA bundle without modifying system trust &mdash; for example `PGSSLROOTCERT` for libpq, `tls.RootCAs` in Go, or the `ca` option in Node's `tls` module.
:::


----------------------------------------

# References > Smtp


Simple Mail Transfer Protocol (SMTP) is the internet standard for email transmission. It operates as a set of rules that govern how email messages are formatted, encrypted, and relayed between servers.

## SMTP in Zerops

Zerops implements a security-first approach to email sending operations, allowing only port 587 for SMTP communication. This decision aligns with modern security practices and helps maintain the platform's integrity.

### Port Configuration

<table className="w-full my-1.5">
  <thead>
    <tr>
      <th className="w-fit">Port</th>
      <th className="w-fit">Status</th>
      <th className="w-full">Description</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td className="w-fit font-semibold">587</td>
      <td className="w-fit">✅&nbsp;Allowed</td>
      <td className="w-full">Modern SMTP submission with STARTTLS</td>
    </tr>
    <tr>
      <td className="w-fit font-semibold">25</td>
      <td className="w-fit">❌&nbsp;Blocked</td>
      <td className="w-full">Traditional SMTP (security risk)</td>
    </tr>
    <tr>
      <td className="w-fit font-semibold">465</td>
      <td className="w-fit">❌&nbsp;Blocked</td>
      <td className="w-full">Legacy SMTPS (deprecated)</td>
    </tr>
  </tbody>
</table>

### Why Port 587

Port 587 is the modern standard for sending emails through SMTP, designed specifically for authenticated client submissions. This port enforces several security measures:

- Mandatory TLS encryption for data protection
- Required authentication for all clients
- Secure transmission through verified providers

#### How It Works

Port 587 implements STARTTLS to establish secure connections. The process follows these steps:

1. Client connects to the SMTP server
2. Server responds with available capabilities
3. Client requests STARTTLS upgrade
4. Connection switches to encrypted TLS
5. Client provides authentication credentials
6. Email transmission begins over secure channel

This implementation balances modern security requirements with broad compatibility, making it the recommended choice for email transmission.

### Port Restrictions and Platform Security

Zerops enforces a strict policy of **blocking ports 25 and 465** for email operations.

:::caution
This is a permanent security measure with no exceptions, designed to protect both the platform and its users.
:::

Port 25, in particular, is frequently exploited for spam distribution across cloud platforms. Instead of providing basic SMTP functionality, we encourage the use of specialized email services that offer:

- Advanced deliverability management
- Comprehensive monitoring and analytics
- Built-in spam protection
- Professional IP reputation management
- Automated bounce handling

This strict policy protects platform integrity. Poor IP reputation from email abuse can cascade across an entire infrastructure. The impact extends beyond email services to affect:

- Legitimate web applications
- Platform response times
- Overall service reliability
- Other customers' applications

This is why Zerops maintains this strict policy - to ensure consistent, reliable service for all platform users.

## Sending Emails from Zerops

### Recommended Approaches

You have two main options for sending emails from your Zerops applications:

1. **Email Provider SMTP Client**
   - You act as a client using their SMTP servers
   - Subject to provider's sending limits and policies

2. **Specialized Email Services**
   - Purpose-built for application email delivery
   - Your own dedicated sending infrastructure
   - Higher limits with scalable pricing
   - Advanced delivery monitoring and analytics

### Configuration Examples

These examples serve as a starting point. Check your email provider's official documentation for current configuration requirements.

:::note
Port 587 is mandatory for all SMTP configurations in Zerops. Other ports (25, 465) are blocked for security reasons.
:::

#### Enterprise Email Providers

<table className="w-full my-1.5">
  <thead>
    <tr>
      <th className="w-fit">Service</th>
      <th className="w-fit">Host</th>
      <th className="w-fit">Port</th>
      <th className="w-fit">Secure</th>
      <th className="w-fit">Username</th>
      <th className="w-full">Password</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td className="w-fit font-semibold">[Gmail](https://support.google.com/a/answer/176600?hl=en)</td>
      <td className="w-fit">smtp.gmail.com</td>
      <td className="w-fit">587</td>
      <td className="w-fit">false</td>
      <td className="w-fit">your.name<span>@</span>gmail.com</td>
      <td className="w-full">App Password required</td>
    </tr>
    <tr>
      <td className="w-fit font-semibold">[Google Workspace](https://support.google.com/a/answer/176600?hl=en)</td>
      <td className="w-fit">smtp-relay.gmail.com</td>
      <td className="w-fit">587</td>
      <td className="w-fit">false</td>
      <td className="w-fit">your.name<span>@</span>your-domain.com</td>
      <td className="w-full">Regular password (App Password if using 2FA)</td>
    </tr>
    <tr>
      <td className="w-fit font-semibold">[Office 365](https://learn.microsoft.com/en-us/exchange/mail-flow-best-practices/how-to-set-up-a-multifunction-device-or-application-to-send-email-using-microsoft-365-or-office-365)</td>
      <td className="w-fit">smtp.office365.com</td>
      <td className="w-fit">587</td>
      <td className="w-fit">false</td>
      <td className="w-fit">your.name<span>@</span>your-domain.com</td>
      <td className="w-full">Account password</td>
    </tr>
  </tbody>
</table>

:::note Google
- Gmail/Office 365: Better for testing or low-volume sending
- Google Workspace: Suitable for business needs with higher limits
:::

#### Email Service Providers

<table className="w-full my-1.5">
  <thead>
    <tr>
      <th className="w-fit">Provider</th>
      <th className="w-fit">Host</th>
      <th className="w-fit">Port</th>
      <th className="w-fit">Username</th>
      <th className="w-fit">Password</th>
      <th className="w-full">Features</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td className="w-fit font-semibold">[SendGrid](https://www.twilio.com/docs/sendgrid/for-developers/sending-email/getting-started-smtp)</td>
      <td className="w-fit">smtp.sendgrid.net</td>
      <td className="w-fit">587</td>
      <td className="w-fit">apikey</td>
      <td className="w-fit">SendGrid API key</td>
      <td className="w-full">• Free tier available
• Real-time analytics
• Webhooks
• Spam detection</td>
    </tr>
    <tr>
      <td className="w-fit font-semibold">[Mailgun](https://documentation.mailgun.com/docs/mailgun/user-manual/sending-messages/#send-via-smtp)</td>
      <td className="w-fit">smtp.mailgun.org</td>
      <td className="w-fit">587</td>
      <td className="w-fit">postmaster<span>@</span>your-domain.com</td>
      <td className="w-fit">Mailgun password</td>
      <td className="w-full">• Free tier available
• Email validation
• Routing rules
• Delivery analytics</td>
    </tr>
    <tr>
      <td className="w-fit font-semibold">[Amazon SES](https://docs.aws.amazon.com/ses/latest/dg/send-email-smtp.html)</td>
      <td className="w-fit">email-smtp.us-east-1.amazonaws.com</td>
      <td className="w-fit">587</td>
      <td className="w-fit">SES access key ID</td>
      <td className="w-fit">SES secret access key</td>
      <td className="w-full">• Pay as you go pricing
• AWS integration
• High deliverability
• Auto-scaling</td>
    </tr>
  </tbody>
</table>

## Best Practices

When implementing email functionality in your applications:

- Store SMTP credentials in environment variables
- Implement proper error handling and retry logic
- Use queue systems for bulk sending to prevent rate limits
- Monitor delivery status and bounce rates
- Keep SMTP libraries and configurations up to date


----------------------------------------

# References > Zcli > Commands


## Basic Usage

```sh
zcli <command> [flags]
```

:::note Tip
All commands support the `-h, --help` flag which displays help information about the command.
:::

:::tip Configuration
For detailed information about configuration options, environment variables, and logging, see the [Zerops CLI Configuration](/references/zcli/configuration) page.
:::

## Command Groups
- [Account & VPN](#account--vpn)
- [Project Management](#project-management)
- [Service Operations](#service-operations)
- [Utility Commands](#utility-commands)

## Account & VPN

### login

Logs you into Zerops using a generated token or your login credentials.

```sh
zcli login <token>
```

### logout

Disconnects from VPN and logs out from your Zerops account.

```sh
zcli logout
```

### vpn up

Connects to the Zerops VPN.

```sh
zcli vpn up [project-id] [flags]
```

**Flags:**
- `--auto-disconnect` - Automatically disconnect from VPN if already connected
- `--mtu int` - Set custom MTU value for Wireguard interface (default: 1420)
- `-P, --project-id string` - Required when you have access to multiple projects

:::note
You can set a default project ID for VPN connections in a `.zcli.yml` file or via the `ZEROPS_PROJECTID` environment variable. See the [Configuration](/references/zcli/configuration) page for details.
:::

### vpn down

Disconnects from the Zerops VPN.

```sh
zcli vpn down
```

:::note
For more detailed information about Zerops VPN configuration and troubleshooting, visit the [VPN Documentation](/references/networking/vpn).
:::

## Project Management

### scope project

Sets the scope for a project. All commands that require project ID will use the selected one.

```sh
zcli scope project [project-id]
```

### scope reset

Resets the scope for a project.

```sh
zcli scope reset
```

### project create

Creates a new project for a specified organization.

```sh
zcli project create [flags]
```

**Flags:**
- `--env-isolation string` - Environment isolation rule [service, none] (default: "service")
- `--mode string` - Project mode [light, serious] (default: "light")
- `--name string` - Project name
- `--org-id string` - Organization ID to create a project for
- `--out string` - Output format using Go template syntax
- `--ssh-isolation string` - SSH isolation rules (default: "vpn")
- `--tags strings` - Project tags (comma-separated list or repeated flag)

### project delete

Deletes a project and all its services.

```sh
zcli project delete [project-id] [flags]
```

**Flags:**
- `--confirm` - Skip confirmation prompts for destructive operations
- `-P, --project-id string` - Required when you have access to multiple projects

### project env

Displays environment variables for the current project scope.

```sh
zcli project env [flags]
```

**Flags:**
- `--export` - Prepends export keyword to each env in output: `export {{.Key}}={{.Value}}`
- `-P, --project-id string` - Required when you have access to multiple projects
- `--service string` - Service name, in which context the environment variables are output
- `--template string` - Output template (default: "`{{.Key}}={{.Value}}`")
- `--user-only` - Exclude all non user env variables

### project list

Lists all projects you have access to.

```sh
zcli project list
```

### project project-import

Creates a new project with one or more services from an [Import YAML](/references/import) definition.

```sh
zcli project project-import <importYamlPath> [flags]
```

**Flags:**
- `--org-id string` - Organization ID where the project should be created (required for multiple organizations)
- `--working-dir string` - Sets a custom working directory (default: "./")

### project service-import

Creates one or more services in an existing project from an [Import YAML](/references/import) definition.

```sh
zcli project service-import <importYamlPath> [flags]
```

**Flags:**
- `-P, --project-id string` - Required when you have access to multiple projects

## Service Operations

### service list

Lists all services in a project.

```sh
zcli service list [flags]
```

**Flags:**
- `-P, --project-id string` - Required when you have access to multiple projects

### service create

Creates a new service for a specified project.

```sh
zcli service create [flags]
```

**Flags:**
- `--env strings` - Environment variables to be set as secrets (comma-separated or repeated flag)
- `--env-file string` - File with environment variables (max 1.0 MiB)
- `--env-isolation string` - Environment isolation rule [service, none] (default: "service")
- `--mode string` - Service mode [ha, non_ha] (default: "non_ha")
- `--name string` - Service name
- `--noop` - Creates service only if none with the same name exists
- `--out string` - Output format using Go template syntax
- `-P, --project-id string` - Required when you have access to multiple projects
- `--ssh-isolation string` - SSH isolation rules (default: "vpn")
- `--start-without-code` - Start service immediately without deployment
- `--working-dir string` - Sets custom working directory (default: "./")
- `--zerops-yaml-path string` - Sets custom path to zerops.yml file

### service push

Builds your application in Zerops and deploys it. This is the recommended way to deploy your code.

```sh
zcli service push [service-id-or-name] [flags]
```

**Flags:**
- `--archive-file-path string` - Creates a tar.gz archive with application code
- `-g, --deploy-git-folder` - Include the .git folder in the upload
- `--disable-logs` - Disable logs during push
- `--no-git` - Upload entire working directory as-is (cannot be combined with --workspace-state or --deploy-git-folder)
- `-P, --project-id string` - Required when you have access to multiple projects
- `-S, --service-id string` - Required when you have access to multiple services
- `--setup string` - Choose setup to use from zerops.yml
- `-v, --verbose` - Log additional debug data to the zCLI [debug log file](/references/zcli/configuration#logging-configuration)
- `--version-name string` - Adds a custom version name
- `--working-dir string` - Sets a custom working directory (default: "./")
- `-w, --workspace-state string` - Defines a version of workspace to push:
- `clean` - pushes the HEAD without local changes
- `staged` - pushes only staged files
- `all` - pushes all staged and unstaged files (default)
- `--zerops-yaml-path string` - Sets a custom path to the zerops.yml file

:::tip
You can also use `zcli push` as shorthand for `zcli service push`.

To avoid specifying `--project-id` and `--service-id` flags repeatedly, you can set default values in a `.zcli.yml` file or via environment variables. See the [Configuration](/references/zcli/configuration) page for details.
:::

### service deploy

Deploys your application to Zerops. Similar to `push` but focuses on deployment only.

```sh
zcli service deploy [service-id-or-name]
```

**Flags:**
Same as [`service push`](#service-push) command.

### service start/stop

Commands to start or stop a Zerops service.

```sh
zcli service start [service-id-or-name] [flags]
zcli service stop [service-id-or-name] [flags]
```

**Flags for both commands:**
- `-P, --project-id string` - Required when you have access to multiple projects
- `-S, --service-id string` - Required when you have access to multiple services

### service delete

Deletes a Zerops service.

```sh
zcli service delete [service-id-or-name] [flags]
```

**Flags:**
- `--confirm` - Skip confirmation prompts for destructive operations
- `-P, --project-id string` - Required when you have access to multiple projects
- `-S, --service-id string` - Required when you have access to multiple services

### service enable-subdomain

Enables access to your service through a Zerops subdomain.

```sh
zcli service enable-subdomain [service-id-or-name] [flags]
```

**Flags:**
- `-P, --project-id string` - Required when you have access to multiple projects
- `-S, --service-id string` - Required when you have access to multiple services

### service log

Gets service runtime or build logs to stdout.

```sh
zcli service log [flags]
```

**Flags:**
- `--follow` - Continuously poll for new log messages
- `--format string` - Log output format (FULL, SHORT, JSON, JSONSTREAM) (default: "FULL")
- `--format-template string` - Custom log format
- `--limit int` - Number of recent log messages to return (1–1000, default: 100)
- `--message-type string` - Select APPLICATION or WEBSERVER log messages (default: "APPLICATION")
- `--minimum-severity string` - Filter by severity level
- `-P, --project-id string` - Required when you have access to multiple projects
- `-S, --service-id string` - Required when you have access to multiple services
- `--show-build-logs` - Show build logs instead of runtime logs

## Utility Commands

### env

Displays global environment variables and their paths.

```sh
zcli env
```

### version

Shows the current zCLI version.

```sh
zcli version
```

### upgrade

Replaces the running zCLI binary in place with a newer release. Downloads the matching asset from GitHub Releases, verifies it against the release's `checksums.txt`, then atomically swaps the binary.

:::note Availability
The `upgrade` command is available in zCLI `v1.1.0` and later. On earlier versions, install the newer release via [install.sh](#downgrading-below-v110) (or your package manager) first.
:::

```sh
zcli upgrade [flags]
```

**Flags:**
- `--check` - Print the current and latest version, then exit without installing. Intended for scripts and package managers.
- `--yes` - Skip the confirmation prompt.
- `--version string` - Install a specific release tag (e.g. `v1.1.0`) instead of the latest. Allows downgrades.
- `--pick-version` - Open an interactive picker listing every release. Mutually exclusive with `--version`.
- `--include-pre-release` - Include pre-release and `-rc` tags in the `--pick-version` picker. Stable releases only by default.
- `--no-cache` - Bypass the on-disk version cache and resolve `latest` directly from the release API. Useful right after a release goes out, before the local cache refreshes.
- `--download-timeout string` - Overall timeout for the binary download as a Go duration (e.g. `5m`, `90s`). `0` disables the timeout. Default `2m`.

**Examples:**
```sh
# Interactive upgrade to the latest release
zcli upgrade

# Unattended upgrade, suitable for scripts
zcli upgrade --yes

# Install a specific tag (and accept downgrade)
zcli upgrade --version v1.1.0 --yes

# Pick from a table of every release
zcli upgrade --pick-version
```

#### Exit codes for `--check`

`zcli upgrade --check` is designed for scripting. It prints `Current:`, `Latest:` (and `Target:` when `--version` is set) on stdout and exits with:

- `0` - up to date.
- `1` - a newer release is available.
- `2` - lookup failed (network, invalid `--version` tag, etc.); the error is on stderr.
- `3` - the resolved target predates `v1.1.0` (the first release that ships `checksums.txt`) and cannot be installed by `zcli upgrade`. Use the install script instead - see below.

#### Package-manager installs

When zCLI is installed through a package manager (`npm`, Homebrew, `nix`, `.deb`), `zcli upgrade` refuses to swap the binary and prints the channel-appropriate command instead - for example `npm install -g @zerops/zcli` or `brew upgrade zcli`. `--check` still works against any install.

#### Downgrading below v1.1.0

Releases before `v1.1.0` don't ship the `checksums.txt` asset that `zcli upgrade` verifies against, so they can only be installed via the install script:

```sh
curl -fsSL https://raw.githubusercontent.com/zeropsio/zcli/main/install.sh | sh -s -- v1.0.67
```

`zcli upgrade --version <old-tag>` and `--pick-version` will print this hint when the chosen target requires the install script.

### show-debug-logs

Displays debug logs for troubleshooting.

```sh
zcli show-debug-logs
```

### support

Displays information about how to contact Zerops support.

```sh
zcli support
```

### completion

Generates shell autocompletion scripts.

```sh
zcli completion {bash|fish|powershell|zsh}
```

**Available Shells:**
- `bash` - Generate an autocompletion script for Bash
- `fish` - Generate an autocompletion script for Fish
- `powershell` - Generate autocompletion script for PowerShell
- `zsh` - Generate an autocompletion script for Zsh

**Example:**
```sh
zcli completion bash > ~/.zerops-completion.bash
echo 'source ~/.zerops-completion.bash' >> ~/.bashrc
```

----------------------------------------

# References > Zcli > Configuration


:::tip Commands Reference
For a comprehensive reference of all available commands, see the [Commands Reference](/references/zcli/commands) page.
:::

## Configuration Overview

You can configure default values for zCLI commands using the following methods (in order of increasing precedence):

1. [Configuration files](#configuration-files)
2. [Environment variables](#environment-variables)
3. [Command-line flags](/references/zcli/commands)

:::note Precedence
This precedence order means that command-line flags will override environment variables, which will override settings in configuration files.
:::

## Configuration Files

zCLI supports configuration via YAML files in the following locations:

1. Global config (user home): `~/.config/zerops/zcli.yaml` or `~/zerops/zcli.yaml`
2. Project-specific config: `./.zcli.yaml` in the root of your application repository

The system first loads the global config file, then merges in the project-specific config if it exists:
- Settings unique to the global config are preserved
- Settings in the project-specific config will override any duplicate keys from the global config

### Configuration File Examples

**Global config file:**
```yaml
# Set organization-wide defaults
workspaceState: "all"
```

**Project-specific file:**
```yaml
# Set project-specific settings
projectId: "your-project-id"
serviceId: "your-service-id"

# Override global workspace state for this project
workspaceState: "clean"
```

## Environment Variables

### Standard Environment Variables

Any flag can be set via environment variables by:
- Using the `ZEROPS_` prefix
- Converting the flag name to uppercase
- Using the full flag name (not shorthand)

**Example:**
```sh
export ZEROPS_WORKSPACESTATE=clean
export ZEROPS_PROJECTID=your-project-id
```

### Special Environment Variables

zCLI also recognizes special environment variables that control its behavior:

#### Terminal Mode Configuration

The `ZEROPS_CLI_TERMINAL_MODE` environment variable controls the interactive mode of zCLI:

```sh
export ZEROPS_CLI_TERMINAL_MODE=<mode>
```

Available modes:
- `auto` (default): Automatically detects if interactive mode can be used and enables it when possible
- `enabled`: Forces interactive mode to be enabled
- `disabled`: Forces interactive mode to be disabled

This setting affects interactive prompts, progress indicators, and other terminal-based user interface elements.

#### Logging Configuration

zCLI maintains a debug log file for the `service push` and `service deploy` commands. This logging feature is designed specifically for debugging purposes. The log file can be found in one of these locations:

**1. Default locations** (checked in this order):
  - `/var/log/zcli.log` (if zCLI has write permissions)
  - `~/.config/zerops/zerops.log` (as fallback)

**2. Custom location** (if specified):
  - Set with `ZEROPS_CLI_LOG_FILE_PATH` environment variable

:::note
zCLI must have write permissions for the specified log file locations.
:::

To enable verbose logging with additional debug information, use the `--verbose` flag (or its shorthand `-v`):
```sh
zcli service push --verbose
zcli service push -v
```

To troubleshoot deployment issues, you can check these log files using commands like `cat` or `tail`:
```sh
# View the entire log file
cat ~/.config/zerops/zerops.log

# Stream new log entries
tail -f ~/.config/zerops/zerops.log
```

----------------------------------------

# References > Zsc


Zerops Setup Control (zsc) is a command-line utility automatically installed in all Zerops containers enabling developers to manage and control container environments directly from within both runtime and build contexts.

Zerops Setup Control provides essential capabilities for container management, including resource scaling, technology installation, and environment configuration.

Zerops Setup Control commands can be executed in two ways:

- **Manual execution**:
  - From the web terminal interface in Zerops GUI
  - Using SSH connections to your containers
- **Automated execution**:
  - As part of your `zerops.yaml` configuration file

## Usage

```sh
zsc <command> [flags]
```

## Commands

---

### help

This command lists available commands and flags on a command by placing `help`, `-h` or `--help` flag after the command.

```sh
zsc help
# or
zsc --help
# or
zsc -h
```

---

### completion

Generate the autocompletion script for zsc for the specified shell.

```sh
zsc completion [command]
```

#### Available sub-commands
- `bash`: Generate the autocompletion script for bash
- `fish`: Generate the autocompletion script for fish
- `powershell`: Generate the autocompletion script for powershell
- `zsh`: Generate the autocompletion script for zsh

#### Available flags
- `-h, --help`: Help for the completion command

---

### backup-create

Creates a backup of any specified stack in your project.

```sh
zsc backup-create <stackName>
```

#### Required parameters
- `<stackName>`: Name of the stack to backup

#### Available flags
- `-h, --help`: Help for the backup-create command

#### Example
```sh
zsc backup-create db
```

---

### cdn

Manages CDN (Content Delivery Network) operations for your Zerops services.

```sh
zsc cdn [command]
```

#### Available sub-commands
- `purge`: Invalidates cached content from the CDN for a specific domain. The purge command allows you to ensure that the most up-to-date content is being served to visitors after making updates to your site.

#### Available flags
- `-h, --help`: Help for the cdn command

#### Examples
```sh
# Purge all CDN cache for a specific domain
zsc cdn purge example.com
# Purge all content using wildcard pattern
zsc cdn purge example.com "/*"
# Purge CDN cache for a specific file (note the $ suffix)
zsc cdn purge example.com "/path/to/my-file$"
# Purge CDN cache for a specific directory
zsc cdn purge example.com "/images/"
```

:::important
- This command must be executed in any container within the project that has the CDN-enabled domain active
- Currently, the purge command only works for the [Static Mode](/features/cdn#static-mode) CDN
:::
---

### crontab

Manages scheduled tasks that are defined in your zerops.yaml configuration.

```sh
zsc crontab [command]
```

#### Available sub-commands
- `list`: List all crontabs defined in zerops.yaml
- `run`: Execute crontab command defined in zerops.yaml

#### Available flags
- `-h, --help`: Help for the crontab command

---

### execOnce

Execute a command exactly once across all containers in a service, preventing duplicate execution in high-availability setups.

```sh
zsc execOnce [flags] <key> -- <command> [args...]
```

#### Required parameters
* `<key>`: A unique identifier for the execution
* `--`: Standard separator indicating the end of options and beginning of the command
* `<command> [args...]`: The actual command to execute and its arguments

#### Available flags
- `-r, --retryUntilSuccessful`: Retry command until it succeeds
- `-v, --verbose`: Verbose output
- `-h, --help`: Help for the execOnce command

#### Behavior
- **On success**: All containers proceed with their tasks
- **On failure**: All containers report the command as failed
- **With --retryUntilSuccessful**: The command is retried on a different container until it succeeds

#### Examples
```sh
# Execute a command once for the entire service stack
zsc execOnce someStaticKey -- /var/www/myBinary some initial command --flag="value" --flag2="value2"

# Run migrations for each new app version deployed to Zerops
zsc execOnce ${ZEROPS_appVersionId} -- php /var/bin/console migrations:continue
```

:::info
This command is ideal for database migrations, initialization scripts, and other operations that should only run once in clustered environments.
:::

---

### fail-me

Deliberately fails the current container for testing purposes.

```sh
zsc fail-me
```

#### Available flags
- `-h, --help`: Help for the fail-me command

---

### install

Run install commands for the specified base technology in your runtime container.

```sh
zsc install <baseName> [flags]
```

#### Required parameters
- `<baseName>`: The technology and version to install - see the full list of supported [base environments](/zerops-yaml/base-list).

#### Available flags
- `--buildBase <string>`: Build base (default "php@8.4")
- `--buildOs <string>`: Build os (default "alpine")
- `-m, --mode <string>`: Mode (default "RUNTIME")
- `--runBase <string>`: Run base (default "php-nginx@8.4")
- `--runOs <string>`: Run os (default "alpine")
- `-h, --help`: Help for the install command

#### Examples
```sh
zsc install rust@1.78
zsc install dotnet@8
zsc install nginx@1.22
```

#### Example usage in `zerops.yaml`
```yaml
zerops:
  - setup: nodejsapp
    build:
      os: ubuntu
      base:
        - nodejs@22
        - python@3.11
    run:
      os: ubuntu
      base: nodejs@22
      prepareCommands:
        - zsc install python@3.11
```

---

### noop

Keep a container alive indefinitely with a non-terminating process.

```sh
zsc noop [flags]
```

#### Available flags
- `-s, --silent`: Disables output to StdOut
- `-h, --help`: Help for the noop command

#### Examples
```sh
zsc noop
zsc noop --silent
```

:::info
The `noop` command is especially useful for:
- Debugging build failures by keeping containers alive for investigation
- Supporting applications that run as background daemons
- Keeping service containers active when your app doesn't have a foreground process
- As a start command in zerops.yaml for services that don't have a natural blocking command
:::

#### Usage in zerops.yaml
```yaml
zerops:
  - setup: myapp
    run:
      start: zsc noop
      ports:
        - port: 8080
          http: true
```

---

### object-storage

Manages object storage operations for backups and restores.

```sh
zsc object-storage [command]
```

#### Available flags
- `-h, --help`: Help for the object-storage command

When using an object storage service, the command requires the following environment variables to be defined:

* `objectstorage_apiUrl` - API URL of the object storage service
* `objectstorage_accessKeyId` - Access key ID for authentication
* `objectstorage_secretAccessKey` - Secret access key for authentication
* `objectstorage_bucketName` - Name of the bucket to use

These environment variables will be automatically available if the object storage service has `envIsolation: none` configured, or if the entire project has `envIsolation: none` set. Otherwise, you need to explicitly reference these environment variables in your `zerops.yaml` file.

#### Sub-commands

#### Common parameters
All sub-commands share these parameters:
- `--storage <string>`: Name of the object storage service
- `--name <string>`: Name of the backup in storage
- `--silent`, `-s`: Suppresses command output (default: false)
- `--no-fail`: Prevents command failure with exit code 1 (default: false)

**list** - Lists all available backups in the specified storage
```sh
zsc object-storage list --storage <storage-name> --name <backup-name>
```

**backup** - Creates a backup of specified directories to object storage
```sh
zsc object-storage backup <directory1> [<directory2>...] --storage <storage-name> --name <backup-name> [options]
```
Arguments:
- `<directory>`: One or more directories to back up (at least one required)

Additional options:
- `--truncate-count <number>`: Number of most recent backups to keep after successful backup (default: 0)
- `-C, --change-directory <directory>`: Change to directory before operation

**restore** - Restores a backup from object storage to specified or original locations
```sh
zsc object-storage restore <directory> --storage <storage-name> --name <backup-name> [options]
```
Arguments:
- `<directory>`: Directory to restore to. If omitted, files are restored to their original locations

Additional options:
- `--dryRun`: Simulates restore operation without performing actual changes
- `--overwrite`: Allows overwriting existing files during restore
- `--index <number>`: Specifies which backup to restore. Non-negative values count from newest (0 = newest, 1 = second newest), negative values count from oldest (-1 = oldest, -2 = second oldest) (default: 0)
- `--ignore-non-existing`: Prevents command failure if backup does not exist
- `--strip-components <number>`: Strip NUMBER leading components from file names on extraction

**truncate** - Removes old backups, keeping only the most recent ones
```sh
zsc object-storage truncate --storage <storage-name> --name <backup-name> [options]
```
Additional options:
- `--dryRun`: Simulates truncate operation without performing actual deletions (default: false)
- `--truncate-count <number>`: Number of most recent backups to keep (default: 5)

#### Examples
```sh
# List all backups
zsc object-storage list --storage objectstorage --name daily-backup

# Create a backup with retention
zsc object-storage backup /var/www --storage objectstorage --name web-backup --truncate-count 5

# Restore with dry run preview
zsc object-storage restore --storage objectstorage --name database-backup --dryRun

# Clean up old backups
zsc object-storage truncate --storage objectstorage --name logs-backup --truncate-count 3
```

#### Example usage in `zerops.yaml`
```yaml
zerops:
  - setup: app
    run:
      initCommands:
        - "zsc object-storage restore --storage objectstorage --name $ZEROPS_StackName --ignore-non-existing ./data/"
      crontab:
        - timing: "*/10 * * * *"
          command: "zsc object-storage backup --storage objectstorage --name $ZEROPS_StackName --truncate-count 5 ./data/"
          allContainers: false
```

---

### resources

Displays the current resource scaling configuration for the container.

```sh
zsc resources
```

#### Available flags
- `-h, --help`: Help for the resources command

#### Example output
```json
{
    "cpuCoreCount": 1,
    "memoryGBytes": 0.25,
    "diskGBytes": 1
}
```

#### Related commands
- `zsc scale`: Dynamically adjust resource allocations

---

### scale

Dynamically adjust CPU or memory resources for the current container for a specified duration.

```sh
zsc scale {cpu|ram} {<value> <duration>|auto}
```

#### Required parameters
- `cpu|ram`: Resource type to scale (either CPU cores or RAM)
- `<value> <duration>` or `auto`: Scale value and duration, or "auto" to disable custom scaling

#### Available flags
- `-h, --help`: Help for the scale command

#### Supported values
- **For RAM**: Value must be suffixed by a unit (KiB, MiB, GiB); number may be a float.
- **For CPU**: Value must not be suffixed; number must be an integer.
- **"auto"**: Disables any custom scaling set via this command and must be used without the duration parameter.
- **"min"** and **"max"**: Set the container to its CURRENT min and max values.
- Numeric values can be prefixed with **"+"** for relative scaling, adding the requested value to currently used resources.
- Duration must be suffixed by a unit (s = seconds, m = minutes, h = hours, d = days) and cannot be less than 10 minutes.

#### Examples
```sh
zsc scale cpu auto
zsc scale cpu 5 1h
zsc scale cpu +2 30m
zsc scale cpu min 10m
zsc scale ram auto
zsc scale ram 5GB 1h
zsc scale ram +2.5GB 600s
zsc scale ram max 10m
```

:::info
- Resource adjustments take effect within approximately 10 seconds
- The container cannot be scaled above or below its max/min resources set in the vertical autoscaling configuration
- If you scale to a value that exceeds the maximum set limit (e.g., 10GB RAM when max is 5GB), the container will only receive the maximum allowed resources
- If service limits are changed while custom scaling is active, the container will automatically adjust to the new boundaries
- If the service auto-scaling configuration is updated, you must call the scale command again to apply custom scaling
:::

:::caution
If there are insufficient resources on the current server, the container might be moved to another node with available resources, which will reset the scale duration.
The container will scale down automatically if resources are not utilized, or if the scale command duration expires.
:::

---

### setSecretEnv

Securely update environment variables containing sensitive information.

```sh
zsc setSecretEnv <key> <content>
```

#### Arguments
- `<key>`: The name of the environment variable to set
- `<content>`: The new value for the variable, or `-` to read from stdin

#### Available flags
- `-h, --help`: Help for the setSecretEnv command

#### Examples
```sh
# Set a secret environment variable directly
zsc setSecretEnv SECRET_KEY "new_value"

# Set a secret environment variable from stdin (useful for multi-line values or piping)
echo "new_value" | zsc setSecretEnv SECRET_KEY -

# Set a secret API key from a file
cat api_key.txt | zsc setSecretEnv API_KEY -
```

:::info
Secret environment variables are encrypted at rest and securely distributed to your containers. Use this command for storing sensitive configuration like API keys, tokens, and passwords.
:::

---

### shared-storage

Manages shared storage volumes for persistent data storage.

```sh
zsc shared-storage [command]
```

#### Available sub-commands
- `mount`: Mounts the shared storage
- `unmount`: Unmounts the shared storage
- `wait`: Waits for readiness of the storage mount

#### Available flags
- `-h, --help`: Help for the shared-storage command

#### Examples
```sh
# View shared-storage help
zsc shared-storage --help

# Mount a shared storage volume
zsc shared-storage mount <storage-name>

# Unmount a shared storage volume
zsc shared-storage unmount <storage-name>

# Wait for a storage mount to be ready
zsc shared-storage wait <storage-name>
```

---

### test

Run diagnostic tests to verify connectivity and service availability.

```sh
zsc test tcp <host>:<port> [flags]
```

#### Required parameters
- `<host>:<port>`: Host and port to test connectivity to

#### Available flags
- `--timeout <duration>`: Maximum test duration (default: 30s)
- `--dialTimeout <duration>`: Single attempt timeout (default: 2s)
- `-4`: Force IPv4
- `-6`: Force IPv6
- `-h, --help`: Help for the test tcp command

#### Example
```sh
# Test TCP connection to a host
zsc test tcp api.zerops:80
zsc test tcp database:5432 --timeout 1m
```

---

### version

Displays the current version of Zsc CLI.

```sh
zsc version
```

#### Available flags
- `-h, --help`: Help for the version command

----------------------------------------

# Ruby > How To > Build Pipeline


Zerops provides a customizable build and runtime environment for your Ruby application.

## Add zerops.yaml to your repository

Start by adding `zerops.yaml` file to the **root of your repository** and modify it to fit your application:

```yaml
zerops:
  # define hostname of your service
  - setup: app
    # ==== how to build your application ====
    build:
      # REQUIRED. Set the base technology for the build environment:
      base: ubuntu/ruby@4.0

      # OPTIONAL. Customise the build environment by installing additional packages
      # or tools to the base build environment.
      # prepareCommands:
      #   - sudo apt-get update
      #   - sudo apt-get install -y some-package

      # OPTIONAL. Set the env variables for the build environment.
      # BUNDLE_PATH makes Bundler install gems into ./vendor/bundle
      # so they can be deployed together with your application.
      envVariables:
        BUNDLE_PATH: vendor/bundle

      # OPTIONAL. Build your application
      buildCommands:
        - bundle install

      # REQUIRED. Select which files / folders to deploy after
      # the build has successfully finished
      deployFiles:
        - ./vendor
        - ./Gemfile
        - ./Gemfile.lock
        - ./config.ru
        - ./src

      # OPTIONAL. Which files / folders you want to cache for the next build.
      # Next builds will be faster when the cache is used.
      cache: vendor

    # ==== how to run your application ====
    run:
      # OPTIONAL. Sets the base technology for the runtime environment:
      base: ubuntu/ruby@4.0

      # OPTIONAL. Sets the internal port(s) your app listens on:
      ports:
        # port number
        - port: 8080

      # OPTIONAL. Customise the runtime Ruby environment by installing additional
      # dependencies to the base Ruby runtime environment.
      # prepareCommands:
      #   - sudo apt-get update
      #   - sudo apt-get install -y some-package

      # OPTIONAL. Run one or more commands each time a new runtime container
      # is started or restarted. These commands are triggered before
      # your Ruby application is started.
      # initCommands:
      #  - rm -rf ./cache

      # OPTIONAL. Set the env variables for the runtime environment.
      envVariables:
        BUNDLE_PATH: vendor/bundle

      # REQUIRED. Your Ruby application start command
      start: bundle exec puma -p 8080 -b tcp://0.0.0.0
```

The top-level element is always `zerops`.

### Setup

The first element `setup` contains the **hostname** of your service. A runtime service with the same hostname must exist in Zerops.
Zerops supports the definition of multiple runtime services in a single `zerops.yaml`. This is useful when you use a monorepo. Just add multiple setup elements in your `zerops.yaml`:

```yaml
zerops:
  # definition for app service
  - setup: app
    # optional
    build: ...
    # optional
    deploy: ...
    # required
    run: ...

  # definition for api service
  - setup: api
    # optional
    build: ...
    # optional
    deploy: ...
    # required
    run: ...
```

Each service configuration contains at least the `run` section. Optional `build` and `deploy` sections can be added to further customize your process.

## Build pipeline configuration

### base

_REQUIRED._ Sets the base technology for the build environment.

Following options are available for Ruby builds:

- `alpine/ruby@4.0`, `ubuntu/ruby@4.0`, `alpine/ruby@latest`, `ubuntu/ruby@latest`
- `alpine/ruby@3.4`, `ubuntu/ruby@3.4`
- `alpine/ruby@3.3`, `ubuntu/ruby@3.3`

The base value always includes the operating system prefix (`ubuntu/` or `alpine/`). The `@latest` tag is an alias that points to Ruby 4.0.

```yaml
zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build:
      # REQUIRED. Sets the base technology for the build environment:
      base: ubuntu/ruby@4.0
      ...
```

<p>
  The base build environment contains {data.ubuntu.default} or {data.alpine.default} (depending on the chosen base prefix), the selected
  major version of Ruby, [Zerops command line tool](/references/cli), `gem`, `bundler` and `git` tools. A full native-extension
  toolchain (gcc, make, libpq-dev, libyaml-dev, libffi-dev, etc.) is included, so gems with C extensions build out of the box.
</p>

:::info
You can change the base environment when you need to. Just simply modify the `zerops.yaml` in your repository.
:::

If you need to install more technologies to the build environment, set multiple values as a yaml array. For example:

```yaml
zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build:
      # REQUIRED. Sets the base technology for the build environment:
      base:
        - ubuntu/ruby@4.0
      prepareCommands:
        - zsc add nodejs@latest
      ...
```

See the full list of supported [build base environments](/zerops-yaml/base-list#runtime-services).

To customise your build environment use the [prepareCommands](#preparecommands) attribute.

:::note
Modifying the base technology will invalidate your build cache. See our [Build Cache Documentation](/features/build-cache) for more details about cache invalidation.
:::

### os

The operating system for the build environment is selected as part of the [base](#base) value. There is no separate `os` attribute for Ruby, choose one of:

- `ubuntu/ruby@4.0`
- `alpine/ruby@4.0`

We are currently using following os version:

- <span>{data.alpine.default}</span>
- <span>{data.ubuntu.default}</span>

:::caution
The os version is fixed and cannot be customised.
:::

:::note
Changing the OS prefix of your base will invalidate your build cache. See our [Build Cache Documentation](/features/build-cache) for details about cache behavior.
:::

### prepareCommands

_OPTIONAL._ Customises the build environment by installing additional dependencies or tools to the base build environment.

The base build environment contains:

- <span>{data.ubuntu.default} or {data.alpine.default} (depending on the chosen base prefix)</span>
- selected version of Ruby defined in the [base](#base) attribute
- [Zerops command line tool](/references/cli)
- `gem`, `bundler` and `git` tools

To install additional packages or tools add one or more prepare commands:

```yaml
zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build:
      # REQUIRED. Set the base technology for the build environment:
      base: ubuntu/ruby@4.0

      # OPTIONAL. Customise the build environment by installing additional packages
      # or tools to the base build environment.
      prepareCommands:
        - sudo apt-get update
        - sudo apt-get install -y some-package
      ...
```

On the `alpine/ruby@4.0` base use `sudo apk add --no-cache some-package` instead.

When the first build is triggered, Zerops will

1. create a build container
2. download your application code from your repository
3. run the prepare commands in the defined order

The application code is available in `/build/source` before the prepare commands are triggered, so you can use any file from your repository in your prepare commands (e.g. a configuration file). The commands themselves run in the `/home/zerops` directory.

:::note
These commands are skipped when using cached environment. Modifying `prepareCommands` will invalidate your build cache. See our [Build Cache Documentation](/features/build-cache) for details about cache invalidation.
:::

#### Command exit code

If any command fails, it returns an exit code other than 0 and the build is canceled. Read the [build log](/ruby/how-to/logs#build-log) to troubleshoot the error. If the command ends successfully, it returns the exit code 0 and Zerops triggers the following command. When all prepare commands are finished, your custom build environment is ready for the build phase.

#### Single or separated shell instances

You can configure your prepare commands to be run in a single shell instance or multiple shell instances. The format is identical to [build commands](#buildcommands).

### buildCommands

_OPTIONAL._ Defines build commands.

```yaml
zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build:
      # REQUIRED. Set the base technology for the build environment:
      base: ubuntu/ruby@4.0

      # OPTIONAL. Set the env variables for the build environment:
      envVariables:
        BUNDLE_PATH: vendor/bundle

      # OPTIONAL. Build your application
      buildCommands:
        - bundle install
      ...
```

Build commands are optional. Zerops triggers each command in the defined order in a dedicated build container, running from the `/build/source` directory.

With `BUNDLE_PATH` set to `vendor/bundle`, Bundler installs your gems into the `vendor` folder inside your project, so they can be deployed together with your application and used at runtime via `bundle exec`.

Before the build commands are triggered the build container contains:

1. base environment defined by the [base](#base) attribute
2. optional customisation of the base environment defined in the [prepareCommands](#preparecommands) attribute
3. your application code

#### Run build commands as a single shell instance

Use following syntax to run all commands in the same environment context. For example, if one command changes the current directory, the next command continues in that directory. When one command creates an environment variable, the next command can access it.

```yaml
buildCommands:
  - |
    bundle install
    bundle exec rake assets:precompile
```

#### Run build commands as a separate shell instances

When the following syntax is used, each command is triggered in a separate environment context. For example, each shell instance starts in the home directory again. When one command creates an environment variable, it won't be available for the next command.

```yaml
buildCommands:
  - bundle install
  - bundle exec rake assets:precompile
```

#### Command exit code

If any command fails, it returns an exit code other than 0 and the build is canceled. Read the [build log](/ruby/how-to/logs#build-log) to troubleshoot the error. If the error log doesn't contain any specific error message, try to run your build with the --verbose option.

```yaml
buildCommands:
  - bundle install --verbose
```

If the command ends successfully, it returns the exit code 0 and Zerops triggers the following command. When all `buildCommands` are finished, the application build is completed and ready for the deploy phase.

### deployFiles

_REQUIRED._ Selects which files or folders will be deployed after the build has successfully finished. To filter out specific files or folders, use [`.deployignore`](#deployignore) file.

```yaml
# REQUIRED. Select which files / folders to deploy after
# the build has successfully finished
deployFiles:
  - ./vendor
  - ./Gemfile
  - ./Gemfile.lock
  - ./config.ru
  - ./src
```

Determines files or folders produced by your build, which should be deployed to your runtime service containers.

The path starts from the **root directory** of your project (the location of `zerops.yaml`). You must enclose the name in quotes if the folder or the file name contains a space.

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

#### Examples

Deploys a folder, and a file from the project root directory:

```yaml
deployFiles:
  - vendor
  - Gemfile
```

Deploys the whole content of the build container:

```yaml
deployFiles: .
```

Deploys a folder, and a file in a defined path:

```yaml
deployFiles:
  - ./path/to/file.txt
  - ./path/to/dir/
```

#### How to use a wildcard in the path

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

Deploys all folders that are located in any path that begins with `/path/to/`

```yaml
deployFiles: ./path/to/~/
```

Deploys all folders that are located in any path that begins with `/path/` and ends with `/to/`

```yaml
deployFiles: ./path/~/to/
```

:::note Example
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 will be cached for the next build.

```yaml
# OPTIONAL. Which files / folders you want to cache for the next build.
# Next builds will be faster when the cache is used.
cache: vendor
```

The cache attribute helps optimize build times by preserving specified files between builds. Caching the `vendor` folder means the next `bundle install` only fetches gems that changed in your `Gemfile.lock`.

The cache attribute supports the [~ wildcard character](#how-to-use-a-wildcard-in-the-path).

Learn more about the [build cache system](/features/build-cache) in Zerops.

### envVariables

_OPTIONAL._ Defines the environment variables for the build environment.

Enter one or more env variables in following format:

```yaml
zerops:
  # define hostname of your service
  - setup: app
    # ==== how to build your application ====
    build:
      base: ubuntu/ruby@4.0
        …

      # OPTIONAL. Defines the env variables for the build environment:
      envVariables:
        BUNDLE_PATH: vendor/bundle
        BUNDLE_WITHOUT: development
```

Read more about [environment variables](/ruby/how-to/env-variables) in Zerops.

## Runtime configuration

### base

_OPTIONAL._ Sets the base technology for the runtime environment.
If you don't specify the `run.base` attribute, Zerops keeps the current Ruby version for your runtime.

Following options are available for Ruby runtimes:

- `alpine/ruby@4.0`, `ubuntu/ruby@4.0`, `alpine/ruby@latest`, `ubuntu/ruby@latest`
- `alpine/ruby@3.4`, `ubuntu/ruby@3.4`
- `alpine/ruby@3.3`, `ubuntu/ruby@3.3`

```yaml
zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build:
      # REQUIRED. Sets the base technology for the build environment:
      base: ubuntu/ruby@4.0
      ...

    # ==== how to run your application ====
    run:
      # OPTIONAL. Sets the base technology for the runtime environment:
      base: ubuntu/ruby@4.0
      ...
```

<p>
  The base runtime environment contains {data.ubuntu.default} or {data.alpine.default} (depending on the chosen base prefix), the
  selected major version of Ruby, Zerops command line tool, `gem`, `bundler` and `git` tools. A full native-extension toolchain
  (gcc, make, libpq-dev, libyaml-dev, libffi-dev, etc.) is included, so gems with C extensions work out of the box.
</p>

:::info
You can change the base environment when you need to. Just simply modify the `zerops.yaml` in your repository.
:::

If you need to install more technologies to the runtime environment, set multiple values as a yaml array. For example:

```yaml
zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build:
      # REQUIRED. Sets the base technology for the build environment:
      base: ubuntu/ruby@4.0
      ...

    # ==== how to run your application ====
    run:
      # OPTIONAL. Sets the base technology for the runtime environment:
      base:
        - ubuntu/ruby@4.0
      prepareCommands:
        - zsc add nodejs@latest
      ...
```

See the full list of supported [run base environments](/zerops-yaml/base-list).

To customise your build environment use the `prepareCommands` attribute.

### os

The operating system for the runtime environment is selected as part of the [base](#base-1) value. There is no separate `os` attribute for Ruby, choose one of:

- `ubuntu/ruby@4.0`
- `alpine/ruby@4.0`

We are currently using following os version:

- <span>{data.alpine.default}</span>
- <span>{data.ubuntu.default}</span>

:::caution
The os version is fixed and cannot be customised.
:::

### ports

_OPTIONAL._ Specifies one or more internal ports on which your application will listen.

Projects in Zerops represent a group of one or more services. Services can be of different types (runtime services, databases, message brokers, object storage, etc.). All services of the same project share a **dedicated private network**. To connect to a service within the same project, just use the service hostname and its internal port.

For example, to connect to a Ruby service with hostname = "app" and port = 8080 from another service of the same project, simply use `app:8080`. Read more about [how to access a Ruby service](/references/networking/internal-access#basic-service-communication).

Each port has following attributes:

| parameter   | description                                                                                                                                                                                                                                                                                                            |
| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| port        | Defines the port number. You can set any port number between _10_ and _65435_. Ports outside this interval are reserved for internal Zerops systems.                                                                                                                                                                   |
| protocol    | **Optional.** Defines the protocol. Allowed values are `TCP` or `UDP`. Default value is `TCP`.                                                                                                                                                                                                                         |
| httpSupport | **Optional.** `httpSupport = true` is the default setting for TCP protocol. Set `httpSupport = false` if a web server isn't running on the port. Zerops uses this information for the configuration of [public access](/features/access). `httpSupport = true` is available only in combination with the TCP protocol. |
| httpSupport | **Optional.** `httpSupport = true` is the default setting for TCP protocol. Set `httpSupport = false` if a web server isn't running on the port. Zerops uses this information for the configuration of [public access](/features/access). `httpSupport = true` is available only in combination with the TCP protocol. |

### prepareCommands

_OPTIONAL._ Customises the Ruby runtime environment by installing additional dependencies or tools to the runtime base environment.

<p>
  The base Ruby environment contains {data.ubuntu.default} or {data.alpine.default} (depending on the chosen base prefix), the selected
  major version of Ruby, [Zerops command line tool](/references/cli) and `gem`, `bundler` and `git` tools. To install
  additional packages or tools add one or more prepare commands:
</p>

```yaml
zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build:
      ...

    # ==== how to run your application ====
    run:
      # OPTIONAL. Customise the runtime environment by installing additional packages
      # or tools to the base Ruby runtime environment.
      prepareCommands:
        - sudo apt-get update
        - sudo apt-get install -y some-package
      ...
```

On the `alpine/ruby@4.0` base use `sudo apk add --no-cache some-package` instead.

When the first deploy with a defined prepare attribute is triggered, Zerops will

1. create a prepare runtime container
2. optionally: [copy selected folders or files from your build container](#copy-folders-or-files-from-your-build-container)
3. run the `prepareCommands` commands in the defined order

:::note
`run.prepareCommands` run in the `/home/zerops` directory.
:::

#### Command exit code

If any command fails, it returns an exit code other than 0 and the deploy is canceled. Read the [prepare runtime log](/ruby/how-to/logs#prepare-runtime-log) to troubleshoot the error. If the command ends successfully, it returns the exit code 0 and Zerops triggers the following command. When all `prepareCommands` commands are finished, your custom runtime environment is ready for the deploy phase.

#### Cache of your custom runtime environment

Some packages or tools can take a long time to install. Therefore, Zerops caches your custom runtime environment after the installation of your custom packages or tools is completed. When the second or following deploy is triggered, Zerops will use the custom runtime cache from the previous deploy if following conditions are met:

1. Content of the [build.addToRunPrepare](#copy-folders-or-files-from-your-build-container) and `run.prepareCommands` attributes didn't change from the previous deploy
2. The custom runtime cache wasn't invalidated in the Zerops GUI.

To invalidate the custom runtime cache go to `yyy`

When the custom runtime cache is used, Zerops doesn't create a prepare runtime container and executes the deployment of your application directly.

#### Single or separated shell instances

You can configure your prepare commands to be run in a single shell instance or multiple shell instances. The format is identical to [build commands](#buildcommands).

### Copy folders or files from your build container

<p>
  The prepare runtime container contains {data.ubuntu.default} or {data.alpine.default} (depending on the chosen base prefix), the
  selected major version of Ruby, [Zerops command line tool](/references/cli) and `gem`, `bundler` and `git` tools.
</p>

The prepare runtime container does not contain your application code nor the built application. If you need to copy some folders or files from the build container to the runtime container (e.g. a configuration file) use the `addToRunPrepare` attribute in the [build section](#build-pipeline-configuration).

```yaml
zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build:
      ...
      addToRunPrepare: ./runtime-config.yaml

    # ==== how to run your application ====
    run:
      # OPTIONAL. Customise the runtime environment by installing additional packages
      # or tools to the base Ruby runtime environment.
      prepareCommands:
        - sudo apt-get update
        - sudo apt-get install -y some-package
      ...
```

In the example above Zerops will copy the `runtime-config.yaml` file from your build container **after the build has finished** into the new **prepare runtime** container. The copied files and folders will be available in the `/home/zerops` folder in the new prepare runtime container before the prepare commands are triggered.

### initCommands

_OPTIONAL._ Defines one or more commands to be run each time a new runtime container is started or a container is restarted.

```yaml
zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build: ...

    # ==== how to run your application ====
    run:
      # OPTIONAL. Run one or more commands each time a new runtime container
      # is started or restarted. These commands are triggered before
      # your Ruby application is started.
      initCommands:
        - rm -rf ./cache
```

These commands are triggered in the runtime container before your Ruby application is started via the [start command](#start).

:::note
`run.initCommands` run in the `/var/www` directory.
:::

Use init commands to clean or initialise your application cache or similar operations.

:::caution
The init commands will delay the start of your application each time a new runtime container is started (including the horizontal [scaling](/ruby/how-to/scaling) or when a runtime container is restarted).

Do not use the init commands for customising your runtime environment. Use the [run:prepareCommands](#preparecommands-1) attribute instead.
:::

#### Command exit code

If any of the `initCommands` fails, it returns an exit code other than 0, but deploy is **not** canceled. After all init commands are finished, regardless of the status code, the application is started. Read the [runtime log](/ruby/how-to/logs#runtime-log) to troubleshoot the error.

#### Single or separated shell instances

You can configure your `initCommands` to be run in a single shell instance or multiple shell instances. The format is identical to [build commands](#buildcommands).

### envVariables

_OPTIONAL._ Defines the environment variables for the runtime environment.

Enter one or more env variables in following format:

```yaml
zerops:
  # define hostname of your service
  - setup: app
    # ==== how to run your application ====
    run:
      # OPTIONAL. Defines the env variables for the runtime environment:
      envVariables:
        RACK_ENV: production
        BUNDLE_PATH: vendor/bundle
        DB_NAME: db
        DB_HOST: db
        DB_USER: db
        DB_PASS: ${db_password}
```

Read more about [environment variables](/ruby/how-to/env-variables) in Zerops.

### start

_REQUIRED._ Defines the start command for your Ruby application.

```yaml
zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build: ...

    # ==== how to run your application ====
    run:
      # REQUIRED. Your Ruby application start command
      start: bundle exec puma -p 8080 -b tcp://0.0.0.0
```

We recommend starting your Ruby application via `bundle exec`, so the gems vendored into `vendor/bundle` during the build are used at runtime. The `-b tcp://0.0.0.0` option makes Puma bind to all interfaces, not just localhost.

### health check

_OPTIONAL._ Defines a health check.

`healthCheck` requires either one `httpGet` object or one `exec` object.

#### httpGet

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

Following attributes are available:

<table className="w-full my-1.5">
  <thead>
    <tr>
      <th className="w-fit whitespace-nowrap">Parameter</th>
      <th className="w-fit whitespace-nowrap">Description</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td className="w-fit whitespace-nowrap font-semibold">port</td>
      <td>Defines the port of the HTTP GET request.
The readiness check will trigger a GET request on <code>{'http://127.0.0.1:{port}/{path}'}</code></td>
    </tr>
    <tr>
      <td className="w-fit whitespace-nowrap font-semibold">path</td>
      <td>Defines the URL path of the HTTP GET request.
The readiness check will trigger a GET request on <code>{'http://127.0.0.1:{port}/{path}'}</code></td>
    </tr>
    <tr>
      <td className="w-fit whitespace-nowrap font-semibold">host</td>
      <td><strong>Optional.</strong> The readiness check is triggered from inside of your runtime container so it always uses the localhost <code>127.0.0.1</code>. If you need to add a <code>host</code> to the request header, specify it in the <code>host</code> attribute.</td>
    </tr>
    <tr>
      <td className="w-fit whitespace-nowrap font-semibold">scheme</td>
      <td><strong>Optional.</strong> The readiness check is triggered from inside of your runtime container so no https is required.
If your application requires a https request, set <code>scheme: https</code></td>
    </tr>
  </tbody>
</table>

**Example:**

```yaml
zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build: ...

    # ==== how to run your application ====
    run:
      # REQUIRED. Your Ruby application start command
      start: bundle exec puma -p 8080 -b tcp://0.0.0.0

      # OPTIONAL. Define a health check with a HTTP GET request option.
      # Configures the check on http://127.0.0.1:80/status
      healthCheck:
        httpGet:
          port: 80
          path: /status
```

#### exec

Configures the health check to run a local command.
Following attributes are available:

| Parameter   | Description                                                                                                                                                                                                                                                                                                                     |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **command** | Defines a local command to be run.
The command has access to the same [environment variables](/ruby/how-to/create#set-secret-environment-variables) as your Ruby application.
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 below. |

**Example:**

```yaml
zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build: ...

    # ==== how to run your application ====
    run:
      # REQUIRED. Your Ruby application start command
      start: bundle exec puma -p 8080 -b tcp://0.0.0.0

      # OPTIONAL. Define a health check with a shell command.
      healthCheck:
        exec:
          command: |
            touch grass
            rm -rf life
            mv /outside/user /home/user
```

### crontab

_OPTIONAL._ Defines cron jobs.

Setup cron jobs in the following format:

```yaml
zerops:
  # define hostname of your service
  - setup: app

    # ==== how to run your application ====
    run:
      crontab:
        # REQUIRED. Sets the command to execute:
        - command: ""
        # REQUIRED. Sets the interval time to execute:
          timing: "0 * * * *"
```

Read more about setting up [cron](/zerops-yaml/cron) in Zerops.

## Deploy configuration

### readiness check

_OPTIONAL._ Defines a readiness check. Read more about how the [readiness check works](/ruby/how-to/deploy-process#readiness-checks) in Zerops.

`readinessCheck` requires either one `httpGet` object or one `exec` object.

#### httpGet

Configures the readiness check to request a local URL using a http GET method.

Following attributes are available:

<table className="w-full my-1.5">
  <thead>
    <tr>
      <th className="w-fit whitespace-nowrap">Parameter</th>
      <th className="w-fit whitespace-nowrap">Description</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td className="w-fit whitespace-nowrap font-semibold">port</td>
      <td>Defines the port of the HTTP GET request.
The readiness check will trigger a GET request on <code>{'http://127.0.0.1:{port}/{path}'}</code></td>
    </tr>
    <tr>
      <td className="w-fit whitespace-nowrap font-semibold">path</td>
      <td>Defines the URL path of the HTTP GET request.
The readiness check will trigger a GET request on <code>{'http://127.0.0.1:{port}/{path}'}</code></td>
    </tr>
    <tr>
      <td className="w-fit whitespace-nowrap font-semibold">host</td>
      <td><strong>Optional.</strong> The readiness check is triggered from inside of your runtime container so it always uses the localhost <code>127.0.0.1</code>. If you need to add a <code>host</code> to the request header, specify it in the <code>host</code> attribute.</td>
    </tr>
    <tr>
      <td className="w-fit whitespace-nowrap font-semibold">scheme</td>
      <td><strong>Optional.</strong> The readiness check is triggered from inside of your runtime container so no https is required.
If your application requires a https request, set <code>scheme: https</code></td>
    </tr>
  </tbody>
</table>

**Example:**

```yaml
zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build: ...

    # ==== how to deploy your application ====
    deploy:
      # OPTIONAL. Define a readiness check with a HTTP GET request option.
      # Configures the check on http://127.0.0.1:80/status
      readinessCheck:
        httpGet:
          port: 80
          path: /status

    # ==== how to run your application ====
    run: ...
```

Read more about how the [readiness check works](/ruby/how-to/deploy-process#readiness-checks) in Zerops.

#### exec

Configures the readiness check to run a local command.
Following attributes are available:

| Parameter   | Description                                                                                                                                                                                                                                                                                                                     |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **command** | Defines a local command to be run.
The command has access to the same [environment variables](/ruby/how-to/create#set-secret-environment-variables) as your Ruby application.
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 below. |

**Example:**

```yaml
zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build: ...

    # ==== how to deploy your application ====
    deploy:
      # OPTIONAL. Define a readiness check with a HTTP GET request option.
      # Configures the check on http://127.0.0.1:80/status
      readinessCheck:
        exec:
          command: |
            touch grass
            rm -rf life
            mv /outside/user /home/user
```

Read more about how the [readiness check works](/ruby/how-to/deploy-process#readiness-checks) in Zerops.


----------------------------------------

# Ruby > How To > Build Process



----------------------------------------

# Ruby > How To > Controls



----------------------------------------

# Ruby > How To > Create


Zerops provides a powerful Ruby runtime service with extensive build support. The Ruby runtime is highly scalable and customizable to suit your development and production needs. With just a few clicks or commands, you can have a production-ready Ruby environment up and running in no time.

## Create a Ruby service using Zerops GUI

First, set up a project in the Zerops GUI. Then go to the project dashboard page and choose **Add new service** in the left menu under the **Services** section. Pick **Ruby** from the list of runtime services, choose a version and operating system (Ubuntu or Alpine), set a hostname and confirm to create the service.

### Choose a Ruby version

Zerops supports the following Ruby versions:

The service type is always specified together with the operating system, e.g. `ubuntu/ruby@4.0` or `alpine/ruby@4.0`. The `@latest` tag (e.g. `ubuntu/ruby@latest`) is an alias that points to Ruby 4.0.

The Ruby runtime images include a full native-extension toolchain (gcc, make, libpq-dev, libyaml-dev, libffi-dev, etc.), so gems with C extensions build out of the box.

:::info
You can easily [upgrade](/ruby/how-to/upgrade) the major version at any time later.
:::

### Set a hostname

Enter a unique service identifier like "app", "cache", "gui", etc. Duplicate services with the same name within the same project are not allowed.

#### Limitations:

- Maximum 25 characters
- Must contain only lowercase ASCII letters (a-z) or numbers (0-9)

:::caution
The hostname is fixed after the service is created and cannot be changed later.
:::

### Set secret environment variables

Add environment variables with sensitive data, such as passwords, tokens, salts, certificates, etc. These will be securely saved inside Zerops and added to your runtime service upon start.

Setting secret environment variables is optional. You can always set them later in the Zerops GUI.

Read more about the [different types of environment variables](/ruby/how-to/env-variables#service-env-variables) in Zerops.

## Create a Ruby service using zCLI

zCLI is the Zerops command-line tool. To create a new Ruby service via the command line, follow these steps:

1. [Install & setup zCLI](/references/cli)
2. [Create a project description file](/ruby/how-to/create#create-a-project-description-file)
3. [Create a project with a Ruby and PostgreSQL service](#full-example)

### Create a project description file

Zerops uses a YAML format to describe the project infrastructure.

#### Basic example:

Create a directory called `my-project`. Inside the `my-project` directory, create a `description.yaml` file with the following content:
```yaml
# basic project data
project:
  # project name
  name: my-project
# array of project services
services:
  - # service name
    hostname: app
    # service type and version number in {os}/ruby@{version} format
    type: ubuntu/ruby@4.0
    # defines the minimum number of containers for horizontal autoscaling
    minContainers: 1
    # defines the maximum number of containers for horizontal autoscaling. Max value = 6.
    maxContainers: 6
    # optional: create env variables
    envSecrets:
      S3_ACCESS_KEY_ID: 'P8cX1vVVb'
      S3_ACCESS_SECRET: 'ogFthuiLYki8XoL73opSCQ'
```

The yaml file describes your future project infrastructure. The project will contain one Ruby version 4.0 service with default [auto scaling](/ruby/how-to/scaling) configuration. Hostname will be set to "app", the internal port(s) the service listens on will be defined later in the [zerops.yaml](/ruby/how-to/build-pipeline#ports). Following secret env variables will be configured:

```env
S3_ACCESS_KEY_ID="P8cX1vVVb"
S3_ACCESS_SECRET="ogFthuiLYki8XoL73opSCQ"
```

#### Full example:

Create a directory my-project. Create an description.yaml file inside the my-project directory with following content:

```yaml
# basic project data
project:
  # project name
  name: my-project
  # optional: project description
  description: A project with a Ruby and PostgreSQL database
  # optional: project tags
  tags:
    - DEMO
    - ZEROPS
# array of project services
services:
  - # service name
    hostname: app
    # service type and version number in {os}/ruby@{version} format
    type: ubuntu/ruby@4.0
    # optional: vertical auto scaling customization
    verticalAutoscaling:
      cpuMode: DEDICATED
      minCpu: 2
      maxCpu: 5
      minRam: 2
      maxRam: 24
      minDisk: 6
      maxDisk: 50
      startCpuCoreCount: 3
      minFreeRamGB: 0.5
      minFreeRamPercent: 20
    # defines the minimum number of containers for horizontal autoscaling. Max value = 6.
    minContainers: 2
    # defines the maximum number of containers for horizontal autoscaling. Max value = 6.
    maxContainers: 4
    # optional: create env variables
    envSecrets:
      S3_ACCESS_KEY_ID: 'P8cX1vVVb'
      S3_ACCESS_SECRET: 'ogFthuiLYki8XoL73opSCQ'
  - # second service hostname
    hostname: db
    # service type and version number in postgresql@{version} format
    type: postgresql@16
    # mode of operation "HA"/"non_HA"
    mode: NON_HA
```

The yaml file describes your future project infrastructure. The project will contain a Ruby service and a [PostgreSQL](/postgresql/overview) service.

Ruby service with "app" hostname, the internal port(s) the service listens on will be defined later in the [zerops.yaml](/ruby/how-to/build-pipeline#ports). Ruby service will run on version 4.0 with a custom vertical and horizontal scaling. Following secret env variables will be configured:

```env
S3_ACCESS_KEY_ID="P8cX1vVVb"
S3_ACCESS_SECRET="ogFthuiLYki8XoL73opSCQ"
```

The hostname of the PostgreSQL service will be set to "db". The [single container](/features/scaling#single-container-mode)(/features/scaling#deployment-modes-databases-and-shared-storage) mode will be chosen and the default auto [scaling configuration](/postgresql/how-to/scale#configure-scaling) will be set.

#### Description of description.yaml parameters

The `project:` section is required. Only one project can be defined.

| Parameter       | Description                                                                                                                     | Limitations             |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------- | ----------------------- |
| **name**        | The name of the new project. Duplicates are allowed.                                                                            |                         |
| **description** | **Optional.** Description of the new project.                                                                                   | Maximum 255 characters. |
| **tags**        | **Optional.** One or more string tags. Tags do not have a functional meaning, they only provide better orientation in projects. |
| **tags**        | **Optional.** One or more string tags. Tags do not have a functional meaning, they only provide better orientation in projects. |

At least one service in `services:` section is required. You can create a project with multiple services. The example above contains Ruby and PostgreSQL services but you can create a `description.yaml` with your own combination of [services](/features/infrastructure).

<table className="w-full my-1.5">
  <thead>
    <tr>
      <th className="w-fit">Parameter</th>
      <th className="w-fit">Description</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td className="w-fit">
        <b>hostname</b>
      </td>
      <td className="w-fit">
        The unique service identifier.
        <ul>
        <li>duplicate services with the same name in the same project are forbidden</li>
        <li>maximum 25 characters</li>
        <li>must contain only lowercase ASCII letters (a-z) or numbers (0-9)</li>
        </ul>
      </td>
    </tr>
    <tr>
      <td className="w-fit">
        <b>type</b>
      </td>
      <td className="w-fit">
        Specifies the service type and version.

        See what [Ruby service types](/references/import-yaml/type-list#runtime-services) are currently supported.
      </td>
    </tr>
    <tr>
      <td className="w-fit">
        <b>verticalAutoscaling</b>
      </td>
      <td className="w-fit">
        <b>Optional.</b> Defines [custom vertical auto scaling parameters](/ruby/how-to/create#set-auto-scaling-configuration).

        All verticalAutoscaling attributes are optional. Not specified
        attributes will be set to their default values.
      </td>
    </tr>
    <tr>
      <td className="w-fit">
        <b> - cpuMode</b>
      </td>
      <td className="w-fit">
        <b>Optional.</b> Accepts `SHARED`, `DEDICATED` values. Default is `SHARED`
      </td>
    </tr>
    <tr>
      <td className="w-fit">
        <b> - minCpu/maxCpu</b>
      </td>
      <td className="w-fit">
        <b>Optional.</b> Set the minCpu or maxCpu in CPU cores (integer).
      </td>
    </tr>
    <tr>
      <td className="w-fit">
        <b> - minRam/maxRam</b>
      </td>
      <td className="w-fit">
        <b>Optional.</b> Set the minRam or maxRam in GB (float).
      </td>
    </tr>
    <tr>
      <td className="w-fit">
        <b> - minDisk/maxDisk</b>
      </td>
      <td className="w-fit">
        <b>Optional.</b> Set the minDisk or maxDisk in GB (float).
      </td>
    </tr>
    <tr>
      <td className="w-fit">
        <b>minContainers</b>
      </td>
      <td className="w-fit">
        <b>Optional.</b> Default = 1. Defines the minimum number of containers
        for [horizontal autoscaling](/ruby/how-to/create#horizontal-auto-scaling).

        <b>Limitations:</b>

        Current maximum value = 10.
      </td>
    </tr>
    <tr>
      <td className="w-fit">
        <b>maxContainers</b>
      </td>
      <td className="w-fit">
        Defines the maximum number of containers for [horizontal autoscaling](/ruby/how-to/create#horizontal-auto-scaling).

        <b>Limitations:</b>

        Current maximum value = 10.
      </td>
    </tr>
    <tr>
      <td className="w-fit">
        <b>envSecrets</b>
      </td>
      <td className="w-fit">
        <b>Optional.</b> Defines one or more secret env variables as a key value
        map. See env variable [restrictions](/ruby/how-to/env-variables#env-variable-restrictions).
      </td>
    </tr>
  </tbody>
</table>

### Create a project based on the description.yaml

When you have your `description.yaml` ready, use the `zcli project project-import` command to create a new project and the service infrastructure.

```sh
Usage:
  zcli project project-import importYamlPath [flags]

Flags:
  -h, --help                Help for the project import command.
      --org-id string        If you have access to more than one organization, you must specify the org ID for which the
                            project is to be created.
      --working-dir string   Sets a custom working directory. Default working directory is the current directory. (default "./")
```

Zerops will create a project and one or more services based on the `description.yaml` content.

Maximum size of the `description.yaml` file is 100 kB.

You don't specify the project name in the `zcli project project-import` command, because the project name is defined in the `description.yaml`.

If you have access to more than one client, you must specify the client ID for which the project is to be created. The `clientID` is located in the Zerops GUI under the client name on the project dashboard page.

### Add Ruby service to an existing project

#### Example:

Create a directory `my-project` if it doesn't exist. Create an `import.yaml` file inside the `my-project` directory with following content:

```yaml
# basic project data
project:
  # project name
  name: my-project
# array of project services
services:
  - # service name
    hostname: app
    # service type and version number in {os}/ruby@{version} format
    type: ubuntu/ruby@4.0
    # defines the minimum number of containers for horizontal autoscaling
    minContainers: 1
    # defines the maximum number of containers for horizontal autoscaling. Max value = 6.
    maxContainers: 6
    # optional: create env variables
    envSecrets:
      S3_ACCESS_KEY_ID: 'P8cX1vVVb'
      S3_ACCESS_SECRET: 'ogFthuiLYki8XoL73opSCQ'
```

The yaml file describes the list of one or more services that you want to add to your existing project. In the example above, one Ruby service version 4.0 with default [auto scaling](/ruby/how-to/scaling) configuration will be added to your project. Hostname of the new service will be set to `app`. Following secret env variables will be configured:

```env
S3_ACCESS_KEY_ID="P8cX1vVVb"
S3_ACCESS_SECRET="ogFthuiLYki8XoL73opSCQ"
```

The content of the `services:` section of `import.yaml` is identical to the project description file. The `import.yaml` never contains the `project:` section because the project already exists.

When you have your `import.yaml` ready, use the `zcli project service-import` command to add one or more services to your existing Zerops project.

```sh
Usage:
  zcli project service-import importYamlPath [flags]

Flags:
  -h, --help                Help for the project service import command.
  -P, --project-id string   If you have access to more than one project, you must specify the project ID for which the
                           command is to be executed.
```

zCLI commands are interactive, when you press enter after `zcli project service-import importYamlPath`, you will be given a list of your projects to choose from.

Maximum size of the import.yaml file is 100 kB.


----------------------------------------

# Ruby > How To > Customize Runtime



----------------------------------------

# Ruby > How To > Deploy Process



----------------------------------------

# Ruby > How To > Env Variables



----------------------------------------

# Ruby > How To > Filebrowser



----------------------------------------

# Ruby > How To > Logs



----------------------------------------

# Ruby > How To > Scaling



----------------------------------------

# Ruby > How To > Shared Storage



----------------------------------------

# Ruby > How To > Trigger Pipeline



----------------------------------------

# Ruby > How To > Upgrade



----------------------------------------

# Ruby > Overview


[Ruby ↗](https://www.ruby-lang.org/en/) is a dynamic, object-oriented programming language with a focus on simplicity and programmer happiness.

As said, there is no need for coding yet, we have created a [Github repository ↗](https://github.com/zerops-recipe-apps/ruby-hello-world-app), a **_recipe_**, containing a simple Ruby (Sinatra) web application served by Puma. The repo will be used as a source from which the app will be built.

1. Log in/sign up to [Zerops GUI ↗](https://app.zerops.io)

2. In the **Projects** box click on **Import a project** and paste in the following YAML config:

```yaml
project:
  name: recipe-ruby
  tags:
    - zerops-recipe

services:
  - hostname: app
    type: ubuntu/ruby@4.0
    zeropsSetup: prod
    enableSubdomainAccess: true
    buildFromGit: https://github.com/zerops-recipe-apps/ruby-hello-world-app

  - hostname: db
    type: postgresql@16
    mode: NON_HA
    priority: 1
```

3. Click on **Import project** and wait until all pipelines have finished.

**That's it, your application is now up and running! :star: Let's check it works:**

1. A _subdomain_ should have been enabled and visible in the project's **IP addressed & Public Routing Overview** box. Its format should look similar to this `https://app-808-8080.prg1.zerops.app`.
2. Click or the `subdomain` URL to open it in a browser and you should see

```
{"type":"ruby","greeting":"Hello from Zerops!","status":{"database":"OK"}}
```

:::tip
Do you have any questions? Check the step-by-step tutorial, browse the documentation and join our **[Discord](https://discord.com/invite/WDvCZ54)** community to get help from our team and other members.
:::

## How to start

It doesn't matter whether it's your first curious introduction to Zerops, you have already mastered the basics and are looking for a tiny detail or inspiration. Below, choose a section that fits your needs:

- [Care for details?](/ruby/how-to/create) — Dive in all Zerops has to offer for your Ruby application.
- [Ruby recipes](https://github.com/zeropsio?q=ruby&type=all&language=&sort=) — Get inspired by already existing repositories, ready to be imported to Zerops.

## Feature Highlights

- [Create Ruby service](/ruby/how-to/create) — Start with creating a Ruby service using GUI or zCLI.
- [Zerops.yaml](/ruby/how-to/build-pipeline#add-zeropsyaml-to-your-repository) — See a full example of zerops.yaml file to create your own app.
- [Scaling configuration](/ruby/how-to/scaling) — Set up scaling of your Ruby application so that it runs smoothly while using only necessary resources.

{" "}

- [Customize build environment](/ruby/how-to/build-process#customize-build-environment)
- [Customize runtime environment](/ruby/how-to/customize-runtime)

## When in doubt, reach out

Don't know how to start or got stuck during the process? You might not be the first one, visit the FAQ section to find out.

In case you haven't found an answer (and also if you have), we and our community are looking forward to hearing from you on Discord.

Have you build something that others might find useful? Don't hesitate to share your knowledge!

- [FAQ](/ruby/faq) — Most common questions in one place.
- [Discord](https://discord.com/invite/WDvCZ54) — Join our core team and Zerops community on Discord. Ask questions and share your tips with other members.

## Popular Guides

- [zCLI](/references/cli) — Get even more out of Zerops with the zCLI command line tool.
- [Zerops VPN](/references/networking/vpn) — Connect to your services easily with Zerops VPN.


----------------------------------------

# Rust > How To > Build Pipeline


Zerops provides a customizable build and runtime environment for your Rust application.

## Add zerops.yaml to your repository

Start by adding `zerops.yaml` file to the **root of your repository** and modify it to fit your application:

```yaml
zerops:
  # define hostname of your service
  - setup: app
    # ==== how to build your application ====
    build:
      # REQUIRED. Set the base technology for the build environment:
      base: rust@latest

      # OPTIONAL. Set the operating system for the build environment.
      # os: ubuntu

      # OPTIONAL. Customize the build environment by installing additional packages
      # or tools to the base build environment.
      # prepareCommands:
      #   - sudo apt-get something
      #   - curl something else

      # OPTIONAL. Build your application
      buildCommands:
        - cargo b --release

      # REQUIRED. Select which files / folders to deploy after
      # the build has successfully finished
      deployFiles:
        - target/release/~app

      # OPTIONAL. Which files / folders you want to cache for the next build.
      # Next builds will be faster when the cache is used.
      # cache: file.txt

    # ==== how to run your application ====
    run:
      # OPTIONAL. Sets the base technology for the runtime environment:
      base: rust@latest

      # OPTIONAL. Sets the internal port(s) your app listens on:
      ports:
        # port number
        - port: 8080

      # OPTIONAL. Customize the runtime Rust environment by installing additional
      # dependencies to the base Rust runtime environment.
      # prepareCommands:
      #   - sudo apt-get something
      #   - curl something else

      # OPTIONAL. Run one or more commands each time a new runtime container
      # is started or restarted. These commands are triggered before
      # your Rust application is started.
      # initCommands:
      #  - rm -rf ./cache

      # REQUIRED. Your Rust application start command
      start: ./app
```

The top-level element is always `zerops`.

### Setup

The first element `setup` contains the **hostname** of your service. A runtime service with the same hostname must exist in Zerops.
Zerops supports the definition of multiple runtime services in a single `zerops.yaml`. This is useful when you use a monorepo. Just add multiple setup elements in your `zerops.yaml`:

```yaml
zerops:
  # definition for app service
  - setup: app
    # optional
    build: ...
    # optional
    deploy: ...
    # required
    run: ...

  # definition for api service
  - setup: api
    # optional
    build: ...
    # optional
    deploy: ...
    # required
    run: ...
```

Each service configuration contains at least the `run` section. Optional `build` and `deploy` sections can be added to further customize your process.

## Build pipeline configuration

### base

_REQUIRED._ Sets the base technology for the build environment.

Following options are available for Rust builds:

- `rust@1`, `rust@latest`, `rust@stable`
- `rust@1.86`
- `rust@1.80`
- `rust@1.78`
- `rust@nightly`

```yaml
zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build:
      # REQUIRED. Sets the base technology for the build environment:
      base: rust@latest
      ...
```

<p>
  The base build environment contains {data.alpine.default}, the selected
  major version of Rust, [Zerops command line tool](/references/cli), `npm` , `yarn`, `git` and `npx` tools.
</p>

:::info
You can change the base environment when you need to. Just simply modify the `zerops.yaml` in your repository.
:::

If you need to install more technologies to the build environment, set multiple values as a yaml array. For example:

```yaml
zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build:
      # REQUIRED. Sets the base technology for the build environment:
      base:
        - rust@latest
      prepareCommands:
        - zsc add go@latest
      ...
```

See the full list of supported [build base environments](/zerops-yaml/base-list#runtime-services).

To customize your build environment use the [prepareCommands](#preparecommands) attribute.

:::note
Modifying the base technology will invalidate your build cache. See our [Build Cache Documentation](/features/build-cache) for more details about cache invalidation.
:::

### os

_OPTIONAL._ Sets the operating system for the build environment.

Following options are available:

- `alpine`
- `ubuntu`

Default value is `alpine`.

We are currently using following os version:

- <span>{data.alpine.default}</span>
- <span>{data.ubuntu.default}</span>

:::caution
The os version is fixed and cannot be customized.
:::

:::note
Modifying the OS will invalidate your build cache. See our [Build Cache Documentation](/features/build-cache) for more details about cache invalidation.
:::

### prepareCommands

_OPTIONAL._ Customizes the build environment by installing additional dependencies or tools to the base build environment.

The base build environment contains:

- <span>{data.alpine.default}</span>
- selected version of Rust defined in the [base](#base) attribute
- [Zerops command line tool](/references/cli)
- `npm`, `yarn`, `git` and `npx` tools

To install additional packages or tools add one or more prepare commands:

```yaml
zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build:
      # REQUIRED. Set the base technology for the build environment:
      base: rust@latest

      # OPTIONAL. Customize the build environment by installing additional packages
      # or tools to the base build environment.
      prepareCommands:
        - cargo b --release
      ...
```

When the first build is triggered, Zerops will

1. create a build container
2. download your application code from your repository
3. run the prepare commands in the defined order

The application code is available in `/build/source` before the prepare commands are triggered, so you can use any file from your repository in your prepare commands (e.g. a configuration file). The commands themselves run in the `/home/zerops` directory.

:::note
These commands are skipped when using cached environment. Modifying `prepareCommands` will invalidate your build cache. See our [Build Cache Documentation](/features/build-cache) for details about cache invalidation.
:::

#### Command exit code

If any command fails, it returns an exit code other than 0 and the build is canceled. Read the [build log](/rust/how-to/logs#build-log) to troubleshoot the error. If the command ends successfully, it returns the exit code 0 and Zerops triggers the following command. When all prepare commands are finished, your custom build environment is ready for the build phase.

#### Single or separated shell instances

You can configure your prepare commands to be run in a single shell instance or multiple shell instances. The format is identical to [build commands](#buildcommands).

### buildCommands

_OPTIONAL._ Defines build commands.

```yaml
zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build:
      # REQUIRED. Set the base technology for the build environment:
      base: rust@latest

      # OPTIONAL. Build your application
      buildCommands:
        - cargo b --release
      ...
```

Build commands are optional. Zerops triggers each command in the defined order in a dedicated build container, running from the `/build/source` directory.

Before the build commands are triggered the build container contains:

1. base environment defined by the [base](#base) attribute
2. optional customisation of the base environment defined in the [prepareCommands](#preparecommands) attribute
3. your application code

#### Run build commands as a single shell instance

Use following syntax to run all commands in the same environment context. For example, if one command changes the current directory, the next command continues in that directory. When one command creates an environment variable, the next command can access it.

```yaml
buildCommands:
  - |
    cargo b --release
```

#### Run build commands as a separate shell instances

When the following syntax is used, each command is triggered in a separate environment context. For example, each shell instance starts in the home directory again. When one command creates an environment variable, it won't be available for the next command.

```yaml
buildCommands:
  - cargo b --release
```

#### Command exit code

If any command fails, it returns an exit code other than 0 and the build is canceled. Read the [build log](/rust/how-to/logs#build-log) to troubleshoot the error. If the error log doesn't contain any specific error message, try to run your build with the --verbose option.

```yaml
buildCommands:
  - cargo b --release
```

If the command ends successfully, it returns the exit code 0 and Zerops triggers the following command. When all `buildCommands` are finished, the application build is completed and ready for the deploy phase.

### deployFiles

_REQUIRED._ Selects which files or folders will be deployed after the build has successfully finished. To filter out specific files or folders, use [`.deployignore`](#deployignore) file.

```yaml
# REQUIRED. Select which files / folders to deploy after
# the build has successfully finished
deployFiles:
  - target/release/~app
```

Determines files or folders produced by your build, which should be deployed to your runtime service containers.

The path starts from the **root directory** of your project (the location of `zerops.yaml`). You must enclose the name in quotes if the folder or the file name contains a space.

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

#### Examples

Deploys a folder, and a file from the project root directory:

```yaml
deployFiles:
  - target/release/~app
```

Deploys the whole content of the build container:

```yaml
deployFiles: .
```

Deploys a folder, and a file in a defined path:

```yaml
deployFiles:
  - ./path/to/file.txt
  - ./path/to/dir/
```

#### How to use a wildcard in the path

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

Deploys all folders that are located in any path that begins with `/path/to/`

```yaml
deployFiles: ./path/to/~/
```

Deploys all folders that are located in any path that begins with `/path/` and ends with `/to/`

```yaml
deployFiles: ./path/~/to/
```
:::note Example
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 will be cached for the next build.

```yaml
# OPTIONAL. Which files / folders you want to cache for the next build.
# Next builds will be faster when the cache is used.
cache: file.txt
```

The cache attribute helps optimize build times by preserving specified files between builds.

The cache attribute supports the [~ wildcard character](#how-to-use-a-wildcard-in-the-path).

Learn more about the [build cache system](/features/build-cache) in Zerops.

### envVariables

_OPTIONAL._ Defines the environment variables for the build environment.

Enter one or more env variables in following format:

```yaml
zerops:
  # define hostname of your service
  - setup: app
    # ==== how to build your application ====
    build:
      base: rust@latest
        …

      # OPTIONAL. Defines the env variables for the build environment:
      envVariables:
        RUST_ENV: production
        DB_NAME: db
        DB_HOST: db
        DB_USER: db
        DB_PASS: ${db_password}
```

Read more about [environment variables](/rust/how-to/env-variables) in Zerops.

## Runtime configuration

### base

_OPTIONAL._ Sets the base technology for the runtime environment.
If you don't specify the `run.base` attribute, Zerops keeps the current Rust version for your runtime.

Following options are available for Rust builds:

- `rust@1`, `rust@latest`, `rust@stable`
- `rust@1.86`
- `rust@1.80`
- `rust@1.78`
- `rust@nightly`

```yaml
zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build:
      # REQUIRED. Sets the base technology for the build environment:
      base: rust@latest
      ...

    # ==== how to run your application ====
    run:
      # OPTIONAL. Sets the base technology for the runtime environment:
        base: rust@latest
      ...
```

<p>
  The base runtime environment contains {data.alpine.default}, the
  selected major version of Rust, Zerops command line tool, npm, yarn, git and
  npx tools.
</p>

:::info
You can change the base environment when you need to. Just simply modify the zerops.yaml in your repository.
:::

If you need to install more technologies to the runtime environment, set multiple values as a yaml array. For example:

```yaml
zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build:
      # REQUIRED. Sets the base technology for the build environment:
      base: rust@latest
      ...

    # ==== how to run your application ====
    run:
      # OPTIONAL. Sets the base technology for the runtime environment:
      base:
        - rust@latest
      prepareCommands:
        - zsc add go@latest
      ...
```

See the full list of supported [run base environments](/zerops-yaml/base-list).

To customize your build environment use the `prepareCommands` attribute.

### os

_OPTIONAL._ Sets the operating system for the runtime environment.

Following options are available:

- `alpine`
- `ubuntu`

Default value is `alpine`.

We are currently using following os version:

- <span>{data.alpine.default}</span>
- <span>{data.ubuntu.default}</span>

:::caution
The os version is fixed and cannot be customised.
:::

### ports

_OPTIONAL._ Specifies one or more internal ports on which your application will listen.

Projects in Zerops represent a group of one or more services. Services can be of different types (runtime services, databases, message brokers, object storage, etc.). All services of the same project share a **dedicated private network**. To connect to a service within the same project, just use the service hostname and its internal port.

For example, to connect to a Rust service with hostname = "app" and port = 8080 from another service of the same project, simply use `app:8080`. Read more about [how to access a Rust service](/references/networking/internal-access#basic-service-communication).

Each port has following attributes:

<table className="w-full my-1.5">
  <thead>
    <tr>
      <th className="w-fit"><strong>Parameter</strong></th>
      <th className="w-fit"><strong>Description</strong></th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td className="w-fit">port</td>
      <td className="w-fit">Defines the port number. You can set any port number between <em>10</em> and <em>65435</em>. Ports outside this interval are reserved for internal Zerops systems.</td>
    </tr>
    <tr>
      <td className="w-fit">protocol</td>
      <td className="w-fit"><strong>Optional.</strong> Defines the protocol. Allowed values are <code>TCP</code> or <code>UDP</code>. Default value is <code>TCP</code>.</td>
    </tr>
    <tr>
      <td className="w-fit">httpSupport</td>
      <td className="w-fit"><strong>Optional.</strong> <code>httpSupport = true</code> is the default setting for TCP protocol. Set <code>httpSupport = false</code> if a web server isn't running on the port. Zerops uses this information for the configuration of [public access](/features/access). <code>httpSupport = true</code> is available only in combination with the TCP protocol.</td>
    </tr>
  </tbody>
</table>

### prepareCommands

_OPTIONAL._ Customises the Rust runtime environment by installing additional dependencies or tools to the runtime base environment.

<p>
  The base Rust environment contains {data.alpine.default}, the selected
  major version of Rust, [Zerops command line tool](/references/cli) and `npm` , `yarn`, `git` and `npx` tools. To install additional packages or tools add one or
  more prepare commands:
</p>

```yaml
zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build:
      ...

    # ==== how to run your application ====
    run:
      # OPTIONAL. Customise the runtime environment by installing additional packages
      # or tools to the base Rust runtime environment.
      prepareCommands:
        - sudo apt-get something
        - curl something else
      ...
```

When the first deploy with a defined prepare attribute is triggered, Zerops will

1. create a prepare runtime container
2. optionally: [copy selected folders or files from your build container](#copy-folders-or-files-from-your-build-container)
3. run the `prepareCommands` commands in the defined order

:::note
`run.prepareCommands` run in the `/home/zerops` directory.
:::

#### Command exit code

If any command fails, it returns an exit code other than 0 and the deploy is canceled. Read the [prepare runtime log](/rust/how-to/logs#prepare-runtime-log) to troubleshoot the error. If the command ends successfully, it returns the exit code 0 and Zerops triggers the following command. When all `prepareCommands` commands are finished, your custom runtime environment is ready for the deploy phase.

#### Cache of your custom runtime environment

Some packages or tools can take a long time to install. Therefore, Zerops caches your custom runtime environment after the installation of your custom packages or tools is completed. When the second or following deploy is triggered, Zerops will use the custom runtime cache from the previous deploy if following conditions are met:

1. Content of the [build.addToRunPrepare](#copy-folders-or-files-from-your-build-container) and `run.prepareCommands` attributes didn't change from the previous deploy
2. The custom runtime cache wasn't invalidated in the Zerops GUI.

To invalidate the Zerops runtime cache go to your service detail in Zerops GUI, choose **Service dashboard & runtime containers** from the left menu and click on the **Open pipeline detail** button. Then click on the **Clear runtime prepare cache** button.

When the prepare cache is used, Zerops doesn't create a prepare runtime container and executes the deployment of your application directly.

#### Single or separated shell instances

You can configure your prepare commands to be run in a single shell instance or multiple shell instances. The format is identical to [build commands](#buildcommands).

### Copy folders or files from your build container

<p>
  The prepare runtime container contains {data.alpine.default}, the
  selected major version of Rust, [Zerops command line tool](/references/cli) and `npm`, `yarn`, `git` and `npx` tools.
</p>

The prepare runtime container does not contain your application code nor the built application. If you need to copy some folders or files from the build container to the runtime container (e.g. a configuration file) use the `addToRunPrepare` attribute in the [build section](#build-pipeline-configuration).

```yaml
zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build:
      ...
      addToRunPrepare: ./runtime-config.yaml

    # ==== how to run your application ====
    run:
      # OPTIONAL. Customise the runtime environment by installing additional packages
      # or tools to the base Rust runtime environment.
      prepareCommands:
        - sudo apt-get something
        - curl something else
      ...
```

In the example above Zerops will copy the `runtime-config.yaml` file from your build container **after the build has finished** into the new **prepare runtime** container. The copied files and folders will be available in the `/home/zerops` folder in the new prepare runtime container before the prepare commands are triggered.

### initCommands

_OPTIONAL._ Defines one or more commands to be run each time a new runtime container is started or a container is restarted.

```yaml
zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build: ...

    # ==== how to run your application ====
    run:
      # OPTIONAL. Run one or more commands each time a new runtime container
      # is started or restarted. These commands are triggered before
      # your Rust application is started.
      initCommands:
        - rm -rf ./cache
```

These commands are triggered in the runtime container before your Rust application is started via the [start command](#start).

:::note
`run.initCommands` run in the `/var/www` directory.
:::

Use init commands to clean or initialise your application cache or similar operations.

:::caution
The init commands will delay the start of your application each time a new runtime container is started (including the horizontal [scaling](/rust/how-to/scaling) or when a runtime container is restarted).

Do not use the init commands for customising your runtime environment. Use the [run:prepareCommands](#preparecommands-1) attribute instead.
:::

#### Command exit code

If any of the `initCommands` fails, it returns an exit code other than 0, but deploy is **not** canceled. After all init commands are finished, regardless of the status code, the application is started. Read the [runtime log](/rust/how-to/logs#runtime-log) to troubleshoot the error.

#### Single or separated shell instances

You can configure your `initCommands` to be run in a single shell instance or multiple shell instances. The format is identical to [build commands](#buildcommands).

### envVariables

_OPTIONAL._ Defines the environment variables for the runtime environment.

Enter one or more env variables in following format:

```yaml
zerops:
  # define hostname of your service
  - setup: app
    # ==== how to run your application ====
    run:
      # OPTIONAL. Defines the env variables for the runtime environment:
      envVariables:
        RUST_ENV: production
        DB_NAME: db
        DB_HOST: db
        DB_USER: db
        DB_PASS: ${db_password}
```

Read more about [environment variables](/rust/how-to/env-variables) in Zerops.

### start

_REQUIRED._ Defines the start command for your Rust application.

```yaml
zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build: ...

    # ==== how to run your application ====
    run:
      # REQUIRED. Your Rust application start command
      start: ./app
```

### health check

_OPTIONAL._ Defines a health check.

`healthCheck` requires either one `httpGet` object or one `exec` object.

#### httpGet

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

Following attributes are available:

<table className="w-full my-1.5">
  <thead>
    <tr>
      <th className="w-fit whitespace-nowrap">Parameter</th>
      <th className="w-fit whitespace-nowrap">Description</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td className="w-fit whitespace-nowrap font-semibold">port</td>
      <td>Defines the port of the HTTP GET request.
The readiness check will trigger a GET request on <code>{'http://127.0.0.1:{port}/{path}'}</code></td>
    </tr>
    <tr>
      <td className="w-fit whitespace-nowrap font-semibold">path</td>
      <td>Defines the URL path of the HTTP GET request.
The readiness check will trigger a GET request on <code>{'http://127.0.0.1:{port}/{path}'}</code></td>
    </tr>
    <tr>
      <td className="w-fit whitespace-nowrap font-semibold">host</td>
      <td><strong>Optional.</strong> The readiness check is triggered from inside of your runtime container so it always uses the localhost <code>127.0.0.1</code>. If you need to add a <code>host</code> to the request header, specify it in the <code>host</code> attribute.</td>
    </tr>
    <tr>
      <td className="w-fit whitespace-nowrap font-semibold">scheme</td>
      <td><strong>Optional.</strong> The readiness check is triggered from inside of your runtime container so no https is required.
If your application requires a https request, set <code>scheme: https</code></td>
    </tr>
  </tbody>
</table>

**Example:**

```yaml
zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build: ...

    # ==== how to run your application ====
    run:
      # REQUIRED. Your Rust application start command
      start: ./app

      # OPTIONAL. Define a health check with a HTTP GET request option.
      # Configures the check on http://127.0.0.1:80/status
      healthCheck:
        httpGet:
          port: 80
          path: /status
```

#### exec

Configures the health check to run a local command.
Following attributes are available:

<table className="w-full my-1.5">
  <thead>
    <tr>
      <th className="w-fit"><strong>Parameter</strong></th>
      <th className="w-fit"><strong>Description</strong></th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td className="w-fit"><strong>command</strong></td>
      <td className="w-fit">
        Defines a local command to be run.

        The command has access to the same [environment variables](/rust/how-to/create#set-secret-environment-variables) as your Rust application.

        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 below.
      </td>
    </tr>
  </tbody>
</table>

**Example:**

```yaml
zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build: ...

    # ==== how to run your application ====
    run:
      # REQUIRED. Your Rust application start command
      start: ./app

      # OPTIONAL. Define a health check with a shell command.
      healthCheck:
        exec:
          command: |
            touch grass
            rm -rf life
            mv /outside/user /home/user
```

### crontab

_OPTIONAL._ Defines cron jobs.

Setup cron jobs in the following format:

```yaml
zerops:
  # define hostname of your service
  - setup: app

    # ==== how to run your application ====
    run:
      crontab:
        # REQUIRED. Sets the command to execute:
        - command: ""
        # REQUIRED. Sets the interval time to execute:
          timing: "0 * * * *"
```

Read more about setting up [cron](/zerops-yaml/cron) in Zerops.

## Deploy configuration

### readiness check

_OPTIONAL._ Defines a readiness check. Read more about how the [readiness check works](/rust/how-to/deploy-process#readiness-checks) in Zerops.

`readinessCheck` requires either one `httpGet` object or one `exec` object.

#### httpGet

Configures the readiness check to request a local URL using a http GET method.

Following attributes are available:

<table className="w-full my-1.5">
  <thead>
    <tr>
      <th className="w-fit whitespace-nowrap">Parameter</th>
      <th className="w-fit whitespace-nowrap">Description</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td className="w-fit whitespace-nowrap font-semibold">port</td>
      <td>Defines the port of the HTTP GET request.
The readiness check will trigger a GET request on <code>{'http://127.0.0.1:{port}/{path}'}</code></td>
    </tr>
    <tr>
      <td className="w-fit whitespace-nowrap font-semibold">path</td>
      <td>Defines the URL path of the HTTP GET request.
The readiness check will trigger a GET request on <code>{'http://127.0.0.1:{port}/{path}'}</code></td>
    </tr>
    <tr>
      <td className="w-fit whitespace-nowrap font-semibold">host</td>
      <td><strong>Optional.</strong> The readiness check is triggered from inside of your runtime container so it always uses the localhost <code>127.0.0.1</code>. If you need to add a <code>host</code> to the request header, specify it in the <code>host</code> attribute.</td>
    </tr>
    <tr>
      <td className="w-fit whitespace-nowrap font-semibold">scheme</td>
      <td><strong>Optional.</strong> The readiness check is triggered from inside of your runtime container so no https is required.
If your application requires a https request, set <code>scheme: https</code></td>
    </tr>
  </tbody>
</table>

**Example:**

```yaml
zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build: ...

    # ==== how to deploy your application ====
    deploy:
      # OPTIONAL. Define a readiness check with a HTTP GET request option.
      # Configures the check on http://127.0.0.1:80/status
      readinessCheck:
        httpGet:
          port: 80
          path: /status

    # ==== how to run your application ====
    run: ...
```

Read more about how the [readiness check works](/rust/how-to/deploy-process#readiness-checks) in Zerops.

#### exec

Configures the readiness check to run a local command.
Following attributes are available:

<table className="w-full my-1.5">
  <thead>
    <tr>
      <th className="w-fit"><strong>Parameter</strong></th>
      <th className="w-fit"><strong>Description</strong></th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td className="w-fit"><strong>command</strong></td>
      <td className="w-fit">
        Defines a local command to be run.

        The command has access to the same [environment variables](/rust/how-to/create#set-secret-environment-variables) as your Rust application.

        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 below.
      </td>
    </tr>
  </tbody>
</table>

**Example:**

```yaml
zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build: ...

    # ==== how to deploy your application ====
    deploy:
      # OPTIONAL. Define a readiness check with a HTTP GET request option.
      # Configures the check on http://127.0.0.1:80/status
      readinessCheck:
        exec:
          command: |
            touch grass
            rm -rf life
            mv /outside/user /home/user
```

Read more about how the [readiness check works](/rust/how-to/deploy-process#readiness-checks) in Zerops.


----------------------------------------

# Rust > How To > Build Process



----------------------------------------

# Rust > How To > Controls



----------------------------------------

# Rust > How To > Create


Zerops provides a Rust runtime service with extensive build support. Rust runtime is highly scalable and customisable to suit both development and production.

## Create Rust service using Zerops GUI

First, set up a project in Zerops GUI. Then go to the project dashboard page and choose **Add new service** in the left menu in the **Services** block. Then add a new Rust service:

[Video: /vids/services/rust.webm](/vids/services/rust.webm)

### Choose Rust version

Following Rust versions are currently supported:

:::info
You can [change](/rust/how-to/upgrade) the major version at any time later.
:::

### Set a hostname

Enter a unique service identifier like "app","cache", "gui" etc. Duplicate services with the same name in the same project are forbidden.

#### Limitations:

- maximum 25 characters
- must contain only lowercase ASCII letters (a-z) or numbers (0-9)

:::caution
The hostname is fixed after the service is created. It can't be changed later.
:::

### Set secret environment variables

Add environment variables with sensitive data, such as password, tokens, salts, certificates etc. These will be securely saved inside Zerops and added to your runtime service upon start.

Setting the secret environment variables is optional. You can set them later in Zerops GUI.

Read more about [different types of env variables](/rust/how-to/env-variables#service-env-variables) in Zerops.

## Create Rust service using zCLI

zCLI is the Zerops command-line tool. To create a new Rust service via the command-line, follow these steps:

1. [Install & setup zCLI](/references/cli)
2. [Create a project description file](/rust/how-to/create#create-a-project-description-file)
3. [Create a project with a Rust and PostgreSQL service](#full-example)

### Create a project description file

Zerops uses a yaml format to describe the project infrastructure.

#### Basic example:

Create a directory `my-project`. Create an `description.yaml` file inside the `my-project` directory with following content:

```yaml
# basic project data
project:
  # project name
  name: my-project
# array of project services
services:
  - # service name
    hostname: app
    # service type and version number in rust@{version} format
    type: rust@latest
    # defines the minimum number of containers for horizontal autoscaling
    minContainers: 1
    # defines the maximum number of containers for horizontal autoscaling. Max value = 6.
    maxContainers: 6
    # optional: create env variables
    envSecrets:
      S3_ACCESS_KEY_ID: 'P8cX1vVVb'
      S3_ACCESS_SECRET: 'ogFthuiLYki8XoL73opSCQ'
```

The yaml file describes your future project infrastructure. The project will contain one Rust version 18 service with default [auto scaling](/rust/how-to/scaling) configuration. Hostname will be set to "app", the internal port(s) the service listens on will be defined later in the [zerops.yaml](/rust/how-to/build-pipeline#ports). Following secret env variables will be configured:

```env
S3_ACCESS_KEY_ID="P8cX1vVVb"
S3_ACCESS_SECRET="ogFthuiLYki8XoL73opSCQ"
```

#### Full example:

Create a directory my-project. Create an description.yaml file inside the my-project directory with following content:

```yaml
# basic project data
project:
  # project name
  name: my-project
  # optional: project description
  description: A project with a Rust and PostgreSQL database
  # optional: project tags
  tags:
    - DEMO
    - ZEROPS
# array of project services
services:
  - # service name
    hostname: app
    # service type and version number in rust@{version} format
    type: rust@latest
    # optional: vertical auto scaling customization
    verticalAutoscaling:
      cpuMode: DEDICATED
      minCpu: 2
      maxCpu: 5
      minRam: 2
      maxRam: 24
      minDisk: 6
      maxDisk: 50
      startCpuCoreCount: 3
      minFreeRamGB: 0.5
      minFreeRamPercent: 20
    # defines the minimum number of containers for horizontal autoscaling. Max value = 6.
    minContainers: 2
    # defines the maximum number of containers for horizontal autoscaling. Max value = 6.
    maxContainers: 4
    # optional: create secret env variables
    envSecrets:
      S3_ACCESS_KEY_ID: 'P8cX1vVVb'
      S3_ACCESS_SECRET: 'ogFthuiLYki8XoL73opSCQ'
  - # second service hostname
    hostname: db
    # service type and version number in postgresql@{version} format
    type: postgresql@12
    # mode of operation "HA"/"non_HA"
    mode: NON_HA
```

The yaml file describes your future project infrastructure. The project will contain a Rust service and a [PostgreSQL](/postgresql/overview) service.

Rust service with "app" hostname, the internal port(s) the service listens on will be defined later in the [zerops.yaml](/rust/how-to/build-pipeline#ports). Rust service will run on version 18 with a custom vertical and horizontal scaling. Following secret env variables will be configured:

```env
S3_ACCESS_KEY_ID="P8cX1vVVb"
S3_ACCESS_SECRET="ogFthuiLYki8XoL73opSCQ"
```

The hostname of the PostgreSQL service will be set to "db". The [single container](/features/scaling#single-container-mode)(/features/scaling#deployment-modes-databases-and-shared-storage) mode will be chosen and the default auto [scaling configuration](/postgresql/how-to/scale#configure-scaling) will be set.

#### Description of description.yaml parameters

The `project:` section is required. Only one project can be defined.

<table className="w-full my-1.5">
  <thead>
    <tr>
      <th className="w-fit"><strong>Parameter</strong></th>
      <th className="w-fit"><strong>Description</strong></th>
      <th className="w-fit"><strong>Limitations</strong></th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td className="w-fit"><strong>name</strong></td>
      <td className="w-fit">The name of the new project. Duplicates are allowed.</td>
      <td className="w-fit"></td>
    </tr>
    <tr>
      <td className="w-fit"><strong>description</strong></td>
      <td className="w-fit"><strong>Optional.</strong> Description of the new project.</td>
      <td className="w-fit">Maximum 255 characters.</td>
    </tr>
    <tr>
      <td className="w-fit"><strong>tags</strong></td>
      <td className="w-fit"><strong>Optional.</strong> One or more string tags. Tags do not have a functional meaning, they only provide better orientation in projects.</td>
      <td className="w-fit"></td>
    </tr>
  </tbody>
</table>

At least one service in `services:` section is required. You can create a project with multiple services. The example above contains Rust and PostgreSQL services but you can create a `description.yaml` with your own combination of [services](/features/infrastructure).

<table className="w-full my-1.5">
  <thead>
    <tr>
      <th className="w-fit">Parameter</th>
      <th className="w-fit">Description</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td className="w-fit">
        <b>hostname</b>
      </td>
      <td className="w-fit">
        The unique service identifier.
        <ul>
        <li>duplicate services with the same name in the same project are forbidden</li>
        <li>maximum 25 characters</li>
        <li>must contain only lowercase ASCII letters (a-z) or numbers (0-9)</li>
        </ul>
      </td>
    </tr>
    <tr>
      <td className="w-fit">
        <b>type</b>
      </td>
      <td className="w-fit">
        Specifies the service type and version.

        See what [Rust service types](/references/import-yaml/type-list#runtime-services) are currently supported.
      </td>
    </tr>
    <tr>
      <td className="w-fit">
        <b>verticalAutoscaling</b>
      </td>
      <td className="w-fit">
        <b>Optional.</b> Defines [custom vertical auto scaling parameters](/rust/how-to/create#set-auto-scaling-configuration).

        All verticalAutoscaling attributes are optional. Not specified
        attributes will be set to their default values.
      </td>
    </tr>
    <tr>
      <td className="w-fit">
        <b> - cpuMode</b>
      </td>
      <td className="w-fit">
        <b>Optional.</b> Accepts `SHARED`, `DEDICATED` values. Default is `SHARED`
      </td>
    </tr>
    <tr>
      <td className="w-fit">
        <b> - minCpu/maxCpu</b>
      </td>
      <td className="w-fit">
        <b>Optional.</b> Set the minCpu or maxCpu in CPU cores (integer).
      </td>
    </tr>
    <tr>
      <td className="w-fit">
        <b> - minRam/maxRam</b>
      </td>
      <td className="w-fit">
        <b>Optional.</b> Set the minRam or maxRam in GB (float).
      </td>
    </tr>
    <tr>
      <td className="w-fit">
        <b> - minDisk/maxDisk</b>
      </td>
      <td className="w-fit">
        <b>Optional.</b> Set the minDisk or maxDisk in GB (float).
      </td>
    </tr>
    <tr>
      <td className="w-fit">
        <b>minContainers</b>
      </td>
      <td className="w-fit">
        <b>Optional.</b> Default = 1. Defines the minimum number of containers
        for [horizontal autoscaling](/rust/how-to/create#horizontal-auto-scaling).

        <b>Limitations:</b>

        Current maximum value = 10.
      </td>
    </tr>
    <tr>
      <td className="w-fit">
        <b>maxContainers</b>
      </td>
      <td className="w-fit">
        Defines the maximum number of containers for [horizontal autoscaling](/rust/how-to/create#horizontal-auto-scaling).

        <b>Limitations:</b>

        Current maximum value = 10.
      </td>
    </tr>
    <tr>
      <td className="w-fit">
        <b>envSecrets</b>
      </td>
      <td className="w-fit">
        <b>Optional.</b> Defines one or more secret env variables as a key value
        map. See env variable [restrictions](/rust/how-to/env-variables#env-variable-restrictions).
      </td>
    </tr>
  </tbody>
</table>

### Create a project based on the description.yaml

When you have your `description.yaml` ready, use the `zcli project project-import` command to create a new project and the service infrastructure.

```sh
Usage:
  zcli project project-import importYamlPath [flags]

Flags:
  -h, --help                Help for the project import command.
      --org-id string        If you have access to more than one organization, you must specify the org ID for which the
                            project is to be created.
      --working-dir string   Sets a custom working directory. Default working directory is the current directory. (default "./")
```

Zerops will create a project and one or more services based on the `description.yaml` content.

Maximum size of the `description.yaml` file is 100 kB.

You don't specify the project name in the `zcli project project-import` command, because the project name is defined in the `description.yaml`.

If you have access to more than one client, you must specify the client ID for which the project is to be created. The `clientID` is located in the Zerops GUI under the client name on the project dashboard page.

### Add Rust service to an existing project

#### Example:

Create a directory `my-project` if it doesn't exist. Create an `import.yaml` file inside the `my-project` directory with following content:

```yaml
# basic project data
project:
  # project name
  name: my-project
# array of project services
services:
  - # service name
    hostname: app
    # service type and version number in rust@{version} format
    type: rust@latest
    # defines the minimum number of containers for horizontal autoscaling
    minContainers: 1
    # defines the maximum number of containers for horizontal autoscaling. Max value = 6.
    maxContainers: 6
    # optional: create env variables
    envSecrets:
      S3_ACCESS_KEY_ID: 'P8cX1vVVb'
      S3_ACCESS_SECRET: 'ogFthuiLYki8XoL73opSCQ'
```

The yaml file describes the list of one or more services that you want to add to your existing project. In the example above, one Rust service version 18 with default [auto scaling](/rust/how-to/scaling) configuration will be added to your project. Hostname of the new service will be set to `app`. Following secret env variables will be configured:

```env
S3_ACCESS_KEY_ID="P8cX1vVVb"
S3_ACCESS_SECRET="ogFthuiLYki8XoL73opSCQ"
```

The content of the `services:` section of `import.yaml` is identical to the project description file. The `import.yaml` never contains the `project:` section because the project already exists.

When you have your `import.yaml` ready, use the `zcli project service-import` command to add one or more services to your existing Zerops project.

```sh
Usage:
  zcli project service-import importYamlPath [flags]

Flags:
  -h, --help                Help for the project service import command.
  -P, --project-id string   If you have access to more than one project, you must specify the project ID for which the
                           command is to be executed.
```

zCLI commands are interactive, when you press enter after `zcli project service-import importYamlPath`, you will be given a list of your projects to choose from.

Maximum size of the import.yaml file is 100 kB.


----------------------------------------

# Rust > How To > Customize Runtime



----------------------------------------

# Rust > How To > Deploy Process



----------------------------------------

# Rust > How To > Env Variables



----------------------------------------

# Rust > How To > Filebrowser



----------------------------------------

# Rust > How To > Logs



----------------------------------------

# Rust > How To > Scaling



----------------------------------------

# Rust > How To > Shared Storage



----------------------------------------

# Rust > How To > Trigger Pipeline



----------------------------------------

# Rust > How To > Upgrade



----------------------------------------

# Rust > Overview


[Rust ↗](https://www.rust-lang.org/) - a language empowering everyone to build reliable and efficient software.

As said, there is no need for coding yet, we have created a [Github repository ↗](https://github.com/zeropsio/recipe-rust-hello-world), a **_recipe_**, containing the most simple Rust web application. The repo will be used as a source from which the app will be built.

### 🚀 Feel free to deploy the recipe yourself

This is the most bare-bones example of Rust running in Zerops — as few libraries as possible,
  just a simple endpoint with connect, read and write to a Zerops PostgreSQL database.

  [Deploy "rust" recipe on Zerops](https://app.zerops.io/recipe/?lf=rust)

1. Log in/sign up to [Zerops GUI ↗](https://app.zerops.io)
2. In the **Projects** box click on **Import a project** and paste in the following YAML config ([source ↗](https://github.com/zeropsio/recipe-rust-hello-world/blob/main/import-project/description.yaml)):

```yaml
project:
  name: my-first-project
services:
  - hostname: helloworld
    type: rust@latest
    minContainers: 1
    maxContainers: 3
    buildFromGit: https://github.com/zeropsio/recipe-rust-hello-world@main
    enableSubdomainAccess: true
```

3. Click on **Import project** and wait until all pipelines have finished.

**That's it, your application is now up and running! :star: Let's check it works:**

1. A _subdomain_ should have been enabled and visible in the project's **IP addressed & Public Routing Overview** box. Its format should look similar to this `https://helloworld-24-8080.prg1.zerops.app`.
2. Click or the `subdomain` URL to open it in a browser and you should see

```
Hello, World!
```

:::tip
Do you have any questions? Check the step-by-step tutorial, browse the documentation and join our **[Discord](https://discord.com/invite/WDvCZ54)** community to get help from our team and other members.
:::

## How to start

- [Care for details?](/rust/how-to/create) — Dive in all Zerops has to offer for your Rust application.

## Feature Highlights

- [Create Rust service](/rust/how-to/create) — Start with creating a Rust service using GUI or zCLI.
- [zerops.yaml](/rust/how-to/build-pipeline#add-zeropsyaml-to-your-repository) — See a full example of zerops.yaml file to create your own app.
- [Scaling configuration](/rust/how-to/scaling) — Set up scaling of your Rust application so that it runs smoothly while using only necessary resources.

{" "}

- [Customize build environment](/rust/how-to/build-process#customize-build-environment)
- [Customize runtime environment](/rust/how-to/customize-runtime)

## When in doubt, reach out

Don't know how to start or got stuck during the process? You might not be the first one, visit the FAQ section to find out.

In case you haven't found an answer (and also if you have), we and our community are looking forward to hearing from you on Discord.

Have you build something that others might find useful? Don't hesitate to share your knowledge!

- [FAQ](/rust/faq) — Most common questions in one place.
- [Discord](https://discord.com/invite/WDvCZ54) — Join our core team and Zerops community on Discord. Ask questions and share your tips with other members.

## Popular Guides

- [zCLI](/references/cli) — Get even more out of Zerops with the zCLI command line tool.
- [Zerops VPN](/references/networking/vpn) — Connect to your services easily with Zerops VPN.


----------------------------------------

# Shared Storage > How To > Connect


This page covers how to connect an existing shared storage to runtime services, how to disconnect it, and how the mount behaves inside your containers.

## How the mount behaves

Once a shared storage is connected to a runtime service, Zerops mounts it at `/mnt/<storage-hostname>` in the runtime containers. For example, `/mnt/teststorage` for a `teststorage` shared storage:

- The content is shared among **all containers** of the connected runtime service; if you connect multiple runtime services, they all see the same content
- Multiple storages can be mounted to a single service (e.g. `/mnt/files1`, `/mnt/files2`)
- The mount point is owned by the `zerops` user and group (no sudo required)
- Mounting removes any existing content of the mount directory
- The mount is only available in runtime containers, not during build and prepare runtime phases
- The mount process logs its standard output and error to the runtime service logs (tagged `zerops-mount-<service-hostname>`); individual file operations are not logged

:::note
The `df` command may show incorrect or misleading information for shared storage mounts. Refer to the Zerops GUI for accurate storage metrics.
:::

## Connect in Zerops GUI

When creating a new shared storage service, you can directly select which runtime services it should be connected to. See [Create shared storage](/shared-storage/how-to/create) for the creation process.

For existing storage, go to the shared storage service detail page and select **Shared storage connections**. Toggle ON any runtime services you wish to connect to this storage.

To disconnect storage, toggle OFF the desired runtime service in the same place.

:::note
Connecting and disconnecting a shared storage is applied live; the runtime containers are not restarted.
:::

## Mount and unmount using zsc

You can also mount and unmount a shared storage from within a runtime container using the `zsc` command:

```sh
# Mount a shared storage
zsc shared-storage mount <storage-hostname>

# Unmount a shared storage
zsc shared-storage unmount <storage-hostname>

# Wait until the storage mount is ready
zsc shared-storage wait <storage-hostname>
```

Run these commands from your runtime container via web terminal or SSH, or as part of your `zerops.yaml` commands. For more details, see the [zsc reference](/references/zsc#shared-storage).

:::caution
The shared storage must be mounted (through the GUI connection toggle or via `zsc shared-storage mount`) before your application can access the `/mnt/<storage-hostname>` directory.

Before stopping or deleting a shared storage service, you must first disconnect (unmount) it from all runtime services.
:::


----------------------------------------

# Shared Storage > How To > Create


## Create Using Zerops GUI

Go to your project dashboard and choose **Add new service** in the left menu in the **Services** block. Then add a new Shared Storage service:

[Video: /vids/services/shared-storage.webm](/vids/services/shared-storage.webm)

### Set a Hostname

Enter a unique service identifier like "storage", "files" etc.

- Maximum 25 characters
- Must contain only lowercase ASCII letters (a-z) or numbers (0-9)
- Must be unique within the project

:::note
The hostname is fixed after the service is created. It can't be changed later.
:::

### Connect to Services

Select one or more of the project's runtime services in the **Share with Services** block:

Runtime services can be [connected and disconnected](/shared-storage/how-to/connect) at any time, even after the shared storage is created.

### Choose Deployment Mode

Choose between **Highly Available** (recommended for production) and **Single Container** (suitable for development). See the [mode comparison](/shared-storage/overview#deployment-modes) and [technical details](/shared-storage/tech-details#deployment-modes).

:::warning
The deployment mode is fixed after the service is created. It can't be changed later.
:::

### Set Auto Scaling Configuration

Configure vertical auto scaling parameters to control resource allocation and costs:

:::note
Raising the disk limits does not raise the usable data capacity, which is capped at 60GB. See [Storage Capacity](/shared-storage/tech-details#storage-capacity) and [Auto Scaling Configuration](/shared-storage/tech-details#auto-scaling-configuration).
:::

## Create Using Import YAML

The deployment mode is part of the service type:

```yaml title="zerops-import.yaml"
services:
  - # Shared storage service in highly available mode
    hostname: teststorage
    type: shared-storage:ha
```

Use `shared-storage:single` for the single container mode.

:::note
You can also pin the underlying engine version directly with `seaweedfs:ha@3` or `seaweedfs:single@3`.
:::

Import the file with the [zCLI](/references/cli):

```sh
zcli project service-import zerops-import.yaml
```

To mount the storage into a runtime service in the same import, add the `mount:` parameter to the runtime service. See the [import reference](/references/import#service-mount-shared-storage) for details and requirements.

### Runtime-Specific Guides

export const languages = [
    { name: "Node.js", link: "/nodejs/how-to/shared-storage#create-nodejs-service-with-a-shared-storage-using-zcli" },
    { name: "PHP", link: "/php/how-to/shared-storage#create-php-service-with-a-shared-storage-using-zcli" },
    { name: "Python", link: "/python/how-to/shared-storage#create-python-service-with-a-shared-storage-using-zcli" },
    { name: "Go", link: "/go/how-to/shared-storage#create-go-service-with-a-shared-storage-using-zcli" },
    { name: ".NET", link: "/dotnet/how-to/shared-storage#create-dotnet-service-with-a-shared-storage-using-zcli" },
    { name: "Rust", link: "/rust/how-to/shared-storage#create-rust-service-with-a-shared-storage-using-zcli" }
]


----------------------------------------

# Shared Storage > How To > Manage


Zerops Shared Storage provides several web interfaces to manage, monitor, and troubleshoot your storage, and automated encrypted backups of your data.

## Web interfaces

The web interfaces are accessible through the [Zerops VPN](/references/networking/vpn).

### Filer UI

* `http://<storage-service-hostname>.zerops:8888`

A web-based interface for managing files and directories:
- Browse the directory structure and create new directories
- Upload new files (up to 64MB per file) and download existing files
- Rename and delete files and directories

### Master UI

* `http://node-stable-1.db.<storage-service-hostname>.zerops:9333`

System status and monitoring information:
- View cluster topology
- Monitor volume servers
- Check system status and health
- View statistics and metrics

### Volume UI

* `http://node-stable-<node-number>.db.<storage-service-hostname>.zerops:8080/ui/index.html`

Monitoring of individual storage volumes:
- View volume status
- Check disk usage
- Monitor I/O operations
- View volume statistics

## Monitoring

Several options are available to help you monitor your Shared Storage:

- **Runtime service logs**: navigate to your runtime service detail page, open the **Runtime Logs** section, and filter using the tag `zerops-mount-<service-hostname>` (standard output and error of the mount process)
- **Shared Storage logs**: access from the Shared Storage service detail page, **Runtime Logs** tab
- **System and volume status**: monitor replication status, disk usage, and performance metrics through the Master UI and Volume UI

## Backups

Zerops provides automated data backup for Shared Storage services with full encryption.

For general backup information including configuration, scheduling, retention, tagging, quotas, and CLI tools, see the [Zerops Backups](/features/backup) documentation.

### Backup format

Shared Storage backups are created using tar archival:

- **Format**: `.tar.gz` (archive of the directory contents)
- **Content**: the entire shared volume (`/mnt/<storage-hostname>`)
- **Storage**: encrypted and stored in isolated object storage

### Restoring backups

To restore a Shared Storage backup:

1. Download the backup file (`.tar.gz`) from the Zerops UI.
2. Transfer the archive into a runtime service that has the shared storage [connected](/shared-storage/how-to/connect), for example over the [Zerops VPN](/references/networking/vpn).
3. Extract the archive into the mount directory from within the runtime container:

```sh
tar -xzf backup.tar.gz -C /mnt/<storage-hostname>
```

:::note
Do not restore by uploading files through the Filer UI. Uploads there are limited to 64MB per file, so extracting the archive directly into the mounted directory is the reliable path.
:::

### Best practices

- Regularly clean up unnecessary files from your Shared Storage to reduce backup size
- Create manual backups with protected tags before major file operations or migrations
- Test your restore process periodically to ensure data integrity


----------------------------------------

# Shared Storage > Overview


Zerops **Shared Storage** is a managed disk volume that mounts as a POSIX-compatible filesystem into your runtime services. Files written by one container are immediately visible to every other container that mounts the same storage, whether they belong to the same service or to different services in the project.

Under the hood it runs [SeaweedFS ↗](https://github.com/seaweedfs/seaweedfs), a distributed filesystem optimized for high-volume storage. See [Technical details](/shared-storage/tech-details) for the architecture.

## Quick start

Add a shared storage to your project and mount it into a runtime service with a `zerops-import.yaml`:

```yaml title="zerops-import.yaml"
services:
  - hostname: teststorage
    # type is shared-storage:{mode}
    type: shared-storage:ha

  - hostname: app
    type: nodejs@22
    buildFromGit: https://github.com/myorg/myapp
    # mount the storage into /mnt/teststorage
    mount:
      - teststorage
```

The storage appears in the runtime containers at `/mnt/teststorage`. See [Create shared storage](/shared-storage/how-to/create) for the GUI flow and configuration details, and [Connect & mount](/shared-storage/how-to/connect) for how the mount behaves.

## Use cases

Shared Storage is a good fit for:

- **Configuration sharing**: deploy configuration once and share it across services (e.g. Apache Airflow configuration and DAG files shared with all worker nodes)
- **Application data**: user uploads, images, documents, and other assets shared between containers (avoid huge trees of tiny files, see [performance considerations](/shared-storage/tech-details#performance-considerations))
- **Fallback to object storage**: applications that strictly require filesystem semantics and cannot work with [object storage](/object-storage/overview)

:::caution Not suitable for databases
Do **not** run databases on Shared Storage. This includes SQLite, Prometheus TSDB, and other filesystem-based databases.

- File locks are enforced **per mount only**: a lock held in one container does not prevent another container from writing to the same file, which leads to data corruption.
- The underlying storage engine is an append-only chunk store: every modification writes new chunks, so the frequent small writes typical for databases cause heavy write amplification.

Use [managed databases](/postgresql/overview) instead. For storing database *backups*, prefer [object storage](/object-storage/overview): it is cheaper and better suited for write-once files.
:::

## Deployment modes

Choose the reliability model when you create the service. It is set through the service `type` and is **fixed for the life of the service**.

<table className="w-full my-1.5">
  <thead>
    <tr>
      <th className="w-fit" style={{ minWidth: '75px' }}>Mode</th>
      <th className="w-fit" style={{ minWidth: '200px' }}>type</th>
      <th className="w-fit">What it is</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td className="w-fit"><b>Highly Available</b></td>
      <td className="w-fit"><code>shared-storage:ha</code></td>
      <td className="w-fit">Two containers with data and metadata replicated 1:1 across both, with automatic repair when a node fails. Recommended for production.</td>
    </tr>
    <tr>
      <td className="w-fit"><b>Single container</b></td>
      <td className="w-fit"><code>shared-storage:single</code></td>
      <td className="w-fit">One container, so lower cost but no redundancy. All data is lost if the container fails. Good for development and non-critical data.</td>
    </tr>
  </tbody>
</table>

## Key limits

- The storage holds at most **60GB of data**, regardless of the disk resource in autoscaling. See [storage capacity](/shared-storage/tech-details#storage-capacity).
- File locks work **only within a single container's mount**, not across containers. See [filesystem capabilities](/shared-storage/tech-details#filesystem-capabilities).
- The mount is available only in runtime containers, not during build and prepare phases.

## Next steps

- [Create shared storage](/shared-storage/how-to/create) — Create a service in the GUI or with zerops-import.yaml.
- [Connect & mount](/shared-storage/how-to/connect) — Connect runtime services and understand how the mount behaves.
- [Manage & backups](/shared-storage/how-to/manage) — Web interfaces, monitoring, backups, and restore.
- [Technical details](/shared-storage/tech-details) — Architecture, storage engine behavior, limits, and autoscaling.

## Need help?

Stuck, or want to share what you built? Our core team and community are on Discord.

- [Discord](https://discord.com/invite/WDvCZ54) — Join the Zerops community on Discord. Ask questions and share your tips.
- [zCLI](/references/cli) — Get more out of Zerops with the command-line tool.


----------------------------------------

# Shared Storage > Tech Details


Zerops Shared Storage is built on [SeaweedFS ↗](https://github.com/seaweedfs/seaweedfs), a distributed filesystem optimized for high-volume storage with efficient retrieval.

## Architecture

Shared Storage consists of three main components:

- **Master Server**: manages metadata and coordinates volume servers
- **Volume Servers**: store the actual file data
- **Filer**: provides a POSIX-compatible interface for file operations

### Storage Engine Behavior

SeaweedFS stores file data in append-only volumes. Files are split into chunks, and when a file is modified, new chunks are written while the old ones remain on disk until they are reclaimed. Frequent small modifications of existing files therefore cause significant write amplification, which is one of the reasons Shared Storage is [not suitable for databases](/shared-storage/overview#use-cases).

An **automatic vacuum process** reclaims the space occupied by deleted and superseded chunks. This process is triggered when the size of deleted content exceeds 15% (reduced from the SeaweedFS default of 30%).

## Deployment Modes

Zerops provides Shared Storage in two deployment modes:

### Highly Available

Recommended for production environments where data reliability is critical.

- **Architecture**: Two containers, each running its own filer and volume server; the master server runs on the first container
- **Data Durability**: Data and filer metadata are replicated 1:1 across both containers
- **Fault Tolerance**:
    - If a node fails, an automatic repair process begins
    - A new container replaces the failed one
    - Data is automatically replicated to the new container (duration depends on data size)
    - During master node failure, mounted directories become temporarily unavailable until the new master initializes (~30s)

### Single Container

Suitable for development environments or non-critical data storage.

- **Architecture**: Master, volume, and filer server all located on a single container
- **Data Durability**: All data is lost if the container fails

:::warning
The deployment mode is fixed after the service is created and cannot be changed later.
:::

## Filesystem Capabilities

Shared Storage supports standard POSIX filesystem operations:

- Create, read, update, and delete files and directories
- Set permissions (with some limitations)
- File locking (per mount only, see the warning below)
- Hard and symbolic links
- Directory listing and traversal

For a complete list of supported features, see the [SeaweedFS FUSE documentation ↗](https://github.com/seaweedfs/seaweedfs/wiki/FUSE-Mount#supported-features).

:::caution File locks are per-mount only
File locks (`flock`, POSIX locks) are enforced only within a single container's mount. A process in another container can freely write to a file you hold locked. Do not rely on file locking for coordination between containers, and do not run [lock-dependent workloads such as databases](/shared-storage/overview#use-cases) on Shared Storage.
:::

## Storage Capacity

:::caution The 60GB data limit is independent of disk scaling
A Shared Storage service holds at most **60GB of data**, no matter how much disk the service scales to. The disk resource (up to 250GB) provides headroom for the vacuum process and filesystem metadata; raising the disk limits in autoscaling does **not** increase the amount of data you can store.

If you need more than 60GB, contact support.
:::

- Maximum storage space: 60GB (can be increased via support request)
- Maximum file size: no fixed limit through the mount (files are stored in chunks), up to the available storage space
- Maximum upload size via Filer UI: 64MB per file

## Performance Considerations

- **Latency**: higher latency compared to local storage due to the network-based distributed architecture
- **Write performance**: for write-heavy workloads, batch operations where possible
- **Small files**: minimize operations with many small files for better performance
- **Mount process memory**: the mount process runs inside each connected runtime container and consumes its memory, roughly 60MB when idle and around 150MB under higher filesystem loads; it is optimized for low RAM usage, which may trade off some performance

## Auto Scaling Configuration

Zerops scales Shared Storage services automatically by raising or lowering the hardware resources of each container.

Vertical auto scaling has the following default configuration:

:::note
Disk size only gives the storage engine working space; the usable data capacity stays capped at 60GB. See [Storage Capacity](#storage-capacity).
:::

For most cases, the default parameters will work without issues. If you need to limit the cost of the Shared Storage service, lower the maximal resources. Zerops will never scale above the selected maximums.

When you are experiencing problems with insufficient Shared Storage performance, increase the minimal resources. Zerops will never scale below the selected minimums.

You can change the auto scaling parameters at any time.


----------------------------------------

# Static > Overview


The Static service provides a way to serve static content through a pre-configured Nginx setup. It balances simplicity with the flexibility needed for modern web applications.

### Experience the simplicity of Zerops

Deploy an Analog app with static hosting in seconds. All you need is a Zerops account.

  [Deploy "analog" recipe on Zerops](https://app.zerops.io/recipe/?lf=analog)

## Quick Start

Add a Static service to your project by including this in your `zerops.yaml`:

```yaml title="zerops.yaml"
zerops:
  - setup: app
    run:
      os: alpine
      base: static
```

## Routing & Configuration

### Default Behavior

Every Static service in Zerops comes with built-in defaults optimized for modern web applications, including Single Page Applications. By default, for any incoming request, the service will:
1. Try to serve the exact path (`$uri`)
2. Try with .html extension (`$uri.html`)
3. Look for an index.html in the directory (`$uri/index.html`)
4. Fall back to `/index.html` (suitable for SPAs)
5. Return 404 if none of the above exist

:::important SPAs
Single Page Applications work out of the box without any additional configuration. The built-in fallback to `/index.html` ensures that client-side routing functions properly.
:::

### Custom Routing Configuration

The Static service allows you to configure additional URL routing and redirects through simple YAML configuration, abstracting away the complexity of Nginx configuration.

Configure custom routing beyond the default behavior in the `run.routing` section of your `zerops.yaml`:

```yaml title="zerops.yaml"
run:
  routing:
    redirects:
      # Only needed for custom redirect scenarios
      - from: /special-path/*
        to: /specific-landing-page
        status: 302
```

### Redirects

#### Relative Redirects

:::note
Remember that SPA routing is already built into the default behavior. You don't need to add any custom redirects for client-side routing to work.
:::

Use relative redirects to route paths within your application. When both `from` and `to` are relative paths, you can omit the `status` code to create a masked redirect that shows the content of the target page while preserving the original URL:

```yaml title="zerops.yaml"
routing:
  redirects:
    # Masked redirect - URL stays the same but shows content from about-us
    - from: /about
      to: /about-us

    # Standard redirect with status code
    - from: /old-page
      to: /new-page
      status: 301

    # Preserve the path when redirecting between directories
    - from: /blog/*
      to: /articles/
      preservePath: true
      status: 302

    # Preserve both path and query parameters
    - from: /posts/*
      to: /blog/
      preservePath: true
      preserveQuery: true
      status: 302
```

:::caution Important
When using `preservePath` with wildcards, ensure the `to` path ends with a `/` to maintain proper path concatenation. For example, `/blog/*` to `/new-blog/` will correctly redirect `/blog/hello.html` to `/new-blog/hello.html`, while `/new-blog` would result in `/new-bloghello.html`.
:::

#### Absolute Redirects

For redirecting between domains or to external URLs, use absolute redirects by including `http://` or `https://`. When using absolute URLs in either `from` or `to`, you must specify a `status` code:

```yaml title="zerops.yaml"
routing:
  redirects:
    # Redirect an old domain to a new one
    - from: https://old-domain.com/*
      to: https://new-domain.com
      status: 301
      preserveQuery: true  # Optional: maintain query parameters

    # Redirect with path preservation
    - from: https://old-site.com/*
      to: https://new-site.com/
      status: 301
      preservePath: true
```

#### Wildcard Matching

Use `*` as a wildcard in your paths:
- **At the end of a path**: Matches any subsequent content
- **At the start of a domain** (after `https://`): Enables regex matching for subdomains

Example of domain management:

```yaml title="zerops.yaml"
run:
  routing:
    redirects:
      # Redirect a specific domain to an article
      - from: https://promo-domain.com/*
        to: https://main-site.com/special-offer
        status: 302

      # Redirect all subdomains to main site
      - from: https://*.old-domain.com/*
        to: https://main-site.com
        status: 302
```

#### Matching Priority

When multiple redirects are configured, they follow Nginx's matching priority system:

1. Exact matches are checked first
2. Simple path matches (without wildcards) are checked next
3. Pattern matches (with wildcards) are checked last

For example:

```yaml title="zerops.yaml"
routing:
  redirects:
    # Exact match for homepage - standard redirect
    - from: /
      to: /home
      status: 302

    # Simple path match - masked redirect
    - from: /about
      to: /about-us

    # Pattern match with path preservation
    - from: /blog/*
      to: /articles/
      preservePath: true
      status: 302
```

In this configuration:
- `/` will redirect to `/home` with a 302 status
- `/about` will show content from `/about-us` but keep the URL as `/about`
- `/blog/post-123.html` will redirect to `/articles/post-123.html`
- Any other path will use the [default behavior](#default-behavior)

#### Common Redirect Patterns

**Domain Migration**
```yaml title="zerops.yaml"
routing:
  redirects:
    - from: https://old-domain.com/*
      to: https://new-domain.com
      status: 301
```
Use permanent (301) redirects when permanently moving content to maintain SEO value.

**Multiple Domain Management**
```yaml title="zerops.yaml"
run:
  routing:
    redirects:
      # Product-specific domain
      - from: https://product-promo.com/*
        to: https://main-site.com/products
        status: 302

      # Campaign domain
      - from: https://special-offer.com/*
        to: https://main-site.com/campaign
        status: 302

      # Legacy domains and subdomains
      - from: https://*.legacy-domain.com/*
        to: https://main-site.com
        status: 302
```

### CORS Configuration

You can enable CORS for your static service by adding a `cors` directive:

```yaml title="zerops.yaml"
run:
  routing:
    # Simple case - automatically converted to '*'
    cors: "*"

    # Full syntax with proper quoting
    cors: "'*' always"
```

The `cors` directive sets the following headers:
- `Access-Control-Allow-Origin`
- `Access-Control-Allow-Methods`
- `Access-Control-Allow-Headers`
- `Access-Control-Expose-Headers`

:::note
The `cors` directive has a special case: if you specify just `"*"`, it's automatically converted to `'*'`. For any other values, you need to include the proper Nginx syntax including quotes.
:::

### Custom Headers

For more control over HTTP headers, use the `headers` directive:

```yaml title="zerops.yaml"
run:
  routing:
    headers:
      - for: "/"
        values:
          # All values need proper quoting since they're inserted directly into Nginx
          X-Frame-Options: "'DENY'"

          # Values with internal quotes need proper YAML escaping
          Content-Security-Policy: '"default-src ''self''"'
```

:::important
Header values are inserted directly into the Nginx configuration **without** additional quotes, which means:

1. **All values must include their own quotes** (typically single quotes)
2. If you need single quotes inside your header value, you must escape them in YAML (using double single quotes)
3. To include the `always` directive, add it after your quoted value
4. For complex values, you can use YAML's block scalar notation (`>-`) for better readability
:::

Here are examples for different header scenarios:

```yaml title="zerops.yaml"
headers:
  - for: "/"
    values:
      # Simple header with proper quoting
      X-Frame-Options: "'DENY'"

      # Header with 'always' directive
      X-XSS-Protection: "'1; mode=block' always"

      # Header with internal single quotes - need double single quotes for escaping
      Content-Security-Policy: '"default-src ''self'' https://cdn.example.com"'

      # Complex header with block scalar notation for better readability
      Content-Security-Policy: >-
        "default-src 'self' https://cdn.example.com;
        script-src 'self' 'unsafe-inline';
        img-src * data:" always
```

When this configuration is processed, it translates to the following Nginx directives:

```
add_header X-Frame-Options 'DENY';
add_header X-XSS-Protection '1; mode=block' always;
add_header Content-Security-Policy "default-src 'self' https://cdn.example.com";
add_header Content-Security-Policy "default-src 'self' https://cdn.example.com; script-src 'self' 'unsafe-inline'; img-src * data:" always;
```

:::important Path Handling
When you specify headers for a path that doesn't have an existing location block, the Static service automatically creates a location with the same [default behavior](#default-behavior) as the root path (trying files in order: `$uri`, `$uri.html`, `$uri/index.html`, `/index.html` or returning 404).

If you add headers for a path that already has a location block, your headers will be merged with the existing configuration.
:::

### Combining CORS and Custom Headers

You can use both CORS and custom headers together:

```yaml title="zerops.yaml"
run:
  routing:
    cors: "'*' always"
    headers:
      - for: "/"
        values:
          X-Frame-Options: "'DENY'"
```

The `cors` directive sets default Access-Control headers for all routes, while the `headers` directive allows you to set additional headers for specific paths.

:::important
If you specify Access-Control headers in the `headers` directive, they will override the ones set by `cors` for that specific path.
:::

## SEO with Prerender

Single Page Applications render content with JavaScript, which most crawlers can't process—they see an empty page instead of your content. This affects traditional search engines, social media platforms, and AI tools like ChatGPT, Perplexity, and Claude.

The Static service includes built-in support for Prerender.io, which automatically detects crawlers and serves them pre-rendered HTML while your users get the full interactive experience.

### Setup

1. Set the `PRERENDER_TOKEN` secret variable with your Prerender.io token
2. The service automatically configures necessary rewrites based on user agents

### Custom Prerender Host

If you're using a custom Prerender host, add it to environment variables in `zerops.yaml`:

```yaml title="zerops.yaml"
run:
  envVariables:
  - PRERENDER_HOST=your.prerender.host
```

:::note Default
The default host is `service.prerender.io` if not specified.
:::

## Framework Integration

The Static service handles static builds from any modern framework. Here's the typical deployment pattern:

```yaml title="zerops.yaml"
zerops:
  - setup: app
    build:
      base: nodejs@20
      buildCommands:
        - npm install
        - npm run build
      deployFiles:
        - dist/~  # Your framework's output directory
    run:
      base: static
```

The key is pointing `deployFiles` to wherever your framework outputs its built files (`dist/`, `build/`, `.output/public/`, etc.).

This configuration:
1. Uses Node.js for building the application
2. Installs dependencies and builds the application
3. Deploys the resulting static files to the Static service

You can enhance this basic setup with:
- Custom redirects for URL management
- Prerender.io integration for SEO
- Additional routing rules as needed

For framework-specific examples, check out our [recipe collection](https://github.com/zeropsio/recipe-analog-static).

## Advanced Topics

### Switching to Full Nginx

If you need more control over your Nginx configuration:

1. Go to your Static service overview in the UI
2. Click the three vertical dots in the left panel
3. Select **Need to switch to full Nginx service?**
4. Copy the generated Nginx configuration
5. Use this configuration as a starting point for a full Nginx service

:::tip
This allows you to move to a more customizable setup while maintaining your existing routing logic.
:::

### Complex Multi-Domain Setups

For advanced scenarios involving multiple domains and complex routing:

```yaml title="zerops.yaml"
run:
  routing:
    redirects:
      # Product-specific domain
      - from: https://product-promo.com/*
        to: https://main-site.com/products
        status: 302

      # Campaign domain
      - from: https://special-offer.com/*
        to: https://main-site.com/campaign
        status: 302

      # Legacy domains and subdomains
      - from: https://*.legacy-domain.com/*
        to: https://main-site.com
        status: 302
```

## Complete Examples

### Development Setup

Configuration for local development with CORS and API proxying:

```yaml title="zerops.yaml"
run:
  routing:
    # CORS with proper quoting
    cors: "'*' always"
    redirects:
      # API requests
      - from: /api/*
        to: https://api.your-domain.com
        status: 302
```

### Production Setup with Security

Security-enhanced configuration for production environments:

```yaml title="zerops.yaml"
run:
  routing:
    headers:
      # Custom headers for default location
      - for: "/*"
        values:
          X-Frame-Options: "'DENY' always"
          X-Content-Type-Options: "'nosniff' always"
          # Note the proper escaping of single quotes
          Content-Security-Policy: '"default-src ''self''" always'
```

----------------------------------------

# Typesense > Overview


Zerops provides a fully managed [Typesense search engine](https://typesense.org/) service that combines developer productivity with enterprise-grade reliability. The platform handles infrastructure complexity through automated deployment, scaling, and maintenance while providing developers full access to Typesense's native capabilities.

## Supported Versions

Currently supported Typesense version:

Import configuration version:

- `typesense@27.1`

## Service Configuration

Our Typesense implementation comes with carefully tuned defaults that diverge from the [standard Typesense configuration](https://typesense.org/docs/27.1/api/server-configuration.html#using-command-line-arguments) in the following ways:

```yaml
thread-pool-size: 16
num-collections-parallel-load: 8
```

These defaults are optimized for most common use cases and managed by the platform. If you need to adjust these settings, please contact us through our [support channels](#support).

### Data Persistence

Typesense data is automatically persisted to disk at `/var/lib/typesense`.

This ensures that data remains intact during service restarts (Typesense automatically reloads the persisted data into memory upon startup).

This persistence mechanism works in both HA and non-HA deployment modes, though with different reliability guarantees as detailed below.

### Deployment Modes

:::warning
The choice between HA and non-HA mode must be made during service creation and cannot be changed later. Make sure to carefully consider your requirements before deploying.
:::

#### Non-HA Mode
- Suitable for development and testing
- Data persistence not guaranteed during node failures
- Lower resource requirements

#### HA Mode
- Implements Typesense's native [**Raft consensus**](https://typesense.org/docs/guide/high-availability.html) mechanism for data replication
- Deploys as a **3-node cluster by default** for optimal reliability
  - Scaling configuration of 3-5 or 3-7 nodes for higher workloads is possible upon request (contact [support](#support) to configure custom node ranges)
- Includes **built-in data synchronization** across all nodes
- Features **automatic leader election** to maintain cluster availability
  - Recovery typically takes up to 1 minute during node failures or leader transitions
  - During these periods, requests may temporarily receive `503 Not Ready or Lagging` or `500 Could not find a leader` responses
  - These states automatically resolve once consensus is reestablished

### API Key Management

The master API key is automatically generated and managed by the platform. You can access it through:
- The service access details in the Zerops GUI
- The `apiKey` environment variable in your service configuration

:::warning
Currently, as a security-focused design decision, the master API key cannot be modified after generation.
:::

### CORS Configuration

Your Typesense instance comes with CORS enabled by default, ensuring seamless integration with frontend applications. Browser-based clients can directly access the instance by providing the `X-Typesense-Api-Key` header, maintaining security while enabling straightforward client-side implementation.

## Network Architecture & Access Patterns

### Access Methods

#### HTTPS Access

When using HTTPS access (either through Zerops subdomain or custom domain), traffic is distributed across nodes via our integrated Nginx proxy layer. This provides a single access point that handles load balancing automatically.

For enabling HTTPS access:
1. Configure through the [Zerops access documentation](/features/access)
2. Or use `enableSubdomainAccess: true` when [importing](/references/import#service-configuration) a Typesense service

#### Direct Node Access

Allows to access individual nodes using internal DNS:
1. **Via [Zerops VPN](/references/networking/vpn)**
2. **Internal Project Access** - services within the same project can reach nodes directly

Node addressing patterns:
##### Standard format
**Format:**```node{n}.db.{hostname}.zerops```
- e.g. `node1.db.typesenseha.zerops`, `node2.db.typesenseha.zerops`
##### Stable DNS records
**Format:**```node-stable-{n}.db.{hostname}.zerops```
- **maintain consistent IP mapping** until node retirement (scaling down or failure events)
- e.g. `node-stable-1.db.typesenseha.zerops`, `node-stable-2.db.typesenseha.zerops`

## Quick Start Example

Here's a simple example of using Typesense with the JavaScript client:

```javascript

const client = new TypesenseClient({
  nodes: [{
    host: 'your-service.zerops.dev', // Your Zerops subdomain
    port: '443',
    protocol: 'https'
  }],
  apiKey: process.env.TYPESENSE_API_KEY,
  connectionTimeoutSeconds: 2
})

// Create a collection
await client.collections().create({
  name: 'companies',
  fields: [
    { name: 'company_name', type: 'string' },
    { name: 'num_employees', type: 'int32' },
    { name: 'country', type: 'string', facet: true }
  ],
  default_sorting_field: 'num_employees'
})

// Example search query
const searchResults = await client.collections('companies')
  .documents()
  .search({
    q: 'tech',
    query_by: 'company_name',
    filter_by: 'country:=USA',
    sort_by: 'num_employees:desc'
  })
```

## Best Practices

#### API Key Security
- Never expose the master API key in client-side code
- Generate scoped search-only API keys for frontend applications
- Rotate API keys periodically through your service configuration

#### High Availability
- Implement retry logic in clients for handling temporary unavailability
- Use stable DNS records for direct node access when needed

#### Performance Optimization
- Utilize batch operations for bulk updates
- Configure appropriate timeout values based on your use case
- Consider data volume when designing collection schemas

## Support

For advanced configurations or custom requirements:
- Join our [Discord community](https://discord.gg/zeropsio)
- Contact support via [email](mailto:support@zerops.io)

----------------------------------------

# Ubuntu > How To > Build Pipeline


Zerops provides a customizable build and runtime environment for your Ubuntu application.

## Add zerops.yaml to your repository

Start by adding `zerops.yaml` file to the **root of your repository** and modify it to fit your application:

```yaml
zerops:
  # define hostname of your service
  - setup: app
    # ==== how to build your application ====
    build:
      # REQUIRED. Set the base technology for the build environment:
      base: ubuntu@24.04

      # OPTIONAL. Customize the build environment by installing additional packages
      # or tools to the base build environment.
      prepareCommands:
        - sudo apt-get something
        - curl something else

      # OPTIONAL. Build your application, e.g. with not officially supported version of your favourite technology
      buildCommands:
        - go build -o app main.go
      # REQUIRED. Select which files / folders to deploy after
      # the build has successfully finished
      deployFiles: app

      # OPTIONAL. Which files / folders you want to cache for the next build.
      # Next builds will be faster when the cache is used.
      cache: some_file

    # ==== how to run your application ====
    run:
      # OPTIONAL. Sets the base technology for the runtime environment:
      base: ubuntu@24.04

      # OPTIONAL. Sets the internal port(s) your app listens on:
      ports:
        # port number
        - port: 8080

      # OPTIONAL. Customize the runtime Ubuntu environment by installing additional
      # dependencies to the base Ubuntu runtime environment.
      prepareCommands:
        - sudo apt-get something
        - curl something else

      # OPTIONAL. Run one or more commands each time a new runtime container
      # is started or restarted. These commands are triggered before
      # your Ubuntu application is started.
      initCommands:
       - rm -rf ./cache

      # REQUIRED. Your Ubuntu application start command
      start: ./app
```

The top-level element is always `zerops`.

### Setup

The first element `setup` contains the **hostname** of your service. A runtime service with the same hostname must exist in Zerops.
Zerops supports the definition of multiple runtime services in a single `zerops.yaml`. This is useful when you use a monorepo. Just add multiple setup elements in your `zerops.yaml`:

```yaml
zerops:
  # definition for app service
  - setup: app
    # optional
    build: ...
    # optional
    deploy: ...
    # required
    run: ...

  # definition for api service
  - setup: api
    # optional
    build: ...
    # optional
    deploy: ...
    # required
    run: ...
```

Each service configuration contains at least the `run` section. Optional `build` and `deploy` sections can be added to further customize your process.

## Build pipeline configuration

### base

_REQUIRED._ Sets the base technology for the build environment.

Following options are available for Ubuntu builds:

- `ubuntu@24.04`
- `ubuntu@22.04`, `ubuntu@latest`

```yaml
zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build:
      # REQUIRED. Sets the base technology for the build environment:
      base: ubuntu@24.04
      ...
```

<p>
  The base build environment contains {data.ubuntu.default}, [Zerops command line tool](/references/cli), `git` and `wget`.
</p>

:::info
You can change the base environment when you need to. Just simply modify the `zerops.yaml` in your repository.
:::

If you need to install more technologies to the build environment, set multiple values as a yaml array. For example:

```yaml
zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build:
      # REQUIRED. Sets the base technology for the build environment:
      base:
        - ubuntu@24.04
      prepareCommands:
        - zsc add nodejs@latest
      ...
```

See the full list of supported [build base environments](/zerops-yaml/base-list#runtime-services).

To customize your build environment use the [prepareCommands](#preparecommands) attribute.

:::note
Modifying the base technology will invalidate your build cache. See our [Build Cache Documentation](/features/build-cache) for more details about cache invalidation.
:::

### prepareCommands

_OPTIONAL._ Customizes the build environment by installing additional dependencies or tools to the base build environment.

The base build environment contains:

- <span>{data.ubuntu.default}</span>
- [Zerops command line tool](/references/cli)
- `git` and `wget`

To install additional packages or tools add one or more prepare commands:

```yaml
zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build:
      # REQUIRED. Set the base technology for the build environment:
      base: ubuntu@24.04

      # OPTIONAL. Customize the build environment by installing additional packages
      # or tools to the base build environment.
      prepareCommands:
        - sudo apt-get something
        - curl something else
      ...
```

When the first build is triggered, Zerops will

1. create a build container
2. download your application code from your repository
3. run the prepare commands in the defined order

The application code is available in `/build/source` before the prepare commands are triggered, so you can use any file from your repository in your prepare commands (e.g. a configuration file). The commands themselves run in the `/home/zerops` directory.

:::note
These commands are skipped when using cached environment. Modifying `prepareCommands` will invalidate your build cache. See our [Build Cache Documentation](/features/build-cache) for details about cache invalidation.
:::

#### Command exit code

If any command fails, it returns an exit code other than 0 and the build is canceled. Read the [build log](/ubuntu/how-to/logs#build-log) to troubleshoot the error. If the command ends successfully, it returns the exit code 0 and Zerops triggers the following command. When all prepare commands are finished, your custom build environment is ready for the build phase.

#### Single or separated shell instances

You can configure your prepare commands to be run in a single shell instance or multiple shell instances. The format is identical to [build commands](#buildcommands).

### buildCommands

_OPTIONAL._ Defines build commands.

```yaml
zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build:
      # REQUIRED. Set the base technology for the build environment:
      base: ubuntu@24.04

      # OPTIONAL. Build your application
      buildCommands:
        - <your build commands>
      ...
```

Build commands are optional. Zerops triggers each command in the defined order in a dedicated build container, running from the `/build/source` directory.

Before the build commands are triggered the build container contains:

1. base environment defined by the [base](#base) attribute
2. optional customisation of the base environment defined in the [prepareCommands](#preparecommands) attribute
3. your application code

For detailed information about build commands, including how to run commands in single or separate shell instances and command exit code handling, refer to the documentation for your specific technology (e.g., [Node.js](/nodejs/how-to/build-pipeline), [Go](/ubuntu/how-to/build-pipeline), [Python](/python/how-to/build-pipeline), etc.).

### deployFiles

_REQUIRED._ Selects which files or folders will be deployed after the build has successfully finished. To filter out specific files or folders, use [`.deployignore`](#deployignore) file.

```yaml
# REQUIRED. Select which files / folders to deploy after
# the build has successfully finished
deployFiles:
  - app
```

Determines files or folders produced by your build, which should be deployed to your runtime service containers.

The path starts from the **root directory** of your project (the location of `zerops.yaml`). You must enclose the name in quotes if the folder or the file name contains a space.

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

#### Examples

Deploys a folder, and a file from the project root directory:

```yaml
deployFiles:
  - app
  - file.txt
```

Deploys the whole content of the build container:

```yaml
deployFiles: .
```

Deploys a folder, and a file in a defined path:

```yaml
deployFiles:
  - ./path/to/file.txt
  - ./path/to/dir/
```

#### How to use a wildcard in the path

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

Deploys all folders that are located in any path that begins with `/path/to/`

```yaml
deployFiles: ./path/to/~/
```

Deploys all folders that are located in any path that begins with `/path/` and ends with `/to/`

```yaml
deployFiles: ./path/~/to/
```

:::note Example
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 will be cached for the next build.

```yaml
# OPTIONAL. Which files / folders you want to cache for the next build.
# Next builds will be faster when the cache is used.
cache: file.txt
```

The cache attribute helps optimize build times by preserving specified files between builds.

The cache attribute supports the [~ wildcard character](#how-to-use-a-wildcard-in-the-path).

Learn more about the [build cache system](/features/build-cache) in Zerops.

### envVariables

_OPTIONAL._ Defines the environment variables for the build environment.

Enter one or more env variables in following format:

```yaml
zerops:
  # define hostname of your service
  - setup: app
    # ==== how to build your application ====
    build:
      base: ubuntu@24.04
        …

      # OPTIONAL. Defines the env variables for the build environment:
      envVariables:
        MODE: production
        DB_NAME: db
        DB_HOST: db
        DB_USER: db
        DB_PASS: ${db_password}
```

Read more about [environment variables](/ubuntu/how-to/env-variables) in Zerops.

## Runtime configuration

### base

_OPTIONAL._ Sets the base technology for the runtime environment.
If you don't specify the `run.base` attribute, Zerops keeps the current Ubuntu version for your runtime.

Following options are available for Ubuntu builds:

- `ubuntu@24.04`
- `ubuntu@22.04`, `ubuntu@latest`

```yaml
zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build:
      # REQUIRED. Sets the base technology for the build environment:
      base: ubuntu@24.04
      ...

    # ==== how to run your application ====
    run:
      # OPTIONAL. Sets the base technology for the runtime environment:
        base: ubuntu@24.04
      ...
```

<p>
  The base runtime environment contains {data.ubuntu.default}, Zerops command line tool, `git` and `wget`.
</p>

:::info
You can change the base environment when you need to. Just simply modify the `zerops.yaml` in your repository.
:::

If you need to install more technologies to the runtime environment, set multiple values as a yaml array. For example:

```yaml
zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build:
      # REQUIRED. Sets the base technology for the build environment:
      base: ubuntu@24.04
      ...

    # ==== how to run your application ====
    run:
      # OPTIONAL. Sets the base technology for the runtime environment:
      base:
        - ubuntu@24.04
      prepareCommands:
        - zsc add nodejs@latest
      ...
```

See the full list of supported [run base environments](/zerops-yaml/base-list).

To customise your build environment use the `prepareCommands` attribute.

### ports

_OPTIONAL._ Specifies one or more internal ports on which your application will listen.

Projects in Zerops represent a group of one or more services. Services can be of different types (runtime services, databases, message brokers, object storage, etc.). All services of the same project share a **dedicated private network**. To connect to a service within the same project, just use the service hostname and its internal port.

For example, to connect to a Ubuntu service with hostname = "app" and port = 8080 from another service of the same project, simply use `app:8080`. Read more about [how to access a Ubuntu service](/references/networking/internal-access#basic-service-communication).

Each port has following attributes:

<table className="w-full my-1.5">
  <thead>
    <tr>
      <th className="w-fit"><strong>Parameter</strong></th>
      <th className="w-fit"><strong>Description</strong></th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td className="w-fit">port</td>
      <td className="w-fit">Defines the port number. You can set any port number between <em>10</em> and <em>65435</em>. Ports outside this interval are reserved for internal Zerops systems.</td>
    </tr>
    <tr>
      <td className="w-fit">protocol</td>
      <td className="w-fit"><strong>Optional.</strong> Defines the protocol. Allowed values are <code>TCP</code> or <code>UDP</code>. Default value is <code>TCP</code>.</td>
    </tr>
    <tr>
      <td className="w-fit">httpSupport</td>
      <td className="w-fit"><strong>Optional.</strong> <code>httpSupport = true</code> is the default setting for TCP protocol. Set <code>httpSupport = false</code> if a web server isn't running on the port. Zerops uses this information for the configuration of [public access](/features/access). <code>httpSupport = true</code> is available only in combination with the TCP protocol.</td>
    </tr>
  </tbody>
</table>

### prepareCommands

_OPTIONAL._ Customises the Ubuntu runtime environment by installing additional dependencies or tools to the runtime base environment.

<p>
  The base Ubuntu environment contains {data.ubuntu.default}, [Zerops command line tool](/references/cli) and `git` and `wget`. To install additional packages or tools add one or more prepare commands:
</p>

```yaml
zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build:
      ...

    # ==== how to run your application ====
    run:
      # OPTIONAL. Customise the runtime environment by installing additional packages
      # or tools to the base Ubuntu runtime environment.
      prepareCommands:
        - sudo apt-get something
        - curl something else
      ...
```

When the first deploy with a defined prepare attribute is triggered, Zerops will

1. create a prepare runtime container
2. optionally: [copy selected folders or files from your build container](#copy-folders-or-files-from-your-build-container)
3. run the `prepareCommands` commands in the defined order

:::note
`run.prepareCommands` run in the `/home/zerops` directory.
:::

#### Command exit code

If any command fails, it returns an exit code other than 0 and the deploy is canceled. Read the [prepare runtime log](/ubuntu/how-to/logs#prepare-runtime-log) to troubleshoot the error. If the command ends successfully, it returns the exit code 0 and Zerops triggers the following command. When all `prepareCommands` commands are finished, your custom runtime environment is ready for the deploy phase.

#### Cache of your custom runtime environment

Some packages or tools can take a long time to install. Therefore, Zerops caches your custom runtime environment after the installation of your custom packages or tools is completed. When the second or following deploy is triggered, Zerops will use the custom runtime cache from the previous deploy if following conditions are met:

1. Content of the [build.addToRunPrepare](#copy-folders-or-files-from-your-build-container) and `run.prepareCommands` attributes didn't change from the previous deploy
2. The custom runtime cache wasn't invalidated in the Zerops GUI.

To invalidate the Zerops runtime cache go to your service detail in Zerops GUI, choose **Service dashboard & runtime containers** from the left menu and click on the **Open pipeline detail** button. Then click on the **Clear runtime prepare cache** button.

When the prepare cache is used, Zerops doesn't create a prepare runtime container and executes the deployment of your application directly.

#### Single or separated shell instances

You can configure your prepare commands to be run in a single shell instance or multiple shell instances. The format is identical to [build commands](#buildcommands).

### Copy folders or files from your build container

<p>
  The prepare runtime container contains {data.ubuntu.default}, [Zerops command line tool](/references/cli) and `git` and `wget`.
</p>

The prepare runtime container does not contain your application code nor the built application. If you need to copy some folders or files from the build container to the runtime container (e.g. a configuration file) use the `addToRunPrepare` attribute in the [build section](#build-pipeline-configuration).

```yaml
zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build:
      ...
      addToRunPrepare: ./runtime-config.yaml

    # ==== how to run your application ====
    run:
      # OPTIONAL. Customise the runtime environment by installing additional packages
      # or tools to the base Ubuntu runtime environment.
      prepareCommands:
        - sudo apt-get something
        - curl something else
      ...
```

In the example above Zerops will copy the `runtime-config.yaml` file from your build container **after the build has finished** into the new **prepare runtime** container. The copied files and folders will be available in the `/home/zerops` folder in the new prepare runtime container before the prepare commands are triggered.

### initCommands

_OPTIONAL._ Defines one or more commands to be run each time a new runtime container is started or a container is restarted.

```yaml
zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build: ...

    # ==== how to run your application ====
    run:
      # OPTIONAL. Run one or more commands each time a new runtime container
      # is started or restarted. These commands are triggered before
      # your Ubuntu application is started.
      initCommands:
        - rm -rf ./cache
```

These commands are triggered in the runtime container before your Ubuntu application is started via the [start command](#start).

:::note
`run.initCommands` run in the `/var/www` directory.
:::

Use init commands to clean or initialise your application cache or similar operations.

:::caution
The init commands will delay the start of your application each time a new runtime container is started (including the horizontal [scaling](/ubuntu/how-to/scaling) or when a runtime container is restarted).

Do not use the init commands for customising your runtime environment. Use the [run:prepareCommands](#preparecommands-1) attribute instead.
:::

#### Command exit code

If any of the `initCommands` fails, it returns an exit code other than 0, but deploy is **not** canceled. After all init commands are finished, regardless of the status code, the application is started. Read the [runtime log](/ubuntu/how-to/logs#runtime-log) to troubleshoot the error.

#### Single or separated shell instances

You can configure your `initCommands` to be run in a single shell instance or multiple shell instances. The format is identical to [build commands](#buildcommands).

### envVariables

_OPTIONAL._ Defines the environment variables for the runtime environment.

Enter one or more env variables in following format:

```yaml
zerops:
  # define hostname of your service
  - setup: app
    # ==== how to run your application ====
    run:
      # OPTIONAL. Defines the env variables for the runtime environment:
      envVariables:
        MODE: production
        DB_NAME: db
        DB_HOST: db
        DB_USER: db
        DB_PASS: ${db_password}
```

Read more about [environment variables](/ubuntu/how-to/env-variables) in Zerops.

### start

_OPTIONAL._ Defines the start command for your Ubuntu application.

```yaml
zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build: ...

    # ==== how to run your application ====
    run:
      # OPTIONAL. Your Ubuntu application start command
      start: ./app
```

### health check

_OPTIONAL._ Defines a health check.

`healthCheck` requires either one `httpGet` object or one `exec` object.

#### httpGet

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

Following attributes are available:

<table className="w-full my-1.5">
  <thead>
    <tr>
      <th className="w-fit whitespace-nowrap">Parameter</th>
      <th className="w-fit whitespace-nowrap">Description</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td className="w-fit whitespace-nowrap font-semibold">port</td>
      <td>Defines the port of the HTTP GET request.
The readiness check will trigger a GET request on <code>{'http://127.0.0.1:{port}/{path}'}</code></td>
    </tr>
    <tr>
      <td className="w-fit whitespace-nowrap font-semibold">path</td>
      <td>Defines the URL path of the HTTP GET request.
The readiness check will trigger a GET request on <code>{'http://127.0.0.1:{port}/{path}'}</code></td>
    </tr>
    <tr>
      <td className="w-fit whitespace-nowrap font-semibold">host</td>
      <td><strong>Optional.</strong> The readiness check is triggered from inside of your runtime container so it always uses the localhost <code>127.0.0.1</code>. If you need to add a <code>host</code> to the request header, specify it in the <code>host</code> attribute.</td>
    </tr>
    <tr>
      <td className="w-fit whitespace-nowrap font-semibold">scheme</td>
      <td><strong>Optional.</strong> The readiness check is triggered from inside of your runtime container so no https is required.
If your application requires a https request, set <code>scheme: https</code></td>
    </tr>
  </tbody>
</table>

**Example:**

```yaml
zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build: ...

    # ==== how to run your application ====
    run:
      # OPTIONAL. Your Ubuntu application start command
      start: ./app

      # OPTIONAL. Define a health check with a HTTP GET request option.
      # Configures the check on http://127.0.0.1:80/status
      healthCheck:
        httpGet:
          port: 80
          path: /status
```

#### exec

Configures the health check to run a local command.
Following attributes are available:

<table className="w-full my-1.5">
  <thead>
    <tr>
      <th className="w-fit"><strong>Parameter</strong></th>
      <th className="w-fit"><strong>Description</strong></th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td className="w-fit"><strong>command</strong></td>
      <td className="w-fit">
        Defines a local command to be run.

        The command has access to the same [environment variables](/ubuntu/how-to/create#set-secret-environment-variables) as your Ubuntu application.

        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 below.
      </td>
    </tr>
  </tbody>
</table>

**Example:**

```yaml
zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build: ...

    # ==== how to run your application ====
    run:
      # REQUIRED. Your Ubuntu application start command
      start: ./app

      # OPTIONAL. Define a health check with a shell command.
      healthCheck:
        exec:
          command: |
            touch grass
            rm -rf life
            mv /outside/user /home/user
```

### crontab

_OPTIONAL._ Defines cron jobs.

Setup cron jobs in the following format:

```yaml
zerops:
  # define hostname of your service
  - setup: app

    # ==== how to run your application ====
    run:
      crontab:
        # REQUIRED. Sets the command to execute:
        - command: ""
        # REQUIRED. Sets the interval time to execute:
          timing: "0 * * * *"
```

Read more about setting up [cron](/zerops-yaml/cron) in Zerops.

## Deploy configuration

### readiness check

_OPTIONAL._ Defines a readiness check. Read more about how the [readiness check works](/ubuntu/how-to/deploy-process#readiness-checks) in Zerops.

`readinessCheck` requires either one `httpGet` object or one `exec` object.

#### httpGet

Configures the readiness check to request a local URL using a http GET method.

Following attributes are available:

<table className="w-full my-1.5">
  <thead>
    <tr>
      <th className="w-fit whitespace-nowrap">Parameter</th>
      <th className="w-fit whitespace-nowrap">Description</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td className="w-fit whitespace-nowrap font-semibold">port</td>
      <td>Defines the port of the HTTP GET request.
The readiness check will trigger a GET request on <code>{'http://127.0.0.1:{port}/{path}'}</code></td>
    </tr>
    <tr>
      <td className="w-fit whitespace-nowrap font-semibold">path</td>
      <td>Defines the URL path of the HTTP GET request.
The readiness check will trigger a GET request on <code>{'http://127.0.0.1:{port}/{path}'}</code></td>
    </tr>
    <tr>
      <td className="w-fit whitespace-nowrap font-semibold">host</td>
      <td><strong>Optional.</strong> The readiness check is triggered from inside of your runtime container so it always uses the localhost <code>127.0.0.1</code>. If you need to add a <code>host</code> to the request header, specify it in the <code>host</code> attribute.</td>
    </tr>
    <tr>
      <td className="w-fit whitespace-nowrap font-semibold">scheme</td>
      <td><strong>Optional.</strong> The readiness check is triggered from inside of your runtime container so no https is required.
If your application requires a https request, set <code>scheme: https</code></td>
    </tr>
  </tbody>
</table>

**Example:**

```yaml
zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build: ...

    # ==== how to deploy your application ====
    deploy:
      # OPTIONAL. Define a readiness check with a HTTP GET request option.
      # Configures the check on http://127.0.0.1:80/status
      readinessCheck:
        httpGet:
          port: 80
          path: /status

    # ==== how to run your application ====
    run: ...
```

Read more about how the [readiness check works](/ubuntu/how-to/deploy-process#readiness-checks) in Zerops.

#### exec

Configures the readiness check to run a local command.
Following attributes are available:

<table className="w-full my-1.5">
  <thead>
    <tr>
      <th className="w-fit"><strong>Parameter</strong></th>
      <th className="w-fit"><strong>Description</strong></th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td className="w-fit"><strong>command</strong></td>
      <td className="w-fit">
        Defines a local command to be run.

        The command has access to the same [environment variables](/ubuntu/how-to/create#set-secret-environment-variables) as your Ubuntu application.

        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 below.
      </td>
    </tr>
  </tbody>
</table>

**Example:**

```yaml
zerops:
  # hostname of your service
  - setup: app
    # ==== how to build your application ====
    build: ...

    # ==== how to deploy your application ====
    deploy:
      # OPTIONAL. Define a readiness check with a HTTP GET request option.
      # Configures the check on http://127.0.0.1:80/status
      readinessCheck:
        exec:
          command: |
            touch grass
            rm -rf life
            mv /outside/user /home/user
```

Read more about how the [readiness check works](/ubuntu/how-to/deploy-process#readiness-checks) in Zerops.


----------------------------------------

# Ubuntu > How To > Build Process


## Build process overview

Zerops starts a temporary build container and performs the following actions:

1. **Installs the build environment** - Sets up base system and  runtime
2. **Downloads your application source code** - From [GitHub ↗](https://www.github.com), [GitLab ↗](https://www.gitlab.com) or via [Zerops CLI](/references/cli)
3. **Optionally customizes the build environment** - Runs prepare commands if configured
4. **Runs the build commands** - Executes your build process
5. **Uploads the application artifact** - Stores build output to internal Zerops storage
6. **Caches selected files** - Preserves specified files for faster future builds

The build container is automatically deleted after the build has finished or failed.

## Build configuration

Configure your  build process in your `zerops.yaml` file according to the  pipeline guide</VarLink>.

## Build environment

### Default  build environment

The default  build environment contains:

- <span>{data.ubuntu.default}</span>
- [zCLI](/references/cli), Zerops command line tool
-

### Customize build environment

To install additional packages or tools, add one or more  to your `zerops.yaml`.

:::info
The application code is available in the `/build/source` folder in your build container before the prepare commands are triggered. This allows you to use any file from your application code in your prepare commands (e.g. a configuration file).
:::

### Build hardware resources

All runtime services use the same hardware resources for build containers:

<table className="w-fit my-1.5">
  <thead>
    <tr className="text-center rounded-lg">
      <th className="w-fit"><strong>HW resource</strong></th>
      <th className="w-fit"><strong>Minimum</strong></th>
      <th className="w-fit"><strong>Maximum</strong></th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td className="w-fit font-semibold">CPU cores</td>
      <td className="w-fit">1</td>
      <td className="w-fit">5</td>
    </tr>
    <tr>
      <td className="w-fit font-semibold">RAM</td>
      <td className="w-fit">8 GB</td>
      <td className="w-fit">8 GB</td>
    </tr>
    <tr>
      <td className="w-fit font-semibold">Disk</td>
      <td className="w-fit">1 GB</td>
      <td className="w-fit">100 GB</td>
    </tr>
  </tbody>
</table>

Build containers start with minimum resources and scale vertically up to maximum capacity as needed.

### Build time limit

The time limit for the whole build pipeline is **1 hour**. After 1 hour, Zerops will terminate the build pipeline and delete the build container.

:::info
Build container resources are not charged separately. Limited build time is included in your [project core plan](/company/pricing#project-core-plans), with additional build time available if needed.
:::

## Troubleshooting  builds

:::tip Advanced troubleshooting
For complex build issues that require investigation, you can enable [debug mode](/features/debug-mode) to pause the build process at specific points and inspect the build container state interactively.
:::

### Build and prepare command failures

If any  or  fails (returns non-zero exit code), the build is canceled. Check the  to troubleshoot the error.

### Build cache issues

If you encounter unexpected build behavior or dependency issues, the problem might be related to cached build data. While Zerops maintains the build cache to speed up deployments, sometimes you may need to start fresh.

To invalidate the build cache:

1. Go to your service detail in Zerops GUI
2. Choose **Pipelines & CI/CD Settings** from the left menu
3. Click on the **Invalidate build cache** button

This will force Zerops to run the next build clean, including all prepare commands.

Learn more about [build cache behavior](/features/build-cache).

## More resources

For more details about the build and deploy pipeline, including how to cancel builds and manage application versions, see the [general pipeline documentation](/features/pipeline).

## Next steps

- Understand the
- Learn how to
- Explore

----------------------------------------

# Ubuntu > How To > Controls



----------------------------------------

# Ubuntu > How To > Create


Zerops provides a Ubuntu runtime service with extensive build support. Ubuntu runtime is highly scalable and customisable to suit both development and production.

## Create Ubuntu service using Zerops GUI

First, set up a project in Zerops GUI. Then go to the project dashboard page and choose **Add new service** in the left menu in the **Services** block. Then add a new Ubuntu service:

[Video: /vids/services/golang.webm](/vids/services/golang.webm)

### Choose Ubuntu version

Following Ubuntu versions are currently supported:

:::info
You can [change](/ubuntu/how-to/upgrade) the major version at any time later.
:::

### Set a hostname

Enter a unique service identifier like "app","cache", "gui" etc. Duplicate services with the same name in the same project are forbidden.

#### Limitations:

- maximum 25 characters
- must contain only lowercase ASCII letters (a-z) or numbers (0-9)

:::caution
The hostname is fixed after the service is created. It can't be changed later.
:::

### Set secret environment variables

Add environment variables with sensitive data, such as password, tokens, salts, certificates etc. These will be securely saved inside Zerops and added to your runtime service upon start.

Setting the secret environment variables is optional. You can set them later in Zerops GUI.

Read more about [different types of env variables](/ubuntu/how-to/env-variables#service-env-variables) in Zerops.

## Create Ubuntu service using zCLI

zCLI is the Zerops command-line tool. To create a new Ubuntu service via the command-line, follow these steps:

1. [Install & setup zCLI](/references/cli)
2. [Create a project description file](/ubuntu/how-to/create#create-a-project-description-file)
3. [Create a project with a Ubuntu and PostgreSQL service](#full-example)

### Create a project description file

Zerops uses a yaml format to describe the project infrastructure.

#### Basic example:

Create a directory `my-project`. Create an `description.yaml` file inside the `my-project` directory with following content:

```yaml
# basic project data
project:
  # project name
  name: my-project
# array of project services
services:
  - # service name
    hostname: app
    # service type and version number in ubuntu@{version} format
    type: ubuntu@24.04
    # defines the minimum number of containers for horizontal autoscaling
    minContainers: 1
    # defines the maximum number of containers for horizontal autoscaling. Max value = 6.
    maxContainers: 6
    # optional: create env variables
    envSecrets:
      S3_ACCESS_KEY_ID: 'P8cX1vVVb'
      S3_ACCESS_SECRET: 'ogFthuiLYki8XoL73opSCQ'
```

The yaml file describes your future project infrastructure. The project will contain one Ubuntu service with default [auto scaling](/ubuntu/how-to/scaling) configuration. Hostname will be set to "app", the internal port(s) the service listens on will be defined later in the [zerops.yaml](/ubuntu/how-to/build-pipeline#ports). Following secret env variables will be configured:

```env
S3_ACCESS_KEY_ID="P8cX1vVVb"
S3_ACCESS_SECRET="ogFthuiLYki8XoL73opSCQ"
```

#### Full example:

Create a directory my-project. Create an description.yaml file inside the my-project directory with following content:

```yaml
# basic project data
project:
  # project name
  name: my-project
  # optional: project description
  description: A project with a Ubuntu and PostgreSQL database
  # optional: project tags
  tags:
    - DEMO
    - ZEROPS
# array of project services
services:
  - # service name
    hostname: app
    # service type and version number in ubuntu@{version} format
    type: ubuntu@24.04
    # optional: vertical auto scaling customization
    verticalAutoscaling:
      cpuMode: DEDICATED
      minCpu: 2
      maxCpu: 5
      minRam: 2
      maxRam: 24
      minDisk: 6
      maxDisk: 50
      startCpuCoreCount: 3
      minFreeRamGB: 0.5
      minFreeRamPercent: 20
    # defines the minimum number of containers for horizontal autoscaling. Max value = 6.
    minContainers: 2
    # defines the maximum number of containers for horizontal autoscaling. Max value = 6.
    maxContainers: 4
    # optional: create secret env variables
    envSecrets:
      S3_ACCESS_KEY_ID: 'P8cX1vVVb'
      S3_ACCESS_SECRET: 'ogFthuiLYki8XoL73opSCQ'
  - # second service hostname
    hostname: db
    # service type and version number in postgresql@{version} format
    type: postgresql@12
    # mode of operation "HA"/"non_HA"
    mode: NON_HA
```

The yaml file describes your future project infrastructure. The project will contain a Ubuntu service and a [PostgreSQL](/postgresql/overview) service.

Ubuntu service with "app" hostname, the internal port(s) the service listens on will be defined later in the zerops.yaml. Ubuntu service will run with a custom vertical and horizontal scaling. Following secret env variables will be configured:

```env
S3_ACCESS_KEY_ID="P8cX1vVVb"
S3_ACCESS_SECRET="ogFthuiLYki8XoL73opSCQ"
```

The hostname of the PostgreSQL service will be set to "db". The [single container](/features/scaling#single-container-mode)(/features/scaling#deployment-modes-databases-and-shared-storage) mode will be chosen and the default auto [scaling configuration](/postgresql/how-to/scale#configure-scaling) will be set.

#### Description of description.yaml parameters

The `project:` section is required. Only one project can be defined.

<table className="w-full my-1.5">
  <thead>
    <tr>
      <th className="w-fit"><strong>Parameter</strong></th>
      <th className="w-fit"><strong>Description</strong></th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td className="w-fit"><strong>hostname</strong></td>
      <td className="w-fit">
        The unique service identifier.

        The hostname of the new database will be set to the `hostname` value.

        <strong>Limitations:</strong>
        <ul>
        <li>duplicate services with the same name in the same project are forbidden</li>
        <li>maximum 25 characters</li>
        <li>must contain only lowercase ASCII letters (a-z) or numbers (0-9)</li>
        </ul>
      </td>
    </tr>
    <tr>
      <td className="w-fit"><strong>type</strong></td>
      <td className="w-fit">
        Specifies the service type and version.

        See what [Ubuntu service types](/references/import-yaml/type-list#runtime-services) are currently supported.
      </td>
    </tr>
    <tr>
      <td className="w-fit"><strong>verticalAutoscaling</strong></td>
      <td className="w-fit">
        <strong>Optional.</strong> Defines [custom vertical auto scaling parameters](/ubuntu/how-to/create#set-auto-scaling-configuration).

        All verticalAutoscaling attributes are optional. Not specified attributes will be set to their default values.
      </td>
    </tr>
    <tr>
      <td className="w-fit"><strong>- cpuMode</strong></td>
      <td className="w-fit">
        <strong>Optional.</strong> Accepts `SHARED`, `DEDICATED` values. Default is `SHARED`
      </td>
    </tr>
    <tr>
      <td className="w-fit"><strong>- minCpu/maxCpu</strong></td>
      <td className="w-fit">
        <strong>Optional.</strong> Set the minCpu or maxCpu in CPU cores (integer).
      </td>
    </tr>
    <tr>
      <td className="w-fit"><strong>- minRam/maxRam</strong></td>
      <td className="w-fit">
        <strong>Optional.</strong> Set the minRam or maxRam in GB (float).
      </td>
    </tr>
    <tr>
      <td className="w-fit"><strong>- minDisk/maxDisk</strong></td>
      <td className="w-fit">
        <strong>Optional.</strong> Set the minDisk or maxDisk in GB (float).
      </td>
    </tr>
    <tr>
      <td className="w-fit"><strong>minContainers</strong></td>
      <td className="w-fit">
        <strong>Optional.</strong> Default = 1. Defines the minimum number of containers for [horizontal autoscaling](/ubuntu/how-to/create#horizontal-auto-scaling).

        <strong>Limitations:</strong>

        Current maximum value = 10.
      </td>
    </tr>
    <tr>
      <td className="w-fit"><strong>maxContainers</strong></td>
      <td className="w-fit">
        Defines the maximum number of containers for [horizontal autoscaling](/ubuntu/how-to/create#horizontal-auto-scaling).

        <strong>Limitations:</strong>

        Current maximum value = 10.
      </td>
    </tr>
    <tr>
      <td className="w-fit"><strong>envSecrets</strong></td>
      <td className="w-fit">
        <strong>Optional.</strong> Defines one or more secret env variables as a key value map. See env variable [restrictions](/ubuntu/how-to/env-variables#env-variable-restrictions).
      </td>
    </tr>
  </tbody>
</table>

### Create a project based on the description.yaml

When you have your `description.yaml` ready, use the `zcli project project-import` command to create a new project and the service infrastructure.

```sh
Usage:
  zcli project project-import importYamlPath [flags]

Flags:
  -h, --help                Help for the project import command.
      --org-id string        If you have access to more than one organization, you must specify the org ID for which the
                            project is to be created.
      --working-dir string   Sets a custom working directory. Default working directory is the current directory. (default "./")
```

Zerops will create a project and one or more services based on the `description.yaml` content.

Maximum size of the `description.yaml` file is 100 kB.

You don't specify the project name in the `zcli project project-import` command, because the project name is defined in the `description.yaml`.

If you have access to more than one client, you must specify the client ID for which the project is to be created. The `clientID` is located in the Zerops GUI under the client name on the project dashboard page.

### Add Ubuntu service to an existing project

#### Example:

Create a directory `my-project` if it doesn't exist. Create an `import.yaml` file inside the `my-project` directory with following content:

```yaml
# basic project data
project:
  # project name
  name: my-project
# array of project services
services:
  - # service name
    hostname: app
    # service type and version number in ubuntu@{version} format
    type: ubuntu@24.04
    # defines the minimum number of containers for horizontal autoscaling
    minContainers: 1
    # defines the maximum number of containers for horizontal autoscaling. Max value = 6.
    maxContainers: 6
    # optional: create env variables
    envSecrets:
      S3_ACCESS_KEY_ID: 'P8cX1vVVb'
      S3_ACCESS_SECRET: 'ogFthuiLYki8XoL73opSCQ'
```

The yaml file describes the list of one or more services that you want to add to your existing project. In the example above, one Ubuntu service version 1 with default [auto scaling](/ubuntu/how-to/scaling) configuration will be added to your project. Hostname of the new service will be set to `app`. Following secret env variables will be configured:

```env
S3_ACCESS_KEY_ID="P8cX1vVVb"
S3_ACCESS_SECRET="ogFthuiLYki8XoL73opSCQ"
```

The content of the `services:` section of `import.yaml` is identical to the project description file. The `import.yaml` never contains the `project:` section because the project already exists.

When you have your `import.yaml` ready, use the `zcli project service-import` command to add one or more services to your existing Zerops project.

```sh
Usage:
  zcli project service-import importYamlPath [flags]

Flags:
  -h, --help                Help for the project service import command.
  -P, --project-id string   If you have access to more than one project, you must specify the project ID for which the
                           command is to be executed.
```

zCLI commands are interactive, when you press enter after `zcli project service-import importYamlPath`, you will be given a list of your projects to choose from.

Maximum size of the import.yaml file is 100 kB.


----------------------------------------

# Ubuntu > How To > Customize Runtime


## Build Custom Runtime Images

Zerops allows you to build custom runtime images (CRI) when the default base runtime images don't meet your application's requirements. This is an optional phase in the [build and deploy pipeline](/features/pipeline#runtime-prepare-phase-optional).

Ubuntu is a versatile base for running anything not explicitly offered as a dedicated Zerops runtime. You can install any packages and tools you need, treating it as a clean OS to customize however you want.

It is also a great option when you need a specific version of a technology (like Go, Node.js, or PHP) that Zerops doesn't support by default—whether it's an older version for legacy projects or a newer release not yet available.

## Configuration

### Default  Runtime Environment

The default  runtime environment contains:

- <span>{data.ubuntu.default}</span>
- [zCLI](/references/cli)
-

### When You Need a Custom Runtime Image

Since Ubuntu serves as a general-purpose base, you'll likely want to customize it for your specific use case. Common scenarios include:

:::important
You should not include your application code in the custom runtime image, as your built/packaged code is deployed automatically into fresh containers.
:::

Here are examples of configuring custom runtime images in your `zerops.yml`:

### Basic  Setup

### Using Build Files in Runtime Preparation

For complete configuration details, see the [runtime prepare phase configuration guide](/features/pipeline#configuration).

## Process and Caching

### How Runtime Prepare Works
The runtime prepare process follows the same steps for all runtimes. See [how runtime prepare works](/features/pipeline#how-it-works) for the complete process details.

### Caching Behavior
Zerops caches custom runtime images to optimize deployment times. Learn about [custom runtime image caching](/features/pipeline#custom-runtime-image-caching) including when images are cached and reused.

### Build Management
For information about managing builds and deployments, see [managing builds and deployments](/features/pipeline#manage-builds-and-deployments).

:::warning
Shared storage mounts are not available during the runtime prepare phase.
:::

## Troubleshooting

If your `prepareCommands` fail, check the  for specific error messages.

----------------------------------------

# Ubuntu > How To > Deploy Process



----------------------------------------

# Ubuntu > How To > Env Variables



----------------------------------------

# Ubuntu > How To > Filebrowser



----------------------------------------

# Ubuntu > How To > Logs



----------------------------------------

# Ubuntu > How To > Scaling



----------------------------------------

# Ubuntu > How To > Shared Storage



----------------------------------------

# Ubuntu > How To > Trigger Pipeline



----------------------------------------

# Ubuntu > How To > Upgrade



----------------------------------------

# Ubuntu > Overview


[Ubuntu ↗](https://ubuntu.com/) is a popular Linux distribution based on Debian, widely used for servers, cloud computing, and containerized applications.

Ubuntu services in Zerops provide a flexible base environment for running applications built with technologies that aren't officially supported by Zerops, or for custom setups requiring full control over the runtime environment.

:::tip
Do you have any questions? Check the step-by-step tutorial, browse the documentation and join our **[Discord](https://discord.com/invite/WDvCZ54)** community to get help from our team and other members.
:::

## Feature Highlights

- [Create Ubuntu service](/ubuntu/how-to/create) — Start with creating an Ubuntu service using GUI or zCLI.
- [zerops.yaml](/ubuntu/how-to/build-pipeline#add-zeropsyaml-to-your-repository) — See a full example of zerops.yaml file to configure your own app.
- [Scaling configuration](/ubuntu/how-to/scaling) — Set up scaling of your Ubuntu service so that it runs smoothly while using only necessary resources.

{" "}

- [Customize build environment](/ubuntu/how-to/build-process#customize-build-environment)
- [Customize runtime environment](/ubuntu/how-to/customize-runtime)

## When in doubt, reach out

Don't know how to start or got stuck during the process? You might not be the first one, visit the FAQ section to find out.

In case you haven't found an answer (and also if you have), we and our community are looking forward to hearing from you on Discord.

Have you built something that others might find useful? Don't hesitate to share your knowledge!

- [FAQ](/ubuntu/faq) — Most common questions in one place.
- [Discord](https://discord.com/invite/WDvCZ54) — Join our core team and Zerops community on Discord. Ask questions and share your tips with other members.

## Popular Guides

- [zCLI](/references/cli) — Get even more out of Zerops with the zCLI command line tool.
- [Zerops VPN](/references/networking/vpn) — Connect to your services easily with Zerops VPN.


----------------------------------------

# Valkey > Overview


Valkey is a powerful, open-source alternative to Redis, offering full compatibility with Redis clients while providing an independent development path focused on community-driven innovation. Deploy and manage Valkey in Zerops' fully managed infrastructure to get instant access to high-performance in-memory data storage.

:::tip
Valkey is our recommended Redis alternative as KeyDB's development has slowed significantly in recent times.
:::

## Supported Versions

Currently supported Valkey versions:

Import configuration version:

- `valkey@7.2`

## Service Configuration

Zerops offers Valkey in two deployment configurations to meet different availability requirements.

### Single Setup
- Single node deployment on port `6379` (non-TLS) and `6380` (TLS)
- Suitable for development or non-critical workloads

See [Persistence](#persistence) for how data is stored and recovered.

### HA (High Availability) Setup

The HA deployment is a 3-node cluster with automatic failover, fronted by an HAProxy load balancer on every node.

- 3-node configuration: 1 primary + 2 replicas
- Client-facing ports (available on every node):
  - `6379` &mdash; read/write (non-TLS), routed to the current primary
  - `6380` &mdash; read/write over TLS, routed to the current primary
  - `7000` &mdash; read-only (non-TLS), load-balanced across replicas
  - `7001` &mdash; read-only over TLS, load-balanced across replicas
- Failover is handled by a built-in [Sentinel](https://valkey.io/topics/sentinel/) cluster. When the primary becomes unreachable, a replica is promoted automatically and HAProxy starts routing writes to it.
- TLS is terminated at HAProxy.
- Connect your application to the standard ports &mdash; the address never changes when the primary moves.

:::note
Replica reads (ports `7000`/`7001`) can lag slightly behind the primary due to asynchronous replication.
:::

**Failover client impact:** expect roughly 10–15 seconds of write unavailability while a new primary is elected and HAProxy reconverges. Read traffic on surviving replicas is unaffected.

:::tip Trusting the TLS certificate
The certificates served on the TLS ports (`6380` and `7001`) are signed by the Zerops Certificate Authority. To verify them from outside Zerops, download and trust the [Zerops CA](/references/networking/zerops-ca) &mdash; e.g. `redis-cli --tls --cacert ./zerops-ca.pem -h <ip> -p 6380 -a <password>`.
:::

## Connecting

Zerops generates the connection details as environment variables on the Valkey service. Reference them from another service in the same project as `${<hostname>_<variable>}` &mdash; for a service named `db`, the connection string is `${db_connectionString}`. The examples below assume the hostname `db`.

| Variable | Example value | Notes |
|---|---|---|
| `hostname` | `db` | Service hostname; reachable as `db.zerops` inside the project |
| `port` | `6379` | Plain (non-TLS) port |
| `portTls` | `6380` | TLS port |
| `password` | *(generated)* | Password for the `default` user (sensitive) |
| `connectionString` | `redis://default:<password>@db.zerops:6379` | Ready-to-use non-TLS URL |
| `connectionTlsString` | `rediss://default:<password>@db.zerops:6380` | Ready-to-use TLS URL |
| `connectionTlsString` | `rediss://default:<password>@db.zerops:6380` | Ready-to-use TLS URL |

In **HA mode** four additional variables expose the read-only replica endpoints (load-balanced across replicas):

| Variable | Example value | Notes |
|---|---|---|
| `portReplicas` | `7000` | Read-only plain port |
| `portTlsReplicas` | `7001` | Read-only TLS port |
| `connectionStringReplicas` | `redis://default:<password>@db.zerops:7000` | Read-only non-TLS URL |
| `connectionTlsStringReplicas` | `rediss://default:<password>@db.zerops:7001` | Read-only TLS URL |
| `connectionTlsStringReplicas` | `rediss://default:<password>@db.zerops:7001` | Read-only TLS URL |

The connection string format is `redis://default:<password>@<hostname>.zerops:<port>` (or `rediss://` for TLS). The username is always `default`.

:::note Authentication
Valkey requires a password. It is generated automatically, exposed as the sensitive `${db_password}` variable, and already embedded in the `connectionString` variables above. Connect with it directly &mdash; e.g. `redis-cli -h db.zerops -p 6379 -a "$db_password"`.

Services created **without** a `password` variable (older deployments) keep working without authentication and are unaffected. **All deployments created since this release require the password.**
:::

### Idle connection timeout

Valkey closes connections that stay **idle for 5 minutes** (`timeout 300`). This is intentional on the managed instances &mdash; we avoid keeping infinite idle connections open. Older Valkey services ran with no timeout (`timeout 0`); if you connected before this change, your connections used to stay open indefinitely.

"Idle" means **no commands sent on the connection** &mdash; the server resets the timer on every command, so a busy connection is never closed. The connections most likely to be affected are long-lived ones that sit waiting rather than sending commands, typically **pub/sub subscribers** and **blocking reads** (`BLPOP`, `XREAD`, …). Most clients reconnect automatically, so you may only see log lines such as `Redis subscriber socket closed; reconnecting if possible.` &mdash; but the reconnect churn can drop pub/sub messages published in the gap.

To keep idle connections open, send an application-level **`PING` on an interval shorter than 300s**. A TCP keep-alive alone is **not** enough &mdash; keepalive packets live below the application layer and don't count as Valkey commands, so they don't reset the idle timer.

Many clients have a built-in option for this. For example, [node-redis](https://github.com/redis/node-redis):

```js
const redisClient = createClient({
  url: redisURL,
  pingInterval: 10000, // send PING every 10s; keeps the connection under the 300s idle limit
});
```

If your client has no equivalent option, run your own heartbeat on every long-lived connection:

```js
const heartbeat = setInterval(() => {
  publisher.ping().catch(() => {});
  subscriber.ping().catch(() => {});
}, 60000); // any interval under 300s
```

For ordinary request/response traffic, a [connection pool](https://valkey.io/topics/clients/) that recycles connections handles this transparently.

## Persistence

Valkey persists data to disk with **AOF (append-only file)**, so the dataset survives restarts and is rebuilt automatically on startup.

- **AOF is enabled** (`appendonly yes`) and synced to disk **every second** (`appendfsync everysec`). After an unclean crash you lose at most ~1 second of the most recent writes.
- **RDB snapshots are disabled** (`save ""`) &mdash; durability relies on AOF, not periodic snapshots.

**Durability by mode:**
- **Single:** the AOF lives on the node's local disk. Data survives service restarts but is lost if the underlying hardware node fails and no backup exists.
- **HA:** writes are additionally replicated to two replicas, so the dataset survives the loss of any single node via automatic failover.

:::note Backups
Platform-managed encrypted backups are available for both Single and HA setups. They are **disabled by default** &mdash; enable them on the service if you need point-in-time recovery beyond AOF and replication.
:::

## Memory and Autoscaling

You don't set `maxmemory` directly. Zerops sizes it at **80% of the container's available RAM** &mdash; precisely 80% of the *smaller* of your configured maximum RAM and the cgroup-allocated RAM. It is re-evaluated and adjusted automatically about every 30 seconds, so `maxmemory` tracks the container as it scales vertically. The remaining 20% covers Valkey's internal overhead (fork on AOF rewrite / replica sync, fragmentation) and the OS.

:::warning Keep minimum free RAM above 20% when customizing autoscaling
If you edit the autoscaling configuration, keep the **minimum free RAM above 20%**. Zerops caps `maxmemory` at 80% of available RAM, so the dataset alone can never push free RAM below 20%. If your minimum free RAM threshold is at or below 20%, the scale-up trigger may **never fire at all** &mdash; free RAM never crosses it, so the service stays stuck at its current size and starts evicting keys (or rejecting writes under `noeviction`) instead of scaling up. Setting the threshold above 20% lets the dataset's growth toward the 80% cap cross the trigger, so the service scales up in time and keeps headroom for the fork during an AOF rewrite or replica sync. The built-in profiles all keep this threshold above 20%.
:::

:::note Check the logs for OOM events
Watch the service's runtime logs for out-of-memory events &mdash; typically the kernel OOM-killer terminating and restarting Valkey when a fork during an AOF rewrite or replica sync briefly inflates memory. Recurring OOMs mean the reserved headroom isn't enough for your workload's peaks. Raise the **minimum free RAM** (more headroom) or the **minimum RAM** (a higher floor) until they stop.
:::

## Tunable Parameters

The `maxmemory-policy` Valkey setting is exposed as an **autoscaling profile override**. In the GUI, open the service's **Automatic scaling configuration**, click **Adjust scaling** and set them under **Overrides**. Zerops applies the change live &mdash; **no service restart**, no client reconnect. In HA mode the change is rolled out to every node.

To set the parameters at creation time, use `profileOverrides` in your import YAML (a `profile` must be selected to use overrides &mdash; available profiles are `hobby`, `staging` and `production`):

```yaml
services:
  - hostname: redis
    type: valkey:ha@7.2
    profile: staging
    profileOverrides:
      maxmemory-policy: noeviction
```

:::note Migrating from environment variables
Services created before profile overrides existed configure this setting via the `VALKEY_MAXMEMORY_POLICY` environment variable. It keeps working, but once a profile override is set it takes precedence over the environment variable.
:::

### `maxmemory-policy`

Default: `allkeys-lru`. Controls what Valkey does when the dataset reaches `maxmemory`.

| Value | Behavior | When to use |
|---|---|---|
| `noeviction` | Reject writes with an OOM error | Datasets where every key must be preserved (session storage without TTL, job queues). Requires careful capacity planning. |
| `allkeys-lru` | Evict least-recently-used keys | General-purpose caching &mdash; the safe default |
| `allkeys-lfu` | Evict least-frequently-used keys | Hot/cold workloads where access frequency matters more than recency |
| `allkeys-random` | Evict random keys | Uniform access patterns (rare) |
| `volatile-lru` | Evict LRU keys *with a TTL set* | Mixed workloads: persistent keys without TTL are protected, cache keys with TTL are evictable |
| `volatile-lfu` | Evict LFU keys with a TTL | Same as `volatile-lru`, frequency-based |
| `volatile-random` | Evict random keys with a TTL | Rarely appropriate |
| `volatile-ttl` | Evict keys with the shortest remaining TTL | When TTL reflects priority |
| `volatile-ttl` | Evict keys with the shortest remaining TTL | When TTL reflects priority |

:::warning `noeviction` and memory pressure
With `noeviction`, Valkey cannot free memory on its own &mdash; once the dataset reaches `maxmemory`, writes fail with OOM errors until the service scales up or keys are deleted. Make sure your autoscaling limits (maximum RAM) leave enough room for the dataset's growth.
:::

## Metrics

Prometheus-compatible metrics are exported by default for scraping, on the port given by the `ZEROPS_PROMETHEUS_PORT` variable (`db:9121`).

## Learn More

- [Official Valkey Documentation](https://valkey.io/docs) - Comprehensive guide to Valkey features

## Support

For advanced configurations or custom requirements:
- Join our [Discord community](https://discord.gg/zeropsio)
- Contact support via [email](mailto:support@zerops.io)

----------------------------------------

# Zcp > Concept > How It Works


The ZCP MCP setup gives a coding agent a **work loop** for Zerops app work. The agent reads live state, chooses the app runtime and dependencies, changes the app, deploys through Zerops, verifies real behavior, and returns proof or a blocker.

The loop is carried by project-scoped Zerops operations, Zerops-specific knowledge, and instructions for what to inspect, what to change, when to ask, and what counts as done. You describe the product outcome; the agent uses the loop to make its decisions visible while it works.

The source of truth is the real project: runtimes, managed services, env references, logs, events, and deploy results. A separate preview sandbox is not the source of truth.

## The work loop

```mermaid
flowchart TD
  intent["Product intent
<code>Build a task board for my team.</code>"]
  state["Live state
services, runtime layout, env vars,
logs, events, saved work state"]
  scope["Runtime target
which app service changes"]
  setup{"Missing or unsuitable
services?"}
  provision["Service setup
use existing services or create
missing runtimes/dependencies"]
  appwork["App work
code, <code>zerops.yaml</code>, env refs,
migrations, seeds, framework config"]
  deploy["Direct deploy through Zerops"]
  reachability{"Runtime reachable?
status, logs, HTTP probe"}
  behavior{"Requested behavior works?
endpoint, UI flow, worker result,
persisted state"}
  evidence["Evidence
build logs, runtime logs,
events, verify output"]
  proof["Proof
URL, endpoint result,
UI state, or stored result"]
  delivery["Delivery after proof
keep direct deploy, push to git,
or hand off"]
  blocker["Blocker
credential, decision,
unsupported fit,
repeated failure"]

  intent --> state --> scope --> setup
  setup -->|yes| provision --> appwork
  setup -->|no| appwork
  appwork --> deploy --> reachability
  reachability -->|no, fixable| evidence --> appwork
  reachability -->|yes| behavior
  behavior -->|no, fixable| evidence
  behavior -->|yes| proof --> delivery
  setup -->|needs decision| blocker
  reachability -->|needs human| blocker
  behavior -->|needs human| blocker

  classDef user stroke:#2d72d9,stroke-width:1.5px;
  classDef zcpbox stroke:#32845a,stroke-width:1.5px;
  classDef work stroke:#c47f17,stroke-width:1.5px;
  classDef done stroke:#7157d9,stroke-width:1.5px;
  classDef stop stroke:#d33f49,stroke-width:1.5px;

  class intent user;
  class state,scope zcpbox;
  class setup,provision,appwork,deploy,reachability,behavior,evidence work;
  class proof,delivery done;
  class blocker stop;
```

The loop keeps the agent working from evidence instead of a guessed checklist: current state, Zerops wiring rules, deploy evidence, and the distinction between proof and blocker.

## What "live state" means

The MCP tools read Zerops instead of asking you to paste a service inventory into the prompt. Useful state includes:

- runtime services and managed services,
- whether the app has one runtime, a dev+stage pair, or local files linked to a Zerops runtime,
- env-var keys and Zerops references,
- recent build/deploy events,
- build logs, runtime logs, and verification output,
- saved work state after an interrupted session.

This is why a short prompt can be enough. The agent can ask what exists, which runtime was last deployed, which checks passed, and where a previous run stopped.

Chat history is not the source of truth. If the agent sounds confused, starts from an old assumption, or a session was interrupted, the recovery move is:

```text
Read current project status and tell me where this project stands before changing anything.
```

## What the workflow handles

The workflow handles the things an agent must resolve during app work so you do not have to name them in the prompt. The tools and instructions supply the state, guidance, operations, and verification surface so the agent can work from evidence.

| What the workflow handles | What the agent gets                                                                                                 | What that means for you                                                       |
| ------------------------- | ------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
| Live state       | Services, env-var keys, Zerops references, recent events, logs, verification output, and saved work state.          | You do not have to paste a service inventory or reconstruct what happened.    |
| Runtime target   | Rules for choosing the app runtime that should receive code changes.                                                | The agent can identify where app work belongs before editing or deploying.    |
| Managed services | Knowledge and env wiring patterns for database, cache, queue, search, storage, mail, and similar services.          | Product intent can imply real dependencies without a manual wiring checklist. |
| Service setup    | Operations for using existing services or creating missing runtimes and dependencies.                               | Runtime layout and dependencies can be established before app work starts.    |
| App wiring       | Zerops-specific rules for `zerops.yaml`, env references, ports, commands, public access, and build/deploy behavior. | The app is wired for Zerops rather than for a generic cloud template.         |
| Deploy evidence  | Build logs, runtime logs, platform events, service status, HTTP checks, and structured verification output.         | A failed deploy becomes a diagnosis surface instead of guesswork.             |
| Behavior proof   | The proof gate is the requested behavior, not only a successful build or reachable root URL.                        | The final answer can point to what was actually checked.                      |
| Delivery handoff | Direct proof first; then git push, CI, or human handoff when that is the chosen delivery choice.                    | Shipping setup follows a verified running result.                             |
| Delivery handoff | Direct proof first; then git push, CI, or human handoff when that is the chosen delivery choice.                    | Shipping setup follows a verified running result.                             |

The exact labels for layouts, delivery modes, and setup routes live in the [Glossary](/zcp/glossary) and [Workflows in depth](/zcp/reference/agent-workflow).

## Service setup prepares the project layout

Before app code work starts, the workflow makes three decisions visible:

- Which runtime service is the app target?
- Which managed services are dependencies?
- Does the existing project layout fit the request?

If the services already exist, the agent can use them. If a needed runtime or dependency is missing, the tools can create it. If the choice affects cost, product scope, credentials, a destructive action, or which stage/runtime should be used, the agent should stop and ask.

Service setup is finished when the app runtime and dependencies are known. It is the layout that lets app work happen in the right place.

## App work changes code and platform wiring together

After the runtime target is known, the agent gets the platform knowledge needed to make the application change. In practice this often spans both source code and Zerops wiring:

- app files,
- `zerops.yaml` build and run setup,
- env references to managed services,
- migrations, seeds, and framework config,
- start commands, ports, and public HTTP support,
- local `.env` generation when using local setup.

That guidance matters because Zerops is its own platform. Service references, build/deploy behavior, public access, scaling, and env resolution do not follow Docker Compose or Kubernetes conventions.

The first functional deploy goes directly through MCP so the agent has a running result to verify. A repository push or CI handoff can follow, but it should not replace the first proof.

## Recovery is evidence-driven

When something fails, the workflow puts the agent on the matching evidence surface — build logs for build failures, prepare/runtime logs for start failures, verify output and request-time logs for behavior failures, transport surfaces for network failures, field-level rejection for config, and the named credential surface for credential failures. The full categories, what to read first, and what to avoid live in [Troubleshooting](/zcp/reference/troubleshooting).

Retrying the same deploy without new evidence is not progress. The loop pushes toward one of three outcomes: fix from a cause, ask for the missing decision, or report a blocker with the category, evidence read, and attempts made.

## Verification has two layers

A successful deploy proves that Zerops accepted the build and started the runtime. Reachability checks prove the service is running and reachable. They still do not prove the product request.

For a task-board app, useful behavior proof might be:

- create a task,
- move it between columns,
- refresh the page,
- confirm the task is still there.

For an API task, proof might be a JSON response from the requested endpoint and stored data behind it. For a worker task, proof might be a processed job and the resulting database or object-storage state. For a staging request, proof belongs on the stage runtime, not only on dev.

The final answer should make proof inspectable: runtime name, URL or endpoint, behavior checked, and delivery choice if one was set.

## Delivery happens after proof

Delivery choice controls how future changes ship after a verified runtime exists: keep direct deploy, push to git, or hand off to CI/release/human action. The user-facing version of this choice and what to tell the agent for each option lives in [Build and ship → Choose delivery after proof](/zcp/workflows/build-with-zcp#choose-delivery-after-proof).

Packaging a running service turns a deployed runtime into a re-importable bundle for another Zerops project. It is useful for handoff or reuse after proof, not for deploying the next app change; see [Package a running service](/zcp/workflows/package-running-service).

## Remote and local setup use the same loop

The same `zcp` binary can run in two places. The control loop stays the same; filesystem and network access change. A human can take over from the same evidence either way: files, runtime target, logs, events, verification result, and delivery state.

| Setup        | What runs where                                                                                                                                             | Practical effect                                                                                                                                                                                     |
| ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Remote setup | A `zcp@1` service runs the `zcp` binary inside Zerops. **Include Coding Agent** adds the bundled agent CLI; **Cloud IDE** adds Browser VS Code. | Work happens inside the remote workspace, with private networking and runtime file mounts. |
| Local setup  | The `zcp` binary runs on your laptop after `zcp init`, and your local editor or CLI agent talks to it.                                         | App files, deploy source, and git credentials stay local. Managed services are reached over Zerops VPN, and `.env` generation bridges credentials into your local app. |
| Local setup  | The `zcp` binary runs on your laptop after `zcp init`, and your local editor or CLI agent talks to it.                                         | App files, deploy source, and git credentials stay local. Managed services are reached over Zerops VPN, and `.env` generation bridges credentials into your local app. |

Choose setup by where the agent and filesystem should live: [Remote or local setup](/zcp/setup/choose-workspace).

## Signs of a healthy run

A well-shaped run should:

- name the runtime target before editing or deploying,
- use existing services when they fit,
- create missing services only before app work starts,
- read logs, events, and verify output when failure occurs,
- distinguish runtime reachability from requested behavior,
- stop before destructive actions, ambiguous runtime/stage choices, or missing credentials,
- end with proof or a blocker.

That is the practical difference between "the agent wrote code" and "the app task is done".

## Next steps

- [Build and ship](/zcp/workflows/build-with-zcp) — normal app work after setup.
- [Workflows in depth](/zcp/reference/agent-workflow) — process gates, generated files, runtime layouts, delivery labels, and completion evidence.


----------------------------------------

# Zcp > Glossary


Use these definitions when a page, workflow status, agent handoff, or policy needs exact wording. In normal prompts, describe the outcome you want.

## Core names

**ZCP MCP** - Zerops Control Plane MCP: the MCP tool surface that exposes project-scoped Zerops operations to coding agents.

**MCP server** - the Model Context Protocol server exposed by the `zcp` binary.

**ZCP MCP tools** - the project-scoped Zerops operations exposed to an agent or MCP-capable client. In MCP clients, this usually appears as the `zerops` server.

**`zcp` binary** - the executable that can run inside remote setup or on your machine in local setup.

**`zcp` service** - the service instance in a Zerops project that hosts remote setup.

**`zcp@1` service** - the Zerops service type used for remote setup.

**zCLI** - the Zerops command-line client for humans, scripts, VPN, and CI. It is separate from ZCP MCP.

**zsc** - the in-container Zerops Setup Control utility used from `zerops.yaml`.

## Setup and workspace

**Remote setup** - the `zcp` binary running inside a Zerops `zcp@1` service.

**Include Coding Agent** - remote setup option that adds a bundled agent CLI (Claude Code, Codex, Antigravity, or Grok Build) and preconfigures it to use ZCP MCP tools.

**Cloud IDE** - browser-based VS Code served by remote setup.

**Browser VS Code** - dashboard entry point into the Cloud IDE.

**AI Agent environment** - recipe environment preset that creates app services plus remote setup with **Include Coding Agent** enabled.

**Local setup** - the `zcp` binary running on your machine after `zcp init`, while your local editor or CLI agent talks to it.

**Env bridge** - local setup behavior that writes a local `.env` snapshot from Zerops env vars and references so local app code can reach managed services over VPN.

**Agent client** - the editor, CLI, hosted agent runtime, or custom MCP client that connects to ZCP MCP.

## Generated files and state

**Generated workflow block** - the managed section in `CLAUDE.md` between `<!-- ZCP:BEGIN -->` and `<!-- ZCP:END -->`. Durable project instructions belong outside it.

**`.mcp.json`** - local MCP server config. It points the local agent client at `zcp serve` and stores `ZCP_API_KEY`; keep it out of git.

**`.zcp/state/`** - local workflow metadata for a project directory: known runtimes, pairing, delivery choice, sessions, deploy attempts, verify attempts, and coordination locks. It is not source code.

**Workflow state** - saved metadata that lets the agent resume, audit, or close a guided run after interruption.

## Workflow

**Bootstrap** - workflow phase that reads the current project and settles which runtime services and managed services the app should use before app code work starts.

**Service setup** - the phase that decides which runtime services and managed services the app should use before app code work starts.

**Develop** - workflow phase that changes app code/config, deploys, verifies reachability and behavior, and fixes failures from evidence.

**Runtime target** - the app runtime selected for the current change, such as `appdev`, `appstage`, `app`, or a linked local target.

<span id="runtime-layout"></span>**Runtime layout** - which app runtime services the workflow should use:

- `standard` - dev runtime plus explicit stage runtime.
- `dev` - one mutable development runtime.
- `simple` - one runtime with no dev/stage split.
- `local-stage` - local source directory linked to one Zerops runtime as deploy target.
- `local-only` - local source directory with no linked runtime yet.

**Managed service** - database, cache, queue, search, storage, mail, or similar dependency. It provides connection details; it is not an app deploy target.

**Direct deploy** - deploy from the current source to the scoped runtime through ZCP MCP. The first verified running result uses direct deploy before delivery setup is applied.

**Reachability verification** - checks that the runtime exists, is running, has no recent blocking errors, and can answer an HTTP probe when it is an HTTP service.

**Behavior verification** - checks that the requested app behavior works on the real URL, endpoint, worker result, or stored state.

**Proof** - user-inspectable completion evidence, such as a URL, endpoint result, UI state, processed job, or stored result.

**Blocker** - a clear stop state with evidence: failure category, runtime in scope, what was tried, and what decision or credential is needed.

## Delivery and production

**Delivery choice** - what happens after a verified deploy: keep direct deploy, push to git, or hand off to CI/release/human process.

**Delivery mode** - exact reference label for delivery choice:

- `auto` - keep direct deploy for future changes.
- `git-push` - commit and push to a configured remote, then observe/verify any tracked build.
- `manual` - external CI, release process, or a human owns future delivery.

**Git-push capability** - whether remote setup has enough remote URL and credential setup to push from remote setup. It can exist even when the current delivery mode is `auto`.

**Build integration** - repository-triggered build/deploy path that ZCP MCP may configure or observe, such as a Zerops dashboard webhook or GitHub Actions. It is separate from git-push capability and delivery mode.

**Package a running service** - workflow that turns one verified runtime and its managed dependencies into a re-importable, git-backed Zerops bundle.

**Production release** - the release operation that moves verified dev or stage work into a separate production Zerops project. It is set up once per project (production infrastructure) and once per runtime (production deploy trigger), then runs every release.

**Production boundary** - policy that production should live in a separate Zerops project without a `zcp` service and receive promoted work through CI, release process, or human action.

## Platform and failure terms

**Service scaling mode** - Zerops scaling setting such as `HA` or `NON_HA`. Different from runtime layout.

**Public subdomain access** - Zerops `.zerops.app` URL access for an eligible HTTP runtime. Workers and non-HTTP services do not get useful public URLs.

<span id="failure-category"></span>**Failure category** - label that points to the first useful evidence surface:

- `build` - build phase failed.
- `start` - build passed, but runtime start or prepare failed.
- `verify` - runtime exists, but reachability or behavior failed.
- `network` - transport, DNS, VPN, SSH, or service-to-service reach failed.
- `config` - `zerops.yaml`, env vars, setup block, or service settings mismatch.
- `credential` - Zerops, git, SSH, managed-service, or external API credential failed.
- `other` - no known category matched.

**Confirmation gate** - an operation that pauses until the user explicitly confirms the named target or consequence.

**Destructive import override** - import action that would replace an existing service stack. ZCP MCP refuses first, names affected services, and requires a matching acknowledgement before proceeding.

## Credentials

**Single-project token** - Zerops token that can access exactly one project. ZCP MCP expects this shape.

**`ZCP_API_KEY`** - single-project Zerops token used by ZCP MCP.

**`GIT_TOKEN`** - git provider credential used by remote git-push delivery when needed.

**`ZEROPS_TOKEN`** - Zerops token commonly used by GitHub Actions or external CI that runs `zcli`.

**External secret** - third-party credential such as Stripe, OpenAI, Mailgun, or GitHub API access. The agent can wire placeholders and env vars, but the secret value remains your responsibility.


----------------------------------------

# Zcp > Overview


This section covers, in order:

<div className="zcp-claim-grid">

<div className="zcp-claim-card">

<span>GET STARTED</span>

<h3>Quickstart and concept</h3>

[Quickstart](/zcp/quickstart) for hands-on; [How it works](/zcp/concept/how-it-works) for the work loop.

</div>

<div className="zcp-claim-card">

<span>SETUP</span>

<h3>Remote or local workspace</h3>

[Remote or local setup](/zcp/setup/choose-workspace), [Trust model](/zcp/security/trust-model), and [Production boundary](/zcp/security/production-policy).

</div>

<div className="zcp-claim-card">

<span>WORKFLOWS</span>

<h3>Build, package, promote</h3>

[Build and ship](/zcp/workflows/build-with-zcp), [Package a running service](/zcp/workflows/package-running-service), [Promote to production](/zcp/workflows/promote-to-production).

</div>

<div className="zcp-claim-card">

<span>REFERENCE</span>

<h3>Troubleshooting and lookup</h3>

[Workflows in depth](/zcp/reference/agent-workflow), [ZCP MCP tools](/zcp/reference/mcp-operations), [Troubleshooting](/zcp/reference/troubleshooting), [Glossary](/zcp/glossary).

</div>

</div>

For the broader feature concept — why coding agents need real project infrastructure rather than a sandbox or generated artifact — start with [Infrastructure for Coding Agents](/features/coding-agents).

With the generated workflow instructions enabled, an app task ends in proof or a blocker. **Proof** is a deployed runtime plus the URL, endpoint response, UI state, worker result, or stored data that shows the requested behavior works. A **blocker** is the agent reading the relevant Zerops evidence and naming the missing credential, decision, unsupported fit, or repeated failure.

Your prompt can stay about the product. Name the stack, runtime layout, acceptance criteria, delivery path, external credentials, or risky approval only when those decisions matter.

## What the agent gets

<div className="zcp-claim-grid">

<div className="zcp-claim-card">

<span>STATE</span>

### Current state

Services, runtime layout, managed dependencies, env-var keys and references, logs, events, deploy history, verification state, and saved work state.

</div>

<div className="zcp-claim-card">

<span>CONTROLS</span>

### Zerops operations

Project-scoped tools for discovering services, changing env vars, managing runtimes, deploying, verifying, scaling, public access, and delivery setup.

</div>

<div className="zcp-claim-card">

<span>INSTRUCTIONS</span>

### Workflow

The generated instructions combine service setup and app development: inspect state, choose the runtime target, use or create services, wire code and `zerops.yaml`, deploy, verify, and choose delivery. The Zerops work stays behind the product task instead of becoming another checklist.

</div>

<div className="zcp-claim-card">

<span>EVIDENCE</span>

### Evidence-based completion

A build or deploy is not the finish line. A completed app task should end with a working URL, endpoint result, UI proof, or a blocker backed by logs, events, and verification evidence.

</div>

</div>

## What you no longer have to script

Without this layer, an app prompt often turns into an operations runbook. With MCP tools and workflow instructions enabled, you should not need to paste:

- the service map, runtime target, dev/stage state, or managed-service inventory,
- database credentials, private hostnames, env-var references, or generated connection strings,
- build logs, runtime logs, event timelines, or a guess about why the last deploy failed,
- a deploy/verify/recovery script for every task,
- a recap after the chat loses context; the agent can read current workflow status.

**You still own the decisions that need human judgment:** product intent, technology constraints, acceptance criteria, external credentials, repository policy, and approval for destructive actions.

## Where it runs

The **same `zcp` binary** runs in both setups. In [remote setup](/zcp/setup/hosted-workspace), Zerops packages it as a `zcp@1` service with Browser VS Code and bundled agent wiring. In [local setup](/zcp/setup/local-agent-bridge), you install it on your machine and connect your own editor or CLI agent. The project surface is the same; the workspace, network access, deploy source, and safety profile differ.

To start, add remote setup in Zerops or initialize local setup beside your editor or CLI agent. The [Quickstart](/zcp/quickstart) uses remote setup because it needs no local install.

## Your agent, credentials, and workspace

**Agent account.** ZCP supports multiple coding agents including Claude Code (Anthropic), Codex (OpenAI), Antigravity, and Grok Build. Remote setup can bundle one of these, already configured for MCP. Zerops wires the agent to the tools; you still authenticate with your own subscription login or API credentials.

**Zerops token.** The MCP server connects through `ZCP_API_KEY`, a Zerops token limited to one project. Remote setup gets it from the platform; local setup reads it from `.mcp.json`. Token details live in [Tokens and credentials](/zcp/security/tokens-and-project-access).

**Workspace freedom.** The `zcp@1` service is still a normal Zerops service. You can install another agent CLI, add private MCP servers or helper tools, edit `CLAUDE.md`, add team dotfiles, and adapt the workspace. Details live in [What remote workspace gives you](/zcp/setup/hosted-workspace).

:::caution Production boundary
Use this setup for development or staging work. Production should stay in a separate Zerops project and receive released work through your CI or release process; see [Promote to production](/zcp/workflows/promote-to-production) for the practical flow and [Production boundary](/zcp/security/production-policy) for the policy.
:::

## What stays outside

This section is not a replacement for Zerops platform references. The Zerops [build and deploy pipeline](/features/pipeline), [permissions](/features/rbac), networking, scaling, and service references remain canonical for platform behavior.


----------------------------------------

# Zcp > Quickstart


Use this when you want the fastest hands-on ZCP loop: deploy an **AI Agent** recipe, authorize your coding agent, open Browser VS Code, and ask for one product change.

ZCP supports multiple coding agents including Claude Code (Anthropic), Codex (OpenAI), Antigravity, and Grok Build. The screenshots below use Claude Code as the walkthrough example.

Some [Zerops recipes](https://app.zerops.io/recipes) include an **AI Agent** environment. That preset creates app services, managed services, the `zcp@1` workspace, Browser VS Code, and bundled agent wiring in one deploy.

This quickstart uses [Laravel showcase](https://app.zerops.io/recipes/laravel-showcase?environment=ai-agent) because it includes real managed services. The same flow works for other recipes that offer AI Agent (local variants exist too).

## Prerequisites

- A Zerops account with permission to create a project.
- A subscription login or API credentials for your chosen coding agent (Claude Code, Codex, Antigravity, or Grok Build). Zerops wires the agent to ZCP, but your agent subscription or model credentials stay yours.

## 1. Choose the AI Agent recipe

1. Open the [Zerops recipes catalog](https://app.zerops.io/recipes).
2. Open a recipe with an **AI Agent** environment. For example, open [Laravel showcase](https://app.zerops.io/recipes/laravel-showcase?environment=ai-agent).
3. Select **AI Agent**.
4. Keep **Coding Agent** and **Cloud IDE** enabled.
5. Deploy the recipe.

The deploy creates app runtimes, managed dependencies, and a `zcp@1` workspace. In this recipe it appears as the `zcp` service. The agent, terminal, and browser IDE run there. App code still deploys to the app runtimes, not to `zcp`.

## 2. Authorize your coding agent

When provisioning finishes, the dashboard opens the authentication flow for your bundled agent. If you are using Claude Code (as in the screenshots below), use your own Claude Code subscription login or API credentials.

This is separate from `ZCP_API_KEY`, the Zerops token used by ZCP. Your agent login or API key is used only by the bundled agent.

If you close the prompt, open the `zcp` service in the dashboard. Its panel shows the browser workspace, web terminal, SSH access, desktop editor access, and agent authorization state.

## 3. Open the workspace

After authentication, continue into **Browser VS Code**. The workspace opens with files, ZCP configuration, terminal access, and your coding agent panel (the Claude Code panel in the screenshots below).

You are now inside the remote workspace. The agent can read live state, use the MCP tools, reach private services, and deploy app changes to the runtimes created by the recipe.

## 4. Ask for a product outcome

In your coding agent, ask for the app behavior in natural language. A good first prompt is intentionally short:

```text
Build a task board for my team.
Tasks should stay saved after refresh.
```

The agent should deploy, verify, read evidence, and return proof for the app task. Add detail only when it changes the work.

Add details when they change the product, stack, runtime layout, acceptance criteria, or delivery preference:

```text
In this Laravel app, add a task board backed by the existing PostgreSQL service.
A user can create a task, refresh the page, and still see it.
```

:::note Prompt shape

Quickstart prompts are short so you can see what ZCP carries behind the request. Longer, detailed prompts are fine for larger engineering work, especially when they change product behavior, stack, runtime layout, acceptance criteria, delivery preference, credentials, or safety approvals.
:::

## 5. Read the proof

The final answer should give you a real URL, endpoint, UI state, stored result, or blocker. Open the URL and try the behavior the agent says it verified.

For the task-board prompt, create a task, refresh the page, and confirm the task is still there. If it disappears, the app is not done; ask the agent to verify that exact behavior again and continue from current evidence rather than starting over.

If the agent cannot finish, useful output names the blocker: missing credential, missing decision, unsupported runtime choice, or repeated failure it could not recover from.

## Next steps

- [Build and ship](/zcp/workflows/build-with-zcp) — Runtime layout, development work, delivery, packaging, and production release.
- [How it works](/zcp/concept/how-it-works) — Live state, runtime fit, app wiring, deploy evidence, behavior proof, and blockers.
- [Trust model](/zcp/security/trust-model) — What the project-scoped token lets the agent do, and where the safety boundary sits.


----------------------------------------

# Zcp > Reference > Agent Workflow


Use this page when you want the process and exact labels behind a run that follows the generated workflow. Normal prompts should still describe outcomes. The workflow exists so the agent can read the project, prepare the right runtime and services, make the app change, deploy, verify, recover from evidence, and stop with proof or a concrete blocker.

The useful mental split is:

| Phase | What it settles | What should be true when it ends |
| ----- | --------------- | -------------------------------- |
| **Bootstrap** | Where the app should run and which services it depends on. | Runtime target and managed dependencies are known. |
| **Develop** | Code, `zerops.yaml`, env wiring, deploy, verification, recovery, and delivery choice. | The requested behavior is proved, or the blocker is concrete. |
| **Develop** | Code, `zerops.yaml`, env wiring, deploy, verification, recovery, and delivery choice. | The requested behavior is proved, or the blocker is concrete. |

For the loop itself, see [How it works](/zcp/concept/how-it-works). This page catalogs the exact phases, routes, layouts, labels, and gates.

## Session layers

Most workflow mistakes come from confusing these layers:

| Layer | What it is | What changes here |
| ----- | ---------- | ----------------- |
| **Workspace** | Where `zcp` and the agent run: remote `zcp@1` service or local machine. | Agent config, tools, local workflow state. App code should not be deployed to the workspace itself. |
| **Target runtime service** | The app runtime in scope: `appdev`, `appstage`, `app`, or a linked local deploy target. | App files, `zerops.yaml`, deploys, runtime logs, verification target. |
| **Managed services** | Databases, caches, queues, search, storage, mail, and similar dependencies. | Schema/data operations and credentials, never app code deploys. |
| **Managed services** | Databases, caches, queues, search, storage, mail, and similar dependencies. | Schema/data operations and credentials, never app code deploys. |

The `zcp` service is the control surface, not the app runtime.

## What drives the workflow

The generated workflow is made from four pieces:

| Piece | Role |
| ----- | ---- |
| **MCP tools** | Project-scoped Zerops operations: discover, deploy, read logs/events, manage env vars, verify, import/export, and related actions. |
| **Generated instructions** | Agent policy for when to inspect, when to ask, when to deploy, what evidence to read, and what counts as done. |
| **Saved workflow state** | Local metadata about bootstrap sessions, runtime pairing, delivery choice, deploy attempts, verify attempts, and interrupted work. |
| **Live Zerops project** | Source of truth for services, status, env refs, logs, events, deploys, runtime files, and public access. |
| **Live Zerops project** | Source of truth for services, status, env refs, logs, events, deploys, runtime files, and public access. |

The workflow does not replace judgment from the user or the agent. It gives the agent a process and evidence surface so app work does not depend on stale chat memory or a pasted runbook.

## Bootstrap

Bootstrap starts before app code changes when the workflow needs to understand or prepare the project layout.

```mermaid
flowchart TD
  start(["Read live project state"])
  interrupted{"Interrupted bootstrap
to resume?"}
  runtime{"Runtime services
already exist?"}
  known{"Request matches
known recipe or stack?"}
  resume(["resume"])
  adopt(["adopt"])
  recipe(["recipe"])
  classic(["classic"])
  done(["Runtime target and dependencies known"])

  start --> interrupted
  interrupted -- yes --> resume --> done
  interrupted -- no --> runtime
  runtime -- yes --> adopt --> done
  runtime -- no --> known
  known -- yes --> recipe --> done
  known -- no --> classic --> done
```

| Route | Use when | Wrong signal |
| ----- | -------- | ------------ |
| `adopt` | Runtime services already exist, including recipe-created projects. | Recreating services that already fit, or targeting the `zcp` service as the app. |
| `recipe` | The project is empty or only has remote setup, and the request matches a known stack recipe. | Treating an unchanged starter as the finished requested product. |
| `classic` | The project is empty and needs a custom service plan. | Writing app code before service ownership and runtime target are known. |
| `resume` | A previous bootstrap was interrupted. | Starting from scratch without checking live services and saved state. |
| `resume` | A previous bootstrap was interrupted. | Starting from scratch without checking live services and saved state. |

Bootstrap ends when the app runtime target and managed dependencies are known. It should also make visible any choice that needs human judgment: cost, credentials, data, runtime layout, production risk, or destructive behavior.

## Runtime layouts

Runtime layout describes which app runtime services the workflow should use. Exact layout labels (`standard`, `dev`, `simple`, `local-stage`, `local-only`) and the runtime names they map to live in the [Glossary](/zcp/glossary#runtime-layout). The user-facing three (dev, dev + stage, stage / linked target) are in [Build and ship → Choose the runtime layout](/zcp/workflows/build-with-zcp#choose-the-runtime-layout). Service scaling mode (`HA`/`NON_HA`) is a separate service setting.

In `standard`, stage is explicit. Work scoped to `appdev` does not silently touch `appstage`; a release or stage verification happens when the user asks for it.

## Develop

Develop is the main app-work loop. It begins after bootstrap has a runtime target and dependencies. It closes only when runtime reachability and requested behavior both pass, or when the agent has a blocker that needs a human decision. The loop itself is in [How it works → The work loop](/zcp/concept/how-it-works#the-work-loop). The labeled steps are:

1. **Name runtime target.** State which runtime is in scope: `appdev`, `appstage`, `app`, or a linked local target.
2. **Change code and config.** Edit app files, `zerops.yaml`, env references, migrations, seeds, framework config, or local `.env` bridge when needed.
3. **Deploy directly first.** The first verified runtime deploy goes through MCP tools. Git or CI handoff comes after proof.
4. **Start or restart if needed.** Dynamic dev runtimes may need an explicit start or restart after deploy. Built-in webserver runtimes do not need a separate dev-server step unless the framework requires one.
5. **Verify runtime reachability.** Check service status, recent error logs, and HTTP readiness when the runtime is an HTTP service.
6. **Verify requested behavior.** Check endpoint body, UI state, job result, persisted data, or another result tied to the user request.
7. **Fix from evidence.** Read failure category, logs, events, and check output. Repeating the same deploy without new evidence is not progress.

Reachability and requested behavior are separate gates. A green deploy with a broken route is not done.

## Failure categories

Failure categories (`build`, `start`, `verify`, `network`, `config`, `credential`, `other`) point the agent to the first useful evidence surface. The full read-first / avoid playbook is in [Troubleshooting → Evidence order](/zcp/reference/troubleshooting#evidence-order); the term definitions are in the [Glossary](/zcp/glossary#failure-category).

Categorization is what turns retries into evidence-driven fixes.

## Delivery after proof

Delivery mode applies after a verified deploy. It does not replace the first proof.

| Exact mode | User-facing choice | Meaning |
| ---------- | ------------------ | ------- |
| `auto` | Keep direct deploy | The agent keeps deploying future changes directly to the target runtime. |
| `git-push` | Push to git | The agent commits and pushes to a configured remote; any resulting build still needs observation and verification. |
| `manual` | External handoff | CI, release process, or a human owns future delivery; the workflow records evidence but does not initiate the next deploy. |
| `manual` | External handoff | CI, release process, or a human owns future delivery; the workflow records evidence but does not initiate the next deploy. |

Git-push capability, delivery mode, and build integration are separate. A project can have git-push configured while still using direct deploy for a given session.

Packaging and production release are deliberate handoffs after proof. Packaging turns a verified runtime into a git-backed import bundle. A production release moves verified work into a separate production project through GUI setup, git/CI triggers, or the team's release process.

## Generated files and state

Remote setup and `zcp init` create configuration around the MCP server and workflow guidance.

| File or directory | Created where | Purpose |
| ----------------- | ------------- | ------- |
| `CLAUDE.md` | Remote workspace or local project directory | Claude Code instruction surface. ZCP MCP writes a managed block between `<!-- ZCP:BEGIN -->` and `<!-- ZCP:END -->`. User content outside that block is preserved. |
| `.claude/settings.local.json` | Remote workspace or local project directory | Claude Code per-project settings and ZCP MCP tool permissions for that directory. |
| `.mcp.json` | Local project directory | Project-local MCP server config. It contains the local `zcp` command and the project-scoped `ZCP_API_KEY`; keep it out of git. |
| `~/.claude.json` and SSH config | Remote setup | Workspace-level Claude Code and SSH wiring used inside the Zerops-hosted workspace. |
| `.zcp/state/` | Working directory where the MCP server runs | Workflow state and service metadata for that project directory. |
| `.zcp/state/` | Working directory where the MCP server runs | Workflow state and service metadata for that project directory. |

The managed `CLAUDE.md` block is refreshed by `zcp init` and by the MCP server when the block already exists. Put durable project instructions outside the ZCP markers. Edits inside the managed block are treated as generated content.

`.zcp/state/` is not application source code and should not be committed. It stores metadata such as known runtime services, local/stage pairing, delivery preference, git-push setup, build integration, first-deploy stamps, workflow sessions, deploy attempts, verify attempts, and local coordination locks.

ZCP MCP does not use `.zcp/state/` as a stale copy of the Zerops project. Service status, logs, events, runtime files, env-var values, and current platform configuration are read from Zerops or from the local filesystem when tools run. Local `.env` files are generated separately and may contain secrets.

Do not edit `.zcp/state/` by hand during normal work. Use workflow operations to reset, resume, iterate, or reconfigure state. Deleting it intentionally discards local memory of services and delivery setup for that directory; the tools can rediscover live Zerops state, but delivery preferences and workflow history may need to be set again.

## Completion evidence

A completed app task should answer:

- which bootstrap route was used when setup was needed,
- which runtime target changed,
- which managed services were used or created,
- which deploy passed,
- which reachability check passed,
- which requested behavior passed,
- which URL, endpoint, UI state, worker result, or stored value proves it,
- which delivery choice applies next,
- or which blocker remains and what evidence supports it.

A clear blocker is acceptable completion only when it names the runtime in scope, failure category, evidence read, fixes tried, and human decision or credential still needed.

## Confirmation gates

Two operations pause because the loss is not safely reversible from inside the conversation: **service deletion** (named approval) and **destructive import override** (refuse-then-acknowledge). See [Tokens and credentials → What ZCP enforces for destructive actions](/zcp/security/tokens-and-project-access#what-zcp-enforces-for-destructive-actions) for the user-facing confirmation flow.

## Auditing a workflow

A workflow run is well-shaped if the evidence answers:

| Question | Evidence |
| -------- | -------- |
| Where did bootstrap start? | Live service list, saved workflow state, and bootstrap route. |
| Where did bootstrap end? | Runtime target, managed dependencies, and any human decisions. |
| Which runtime was developed and deployed? | Runtime target, deploy result, events, and logs. |
| What proved reachability? | Verify output, service status, public URL, or HTTP probe. |
| What proved behavior? | Endpoint, UI flow, job result, database/object state, or other requested proof. |
| What controls future delivery? | Delivery mode, git-push state, build integration, package bundle, or production release handoff note. |
| What controls future delivery? | Delivery mode, git-push state, build integration, package bundle, or production release handoff note. |

## Related reference

- [ZCP MCP tools](/zcp/reference/mcp-operations) — operation names and direct tool calls.
- [Troubleshooting](/zcp/reference/troubleshooting) — recovery order when a run gets stuck.
- [Glossary](/zcp/glossary) — exact terms used across the ZCP MCP reference.


----------------------------------------

# Zcp > Reference > Index


Reference pages exist for the moments when an exact label, tool name, or recovery step matters. For day-to-day app work, start in [Build and ship](/zcp/workflows/build-with-zcp); for the loop itself, [How it works](/zcp/concept/how-it-works).

- [Workflows in depth](/zcp/reference/agent-workflow) — Catalog of phases, routes, layouts, and labels behind a generated-workflow run.
- [ZCP MCP tools](/zcp/reference/mcp-operations) — Exact tool names and surface for custom MCP clients or agent policy.
- [Troubleshooting](/zcp/reference/troubleshooting) — When the agent is stuck, a session was interrupted, deploys keep failing, or you are taking over manually.
- [Glossary](/zcp/glossary) — Definitions for terms across pages and workflow status (`appdev`, `local-stage`, `delivery mode`, etc.).

## Common scenarios

<div className="zcp-claim-grid">

<div className="zcp-claim-card">

<span>SCENARIO</span>

### Debugging a stuck deploy

[Troubleshooting → Evidence order](/zcp/reference/troubleshooting#evidence-order) names what to read first; [Workflows in depth → Failure categories](/zcp/reference/agent-workflow#failure-categories) maps the labels.

</div>

<div className="zcp-claim-card">

<span>SCENARIO</span>

### Building a custom MCP client

[ZCP MCP tools](/zcp/reference/mcp-operations) for the tool surface; [Workflows in depth → What drives the workflow](/zcp/reference/agent-workflow#what-drives-the-workflow) for what the generated workflow adds on top of bare tools.

</div>

<div className="zcp-claim-card">

<span>SCENARIO</span>

### Auditing a finished run

[Workflows in depth → Completion evidence](/zcp/reference/agent-workflow#completion-evidence) for what should be in the final answer; [Trust model → Audit evidence](/zcp/security/trust-model#audit-evidence) for what Zerops records platform-side.

</div>

</div>


----------------------------------------

# Zcp > Reference > Mcp Operations


Most app work should be phrased as an outcome: build this, fix that, deploy and prove it. Operation names matter when you configure agent-client policy, debug an MCP integration, build a custom client, or use ZCP MCP pragmatically as a set of project-scoped Zerops tools.

ZCP MCP is the MCP server exposed by the `zcp` binary. Any MCP-capable client can connect to it and call tools such as `zerops_discover`, `zerops_logs`, `zerops_events`, `zerops_deploy`, or `zerops_verify`.

## Tool-only use

The MCP server exposes operations. It does not, by itself, decide the whole app lifecycle.

Claude Code with the generated workflow uses its instructions to decide sequencing: inspect state before changing things, choose the runtime target, use existing services or create missing ones, deploy, read failure evidence, verify requested behavior, and stop with proof or a blocker.

Tool-only use is valid when you want a custom MCP client, script, dashboard, policy-gated agent, or narrow operational task. In that setup, your integration owns the sequencing:

- which project services are in scope,
- when a deploy is allowed,
- what counts as verification,
- which logs or events should be read after failure,
- when to ask a human,
- when to stop.

Tool-level gates still apply. Service deletion requires explicit named approval, and destructive import override requires an acknowledgement of the exact targets.

If you use Claude Code but do not want the generated workflow guidance, keep the MCP connection and remove the ZCP-managed workflow block from `CLAUDE.md`, or keep your own policy outside the ZCP markers. What you lose is the generated instruction layer that makes the agent plan around live state, deploy with bounded retries, verify behavior, and report proof or a concrete blocker.

Generated files and workflow state are documented in [Workflows in depth](/zcp/reference/agent-workflow#generated-files-and-state).

## What the tools can do

| Area | Tools | Typical use |
| ---- | ----- | ----------- |
| Discover | `zerops_discover` | Read services, service metadata, env-var keys, and project topology. |
| Observe | `zerops_logs`, `zerops_events`, `zerops_verify`, `zerops_process` | Diagnose deploys, read runtime/build evidence, run health checks, and watch async processes. |
| Deploy | `zerops_deploy` | Push source through Zerops build/deploy pipeline and return build/deploy evidence. |
| Configure | `zerops_env`, `zerops_subdomain`, `zerops_scale`, `zerops_manage` | Change env vars, public subdomain access, scaling, lifecycle, reload/restart, and storage attachment. |
| Import/export | `zerops_import`, `zerops_export`, `zerops_preprocess` | Import project/service YAML, read export YAML, and expand Zerops preprocessor expressions. |
| Workspace | `zerops_mount` | Mount or unmount runtime filesystems in remote setup. |
| Workflow | `zerops_workflow` | Track, recover, or configure workflow sessions and packaging/export flow. |
| Destructive | `zerops_delete` | Delete one named service after explicit user approval. |
| Destructive | `zerops_delete` | Delete one named service after explicit user approval. |

Recipe-authoring and ZCP-internal maintenance operations are intentionally out of scope for this public reference.

## Read-only operations

| Operation | Purpose |
| --------- | ------- |
| `zerops_discover` | Read services, ports, env-var keys, and current state. |
| `zerops_export` | Read platform project/service export YAML and service metadata. |
| `zerops_logs` | Read runtime/build logs filtered by service, severity, time, or search. |
| `zerops_events` | Read service activity, deploys, builds, scaling, and failures. |
| `zerops_verify` | Run service health, recent error log, and HTTP-readiness checks. |
| `zerops_knowledge` | Fetch ZCP MCP guidance or platform knowledge for the current state. |
| `zerops_process` | Check a known async process; cancel is a mutating action. |
| `zerops_process` | Check a known async process; cancel is a mutating action. |

## Mutating operations

| Operation | Purpose |
| --------- | ------- |
| `zerops_deploy` | Ship code through the Zerops build and deploy pipeline. |
| `zerops_env` | Read, set, delete, or generate env vars and local `.env` files. |
| `zerops_manage` | Start, stop, restart, reload, or connect storage. |
| `zerops_scale` | Change CPU, RAM, disk, CPU mode, or container autoscaling where supported. `HA`/`NON_HA` is set at service creation. |
| `zerops_subdomain` | Enable or disable public subdomain access. |
| `zerops_delete` | Delete a service. Explicit named approval is required. |
| `zerops_delete` | Delete a service. Explicit named approval is required. |

## Operational setup

| Operation | Purpose |
| --------- | ------- |
| `zerops_workflow` | Track, recover, or configure workflow sessions; also carries the package-running-service export flow. |
| `zerops_import` | Import project/service definitions. Destructive override is gated. |
| `zerops_mount` | Mount or unmount runtime filesystems in remote setup. |
| `zerops_preprocess` | Expand Zerops preprocessor expressions. |
| `zerops_preprocess` | Expand Zerops preprocessor expressions. |

## Remote and local tool differences

The operation names are the same, but the filesystem and network boundary differ.

| Area | Remote setup | Local setup |
| ---- | ------------ | ----------- |
| Files | Runtime files through SSHFS or remote containers. | Local working directory. |
| Deploy source | Remote service or batch deploy inside Zerops. | Local `workingDir`. |
| Dev server | Remote setup can run or inspect remote dev processes. | Your local tool owns the dev server. |
| Env bridge | Env vars are already available in Zerops. | `.env` generation resolves Zerops references for local use. |
| Git | Workspace-managed credentials. | User's local git credentials. |
| Git | Workspace-managed credentials. | User's local git credentials. |

## Confirmation gates

Two operations require explicit care:

- **Service deletion** requires explicit user approval in the current conversation, by service name.
- **Destructive import override** first refuses and names what would be replaced; a second call must acknowledge the same targets.

See [Tokens and credentials](/zcp/security/tokens-and-project-access#what-zcp-enforces-for-destructive-actions) for the user-facing confirmation flow.

## Related reference

- [Workflows in depth](/zcp/reference/agent-workflow) - how a generated-workflow run uses these tools.
- [Troubleshooting](/zcp/reference/troubleshooting) - evidence order when a run gets stuck.
- [Tokens and credentials](/zcp/security/tokens-and-project-access) - token scope, storage, and confirmation gates.


----------------------------------------

# Zcp > Reference > Troubleshooting


Use troubleshooting when the agent is confused, a session was interrupted, deploy keeps failing, verification does not match the final answer, or you are taking over manually.

Start from current state, not chat memory:

```text
Read current project status and tell me where things stand before changing anything.
```

That should make the agent read live services, saved workflow state, recent deploys, logs, events, and verification output before it edits anything else.

## Find where the run is stuck

| Stuck point | Ask for | What you should get |
| ----------- | ------- | ------------------- |
| Agent lost context | Current project status and services in scope. | Runtime target, managed services, last deploy, last verify result, and any saved workflow state. |
| Service setup is unclear | Runtime target and dependency plan. | Which existing services will be used, which missing services are needed, and what needs human approval. |
| Deploy failed | Failure category plus build logs, runtime logs, and recent service events. | A cause or next diagnostic step, not another blind deploy. |
| Runtime is reachable but app behavior fails | The failing behavior check and request-time runtime logs. | Endpoint/UI/job/data evidence tied to the product request. |
| Local app cannot reach services | VPN state, generated `.env`, and selected runtime/setup. | Whether MCP auth works separately from private service access. |
| Delivery is ambiguous | Delivery mode, git-push state, build integration, or handoff note. | What will happen after proof: direct deploy, git push, CI, package, or production handoff. |
| Delivery is ambiguous | Delivery mode, git-push state, build integration, or handoff note. | What will happen after proof: direct deploy, git push, CI, package, or production handoff. |

Useful prompt:

```text
Show me the runtime in scope, failure category, evidence read, fixes tried, and the next decision needed.
```

## Evidence order

The useful evidence depends on the failure category surfaced by deploy or verify tools.

| Category | Read first | Avoid |
| -------- | ---------- | ----- |
| `build` | Build logs, build commands, dependency manifests, deploy file list. | Runtime logs; the runtime did not start yet. |
| `start` | Prepare/runtime logs, start command, ports, env references. | Rebuilding without checking why the process exited. |
| `verify` | Failing check detail, HTTP response, request-time runtime logs, stored state. | Calling a green deploy "done" before behavior passes. |
| `network` | VPN, SSH, DNS, subdomain readiness, service status, transport error. | Editing app code before proving connectivity. |
| `config` | Field-level rejection, `zerops.yaml`, setup name, env references, service settings. | Guessing from service names or dashboard memory. |
| `credential` | The named credential surface: `ZCP_API_KEY`, git, SSH, managed-service, CI, or external API. | Rotating unrelated secrets. |
| `other` | Raw events/logs and the exact phase that failed. | Repeating the same attempt after the same unknown reason. |
| `other` | Raw events/logs and the exact phase that failed. | Repeating the same attempt after the same unknown reason. |

Failure categories come from the deploy/verify evidence surface. They are not a verdict; they tell the agent where the next useful signal is.

## Local setup checks

Local setup has two separate connections:

- MCP uses `ZCP_API_KEY` to talk to the Zerops API.
- Your local app and shell use `zcli vpn up` to reach private service hostnames such as `db` or `cache`.

That means MCP can work while the app cannot reach the database.

| Symptom | Check |
| ------- | ----- |
| Agent does not list the `zerops` MCP server. | Relaunch the agent from the directory containing `.mcp.json`. |
| MCP startup says the token reaches multiple projects. | Replace `ZCP_API_KEY` with a single-project token. |
| Re-running `zcp init` made MCP disappear. | Re-add the `ZCP_API_KEY` env block to `.mcp.json` and restart the agent. |
| Local app cannot reach `db`, `cache`, or storage hostnames. | Run `zcli vpn up <project-id>` again. |
| Local app reads stale credentials. | Regenerate `.env`; it is a snapshot, not a live sync. |
| `zcp` is not found after install. | Add `~/.local/bin` or the install target to `PATH`, then restart the shell/agent. |
| `zcp` is not found after install. | Add `~/.local/bin` or the install target to `PATH`, then restart the shell/agent. |

For local setup details, use [Run locally](/zcp/setup/local-agent-bridge).

## Manual takeover

If you take over from the agent, read evidence in this order:

1. Service list and runtime target.
2. Service-scoped events for the runtime in question.
3. Build logs for build failures, runtime logs for start or request failures.
4. Verify output for reachability and requested behavior.
5. Git history only when delivery uses git-push or CI.

Do not inspect every service first. Start with the runtime in scope and expand only when the evidence points to a dependency.

## When to stop

Stop the loop when:

- the same failure repeats without new evidence,
- the agent needs an external credential,
- the target runtime or stage choice is ambiguous,
- a destructive action would delete or replace a service,
- production release authority is needed,
- the request no longer fits the current project layout.

A blocker is acceptable only when it names the runtime in scope, failure category, evidence read, fixes attempted, and the human decision or credential still needed.

Before destructive recovery, read service-scoped events, logs, deploy/verify result, and git history when delivery uses git-push. Token scope and destructive confirmations are covered in [Tokens and credentials](/zcp/security/tokens-and-project-access).


----------------------------------------

# Zcp > Security > Production Policy


Use the MCP setup in development or staging. Keep production in a separate Zerops project without a `zcp` service. Production deploys should come from CI, a release pipeline, or a deliberate human `zcli` push using production credentials.

Zerops does not prevent you from adding `zcp` to production. The policy exists because ZCP MCP gives a coding agent operational access. In production, that is the wrong blast radius for normal app development.

The production boundary does not make ZCP output disposable. The intended path is production-shaped dev or stage infrastructure, verified behavior, and then a controlled production release outside the agent loop.

## Recommended project layout

| Project                       | Contains                                                                                                | Who operates it                |
| ----------------------------- | ------------------------------------------------------------------------------------------------------- | ------------------------------ |
| Development / staging project | `zcp` service, agent workspace, dev runtime, optional stage runtime, non-production managed services    | Agent plus humans              |
| Production project            | Production runtimes, production managed services, production env values, production backups and scaling | CI/release process plus humans |
| Production project            | Production runtimes, production managed services, production env values, production backups and scaling | CI/release process plus humans |

The two projects use different Zerops tokens. A development token cannot reach production. A production token should not be placed in the development `zcp` service or a local `.mcp.json` used by the agent.

## Why production is a separate project

- **The Zerops project is the security boundary.** ZCP binds to one project at startup. Keeping production separate prevents a development agent from touching it by accident.
- **Secrets stay clean.** Production env values, database credentials, object-storage keys, and third-party secrets stay in the production project.
- **Operational policies can differ.** Production often needs HA services, stronger backup retention, stricter scaling, alerts, and release approvals. Development can stay cheaper and more flexible.
- **Audit trails stay readable.** Development experiments and agent retries do not mix with production deploy evidence.

This separation matters even when the same source repository deploys to both projects.

## What stage proves

Stage is the production-like rehearsal inside development or staging. It is where the agent proves the change before the release leaves the ZCP loop.

Use stage to match production where it matters:

- same runtime family and version,
- same managed service types,
- same build and start command pattern,
- same deploy route,
- behavior checks against a real running service.

Stage is not production. It should use non-production data and non-production secrets. A green stage means the change is ready for release, not that the agent should deploy to production itself.

## The release

After stage verifies, ZCP's job is done for that change. The production release happens outside the agent loop:

- CI deploys a merged commit or release tag to the production project.
- A release pipeline runs `zcli push` with a production-scoped `ZEROPS_TOKEN`.
- A human runs `zcli push` against the production project with production credentials.

The agent can prepare the handoff by pushing code, summarizing verification evidence, and naming the runtime and URL it verified. It should not bridge development to production.

For the practical workflow, see [Promote to production](/zcp/workflows/promote-to-production).

## Credential rules

| Credential                          | Production policy                                                                                        |
| ----------------------------------- | -------------------------------------------------------------------------------------------------------- |
| Development `ZCP_API_KEY`           | Never grants production access. Keep it scoped to the development/staging project.                       |
| Production `ZEROPS_TOKEN`           | Store only in the production CI/release secret store. Do not place it in the development `zcp` service.  |
| Agent subscription or model API key | May be used by the agent, but it does not grant Zerops production access by itself.                      |
| Git credentials                     | May push source changes, but production deploy authority should stay with the release process.           |
| Git credentials                     | May push source changes, but production deploy authority should stay with the release process.           |

If a production deploy fails, investigate in the production project with production logs, events, backups, and CI output. Do not attach the development agent directly to production as a shortcut.

## Production separation rules

| Rule                                                              | Why it matters                                                                        |
| ----------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
| Keep the production project without a `zcp` service               | Production should not host an agent workspace with operational access.                |
| Keep production tokens out of local `.mcp.json`                   | Local agents should operate development or staging projects, not production.          |
| Keep production `ZEROPS_TOKEN` in the release secret store        | Development tooling should not deploy to production outside the release process.      |
| Treat stage proof as release evidence, not production approval    | Stage is the rehearsal; production approval is a separate release decision.           |
| Promote through CI, release tooling, or a deliberate human action | Production execution should use production credentials.                               |
| Promote through CI, release tooling, or a deliberate human action | Production execution should use production credentials.                               |

## Acceptable agent involvement

The agent can still help before the production release:

- make the code change in development,
- deploy and verify dev/stage runtimes,
- produce the URL, endpoint result, or UI proof it verified,
- push or prepare the branch your team uses for review,
- summarize release notes and known blockers for the human or CI handoff.

ZCP's involvement stops at the handoff. Production execution belongs to the release process.

## Related security

- [Promote to production](/zcp/workflows/promote-to-production) - practical production release paths after ZCP proof.
- [Trust model](/zcp/security/trust-model) - the boundary that makes this policy enforceable.
- [Tokens and credentials](/zcp/security/tokens-and-project-access) - production and development credentials stay separate.


----------------------------------------

# Zcp > Security > Tokens And Project Access


ZCP uses a Zerops API token to operate exactly one project. The important rule is simple: `ZCP_API_KEY` is the Zerops credential for ZCP, not an agent login, not a git token, and not a general account token.

Remote setup gets `ZCP_API_KEY` from Zerops. Local setup reads it from `.mcp.json`. In both setups, ZCP validates the token at startup and refuses tokens that resolve to no project or multiple projects.

## Credential map

| Name                         | What it authorizes                           | Where it belongs                                                            |
| ---------------------------- | -------------------------------------------- | --------------------------------------------------------------------------- |
| `ZCP_API_KEY`                | ZCP against one Zerops project               | Remote: `zcp` service env injected by Zerops. Local: `.mcp.json` env block. |
| Agent login or model API key | The coding agent itself                      | The bundled agent in remote setup, or your local agent client.              |
| `GIT_TOKEN`                  | Git push from remote setup to a git provider | Secret env var on the `zcp` service when remote git-push delivery needs it. |
| `ZEROPS_TOKEN`               | `zcli` in GitHub Actions or external CI      | Separate Zerops delivery token stored in the CI/release secret store.       |
| `ZEROPS_TOKEN`               | `zcli` in GitHub Actions or external CI      | Separate Zerops delivery token stored in the CI/release secret store.       |

Keeping these names separate prevents most setup and delivery failures.

## Recommended `ZCP_API_KEY` shape

Use a Zerops API token with **Custom access per project**, exactly one selected project, and **Full access** for normal agent work.

Read-only tokens can authenticate, but they fail as soon as the agent needs to deploy, write env vars, restart services, scale, or change public access. Account-wide or multi-project tokens are refused before the agent can operate.

To generate the token:

1. Open [Settings -> Access Tokens Management](https://app.zerops.io/settings/token-management).
2. Create a token and name it for the project, for example `zcp-<project-slug>`.
3. Choose **Custom access per project**.
4. Add exactly one project.
5. Set that project to **Full access** for normal ZCP MCP work.
6. Create the token and copy the value. Zerops shows it only at creation time.

The token's blast radius equals the project and its granted permissions. Other projects, organization settings, and billing stay out of reach. Zerops [Roles & Permissions](/features/rbac#integration-tokens) remain the platform authority.

## Rejected token shapes

ZCP validates token shape at startup.

| Token shape                         | What happens                                | Fix                                                                  |
| ----------------------------------- | ------------------------------------------- | -------------------------------------------------------------------- |
| Account-wide or multi-project token | ZCP refuses to start.                       | Generate a token scoped to exactly one project.                      |
| Token with no project access        | ZCP refuses to start.                       | Grant one project or create a new single-project token.              |
| Expired or revoked token            | ZCP refuses to start or receives HTTP 401.  | Replace the token and restart the agent or ZCP process.              |
| Read-only project token             | Startup may pass, but mutations fail later. | Use full access for normal agent work, or expect read-only behavior. |
| Read-only project token             | Startup may pass, but mutations fail later. | Use full access for normal agent work, or expect read-only behavior. |

Common messages:

| Message                                                        | Meaning                                           |
| -------------------------------------------------------------- | ------------------------------------------------- |
| `Token accesses N projects; use project-scoped token`          | The token can see more than one project.          |
| `Token has no project access`                                  | The token authenticates but reaches no project.   |
| `No authentication found: set ZCP_API_KEY or log in with zcli` | The `zcp` process did not receive a usable token. |
| `AUTH_TOKEN_EXPIRED` or HTTP 401                               | The token expired, was revoked, or is invalid.    |
| `AUTH_TOKEN_EXPIRED` or HTTP 401                               | The token expired, was revoked, or is invalid.    |

For ZCP MCP setup, provide `ZCP_API_KEY`. `zcli` login is a diagnostic fallback, not the normal agent setup.

## Where the token lives - remote vs local {#where-the-token-lives--remote-vs-local}

ZCP reads `ZCP_API_KEY` from its process environment at startup. It does not write the token somewhere else or exchange it for a derived credential.

| Setup                                        | Where `ZCP_API_KEY` comes from                          | Who provisions it                                        |
| -------------------------------------------- | ------------------------------------------------------- | -------------------------------------------------------- |
| [Remote setup](/zcp/setup/hosted-workspace)  | The `zcp` service environment                           | Zerops injects it automatically when the service starts. |
| [Local setup](/zcp/setup/local-agent-bridge) | The `env` block of `.mcp.json` in the app directory     | You add it after `zcp init`.                             |
| [Local setup](/zcp/setup/local-agent-bridge) | The `env` block of `.mcp.json` in the app directory     | You add it after `zcp init`.                             |

In remote setup, do not hand-edit `ZCP_API_KEY`. Replace or rotate it through the Zerops-managed surface so the service keeps the intended project boundary.

In local setup, `zcp init` writes a token-less `.mcp.json`. Add the token manually:

```json
{
  "mcpServers": {
    "zerops": {
      "command": "zcp",
      "args": ["serve"],
      "env": {
        "ZCP_API_KEY": "<your-single-project-token>"
      }
    }
  }
}
```

Add `.mcp.json` to `.gitignore`. Each app directory should have its own file and token. Switching projects means switching directories, not editing one shared credential.

## Agent credentials are separate

The bundled agent in remote setup may ask you to sign in or provide a model API key. That is not `ZCP_API_KEY`.

Zerops wires the agent to ZCP. It does not provide your model subscription, store your agent login, or rotate your agent provider credentials. Treat the agent account exactly as you would outside Zerops.

## Git and CI credentials

`GIT_TOKEN` matters only when remote setup pushes to a git remote. It authorizes git provider access from the `zcp` service. In local setup, your local git CLI uses your normal SSH key or credential helper, so ZCP does not need `GIT_TOKEN`.

`ZEROPS_TOKEN` is a Zerops API token used by GitHub Actions or another CI system when that system runs `zcli` against Zerops. It is not a GitHub token. Use a separate delivery token so ZCP sessions and CI/release workflows can be named, rotated, and audited independently.

For production delivery, `ZEROPS_TOKEN` should reach production only and live only in the production CI or release secret store.

With GitHub CLI, the secret shape is:

```bash
gh secret set ZEROPS_TOKEN -b "$ZEROPS_DELIVERY_TOKEN"
```

Use the GitHub UI or your CI secret manager instead if your team does not allow local CLI secret writes.

## Rotation

Rotate in the Zerops dashboard, then update the surface that consumes the token.

| Surface              | Rotation step                                                                                                                            |
| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| Remote `ZCP_API_KEY` | Reconfigure or redeploy the remote workspace through the dashboard-managed flow, then restart the `zcp` service so the process gets the new value. |
| Local `ZCP_API_KEY`  | Paste the new token into `.mcp.json`, then restart the local agent client.                                                               |
| `ZEROPS_TOKEN` in CI | Replace the repository or CI secret. The next workflow run uses the new value.                                                           |
| `GIT_TOKEN`          | Replace the git-provider credential stored for remote setup.                                                                             |
| `GIT_TOKEN`          | Replace the git-provider credential stored for remote setup.                                                                             |

Rotation is picked up on the next process start or CI run, not in the middle of a live agent session.

## What ZCP enforces for destructive actions

A valid token does not remove every guardrail. ZCP MCP adds explicit confirmation for operations where the loss is not safely reversible from inside the conversation.

| Operation                                                 | Gate                                                                                                                                                   |
| --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Service deletion                                          | Requires explicit approval in the same conversation, including the service name. Remote setup also blocks deleting the `zcp` service it is running in. |
| Wholesale service replacement after failed deploy history | The first request refuses, surfaces what would be replaced, and requires the agent to read failure evidence before asking you to confirm.              |
| Wholesale service replacement after failed deploy history | The first request refuses, surfaces what would be replaced, and requires the agent to read failure evidence before asking you to confirm.              |

Deploys, env changes, lifecycle actions, restarts, scaling, and public-access changes do not get an additional ZCP-specific confirmation gate. They are normal operations for a full-access token and should be reviewed through service events, logs, verification output, and team policy.

Approval from a previous chat does not carry forward. A new conversation needs a new approval.

## Evidence before destructive recovery

When a service has recent failure history, ZCP enforces one recovery rule: read the platform evidence before destroying or replacing the service.

The agent should inspect service events, build logs, runtime logs, and failure summaries, then either fix the cause or show you the evidence before asking for destructive confirmation. The point is to preserve the failure context the next session needs.

A service waiting for first code deploy is not the same thing as a failed service. The gate is about recorded failure history, not idle state.

Threat model and boundaries: [Trust model](/zcp/security/trust-model).

## Credential checks

- **Account-wide full-access tokens are refused.** ZCP needs one project, not a broad account credential.
- **`zcp init` regenerates `.mcp.json`.** Re-add `ZCP_API_KEY` after rerunning it.
- **`GIT_TOKEN` is not `ZCP_API_KEY`.** One authorizes git provider access; the other authorizes Zerops operations.
- **`ZEROPS_TOKEN` in GitHub Actions is not a GitHub PAT.** It is a Zerops API token for `zcli`.
- **A rotated token needs a restart.** The live ZCP process keeps the old environment value until it starts again.
- **A successful confirmation is still destructive.** Backups, git history, and service events are your recovery evidence; ZCP does not auto-rollback a confirmed deletion or replacement.

## Related pages

- [Trust model](/zcp/security/trust-model) - the access boundary this page enforces.
- [What remote workspace gives you](/zcp/setup/hosted-workspace) - automatic token injection.
- [Run locally](/zcp/setup/local-agent-bridge) - local `.mcp.json` token setup.
- [Production boundary](/zcp/security/production-policy) - why production gets separate credentials.
- [GitHub integration](/references/github-integration) - CI secret usage with Zerops.


----------------------------------------

# Zcp > Security > Trust Model


The trust model starts with one rule: one ZCP process operates one Zerops project. `ZCP_API_KEY` decides that boundary at startup, and ZCP refuses tokens that resolve to no project or multiple projects.

That boundary is strong on the Zerops side. It does not make the agent harmless. A valid token can still deploy, change env vars, restart services, read logs, scale services, and change public access when Zerops permissions allow it. Treat it like an operations credential.

## Boundary summary

| Question                             | Answer                                                                                      |
| ------------------------------------ | ------------------------------------------------------------------------------------------- |
| What project can ZCP see?            | Exactly one project resolved from `ZCP_API_KEY` at startup.                                 |
| What can ZCP change?                 | Whatever Zerops RBAC grants that token inside the project.                                  |
| What is outside reach?               | Other projects, organization-wide settings, billing, and any operation Zerops RBAC rejects. |
| What network can remote setup reach? | Private services from inside the `zcp` service.                                             |
| What network can local setup reach?  | The Zerops API directly, plus private services only when your laptop VPN is up.             |
| Who owns the agent login?            | You. The agent subscription or model API key is separate from `ZCP_API_KEY`.                |
| Who owns the agent login?            | You. The agent subscription or model API key is separate from `ZCP_API_KEY`.                |

Zerops [RBAC](/features/rbac) remains the authority. ZCP does not bypass platform permissions; it exposes project operations to the agent only through the token it was given.

## Remote and local blast radius

Remote setup and local setup share the same Zerops boundary, but not the same surroundings.

| Area                       | Remote setup                                                                 | Local setup                                                     |
| -------------------------- | ---------------------------------------------------------------------------- | --------------------------------------------------------------- |
| Agent location             | Inside the `zcp@1` service when **Include Coding Agent** is enabled          | On your machine through your editor or CLI agent                |
| Files visible to the agent | Workspace files and mounted runtime files                                    | Local files and anything your client permits                    |
| Private service access     | Private network without laptop VPN                                           | `zcli vpn up <project-id>` from your machine                    |
| Local machine exposure     | No direct access to your laptop                                              | Agent client runs as your local user                            |
| Best safety posture        | Keep ZCP in a development/staging project and avoid mounting unrelated files | Restrict client permissions, shell access, and filesystem scope |
| Best safety posture        | Keep ZCP in a development/staging project and avoid mounting unrelated files | Restrict client permissions, shell access, and filesystem scope |

Remote setup is contained inside Zerops by design. Local setup is supervise-the-client by design. Either can be right, but local setup requires more attention to your agent client's local permissions.

## Credential ownership

There are three separate credential surfaces people often mix together:

| Credential                          | Owner                        | Purpose                                                |
| ----------------------------------- | ---------------------------- | ------------------------------------------------------ |
| `ZCP_API_KEY`                       | Zerops token                 | Lets ZCP operate one Zerops project.                   |
| Agent subscription or model API key | You / the agent provider     | Lets the coding agent run. Zerops does not provide it. |
| Git or CI credentials               | You / your repository system | Lets finished work push to git or deploy through CI.   |
| Git or CI credentials               | You / your repository system | Lets finished work push to git or deploy through CI.   |

In both setups, the agent account is still authenticated through the agent's own login flow. For where each credential lives (remote injection vs `.mcp.json`), rotation, rejected token shapes, and `GIT_TOKEN` / `ZEROPS_TOKEN`, see [Tokens and credentials](/zcp/security/tokens-and-project-access).

## What the token lets the agent do

The agent can perform normal operational work when the token has permission:

- discover runtime and managed services,
- create or adjust services when the task requires it,
- read and write service env vars,
- deploy app code to runtime services,
- read build logs, runtime logs, and service events,
- restart, reload, stop, start, or scale services,
- enable or disable public access,
- prepare delivery such as git push or CI handoff.

This is why development and staging projects are the right place for ZCP. Production should be a separate project without a `zcp` service; see [Production boundary](/zcp/security/production-policy).

## Remote setup specifics

- **`zcp` service is not the app.** It is the workspace and control surface. Deploys target app runtimes, not the `zcp` service.
- **The service has operational reach.** A terminal in the `zcp` service can use the same ZCP access as the agent. Review the dashboard's additional changes before deploying the service; they are what give the workspace its operating surface.
- **Network reach is broader than file reach.** The workspace can reach private services, but it only sees runtime files that are mounted into it.
- **Do not hand-edit `ZCP_API_KEY`.** Remote setup gets the value from Zerops. Manual replacement can break the intended one-project boundary.

## Local setup specifics

- **The agent inherits local reach.** ZCP MCP is limited to one project, but the local agent client can read files, run commands, and use credentials allowed by your client settings.
- **Each local directory has its own config.** `.mcp.json` and `.zcp/state/` belong to one app directory. Launching from the wrong directory can connect the wrong token or no token.
- **VPN is outside MCP authority.** Bringing up Zerops VPN needs your operating-system approval. The tools cannot grant that for the agent.
- **`.env` files are snapshots.** They contain real project credentials and should stay out of git.

## Human confirmation gates

Most project operations do not get an extra ZCP-specific confirmation prompt. Deploys, env changes, restarts, scaling, and public-access changes are normal project operations and are audited through platform evidence.

ZCP MCP adds hard gates where the loss is not safely reversible from the conversation: **service deletion** (explicit same-conversation approval by service name; remote setup also blocks deleting the `zcp` service it is running in) and **wholesale service replacement after failed deploy history** (refuse-then-acknowledge with failure evidence first). Approval from an old chat does not carry forward. The full enforcement rules are in [Tokens and credentials → What ZCP enforces for destructive actions](/zcp/security/tokens-and-project-access#what-zcp-enforces-for-destructive-actions).

## Audit evidence

Zerops records platform-side evidence. It does not record the agent's private reasoning, every shell edit, browser-helper action, or prompt history outside your agent client.

When taking over from an agent, read evidence in this order:

1. service-scoped events,
2. build logs,
3. runtime logs,
4. deploy and verification output,
5. git history when delivery uses git-push.

| Surface        | What it proves                                                            | What it does not prove                       |
| -------------- | ------------------------------------------------------------------------- | -------------------------------------------- |
| Service events | Deploy lifecycle, failures, restarts, scaling, and public-access changes. | The exact source edit that caused the event. |
| Build logs     | Dependency install, build commands, compile/package failures.             | Runtime request behavior after deploy.       |
| Runtime logs   | Start crashes, port binding, request-time app errors.                     | Why the build failed.                        |
| Verify output  | Whether reachability and requested behavior passed.                       | That unrelated app flows work.               |
| Git history    | Source changes pushed during git-push delivery.                           | Uncommitted shell edits.                     |
| Git history    | Source changes pushed during git-push delivery.                           | Uncommitted shell edits.                     |

Filter by service hostname when possible. Project-level timelines can include unrelated services and older failures.

## Related security

- [Tokens and credentials](/zcp/security/tokens-and-project-access) - token scope, storage, rotation, and confirmation gates.
- [Remote or local setup](/zcp/setup/choose-workspace) - compare blast radius before setup.
- [Production boundary](/zcp/security/production-policy) - keep production outside the agent loop.


----------------------------------------

# Zcp > Setup > Choose Workspace


Use this page to decide where the agent workspace lives: inside Zerops, or on your machine beside the local app directory.

Both setups connect the agent to one Zerops project and the same project-scoped operations. The tradeoff is where the agent works: filesystem ownership, private-service access, credential location, bundled tooling, and shell blast radius. The runtime layout is a separate app-work decision.

## What you are choosing

**Remote setup** always includes the `zcp@1` workspace service. If the chosen **runtime layout** has a development runtime, the agent works with that service too.

**Local setup** does not need the workspace service or a separate development runtime. It runs beside your **local source tree** and deploys to the Zerops runtime you choose to link.

Remote setup is the **safer default** for broader agent autonomy because the agent shell, private networking, and workspace files stay **inside Zerops** instead of on your machine. Use local setup when local files, data, desktop tools, git credentials, or a **local-only agent client** need to stay local.

## Setup comparison

|                         | Remote setup                                      | Local setup                                  |
| ----------------------- | ------------------------------------------------- | -------------------------------------------- |
| Workspace service       | Always has `zcp@1`.                               | Not required.                                |
| Development runtime     | Only if the runtime layout includes one.          | Not required for local work.                 |
| `zcp` process           | Runs in Zerops.                                   | Runs on your machine.                        |
| Agent process           | Runs in the remote workspace.                     | Runs in your local editor or CLI.            |
| Files the agent edits   | Workspace files and mounted runtime files.        | Files on your machine.                       |
| Private service access  | Private Zerops network from the workspace.        | Zerops VPN from your machine.                |
| Token storage           | Injected into the workspace service.              | `.mcp.json` in the local app directory.      |
| Git credentials         | Configured inside the workspace service.          | Your local git credentials.                  |
| Safety posture          | Broad agent shell permissions stay in Zerops.     | Agent shell permissions affect your machine. |
| Safety posture          | Broad agent shell permissions stay in Zerops.     | Agent shell permissions affect your machine. |

## Starting points

Remote setup can start from:

- **Recipe with AI Agent environment.** A guided path for a known stack. A recipe creates app services, managed services, and the `zcp@1` workspace together.
- **New Zerops setup with remote setup enabled.** Start from blank services or a custom stack and add the `zcp@1` service during creation.
- **Existing development or staging setup.** Add the `zcp` workspace next to services that already exist. Do not add ZCP to production; promote verified work through your release process instead.

Local setup can start from:

- **Empty local directory.** The agent creates the app structure from a product request and uses ZCP to select or create Zerops services.
- **Existing app directory.** The app code, editor setup, local data, and git credentials already live on your machine.
- **Recipe prepared for local setup.** The recipe creates the Zerops service baseline, while the agent and files stay local.

## Runtime layout is separate

Remote or local only answers where the agent and `zcp` process run. The project can still use:

- one mutable dev runtime,
- a dev + stage pair,
- a single app runtime,
- local files linked to a stage target.

That choice belongs to app work: [Build and ship](/zcp/workflows/build-with-zcp#choose-the-runtime-layout).

Stage is not production. Keep production in a separate Zerops project and promote work through your release process; see [Production boundary](/zcp/security/production-policy).

## Switching later

Remote and local setup are not permanent, but switching is a handoff between workspaces, not a sync operation. Before switching, make the handoff explicit:

- Preserve the current source tree through git or another explicit copy path.
- Choose one deploy source for the next task: the remote workspace, mounted runtime files, or the local app directory.
- Do not edit mounted runtime files and a local repo in parallel unless you have a merge plan.
- Regenerate local `.env` snapshots after Zerops env changes.
- If the local deploy target changed, have the agent inspect the current local link before deploying.

## Next steps

- [What remote workspace gives you](/zcp/setup/hosted-workspace) - remote setup, Browser VS Code, bundled agent CLI, and workspace persistence.
- [Run locally](/zcp/setup/local-agent-bridge) - local install, `zcp init`, `.mcp.json`, VPN, env snapshots, and deploy target linking.
- [Trust model](/zcp/security/trust-model) - how the safety boundary changes between remote setup and local setup.


----------------------------------------

# Zcp > Setup > Hosted Workspace


A remote workspace puts the agent, terminal, and optional browser IDE inside Zerops, next to private networking and ZCP access.

The `zcp@1` service runs the same `zcp` binary used by local setup, but broad shell permissions and private service access stay in a clean Zerops service instead of on your laptop.

Use remote setup when you want the default workspace, a safer boundary for broad agent permissions, or a preconfigured environment with a bundled coding agent and Browser VS Code.

App code still deploys to your app runtime services. The `zcp` service is the workspace and control surface; it is not the application runtime.

Taking over is straightforward in this setup. You open the same workspace, terminal, files, and workflow status the agent used, then continue, inspect, or stop the work from there.

## What it includes

- **`zcp@1` workspace service.** Runs ZCP inside Zerops and gives the agent project-scoped operations.
- **Platform-injected `ZCP_API_KEY`.** Zerops injects the token into the workspace; you normally do not set it by hand.
- **Bundled coding agent when enabled.** The **Include Coding Agent** option installs and preconfigures one of the supported agents: Claude Code (Anthropic), Codex (OpenAI), Antigravity, or Grok Build. You authenticate with your own subscription login or API credentials.
- **Browser VS Code when enabled.** The **Cloud IDE** option gives you a browser editor, terminal, and a place to supervise or take over the agent session.
- **Private networking.** The workspace can reach managed services by hostname without laptop VPN.
- **Open workspace model.** You can add other agent CLIs, private MCP servers, helper processes, dotfiles, package installs, or a derived team image.

For the local alternative, see [Run locally](/zcp/setup/local-agent-bridge). For the tradeoffs, see [Remote or local setup](/zcp/setup/choose-workspace).

## Choose a starting point

### First-time trial

Use the [Quickstart](/zcp/quickstart) when you want the guided recipe route. It covers the recipe catalog, **AI Agent** environment, coding agent authentication, Browser VS Code, first product prompt, and proof.

After provisioning, continue with a product prompt in [Build and ship](/zcp/workflows/build-with-zcp).

### Recipe with AI Agent environment

Use this when you want a guided stack baseline for development or staging. A recipe with an **AI Agent** environment creates app services, managed services, and the `zcp@1` workspace together.

Keep **Coding Agent** enabled when you want a bundled coding agent. Keep **Cloud IDE** enabled when you want Browser VS Code.

### New Zerops setup with remote setup enabled

Use this when you want blank services or a custom stack.

1. Open [Add new project](https://app.zerops.io/dashboard/project-add).
2. Enter the project name, region, and tags.
3. Enable the `zcp@1` remote setup service.
4. Keep **Include Coding Agent** enabled if you want a bundled coding agent.
5. Keep **Cloud IDE** enabled if you want browser VS Code.
6. Create the project.

This gives you the `zcp@1` workspace. App runtimes and managed services may still be created later by normal ZCP app work.

### Existing development or staging setup

Use this when runtime or managed services already exist in development or staging. Do not add `zcp` to production; promote verified work through your release process.

Add a `zcp` service from the dashboard the same way you add another Zerops service. The workspace appears next to the existing services and receives ZCP access from the platform.

The agent should still read current state before changing anything. Existing services are context, not instructions for the next task.

## Open the workspace

For a returning remote workspace, open the existing `zcp` service:

1. Open the project in the [Zerops dashboard](https://app.zerops.io/).
2. Open the `zcp` service.
3. Use **Browser VS Code** when **Cloud IDE** is enabled.
4. Complete your coding agent login or API-token flow if prompted (Claude Code, Codex, Antigravity, or Grok Build).

After authentication, your coding agent is connected to ZCP and ready to work from the Browser VS Code terminal. If the workspace was already authorized, use the same route to resume, supervise, or take over work.

First load can take a minute while the image, Cloud IDE, and bundled agent finish starting. If the page opens before the service is ready, wait until the service is running and reload.

## Use your own editor or tools

Browser VS Code is the quickest entry point, not the only one.

Editors that support remote development can connect to the workspace or runtime services over SSH, depending on how your team wants to work. Common options include VS Code Remote SSH, JetBrains Gateway, Cursor, Zed, and plain SSH.

This keeps the agent and private network inside Zerops while letting you use a desktop editor UI. Broader editor patterns live in [Local & Remote Development](/features/local-remote-development#native-ide-over-ssh).

You can also install another agent CLI or additional MCP servers inside the `zcp` service. The bundled agent flow is a convenience, not a closed product boundary.

## Advanced customization guardrails

Tools installed inside the `zcp` service may see workspace environment variables, private networking, and any runtime files mounted into the workspace. Use trusted and pinned tools. Keep model credentials, git delivery tokens, external API keys, and production credentials out of the workspace unless the current task explicitly needs them.

## What belongs where

| Concern              | Where it belongs                                                                                                            |
| -------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| Agent workspace      | The `zcp@1` service: agent CLI, browser VS Code, shell tools, MCP servers, helper processes, dotfiles.                      |
| App code deploys     | Your app runtime services; not the `zcp` workspace service.                                                                 |
| `ZCP_API_KEY`        | Injected by Zerops into the `zcp` workspace.                                                                                |
| Agent account        | Your agent subscription login or model API credential. Zerops wires the agent to ZCP, but the agent account remains yours. |
| Git credentials      | Configured inside the workspace when the agent should commit or push from remote setup.                                     |
| Production release   | A separate production project and release process.                                                                          |
| Production release   | A separate production project and release process.                                                                          |

## Runtime file access

Remote setup can mount runtime service filesystems into the `zcp` workspace after the first setup pass. Each mounted runtime appears as its own folder. Editing a mounted file changes the file inside that runtime service, with no upload step from your laptop.

Filesystem reach is narrower than network reach. The workspace can reach services over the private network, but it only sees runtime files mounted into it.

## Make customization persistent

The `zcp@1` service is a normal Zerops service. One-off shell installs disappear when the service is rebuilt unless you make them part of the service setup.

Use these patterns:

- **Small additions:** put package installs, dotfiles, or bootstrap scripts into service init commands.
- **Team-standard workspace:** build a derived image based on `zcp@1` with required tools already present.
- **Helper processes:** run private helpers next to the agent and editor workspace when your team needs internal integrations.

Keep app runtime build steps with the runtime services. The remote workspace carries the agent, tools, and ZCP access; runtime services own app builds and deploys.

## Next steps

- [Build and ship](/zcp/workflows/build-with-zcp) - normal app work after setup.
- [Tokens and credentials](/zcp/security/tokens-and-project-access) - how `ZCP_API_KEY`, git credentials, and CI secrets differ.


----------------------------------------

# Zcp > Setup > Local Agent Bridge


Local setup installs the `zcp` binary on your machine and runs it from the app directory where your agent works.

Use it when the agent should work next to local files, local data, your desktop editor, terminal tools, and git credentials. The MCP server limits Zerops operations to one project, but the agent client runs as your local user, so local approvals and filesystem allowlists matter.

[Remote setup](/zcp/setup/hosted-workspace) is the safer default when the agent does not need local files or tools. Use local setup when local control is the point.

:::warning Local setup maturity
Local setup has more moving parts than remote setup and may change faster. The binary install path, `.mcp.json` shape, and files written by `zcp init` are still settling between releases.
:::

## Choose a local starting point

Pick the folder that should own app work:

- **Empty local directory.** Start with no app code yet. The agent can create the app structure and use the MCP tools to select or create Zerops services.
- **Existing app directory.** Use this when app code, local data, editor setup, test fixtures, and git credentials already live on your machine.
- **Recipe prepared for local setup.** Use a recipe to create the Zerops service baseline, then run the agent locally from the directory that should own source changes.

After that choice, the mechanics are the same: install `zcp`, run `zcp init`, add `ZCP_API_KEY`, start VPN when private service access is needed, and link a runtime when the agent should deploy.

## What local setup gives the agent

- **Local files as source.** The agent edits the directory on your machine, and deploys use that working directory.
- **Your editor and terminal.** Framework CLIs, test runners, local data, and local feedback stay under your normal tools.
- **Your git credentials.** Pushes use your local git CLI, SSH agent, or credential helper.
- **Zerops operations.** The MCP tools let the agent discover services, generate env snapshots, deploy to linked runtimes, read logs, and verify.
- **Private service access through VPN.** Your local app and shell reach private service hostnames through `zcli vpn up`.

Security note: local setup cannot protect your laptop from the agent client. Configure approvals as you would for any local coding agent.

## Prerequisites

- A Zerops project. Create one from the [Zerops dashboard](https://app.zerops.io/dashboard/project-add), from a [recipe](https://app.zerops.io/recipes), or use an existing development/staging setup.
- [zCLI](/references/cli) installed and authenticated on your machine.
- A compatible local agent client installed and logged in.
- A **single-project Zerops token**. Multi-project tokens are refused at startup.
- A local directory where the agent should run.

You do not need MCP just to develop locally against Zerops services as a human. `zcli vpn up` plus your editor is enough. Add MCP when a local coding agent should also understand and operate Zerops.

## 1. Get `ZCP_API_KEY`

The MCP server needs a Zerops API token that reaches exactly one project. For normal agent work, use a full-access token; read-only tokens can authenticate but fail on deploys, env changes, lifecycle actions, and other mutations. Token generation, rejected shapes, and rotation are covered in [Tokens and credentials](/zcp/security/tokens-and-project-access).

## 2. Install `zcp`

```bash
curl -sSfL https://raw.githubusercontent.com/zeropsio/zcp/main/install.sh | sh
```

The installer downloads the latest release for your platform into `~/.local/bin`, or `/usr/local/bin` when run as root. Verify the install:

```bash
zcp version
```

If your shell cannot find `zcp`, add the install directory to `PATH` and reload the shell.

## 3. Run `zcp init`

From the local directory the agent should operate:

```bash
zcp init
```

`zcp init` writes local MCP config and agent instructions:

- `.mcp.json` - MCP server config for this directory.
- `CLAUDE.md` - agent instructions for Zerops work.
- `.claude/settings.local.json` - Claude Code per-project settings when that client is used.
- `~/.config/zerops/aliases` plus a shell-rc sourcing line - helper aliases for launching the agent here.
- `.zcp/state/` - workflow state created when MCP first writes local state.

Re-running `zcp init` may refresh generated config. `CLAUDE.md` preserves edits outside managed markers, but `.mcp.json` is regenerated from the token-less template. If you rerun it, re-check the `ZCP_API_KEY` block before launching the agent.

## 4. Add `ZCP_API_KEY`

`zcp init` writes a token-less `.mcp.json`. Add the project token under the `env` block:

```json
{
  "mcpServers": {
    "zerops": {
      "command": "zcp",
      "args": ["serve"],
      "env": {
        "ZCP_API_KEY": "<your-single-project-token>"
      }
    }
  }
}
```

Add `.mcp.json` to `.gitignore`. It contains a live Zerops credential and should not leave the machine. Each app directory should have its own `.mcp.json` and token.

The server name `zerops` is intentional. Do not rename it unless your agent client requires a different name and you understand the prompt/instruction changes.

## 5. Launch the agent from the app directory

Start the agent from the directory that contains `.mcp.json`. The client should list `zerops` as an available MCP server.

Sanity check:

```text
List the Zerops services through MCP.
```

A working connection answers with the runtime and managed services. If not, check the launch directory, token scope, and whether the client loaded `.mcp.json`.

## 6. Bring up VPN when private services are needed

The MCP server can talk to the Zerops API without VPN. Your local app, shell, tests, database clients, and framework commands need VPN to reach private hostnames such as `db` or `cache`.

```bash
zcli vpn up <project-id>
```

VPN setup needs admin or root approval on macOS and Linux. The tools can tell the agent which command is needed, but they cannot approve or start it for you. After the tunnel is up, service hostnames resolve from your machine; rerun the command when local service connections fail.

## 7. Generate local env when needed

When the local app needs service credentials, ask the agent for the app work and let the tools generate the env bridge. For a standalone check:

```text
Generate a .env file for my local app from Zerops env references.
```

Env generation needs `zerops.yaml` in the working directory, the runtime or setup the local app should use, a matching `setup:` entry, and non-empty `run.envVariables` under that setup.

The tools read `run.envVariables`, resolve Zerops references such as `${db_user}`, `${db_password}`, and `${db_hostname}`, and write the resulting values into `.env`. Cross-service references resolve recursively, so a `DATABASE_URL` can land as a complete local connection string.

If those inputs are missing, the agent should fix `zerops.yaml` or ask for the target runtime/setup. It should not invent env values from service names or dashboard memory.

The file is a snapshot, not a live sync. Regenerate it after changing env variables in Zerops. VPN is still required for your local app to use private service hostnames from that `.env`.

Keep `.env` out of git. It contains real connection values.

## 8. Link a deploy target

Local setup needs a Zerops runtime when the agent should deploy from your working directory. A stage runtime is the usual target because it lets local work prove itself before the production release.

If there is exactly one runtime, the agent can use it automatically. If multiple runtimes exist, it should ask which one to link:

```text
Link this local directory to appstage for deploys.
```

Without a linked runtime, the tools can still inspect services and generate env snapshots, but local deploys need a target first.

## What stays outside

MCP does not replace your local feedback loop. Vite, Valet, Docker Compose, your IDE runner, framework CLIs, local fixtures, and test data stay under your normal tooling.

Local setup does not mount Zerops runtime filesystems on your laptop. Remote setup can mount runtime files into the workspace; local setup works from files on your machine. To inspect runtime files from your machine, use [SSH](/references/networking/ssh) directly.

The MCP server does not own your git credentials. In local setup, your local git CLI, SSH agent, or credential helper handles pushes.

## Local setup checks

- **Launch directory matters.** Start the agent from the folder that contains `.mcp.json`.
- **`zcp init` can remove the token from `.mcp.json`.** Re-add `ZCP_API_KEY` after rerunning init.
- **VPN is separate from MCP auth.** MCP may work while your app still cannot reach `db`.
- **`.env` generation depends on `run.envVariables`.** If generation fails, check that the working directory has `zerops.yaml`, the selected `setup:` exists, and env entries live under `run.envVariables`.
- **`.env` is a credential snapshot.** Regenerate after env changes and keep it out of git.

## Next steps

- [Build and ship](/zcp/workflows/build-with-zcp) - normal app work after setup.
- [Tokens and credentials](/zcp/security/tokens-and-project-access) - token scope, storage, rotation, and destructive confirmations.


----------------------------------------

# Zcp > Workflows > Build With Zcp


Use Build and ship for the decisions that shape normal app work. ZCP MCP gives the agent Zerops project state, platform guidance, project-scoped operations, deploy evidence, and recovery rules. You still decide what should be built, where it should run, how strict the acceptance criteria are, and what happens after proof.

```text
Build a task board.
Tasks should stay saved after refresh.
```

A prompt can be that short when the outcome is enough. Add detail when it changes behavior, architecture, stack, runtime layout, acceptance criteria, credentials, delivery, packaging, or the production release.

The expected output is a verified running change, not only generated files. The agent should prove the request against a real runtime, real managed services when used, and the logs, events, and checks that explain what happened.

## The decisions

<div className="zcp-lifecycle-diagram">
  <div className="zcp-lifecycle-prompt">
    <span>Product prompt</span>
    <code>Build a task board...</code>
  </div>
  <div className="zcp-lifecycle-down" aria-hidden="true" />
  <div className="zcp-lifecycle-flow">
    <section className="zcp-lifecycle-stage zcp-lifecycle-stage--infra">
      <h3>1. Runtime layout</h3>
      <p>Choose where app work should land.</p>
      <ul>
        <li>Use existing services</li>
        <li>Create missing services</li>
        <li>Pick dev, stage, or linked target</li>
      </ul>
    </section>
    <section className="zcp-lifecycle-stage zcp-lifecycle-stage--dev">
      <h3>2. Development</h3>
      <p>The agent gets current state, Zerops knowledge, deploy evidence, and your product instructions.</p>
    </section>
    <section className="zcp-lifecycle-stage zcp-lifecycle-stage--delivery">
      <h3>3. After proof</h3>
      <p>Decide what happens to verified work.</p>
      <ul>
        <li>Direct deploy, git, or CI</li>
        <li>Optional package bundle</li>
        <li>Production release</li>
      </ul>
    </section>
  </div>
</div>

You do not run these steps by hand. They are the parts where your intent changes what the agent should do. If you do not specify a choice, the agent should infer from current project state and ask only when the decision changes cost, credentials, runtime layout, delivery, production risk, or destructive behavior.

## 1. Choose the runtime layout {#choose-the-runtime-layout}

When the app runtime and dependencies are unclear, the workflow prepares the layout before feature work starts. It reads current state, uses existing services when they fit, creates missing runtimes or managed services when needed, and stops when the agent knows where app code belongs.

The main user-facing choice is runtime layout. Let the agent infer it from the project, or name it in the prompt when it matters.

| Runtime layout            | Use when                                                                                  | What to tell the agent                                  |
| ------------------------- | ----------------------------------------------------------------------------------------- | ------------------------------------------------------- |
| **Dev**                   | You want one mutable runtime for fast iteration, experiments, or early app work.          | `Build a small Node.js API on dev.`                     |
| **Dev + stage**           | You want a development runtime plus a separate runtime for review or release rehearsal.  | `Build a Node.js API with PostgreSQL on dev+stage.`     |
| **Stage / linked target** | You work from local files or a single target runtime and want the workflow to use that target. | `Use appstage as the deploy target for this local app.` |
| **Stage / linked target** | You work from local files or a single target runtime and want the workflow to use that target. | `Use appstage as the deploy target for this local app.` |

The layout is about app runtimes, not where the `zcp` binary runs. Remote setup can use any of these layouts from the `zcp@1` workspace. Local setup usually works from local files into a linked stage or app runtime.

Managed services such as PostgreSQL, Valkey, queues, search, storage, or mail are dependencies. The agent gets their state and wiring patterns, but app code deploys to runtime services.

## 2. Development {#develop-with-live-project-context}

Development is still a normal coding conversation with the agent. You describe the product behavior, stack constraints, acceptance criteria, and anything the agent must not guess.

MCP adds the Zerops side of that conversation: current project state, platform knowledge, project-scoped operations, deploy/log evidence, verification checks, recovery rules, and saved work state. Because of that, you usually do not paste service inventory, env wiring, deploy logs, or a "deploy and verify" checklist into the prompt.

The useful things to name are:

- the behavior you want and how it should be verified,
- stack, framework, managed-service, or runtime target preferences,
- whether the agent should inspect or continue existing work first,
- approval boundaries for cost, credentials, data, production, or destructive actions.

Expect the agent to ask when one of those choices is missing. Otherwise, it should use project context while it works and finish with proof or a blocker.

## 3. Choose delivery after proof {#choose-delivery-after-proof}

Delivery preference is how app work closes after there is a verified result. Include it in the original prompt or set it later.

The first functional deploy is still direct so the agent can prove the app runs. Delivery preference decides what happens after that proof and how later sessions should finish similar work.

| Delivery preference    | What it means                                                                                      | What to tell the agent                                                      |
| ---------------------- | -------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
| **Keep direct deploy** | The agent keeps deploying directly to the target runtime for fast dev/stage iteration.             | `Keep direct deploy for now.`                                               |
| **Push to git**        | The agent commits and pushes working changes to the configured repository.                         | `When the app works, push changes to git@github.com:my-org/task-board.git.` |
| **CI / handoff**       | A repository integration, GitHub Actions workflow, release process, or human owns the next deploy. | `Set up GitHub Actions delivery for future deploys after the app works.`    |
| **CI / handoff**       | A repository integration, GitHub Actions workflow, release process, or human owns the next deploy. | `Set up GitHub Actions delivery for future deploys after the app works.`    |

The workflow records the delivery choice so later work can follow it. Git credentials, CI secrets, and production credentials are separate from `ZCP_API_KEY`; see [Tokens and credentials](/zcp/security/tokens-and-project-access).

## 4. Package a verified runtime {#package-a-verified-runtime}

After a runtime is verified, you can ask the agent to prepare it as a re-importable Zerops project bundle. Use this when the app should become a reusable starter, customer handoff, demo project, or clean staging project.

The prompt can be one sentence:

```text
Package appstage as a buildFromGit import bundle, commit it, and push it to git so I can import it into a fresh Zerops project.
```

The export workflow prepares `zerops-project-import.yaml` and `zerops.yaml` in the same git repo as the app. The import file contains one runtime with `buildFromGit:` pointing back to that repo, plus managed services needed for Zerops env references to resolve when the bundle is imported into a fresh project.

The agent may still ask which runtime to package, which half of a dev+stage pair to use, how to classify project env vars, or how to configure git push. Once pushed, the target project can import the bundle from the dashboard or with `zcli project project-import zerops-project-import.yaml`.

Packaging is not the next deploy of the same app. For the next app change, keep using the normal build/deploy/verify loop. Use packaging when the output you want is a git-backed import bundle; see [Package a running service](/zcp/workflows/package-running-service).

## 5. Prepare the production release {#prepare-production-release}

The production release is where authority changes. The agent prepares verified work and release evidence; production execution belongs to Zerops project settings, CI, release tooling, or a deliberate human action with production credentials.

The useful split is:

| Job | How often | What happens |
| --- | --- | --- |
| **Production infrastructure** | Once per production project | Export the verified project as YAML in the GUI, edit it for production, then import it as a new project. |
| **Production deploy trigger** | Once per production runtime | Connect the production runtime to git, usually with a tag trigger. |
| **Production release** | Every release | Verify in dev/stage, push source to git, then trigger production through your tag or release process. |
| **Production release** | Every release | Verify in dev/stage, push source to git, then trigger production through your tag or release process. |

Production should be a separate Zerops project without a `zcp` service. Production credentials are not `ZCP_API_KEY`; keep them in CI or release tooling. For the full release guide, see [Promote to production](/zcp/workflows/promote-to-production).

## What the final answer should contain

For a completed app task, the agent should report:

- the runtime service it changed,
- the deploy or verification target,
- the URL, endpoint, UI state, job result, or stored data that proves the requested behavior,
- managed services, env vars, or delivery settings it touched,
- the delivery preference, packaging output, or production release state that now applies.

If the task is incomplete, the final answer should name the blocker, the evidence read, what was tried, and the decision or credential needed from you.


----------------------------------------

# Zcp > Workflows > Package Running Service


Use packaging when a verified runtime should become a re-importable Zerops bundle. It is a handoff or reuse task after the app already works, not the normal way to deploy the next change.

You can ask for it directly:

```text
Package appstage as a buildFromGit import bundle.
Commit it and push it to git.
```

The result is a single git repo that contains the app source, [`zerops.yaml`](/zerops-yaml/specification), and a project [import file](/references/import) named `zerops-project-import.yaml`. The import file uses `buildFromGit:` so a fresh Zerops project can rebuild the app from the repo instead of carrying source code inside YAML.

Packaging starts from a deployed Zerops runtime. If important source changes exist only on your laptop, deploy or push them first so the runtime and git repo match what you want to package.

## When to package

Package a runtime when you need:

- a running runtime and its managed dependencies reproduced in another Zerops project,
- a reusable starter, demo, handoff, customer project, or clean staging baseline,
- a repo commit that carries the Zerops import shape next to the app source,
- the destination project to build from git.

Do not use packaging for:

- the next app deploy; use the normal build, deploy, and verify loop,
- the production release; production needs its own infrastructure, credentials, domains, and release trigger,
- moving managed-service data; backups and restores are separate.

For production setup, follow [Promote to production](/zcp/workflows/promote-to-production). Packaging can help create a reusable app bundle, but it does not decide production infrastructure or release policy.

## What the agent prepares

The agent packages **one** runtime. If the project has dev and stage runtimes, it asks which one to use because they can have different env values, start commands, or `setup:` blocks.

Managed services come along as dependencies when the runtime's `zerops.yaml` needs their env references. You do not pick databases, caches, queues, or search services one by one.

The workflow then prepares:

- `zerops-project-import.yaml` - the project and service shape for the destination project,
- `zerops.yaml` - the runtime build and run configuration,
- a git commit and push when git delivery is configured or explicitly requested.

If the runtime has no usable `zerops.yaml` or git remote, the agent has to fix that first. A bundle is only useful when the destination project can pull source and build it from git.

## Env vars need review

Project env vars are the main place where the agent may ask you to decide. Each value gets one bucket:

| Bucket | Use for | Bundle result |
| --- | --- | --- |
| `infrastructure` | Values derived from managed services, such as database or cache references. | Omitted from project envs; the new managed service provides fresh values. |
| `auto-secret` | App-owned signing or encryption keys that can be regenerated. | Fresh generated secret on import. |
| `external-secret` | Third-party credentials such as Stripe, OpenAI, Mailgun, or GitHub. | `REPLACE_ME` placeholder. |
| `plain-config` | Literal non-secret config such as log level, feature flags, or public app settings. | Copied as-is. |
| `plain-config` | Literal non-secret config such as log level, feature flags, or public app settings. | Copied as-is. |

Do not treat this as a key-name guessing game. The agent should inspect source code and ask when classification changes behavior. For example, regenerating a Laravel `APP_KEY`, Django `SECRET_KEY`, or session secret can break existing encrypted state. If state continuity matters, carry the existing value instead of generating a new one.

## What is not included

| Not included | What to do instead |
| --- | --- |
| Managed-service data | Restore from [Backup](/features/backup) or another migration path. |
| Real third-party secrets | Fill placeholders in the destination project before deploying. |
| Production domains, scaling, backups, and release triggers | Configure them in the destination project. |
| A repeatable production release process | Use your CI or release workflow; see [Promote to production](/zcp/workflows/promote-to-production). |
| A repeatable production release process | Use your CI or release workflow; see [Promote to production](/zcp/workflows/promote-to-production). |

## Use the bundle

After the bundle is pushed, import `zerops-project-import.yaml` in the destination project through the dashboard or with `zcli project project-import zerops-project-import.yaml`.

Before opening the new project to users:

- fill `REPLACE_ME` values,
- restore or seed data when needed,
- review service scaling and public access,
- run a normal deploy and verification pass in the destination project.


----------------------------------------

# Zcp > Workflows > Promote To Production


Use this after the agent has proved work in development or stage. The production release is the point where authority changes: the agent can prepare proof, source changes, and setup notes, but production execution belongs to Zerops project settings, CI, release tooling, or a deliberate human action with production credentials.

Production should be a separate Zerops project without a `zcp` service. That keeps the development agent out of the production blast radius while still letting verified work reach production.

## The simple production path

There are three different jobs. Two are setup work; one is the repeatable release operation.

| Job | How often | Simplest path |
| --- | --- | --- |
| **Create production infrastructure** | Once per production project | Export the verified Zerops project as YAML in the GUI, edit it for production, then import it as a new project. |
| **Connect the production deploy trigger** | Once per production runtime | In the production project, connect the git repository in the Zerops GUI and trigger builds from release tags. |
| **Release an app change** | Every release | Verify in dev/stage, push source to git, then create the release tag or use your team's release process. |
| **Release an app change** | Every release | Verify in dev/stage, push source to git, then create the release tag or use your team's release process. |

This page uses the GUI path because it is the clearest path available today. More customized teams can replace the GUI trigger with GitHub Actions or another CI system later.

## 1. Create production infrastructure

Do this once when you need a production project for a verified app.

1. Open the development or staging project that contains the verified runtime.
2. Use **Export project as yaml**.
3. Edit the exported YAML for production.
4. Import the edited YAML as a new Zerops project.

Before import, review the YAML as production infrastructure, not as a blind copy of the development project:

- remove the `zcp` service,
- remove dev-only runtimes and tools such as Mailpit or Adminer,
- keep the runtime and managed services that production actually needs,
- choose production `mode` values before creation, especially `HA` for databases that need it,
- set production `minContainers`, autoscaling, and core package,
- replace development secrets with production secrets or placeholders,
- plan managed-service data restore or migrations,
- configure production domains, DNS, public access, SMTP, object storage, backups, queues, search, and cache as needed.

Before opening production traffic, get familiar with the deeper Zerops production surface: service modes, scaling, deploy pipeline, health checks, backups, public access, and domains. If the app should use a real domain, follow [Public Access Configuration](/references/networking/public-access).

Project export/import creates the production infrastructure. Do not rely on it as the code delivery mechanism. The app source should be in git, and the first production code deploy should come through the production deploy trigger.

## 2. Connect the production deploy trigger

Do this once for each production runtime that should build from git.

The simplest path is the Zerops GitHub or GitLab integration in the production project:

1. Open the production runtime service.
2. Connect the git repository.
3. Choose **New tag** as the production trigger.
4. Add a tag filter if your team uses one, for example `v*`.
5. Keep production env vars and secrets in the production Zerops project.

For stage, a branch trigger can be convenient. For production, a tag trigger is easier to reason about: a normal source push can update stage, while a deliberate release tag updates production.

If your team needs approvals, custom tests, generated artifacts, or stricter audit, use GitHub Actions or another CI system instead. In that setup, store a production-scoped `ZEROPS_TOKEN` in the CI secret store and run the production deploy from CI.

## 3. Release an app change

This is the repeatable operation after production infrastructure and the deploy trigger exist. The exact release command is yours: define it in your repository instructions, agent skill, CI guide, or team release checklist.

For example, if production deploys from release tags, the user instruction can be as direct as:

```text
Create the release tag for production and push it to git.
```

Use the wording that matches your CI/CD. The release step can be a manual CLI action, a `git push`, a tag push, a pull request, a protected branch merge, or a CI job. That part is your team preference and production setup, not a rule from these docs.

The important rule is that the agent should name what it pushed and whether that push triggers stage, production, both, or neither. If production release requires a tag, the final answer should say the tag name or the exact tag command.

## What not to carry into production

Do not copy these from the development project into production:

- the `zcp` service,
- development `ZCP_API_KEY`,
- local `.mcp.json`,
- development secrets,
- test data unless it is intentionally migrated,
- dev-only utilities such as Mailpit or Adminer,
- `.zerops.app` preview routing as the final public entry point.

Use production-specific domains, secrets, backup policy, scaling, and release credentials.

## What the agent should hand you

A useful release handoff from the agent contains:

- runtime and project where the change was verified,
- URL, endpoint, UI state, job result, or stored data that proves the requested behavior,
- commit, branch, PR, or suggested release tag,
- whether the git push triggers stage, production, both, or neither,
- services to keep, remove, or change before importing production infrastructure,
- env vars, managed services, migrations, or delivery settings touched,
- external secrets still needed,
- managed-service data that must be restored or migrated,
- production blockers that need a human decision.

If the answer only says that files were changed, the release handoff is incomplete. Ask for the verification evidence and the exact release artifact.

Production hardening belongs in your team's production checklist. This page only defines the handoff from verified dev or stage work into production authority.

## Related production references

- [Production boundary](/zcp/security/production-policy) — Why production stays outside the agent loop.
- [Import & Export YAML Configuration](/references/import) — Project export and import reference.
- [Public Access Configuration](/references/networking/public-access) — Custom domains, DNS, SSL, and production public access.


----------------------------------------

# Zerops Yaml > Base List


This is a list of all currently supported versions of technologies that can be used for <code>[build.base](/zerops-yaml/specification#base-required)</code> and <code>[run.base](/zerops-yaml/specification#base)</code> sections in `zerops.yaml`.

:::note
Versions listed on the same line are aliases of the same underlying version.
:::

## Runtime services

<table className="w-full my-1.5 whitespace-nowrap">
  <thead>
    <tr>
      <th rowspan="2" className="">Service Type</th>
      <th rowspan="2" className="">Supported OS</th>
      <th colspan="2" className="w-full">Versions</th>
    </tr>
  <tr>
    <th colspan="2" className="w-full">Build / Runtime</th>
  </tr>
</thead>
  <tbody>
    <tr>
     <td className="w-fit">Bun</td>
     <td className="w-fit">`ubuntu` / `alpine`</td>
     <td colspan="2" className="w-fit">
- `bun@1.3.9`, `bun@1.3`, `bun@latest`
- `bun@1.2.2`, `bun@1.2`
- `bun@nightly`
- `bun@canary`
- `bun@1.1.34`, `bun@1.1(Ubuntu only)`
</td>
    </tr>
    <tr>
     <td className="w-fit">Deno</td>
     <td className="w-fit">`ubuntu`</td>
     <td colspan="2" className="w-fit">
- `deno@2.0.0`, `deno@2`, `deno@latest`
- `deno@1.45.5`, `deno@1`
</td>
    </tr>
    <tr>
     <td className="w-fit">.NET</td>
     <td className="w-fit">`ubuntu` / `alpine`</td>
     <td colspan="2" className="w-fit">
- `dotnet@10`, `dotnet@latest`
- `dotnet@9`
- `dotnet@8`
- `dotnet@7`
- `dotnet@6`
</td>
    </tr>
    <tr>
     <td className="w-fit">Elixir</td>
     <td className="w-fit">`ubuntu` / `alpine`</td>
     <td colspan="2" className="w-fit">
- `elixir@1.16`, `elixir@1`, `elixir@latest`
</td>
    </tr>
    <tr>
     <td className="w-fit">Gleam</td>
     <td className="w-fit">`ubuntu`</td>
     <td colspan="2" className="w-fit">
- `gleam@1.5`, `gleam@1`, `gleam@latest`
</td>
    </tr>
    <tr>
     <td className="w-fit">Go</td>
     <td className="w-fit">`ubuntu` / `alpine`</td>
     <td colspan="2" className="w-fit">
- `go@1.22`, `go@1`, `golang@1`, `go@latest`, `golang@latest`
</td>
    </tr>
    <tr>
     <td className="w-fit">Java</td>
     <td className="w-fit">`ubuntu` / `alpine`</td>
     <td colspan="2" className="w-fit">
- `java@21`, `java@latest`
- `java@17`
</td>
    </tr>
    <tr>
      <td className="w-fit">Node.js</td>
      <td className="w-fit">`ubuntu` / `alpine`</td>
      <td colspan="2" className="w-fit">
- `nodejs@24`, `nodejs@latest`
- `nodejs@22`
- `nodejs@20`
- `nodejs@18`
</td>
    </tr>
    <tr>
      <td className="w-fit">Python</td>
      <td className="w-fit">`ubuntu` / `alpine`</td>
      <td colspan="2" className="w-fit">
- `python@3.14 (Ubuntu only)`, `python@latest`
- `python@3.12`
- `python@3.11`
</td>
    </tr>
    <tr>
      <td className="w-fit">Rust</td>
      <td className="w-fit">`ubuntu` / `alpine`</td>
      <td colspan="2" className="w-fit">
- `rust@1`, `rust@latest`, `rust@stable`
- `rust@1.86`
- `rust@1.80`
- `rust@1.78`
- `rust@nightly`
</td>
    </tr>
      <tr>
        <th className="w-fit">&nbsp;</th>
        <th className="w-fit">&nbsp;</th>
        <th className="w-full">Build</th>
        <th className="w-full">Runtime</th>
      </tr>
    <tr>
      <td className="w-fit">PHP + Apache</td>
      <td className="w-fit">`ubuntu` / `alpine`</td>
      <td className="w-fit">
- `php@8.5`, `php@latest`
- `php@8.4`
- `php@8.3`
- `php@8.1`
</td>
      <td className="w-fit">
- `php-apache@8.5`, `php-apache@latest`
- `php-apache@8.4`
- `php-apache@8.3`
- `php-apache@8.1`
</td>
    </tr>
    <tr>
      <td className="w-fit">PHP + nginx</td>
      <td className="w-fit">`ubuntu` / `alpine`</td>
      <td className="w-fit">
- `php@8.5`, `php@latest`
- `php@8.4`
- `php@8.3`
- `php@8.1`
</td>
      <td className="w-fit">
- `php-nginx@8.5`, `php-nginx@latest`
- `php-nginx@8.4`
- `php-nginx@8.3`
- `php-nginx@8.1`
</td>
    </tr>
  </tbody>
</table>

## Static services

<table className="w-full my-1.5 whitespace-nowrap">
  <thead>
    <tr>
      <th rowspan="2" className="">Service Type</th>
      <th rowspan="2" className="">Supported OS</th>
      <th colspan="2" className="w-full">Versions</th>
    </tr>
  <tr>
    <th className="w-full">Build</th>
    <th className="w-full">Runtime</th>
  </tr>
  </thead>
  <tbody>
    <tr>
      <td className="w-fit">nginx</td>
      <td className="w-fit">`ubuntu`/`alpine`</td>
      <td className="w-fit">-</td>
      <td className="w-fit">
- `nginx@1.22`, `nginx@latest`
</td>
    </tr>
    <tr>
      <td className="w-fit">static</td>
      <td className="w-fit">`ubuntu`/`alpine`</td>
      <td className="w-fit">-</td>
      <td className="w-fit">
- `static`, `static@1.0`, `static@latest`
</td>
    </tr>
  </tbody>
</table>

## Containers and virtual machines

<table className="w-full my-1.5 whitespace-nowrap">
  <thead>
    <tr>
      <th rowspan="2" className="">Service Type</th>
      <th rowspan="2" className="">Supported OS</th>
      <th colspan="2" className="w-full">Versions</th>
    </tr>
  <tr>
    <th className="w-full">Build</th>
    <th className="w-full">Runtime</th>
  </tr>
  </thead>
  <tbody>
    <tr>
      <td className="w-fit">Docker</td>
      <td className="w-fit">`alpine`</td>
      <td className="w-fit">-</td>
      <td className="w-fit">
- `docker@26.1`, `docker@latest`
</td>
    </tr>
    <tr>
      <td className="w-fit">Alpine</td>
      <td className="w-fit">`alpine`</td>
      <td colspan="2" className="w-fit">
- `alpine@3.23`, `alpine@latest`
- `alpine@3.22`
- `alpine@3.21`
- `alpine@3.20`
- `alpine@3.19`
- `alpine@3.18`
- `alpine@3.17`
</td>
    </tr>
    <tr>
      <td className="w-fit">Ubuntu</td>
      <td className="w-fit">`ubuntu`</td>
      <td colspan="2" className="w-fit">
- `ubuntu@24.04`
- `ubuntu@22.04`, `ubuntu@latest`
</td>
    </tr>
  </tbody>
</table>

----------------------------------------

# Zerops Yaml > Cron


Cron jobs are scheduled commands that execute automatically inside a service's containers based on defined timing rules.

In Zerops, these jobs are configured in the `run` section of `zerops.yaml` file under the `crontab` key.

## Parameters

### command
*string, REQUIRED*

The shell command to execute at the scheduled time. This can be any valid command.

### timing
*string, REQUIRED*

The schedule for when the task should run, specified in standard cron format using five space-separated fields:
  - Minute (0–59)
  - Hour (0–23)
  - Day of the month (1–31)
  - Month (1–12)
  - Day of the week (0–7; both 0 and 7 represent Sunday)

#### Examples
  - `"0 5 * * *"` – Runs daily at 5:00 AM.
  - `"*/10 * * * *"` – Runs every 10 minutes.

### allContainers
*boolean, REQUIRED*

**Options:**
- `true` – Command runs on all containers.
- `false` – Command runs on only one container.

### workingDir
*string, REQUIRED*

Specifies the directory where the command will be executed. If not set, it defaults to `/var/www`.

## Example Configurations
Here’s a basic example of how to set up a cron job in your service's `zerops.yaml`:

```yaml
run:
  crontab:
    - command: "date >> /var/log/cron.log"
      timing: "0 * * * *"
```
This configuration logs the current date to `/var/log/cron.log` every hour.

### Running on Multiple Containers
By default, cron jobs run on a single container, even if multiple containers exist for the service. To execute a command across all containers, you can use the `allContainers` parameter:

```yaml
run:
  crontab:
    - command: "rm -rf /tmp/*"
      timing: "0 0 * * *"
      allContainers: true
```
This example removes temporary files from all containers every day at midnight.

### Custom Working Directory
You can also specify a custom working directory for your commands using the `workingDir` parameter:

```yaml
run:
  crontab:
    - command: "php artisan schedule:run"
      timing: "* * * * *"
      workingDir: /var/www/html
```
In this case, the command runs every minute in the `/var/www/html` directory.

### Multiple Cronjobs
It is possible to define multiple cron jobs as a YAML object list under the `crontab` key.

```yaml
run:
  crontab:
    - command: ...
      ...
    - command: ...
      ...
```


----------------------------------------

# Zerops Yaml > Specification


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:

- {data.alpine.default}
- {data.ubuntu.default}

```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: ${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](/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: ${db_password}
```

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


----------------------------------------