Zerops YAML Configuration

The zerops.yml file is crucial for defining how Zerops should build and deploy your application. Add the zerops.yml file to the root of your repository and customize it to suit your application's needs.

---

Quick Links to Runtime-Specific Guides

• Node.js
• PHP
• Python
• Go
• .NET
• Rust
• Java
• nginx static

Basic Structure

zerops.yml

zerops:
  - setup: <service_name>
    build: ...
    run: ...

• The top-level element is always zerops.
• setup contains the hostname of your service (must exist in Zerops).
• Multiple services can be defined in a single zerops.yml (useful for monorepos):

zerops:
  - setup: app
    build: ...
    run: ...

  - setup: api
    build: ...
    run: ...

Each service configuration requires build and run sections. An optional deploy section can be added for readiness checks.

Build Configuration

base (Required)

Sets the base technology for the build environment. See available options.

build:
  base: nodejs@latest

You can specify multiple technologies:

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

os (Optional)

Sets the operating system for the build environment. Options:

• alpine (default)
• ubuntu

Current versions:

• Alpine 3.19
• Ubuntu 22.04

build:
  os: ubuntu

prepareCommands (Optional)

Customizes the build environment by installing additional dependencies or tools.

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

buildCommands (Required)

Defines the commands to build your application.

build:
  buildCommands:
    - npm install
    - npm run build

Running commands in a single shell instance:

buildCommands:
  - |
    npm install
    npm run build

deployFiles (Required)

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

build:
  deployFiles:
    - dist
    - package.json
    - node_modules

Using wildcards:

deployFiles: ./path/~/to/file.txt

.deployignore

Use a .deployignore file to exclude specific files or folders from deployment.

cache (Optional)

Defines which files or folders to cache for subsequent builds.

build:
  cache: node_modules

envVariables (Optional)

Sets environment variables for the build environment.

build:
  envVariables:
    DB_NAME: db
    DB_HOST: db
    DB_USER: db
    DB_PASS: ${db_password}

Runtime Configuration

base (Optional)

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

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.

run:
  ports:
    - port: 8080
      protocol: TCP
      httpSupport: true

prepareCommands (Optional)

Customizes the runtime environment by installing additional dependencies or tools.

addToRunPrepare (Optional)

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

initCommands (Optional)

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

run:
  initCommands:
    - rm -rf ./cache

start (Required for some runtimes)

Defines the start command for your application.

run:
  start: npm start

startCommands (Optional)

Defines start commands

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

run:
  startCommands:
    # start the application
    - command: npm run start:prod
      name: server
    # start the replication
    
    - command: litestream replicate -config=litestream.yml
      name: replication
      # restore the database on container init
      initCommands:
        - litestream restore -if-replica-exists -if-db-not-exists -config=litestream.yml $DB_NAME

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

healthCheck (Optional)

Defines a health check for your application.

run:
  healthCheck:
    httpGet:
      port: 80
      path: /status

Deploy Configuration

readinessCheck (Optional)

Defines a readiness check for your application. (See readiness checks)

deploy:
  readinessCheck:
    httpGet:
      port: 80
      path: /status
      host: 127.0.0.1
      scheme: https

    # Or use commands
    exec:
      command: |
        touch grass
        rm -rf life
        mv /outside/user /home/user

Note

For more detailed information on specific configurations, refer to the runtime-specific guides linked at the beginning of this document.

---