Create a Node.js service in Zerops

Zerops provides a powerful Node.js runtime service with extensive build support. The Node.js runtime is highly scalable and customizable to suit your development and production needs. With just a few clicks or commands, you can have a production-ready Node.js environment up and running in no time.

Create a Node.js service using Zerops GUI

First, set up a project in the Zerops GUI. Then go to the project dashboard page and choose Add new service in the left menu under the Services section. From there, you can add a new Node.js service:

Choose a Node.js version

Zerops supports the following Node.js major versions:

• 18
• 20
• 22

Info

You can easily upgrade the major version at any time later.

Set a hostname

Enter a unique service identifier like "app", "cache", "gui", etc. Duplicate services with the same name within the same project are not allowed.

Limitations:

• Maximum 25 characters
• Must contain only lowercase ASCII letters (a-z) or numbers (0-9)

Caution

The hostname is fixed after the service is created and cannot be changed later.

Set secret environment variables

Add environment variables with sensitive data, such as passwords, tokens, salts, certificates, etc. These will be securely saved inside Zerops and added to your runtime service upon start.

Setting secret environment variables is optional. You can always set them later in the Zerops GUI.

Read more about the different types of environment variables in Zerops.

Configure auto scaling

Zerops automatically scales Node.js services both vertically and horizontally. Vertical scaling adjusts the hardware resources (CPU, RAM, and disk) of a Node.js container, while horizontal scaling adds or removes entire containers.

CPU Mode

Shared Your application gets a full physical CPU core, but it is shared with up to 10 other applications. The power your application receives depends on the other applications running on the same CPU core. In the best-case scenario, your application gets 10/10 of the CPU core power, and 1/10 in the worst-case scenario.

Dedicated The CPU core is dedicated exclusively to your application.

Info

See the pricing for the difference between CPU modes.

You can choose the CPU mode when starting a new service or change it later. The CPU mode doesn't change automatically.

Vertical auto scaling

Vertical auto scaling has the following default configuration:

	Minimum resource	Maximum resource
CPU cores	1	5
RAM	0.25 GB	32 GB
Disk	1 GB	100 GB

Node.js services always start with the minimal resources.

In most cases, the default parameters will work without issues. If you need to limit the cost of the Node.js service, you can lower the maximum resources. Zerops will never scale above the selected maximums.

If you experience insufficient Node.js performance or capacity, you can increase the minimum resources. Zerops will never scale below the selected minimums.

Tip

Learn more about how to fine-tune the auto scaling to fit your application's needs.

Info

You can change the vertical auto scaling parameters at any time.

Horizontal auto scaling

When a container needs more CPU or RAM but is already consuming the maximum resources defined for vertical auto scaling, Zerops will add a new container to your Node.js service. When your Node.js service doesn't need as much power and all containers are vertically scaled down such that their CPU allocation is near the minimum resources, Zerops will gradually remove entire containers.

Horizontal auto scaling has the following default configuration:

Minimum containers	1
Maximum containers	6

Node.js services always start with the minimum number of containers.

You can increase the minimum or decrease the maximum number of containers. The horizontal scaling parameters can be changed later.

Learn more about Node.js auto scaling in Zerops.

Single container vs. High Availability

When creating a new runtime service, you can choose the minimum and maximum number of containers. If you set the maximum limit to one, the service will run in a single container and no horizontal scaling will occur.

Caution

If the single container fails, Zerops will automatically start a new container and deploy your application. However, the application will be unavailable for a short period. This mode is recommended for non-critical applications or development environments.

By increasing the maximum number of containers for your service, you enable horizontal auto scaling. Zerops will then add containers based on your application's load. An application running on two or more containers is in High Availability mode, which we highly recommend for production. When the load drops, containers will be gradually removed down to the defined minimum.

Each container of the same service is strictly installed on a different server. This prevents temporary outages in case any of the Zerops servers fail. If the connection to a container is broken, Zerops immediately redirects incoming traffic to other containers. A new container will be started automatically, and the broken container will be deleted.

Caution

Make sure your application is designed to run in multiple containers.

Create a Node.js service using zCLI

zCLI is the Zerops command-line tool. To create a new Node.js service via the command line, follow these steps:

1. Install & setup zCLI
2. Create a project description file
3. Create a project with a Node.js and PostgreSQL service

Create a project description file

Zerops uses a YAML format to describe the project infrastructure.

Basic example:

Create a directory called my-project. Inside the my-project directory, create a description.yml file with the following content:

# basic project data
project:
  # project name
  name: my-project
# array of project services
services:
  - # service name
    hostname: app
    # service type and version number in nodejs@{version} format
    type: nodejs@latest
    # defines the minimum number of containers for horizontal autoscaling
    minContainers: 1
    # defines the maximum number of containers for horizontal autoscaling. Max value = 6.
    maxContainers: 6
    # optional: create env variables
    envSecrets:
      S3_ACCESS_KEY_ID: 'P8cX1vVVb'
      S3_ACCESS_SECRET: 'ogFthuiLYki8XoL73opSCQ'

The yaml file describes your future project infrastructure. The project will contain one Node.js version 20 service with default auto scaling configuration. Hostname will be set to "app", the internal port(s) the service listens on will be defined later in the zerops.yml. Following secret env variables will be configured:

S3_ACCESS_KEY_ID="P8cX1vVVb"
S3_ACCESS_SECRET="ogFthuiLYki8XoL73opSCQ"

Full example:

Create a directory my-project. Create an description.yml file inside the my-project directory with following content:

# basic project data
project:
  # project name
  name: my-project
  # optional: project description
  description: A project with a Node.js and PostgreSQL database
  # optional: project tags
  tags:
    - DEMO
    - ZEROPS
# array of project services
services:
  - # service name
    hostname: app
    # service type and version number in nodejs@{version} format
    type: nodejs@latest
    # optional: vertical auto scaling customization
    verticalAutoscaling:
      cpuMode: DEDICATED
      minCpu: 2
      maxCpu: 5
      minRam: 2
      maxRam: 24
      minDisk: 6
      maxDisk: 50
      startCpuCoreCount: 3
      minFreeRamGB: 0.5
      minFreeRamPercent: 20
    # defines the minimum number of containers for horizontal autoscaling. Max value = 6.
    minContainers: 2
    # defines the maximum number of containers for horizontal autoscaling. Max value = 6.
    maxContainers: 4
    # optional: create env variables
    envSecrets:
      S3_ACCESS_KEY_ID: 'P8cX1vVVb'
      S3_ACCESS_SECRET: 'ogFthuiLYki8XoL73opSCQ'
  - # second service hostname
    hostname: db
    # service type and version number in postgresql@{version} format
    type: postgresql@12
    # mode of operation "HA"/"non_HA"
    mode: NON_HA

The yaml file describes your future project infrastructure. The project will contain a Node.js service and a PostgreSQL service.

Node.js service with "app" hostname, the internal port(s) the service listens on will be defined later in the zerops.yml. Node.js service will run on version 20 with a custom vertical and horizontal scaling. Following secret env variables will be configured:

S3_ACCESS_KEY_ID="P8cX1vVVb"
S3_ACCESS_SECRET="ogFthuiLYki8XoL73opSCQ"

The hostname of the PostgreSQL service will be set to "db". The single container mode will be chosen and the default auto scaling configuration will be set.

Description of description.yml parameters

The project: section is required. Only one project can be defined.

Parameter	Description	Limitations
name	The name of the new project. Duplicates are allowed.
description	Optional. Description of the new project.	Maximum 255 characters.
tags	Optional. One or more string tags. Tags do not have a functional meaning, they only provide better orientation in projects.

At least one service in services: section is required. You can create a project with multiple services. The example above contains Node.js and PostgreSQL services but you can create a description.yml with your own combination of services.

Parameter	Description
hostname	The unique service identifier. The hostname of the new database will be set to the hostname value. Limitations: - duplicate services with the same name in the same project are forbidden maximum 25 characters - must contain only lowercase ASCII letters (a-z) or numbers (0-9)
type	Specifies the service type nodejs and version. Set type: nodejs<span>@</span>&lt;version&gt; or nodejs<span>@</span>latest Limitations: Following Node.js major versions are currently supported: 20, 18,16
verticalAutoscaling	Optional. Defines custom vertical auto scaling parameters . All verticalAutoscaling attributes are optional. Not specified attributes will be set to their default values.
- cpuMode	Optional. Accepts SHARED, DEDICATED values. Default is SHARED
- minCpu/maxCpu	Optional. Set the minCpu or maxCpu in CPU cores (integer).
- minRam/maxRam	Optional. Set the minRam or maxRam in GB (float).
- minDisk/maxDisk	Optional. Set the minDisk or maxDisk in GB (float).
minContainers	Optional. Default = 1. Defines the minimum number of containers for horizontal autoscaling . Limitations: Current maximum value = 6.
maxContainers	Defines the maximum number of containers for horizontal autoscaling . Limitations: Current maximum value = 6.
envSecrets	Optional. Defines one or more secret env variables as a key value map. See env variable restrictions .

Create a project based on the description.yml

When you have your description.yml ready, use the zcli project project-import command to create a new project and the service infrastructure.

Usage:
  zcli project project-import importYamlPath [flags]

Flags:
  -h, --help                the project import command.
      --orgId string        If you have access to more than one organization, you must specify the org ID for which the
                            project is to be created.
      --workingDie string   Sets a custom working directory. Default working directory is the current directory. (default "./")

Zerops will create a project and one or more services based on the description.yml content.

Maximum size of the description.yml file is 100 kB.

You don't specify the project name in the zcli project project-import command, because the project name is defined in the description.yml.

If you have access to more than one client, you must specify the client ID for which the project is to be created. The clientID is located in the Zerops GUI under the client name on the project dashboard page.

Add Node.js service to an existing project

Example:

Create a directory my-project if it doesn't exist. Create an import.yml file inside the my-project directory with following content:

# basic project data
project:
  # project name
  name: my-project
# array of project services
services:
  - # service name
    hostname: app
    # service type and version number in nodejs@{version} format
    type: nodejs@latest
    # defines the minimum number of containers for horizontal autoscaling
    minContainers: 1
    # defines the maximum number of containers for horizontal autoscaling. Max value = 6.
    maxContainers: 6
    # optional: create env variables
    envSecrets:
      S3_ACCESS_KEY_ID: 'P8cX1vVVb'
      S3_ACCESS_SECRET: 'ogFthuiLYki8XoL73opSCQ'

The yaml file describes the list of one or more services that you want to add to your existing project. In the example above, one Node.js service version 20 with default auto scaling configuration will be added to your project. Hostname of the new service will be set to app. Following secret env variables will be configured:

S3_ACCESS_KEY_ID="P8cX1vVVb"
S3_ACCESS_SECRET="ogFthuiLYki8XoL73opSCQ"

The content of the services: section of import.yml is identical to the project description file. The import.yml never contains the project: section because the project already exists.

When you have your import.yml ready, use the zcli project service-import command to add one or more services to your existing Zerops project.

Usage:
  zcli project service-import importYamlPath [flags]

Flags:
  -h, --help               the project service import command.
      --projectId string   If you have access to more than one project, you must specify the project ID for which the
                           command is to be executed.

zCLI commands are interactive, when you press enter after zcli project service-import importYamlPath, you will be given a list of your projects to choose from.

Maximum size of the import.yml file is 100 kB.