Skip to main content
This quickstart guide will walk you through deploying a complete Node.js application with PostgreSQL database on Zerops. You’ll go from zero to a running application with just a few clicks—no complex configuration required.

​
What You’ll Deploy

You’ll deploy a simple Node.js web application that:
  • Connects to a PostgreSQL database
  • Exposes a REST API endpoint
  • Runs on a production-ready infrastructure with automatic scaling
  • Gets a public subdomain for instant access
The entire stack will be configured, built, and deployed automatically.

​
Prerequisites

All you need is:
  • A web browser
  • 5 minutes of your time
No credit card required for initial testing.
1

Create Your Zerops Account

Navigate to the Zerops GUI and sign up for a free account.You can register using:
  • Email and password
  • GitHub account
  • GitLab account
  • Google account
After signing up, you’ll land on your project dashboard.
2

Import the Node.js Recipe Project

On your dashboard, locate the Projects section and click on Import a project.Copy and paste this YAML configuration:
project:
  name: recipe-nodejs
  tags:
    - zerops-quickstart

services:
  - hostname: api
    type: nodejs@20
    enableSubdomainAccess: true
    buildFromGit: https://github.com/zeropsio/recipe-nodejs

  - hostname: db
    type: postgresql@16
    mode: NON_HA
    priority: 1
Click Import project to start the deployment.

​
What This Configuration Does

Let’s break down what’s happening:Project Configuration:
  • Creates a new project named recipe-nodejs
  • Tags it for easy identification
API Service (Node.js):
  • Creates a Node.js 20 runtime service named api
  • Enables public access via Zerops subdomain
  • Automatically builds from the GitHub repository
  • Configures load balancing, SSL, and autoscaling
Database Service (PostgreSQL):
  • Creates a PostgreSQL 16 database named db
  • Runs in NON_HA mode (single container for development)
  • Priority 1 ensures the database starts before the API
  • Automatically configures secure internal networking
The buildFromGit parameter triggers a one-time build and deployment from the specified repository. The repository contains a zerops.yaml file that tells Zerops how to build and run the application.
3

Watch the Deployment Process

After clicking import, Zerops will:
  1. Create project infrastructure (5-10 seconds)
    • Deploy L3 balancer with firewall
    • Set up L7 load balancer for HTTP traffic
    • Configure logging and statistics containers
    • Assign IPv6 and IPv4 addresses
  2. Create the PostgreSQL database (10-15 seconds)
    • Provision storage
    • Initialize database cluster
    • Set up automatic backups
    • Generate connection credentials
  3. Build the Node.js application (30-60 seconds)
    • Clone the GitHub repository
    • Create build container with Node.js 20
    • Run npm install
    • Execute build commands
    • Create application artifact
  4. Deploy to runtime (10-15 seconds)
    • Create runtime container(s)
    • Deploy built application
    • Run database migrations
    • Start the application
    • Configure routing and SSL
You can watch the build progress in real-time by clicking on the running pipeline in your service detail.
The build log shows every command executed during the build process. This is incredibly useful for debugging if something goes wrong.
4

Access Your Deployed Application

Once all pipelines complete (indicated by green checkmarks), your application is live!

​
Find Your Application URL

  1. Navigate to your project dashboard
  2. Click on the api service
  3. Look for the IP Addresses & Public Routing Overview section
  4. Find the subdomain URL (format: https://api-<random-id>-8080.prg1.zerops.app)

​
Test the Application

Click the subdomain URL to open your application in a browser. You should see:
Hello, World!
This simple response confirms your Node.js application is running and successfully connected to the PostgreSQL database.

​
What Just Happened?

Behind the scenes, your application:
  • Connected to the PostgreSQL database using environment variables automatically provided by Zerops
  • Ran database migrations during the initialization phase
  • Started serving HTTP requests through the load balancer
  • Got automatic SSL certificate for HTTPS access
Your application is now running on production-ready infrastructure with automatic scaling, load balancing, and monitoring enabled!
5

Explore the Zerops Dashboard

Now that your application is running, explore the Zerops dashboard to see what’s available:

​
Service Overview

  • Runtime Log: Real-time logs from your application
  • Build Log: History of all builds and deployments
  • Metrics: CPU, RAM, and disk usage with automatic scaling visualization
  • Containers: View and manage individual containers

​
Database Management

  • Connection Info: Access credentials and connection strings
  • Backups: Automatic backup configuration and manual backup triggers
  • Metrics: Database performance monitoring
  • Logs: PostgreSQL server logs

​
Project Settings

  • Environment Variables: Manage secrets and configuration
  • Public Access: Configure domains and routing
  • VPN: Connect to your project’s private network
  • Team: Invite collaborators
All of this infrastructure—load balancers, firewalls, SSL certificates, logging, monitoring—is fully managed by Zerops. You just focus on your code.

​
Understanding zerops.yaml

The magic behind the automated deployment is the zerops.yaml file in the recipe repository. Let’s look at what it contains: 
zerops:
  - setup: api
    build:
      base: nodejs@20
      buildCommands:
        - npm i
        - npm run build
      deployFiles: ./dist
      cache: node_modules
    run:
      base: nodejs@20
      start: npm start

​
Configuration Breakdown

setup: api - Links this configuration to the api service Build Phase:
  • base: nodejs@20 - Uses Node.js 20 build environment
  • buildCommands - Commands to build your application
  • deployFiles: ./dist - Only deploys the dist folder to runtime (smaller, faster)
  • cache: node_modules - Caches dependencies for faster subsequent builds
Run Phase:
  • base: nodejs@20 - Uses Node.js 20 runtime environment
  • start: npm start - Command to start your application
This simple configuration gives you:
  • Automatic dependency installation
  • Production builds
  • Optimized artifact deployment
  • Fast rebuilds with caching
  • Zero-downtime deployments

Full zerops.yaml Reference

Learn about all available configuration options

​
What’s Next?

​
Deploy Your Own Application

Now that you’ve deployed a recipe, try deploying your own application:
1

Add zerops.yaml to Your Repository

Create a zerops.yaml file in the root of your repository based on the example above. Customize the build and start commands for your application.
2

Create Services in Zerops

Use the import YAML configuration to create your project structure, or create services manually through the GUI.
3

Connect Your Repository

In your service detail, go to Pipelines & CI/CD settings and connect your GitHub or GitLab repository for automatic deployments.

​
Explore More Recipes

Browse our GitHub organization for ready-to-deploy recipes in various technologies:

Node.js Recipes

Express, NestJS, Next.js examples

PHP Recipes

Laravel, Symfony applications

Python Recipes

Django, FastAPI projects

Go Recipes

Go web applications and APIs

​
Learn Core Concepts

Project Infrastructure

Understand how Zerops organizes projects and services

Automatic Scaling

Configure horizontal and vertical autoscaling

Build Pipeline

Master the build and deploy pipeline

Environment Variables

Manage secrets and configuration

​
Use the CLI

For advanced workflows, install the Zerops CLI: 
# Install zCLI
npm i -g @zerops/zcli

# Login
zcli login

# Push code to trigger build
zcli service push

# Connect to VPN
zcli vpn start

CLI Documentation

Explore all CLI commands and capabilities

​
Get Help

Running into issues or have questions?

Discord Community

Join our Discord server for real-time help from the Zerops team and community

Documentation

Browse the complete documentation for detailed guides and references

​
Congratulations!

You’ve successfully deployed your first application on Zerops. You now have:
Production-ready infrastructure with load balancing and SSL
Automatic scaling configured and ready
Zero-downtime deployment pipeline
Comprehensive logging and monitoring
A foundation to build your next great application
Welcome to Zerops—now go build something amazing!

Build docs developers (and LLMs) love

Get started for freeTalk to us