Skip to main content
Zerops provides a customizable build and runtime environment for Node.js applications. Configure your entire pipeline using a zerops.yaml file in your repository root.

​
Basic zerops.yaml Structure

Here’s a complete example: 
zerops:
  - setup: app
    build:
      base: nodejs@20
      buildCommands:
        - npm ci
        - npm run build
      deployFiles:
        - dist
        - node_modules
        - package.json
      cache: node_modules
    
    run:
      base: nodejs@20
      ports:
        - port: 3000
          httpSupport: true
      start: npm start

​
Build Configuration

​
base

Required. Sets the Node.js version for the build environment. 
build:
  base: nodejs@20
Available versions:
  • nodejs@18
  • nodejs@20
  • nodejs@22
  • nodejs@latest
The base environment includes:
  • Alpine Linux (latest)
  • Selected Node.js version
  • npm, yarn, git, and npx
  • Zerops CLI (zsc)
Changing the base version invalidates your build cache.

​
os

Optional. Choose the operating system. 
build:
  base: nodejs@20
  os: ubuntu  # or alpine (default)
Options:
  • alpine (default) - Alpine Linux 3.19
  • ubuntu - Ubuntu 22.04

​
prepareCommands

Optional. Install additional dependencies before building. 
build:
  base: nodejs@20
  prepareCommands:
    - apt-get update
    - apt-get install -y python3 make g++
    - npm install -g pnpm
Zerops runs prepare commands in order before your build:
  1. Creates a build container
  2. Downloads your code to /var/www
  3. Runs prepare commands
  4. Proceeds to build commands
These commands are cached. Modifying prepareCommands invalidates the cache.

​
buildCommands

Optional. Define commands to build your application. 
buildCommands:
  - npm ci
  - npm run build
  - npm test
Common build patterns: 
buildCommands:
  - npm ci
  - npm run build
If any command returns a non-zero exit code, the build fails. Check build logs for debugging.

​
deployFiles

Required. Specify which files to deploy after a successful build. 
deployFiles:
  - dist
  - node_modules
  - package.json
Common patterns: 
deployFiles:
  - dist
  - node_modules
  - package.json

​
Using Wildcards

Use ~ as a wildcard: 
# Deploy all package.json files in any directory
deployFiles: ./~/package.json

# Deploy all folders under src/
deployFiles: ./src/~/

​
.deployignore

Create a .deployignore file to exclude files:
.deployignore
# Ignore test files
**/*.test.js
**/*.spec.js

# Ignore documentation
/docs
*.md

# Ignore development files
.env.local
.vscode

​
cache

Optional. Cache files/folders for faster builds. 
cache: node_modules
Multiple paths: 
cache:
  - node_modules
  - .npm
  - dist
Caching node_modules can significantly speed up builds when dependencies don’t change.

​
envVariables

Optional. Set environment variables for the build. 
build:
  envVariables:
    NODE_ENV: production
    API_URL: https://api.example.com
    DB_HOST: db

​
Runtime Configuration

​
base

Optional. Set the Node.js version for runtime (defaults to build version). 
run:
  base: nodejs@20

​
ports

Optional. Define which ports your app listens on. 
run:
  ports:
    - port: 3000
      httpSupport: true
    - port: 8080
      protocol: TCP
Port configuration:
  • port - Port number (10-65435)
  • protocol - TCP (default) or UDP
  • httpSupport - Enable HTTP routing (default: true for TCP)
Other services in your project can access your app using hostname:port (e.g., app:3000).

​
prepareCommands

Optional. Customize the runtime environment. 
run:
  prepareCommands:
    - apt-get update
    - apt-get install -y imagemagick
These commands run once when creating the runtime container and are cached.

​
initCommands

Optional. Run commands each time a container starts. 
run:
  initCommands:
    - rm -rf ./tmp/*
    - mkdir -p ./uploads
Init commands delay container startup. Use prepareCommands for environment setup.

​
start

Required. Command to start your application. 
run:
  start: npm start
Common start commands: 
start: npm start

​
envVariables

Optional. Set runtime environment variables. 
run:
  envVariables:
    NODE_ENV: production
    PORT: 3000
    DB_HOST: db
    DB_PASSWORD: ${db_password}  # Reference secret variable

​
healthCheck

Optional. Configure health checks. 
run:
  healthCheck:
    httpGet:
      port: 3000
      path: /health
      scheme: http

​
Complete Example

Here’s a production-ready configuration: 
zerops:
  - setup: app
    build:
      base: nodejs@20
      os: alpine
      
      prepareCommands:
        - npm install -g pnpm
      
      buildCommands:
        - pnpm install --frozen-lockfile
        - pnpm run build
        - pnpm run test
      
      deployFiles:
        - dist
        - node_modules
        - package.json
      
      cache:
        - node_modules
        - .pnpm-store
      
      envVariables:
        NODE_ENV: production
    
    run:
      base: nodejs@20
      
      ports:
        - port: 3000
          httpSupport: true
      
      initCommands:
        - mkdir -p /var/www/tmp
      
      start: node dist/server.js
      
      envVariables:
        NODE_ENV: production
        PORT: 3000
        DB_HOST: db
        DB_PASSWORD: ${db_password}
      
      healthCheck:
        httpGet:
          port: 3000
          path: /health

​
Next Steps

Deployment Process

Learn how deployments work in Zerops.

Scaling Configuration

Configure auto-scaling for your app.

Build docs developers (and LLMs) love

Get started for freeTalk to us