The base build environment contains Alpine 3.20, the selected major version of Bun, [Zerops command line tool](/references/cli), `npm`, `yarn`, `git` and `npx` tools.
:::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: - Alpine 3.20 - Ubuntu 24.04 :::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: - Alpine 3.20 - 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 the `/var/www` 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). :::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. 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: ``` 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: ```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 ... ```The base runtime environment contains Alpine 3.20, the selected major version of Bun, Zerops command line tool, `npm`, `yarn`, `git` and `npx` tools.
:::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: - Alpine 3.20 - Ubuntu 24.04 :::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. | ### prepareCommands _OPTIONAL._ Customises the Bun runtime environment by installing additional dependencies or tools to the runtime base environment.The base Bun environment contains Alpine 3.20 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:
```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 #### 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 containerThe prepare runtime container contains Alpine 3.20, the selected major version of Bun, [Zerops command line tool](/references/cli) and `npm`, `yarn`, `git` and `npx` tools.
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). 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: ``` 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:| Parameter | Description |
|---|---|
| port | Defines the port of the HTTP GET request.
The readiness check will trigger a GET request on {'http://127.0.0.1:{port}/{path}'} |
| path | Defines the URL path of the HTTP GET request.
The readiness check will trigger a GET request on {'http://127.0.0.1:{port}/{path}'} |
| host | Optional. The readiness check is triggered from inside of your runtime container so it always 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 readiness check is triggered from inside of your runtime container so no https is required.
If your application requires a https request, set scheme: https |
| Parameter | Description |
|---|---|
| port | Defines the port of the HTTP GET request.
The readiness check will trigger a GET request on {'http://127.0.0.1:{port}/{path}'} |
| path | Defines the URL path of the HTTP GET request.
The readiness check will trigger a GET request on {'http://127.0.0.1:{port}/{path}'} |
| host | Optional. The readiness check is triggered from inside of your runtime container so it always 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 readiness check is triggered from inside of your runtime container so no https is required.
If your application requires a https request, set scheme: https |