Node.js Deployment Process

Zerops handles Node.js deployments automatically with zero-downtime updates, health checks, and intelligent traffic routing.

Deployment Flow

When you trigger a deployment, Zerops follows this process:

Build Phase

Creates a build container with your specified Node.js version
Runs prepareCommands to set up the build environment
Executes buildCommands to build your application
Collects files specified in deployFiles

Prepare Runtime

Creates a runtime container (if needed)
Runs runtime prepareCommands (cached after first run)
Copies built files to /var/www

Deploy

Runs initCommands on each container
Starts your application with the start command
Performs readiness checks
Routes traffic to healthy containers

Cleanup

Once new containers are healthy, old containers are gracefully shut down.

Triggering Deployments

From Git Repository

Automatic deployment from Git:

Configure Git integration

In the Zerops GUI:

Navigate to your service
Click Deploy
Select From Git
Enter repository URL and branch

Automatic triggers

Zerops automatically deploys when:

You push to the configured branch
You manually trigger a deployment

Using zCLI

Deploy from your local machine:

# Deploy from current directory
zcli push

# Deploy specific service
zcli push --serviceId=<service-id>

GitHub Actions

Automate deployments with GitHub Actions:

.github/workflows/deploy.yml

name: Deploy to Zerops

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Deploy to Zerops
        uses: zeropsio/github-action@v1
        with:
          token: ${{ secrets.ZEROPS_TOKEN }}
          serviceId: ${{ secrets.ZEROPS_SERVICE_ID }}

Readiness Checks

Readiness checks ensure new containers are healthy before receiving traffic.

HTTP Readiness Check

Check if your application responds to HTTP requests:

zerops:
  - setup: app
    deploy:
      readinessCheck:
        httpGet:
          port: 3000
          path: /health
          scheme: http
    run:
      start: npm start

How HTTP checks work

Zerops repeatedly sends GET requests to http://127.0.0.1:3000/health until:

The endpoint returns HTTP 200
The timeout is reached (deployment fails)

Your /health endpoint should verify:

The server is running
Database connections are ready
Critical services are available

Command Readiness Check

Run a custom command to verify readiness:

zerops:
  - setup: app
    deploy:
      readinessCheck:
        exec:
          command: |
            node -e "require('./health-check.js')"

Example health check script:

health-check.js

const { Pool } = require('pg');

async function healthCheck() {
  const pool = new Pool({
    host: 'db',
    database: 'db',
    user: 'db'
  });
  
  try {
    // Check database connection
    await pool.query('SELECT 1');
    
    // Check critical services
    // ...
    
    console.log('Health check passed');
    process.exit(0);
  } catch (error) {
    console.error('Health check failed:', error);
    process.exit(1);
  } finally {
    await pool.end();
  }
}

healthCheck();

Zero-Downtime Deployments

Zerops ensures your application stays available during deployments:

How It Works

New containers start - Zerops creates new runtime containers with updated code
Readiness checks - New containers must pass health checks
Traffic shift - Load balancer routes traffic to new containers
Graceful shutdown - Old containers finish existing requests before stopping

During deployment, both old and new versions may serve requests briefly. Ensure backwards compatibility.

Rolling Updates

With multiple containers, Zerops updates them progressively:

services:
  - hostname: app
    type: nodejs@20
    minContainers: 3
    maxContainers: 6

Update process:

Update 1st container → health check → route traffic
Update 2nd container → health check → route traffic
Update 3rd container → health check → route traffic
Continue until all containers updated

Deployment Logs

Monitor deployments in real-time:

Build Log

View build progress:

prepareCommands output
buildCommands execution
Dependency installation
Build errors and warnings

Runtime Log

Monitor application startup:

Container initialization
initCommands output
Application start command
Runtime errors

Access Logs

View logs in Zerops GUI:

Go to your service
Click Logs
Select log type (Build, Runtime, etc.)
Filter by time range

Environment Variables in Deployment

Manage environment variables across deployments:

Secret Variables

Set sensitive data in the GUI (not in zerops.yaml):

services:
  - hostname: app
    envSecrets:
      DB_PASSWORD: secretvalue
      API_KEY: abc123

Build vs Runtime Variables

Build Variables
Runtime Variables

Available during build:

build:
  envVariables:
    NODE_ENV: production
    API_URL: https://api.example.com

Available when app runs:

run:
  envVariables:
    NODE_ENV: production
    PORT: 3000
    DB_HOST: db

Referencing Secret Variables

Reference secrets set in GUI:

run:
  envVariables:
    DB_PASSWORD: ${db_password}
    API_KEY: ${api_key}

Deployment Strategies

Blue-Green Deployment

Manually test before switching traffic:

Deploy to a new service
Test using internal hostname
Switch public domain to new service
Remove old service

Canary Deployment

Gradually roll out to users:

Deploy with minimum containers:
```
minContainers: 1
maxContainers: 10
```
Monitor metrics (errors, performance)
Increase minContainers if stable
Scale to full capacity

Rollback

If a deployment fails or causes issues:

Via GUI

Go to service detail
Click Deployments history
Select previous successful deployment
Click Redeploy

Via Git

# Revert the commit
git revert HEAD
git push

# Zerops automatically deploys the reverted version

Troubleshooting Deployments

Build Fails

Dependency installation fails

Check your package manager:

buildCommands:
  - npm ci --verbose  # Show detailed output
  - npm run build

Ensure package-lock.json is committed.

Build command errors

Test locally first:

# Run the same commands locally
npm ci
npm run build

Check build logs for specific errors.

Out of memory

Increase build resources or optimize build:

buildCommands:
  - node --max-old-space-size=4096 node_modules/.bin/webpack

Readiness Check Fails

Health endpoint not responding

Ensure your app listens on the correct port:

const PORT = process.env.PORT || 3000;
app.listen(PORT, '0.0.0.0', () => {
  console.log(`Server running on port ${PORT}`);
});

Database connection fails

Check database service is running and accessible:

// Use service hostname
const pool = new Pool({
  host: 'db',  // Not 'localhost'
  database: 'db',
  user: 'db'
});

Best Practices

Use Health Checks

Always implement readiness checks to prevent routing traffic to broken deployments.

Test Locally First

Run build commands locally before deploying to catch issues early.

Monitor Logs

Watch deployment logs in real-time to catch issues immediately.

Keep Dependencies Updated

Regular updates prevent security issues and deployment failures.

Next Steps

Configure Scaling

Set up auto-scaling for your application.

Build Pipeline

Advanced build configuration options.

JavaScript Runtimes

Backend Languages

Web Servers & Static

Node.js Deployment Process

Deployment Flow

Triggering Deployments

From Git Repository

Using zCLI

GitHub Actions

Readiness Checks

HTTP Readiness Check

Command Readiness Check

Zero-Downtime Deployments

How It Works

Rolling Updates

Deployment Logs

Build Log

Runtime Log

Access Logs

Environment Variables in Deployment

Secret Variables

Build vs Runtime Variables

Referencing Secret Variables

Deployment Strategies

Blue-Green Deployment

Canary Deployment

Rollback

Troubleshooting Deployments

Build Fails

Readiness Check Fails

Best Practices

Use Health Checks

Test Locally First

Monitor Logs

Keep Dependencies Updated

Next Steps

Configure Scaling

Build Pipeline

Build docs developers (and LLMs) love

JavaScript Runtimes

Backend Languages

Web Servers & Static

​Deployment Flow

​Triggering Deployments

​From Git Repository

​Using zCLI

​GitHub Actions

​Readiness Checks

​HTTP Readiness Check

​Command Readiness Check

​Zero-Downtime Deployments

​How It Works

​Rolling Updates

​Deployment Logs

​Build Log

​Runtime Log

​Access Logs

​Environment Variables in Deployment

​Secret Variables

​Build vs Runtime Variables

​Referencing Secret Variables

​Deployment Strategies

​Blue-Green Deployment

​Canary Deployment

​Rollback

​Troubleshooting Deployments

​Build Fails

​Readiness Check Fails

​Best Practices

Use Health Checks

Test Locally First

Monitor Logs

Keep Dependencies Updated

​Next Steps

Configure Scaling

Build Pipeline

Build docs developers (and LLMs) love

Deployment Flow

Triggering Deployments

From Git Repository

Using zCLI

GitHub Actions

Readiness Checks

HTTP Readiness Check

Command Readiness Check

Zero-Downtime Deployments

How It Works

Rolling Updates

Deployment Logs

Build Log

Runtime Log

Access Logs

Environment Variables in Deployment

Secret Variables

Build vs Runtime Variables

Referencing Secret Variables

Deployment Strategies

Blue-Green Deployment

Canary Deployment

Rollback

Troubleshooting Deployments

Build Fails

Readiness Check Fails

Best Practices

Next Steps