# Configure Your Nginx build & deploy 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: ```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 ... ```

The base runtime environment contains Alpine 3.20, the selected major version of Nginx, [Zerops command line tool](/references/cli) and `composer`, `git` and `wget`.

:::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: - Alpine 3.20 - Ubuntu 24.04 :::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:
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._ Customizes the Nginx runtime environment by installing additional dependencies or tools to the runtime base environment.

The base Nginx environment contains Alpine 3.20, 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:

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

The prepare runtime container contains Alpine 3.20, the selected major version of Nginx, [Zerops command line tool](/references/cli) and `composer`, `git` and `wget`.

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. 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: ``` 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:
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
**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:
Parameter Description
command 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.
**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:
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
**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:
Parameter Description
command 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.
**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.