Node.js build process

Customize NodeJS build environment

The default NodeJS build environment contains:

• Alpine 3.20
• Selected version of Node.js when the runtime service was created.
• zCLI
• NPM, Yarn, Git and NPX tools

Note

To use Ubuntu instead of the default Alpine, set the build.os attribute.

Additional packages and tools can be installed using build.prepareCommands.

Description of the build process

Zerops starts a temporary build container and performs following actions:

1. Installs the build environment
2. Downloads your application source code from GitHub ↗, GitLab ↗ or via Zerops CLI
3. Optionally customizes the build environment
4. Runs the build commands
5. Uploads the application artefact to the internal Zerops storage
6. Optionally customizes the runtime environment
7. Deploys your application

The build container is automatically deleted after the build has finished or failed.

Cancel running build

When you know that the running build is not correct and you want to cancel it, you can do it in Zerops GUI. Go to the service detail, open the list of running processes and click on the Open pipeline detail button. Then click on the Cancel build button.

Caution

The build cancellation is available before the build pipeline is finished. When the build is finished, the deployment cannot be cancelled.

Customize Node.js build environment

The default Node.js build environment contains:

• Alpine 3.20
• selected version of Node.js defined in zerops.yml build.base parameter
• zCLI, Zerops command line tool
• npm, yarn, git and npx tools

If you prefer the Ubuntu OS instead of Alpine, set the build.os attribute to ubuntu. To install additional packages or tools add one or more build.prepareCommands commands to your zerops.yml.

Info

The application code is available in the /var/www folder in your build container before the prepare commands are triggered. This allows you to use any file from your application code in your prepare commands (e.g. a configuration file).

Node.js build hardware resources

Build of your Node.js application is run in a separate build container with following resource configuration:

HW resource	Minimum	Maximum
CPU cores	6	20
RAM	8 GB	8 GB
Disk	1 GB	100 GB

The build container is always started with the minimum hardware resources and scales vertically up to the maximum resources.

Info

Hardware resources of the build containers are not charged. The build costs are covered by the standard Zerops project fee.

Build time limit

The time limit for the whole build pipeline is 1 hour. After 1 hour, Zerops will terminate the build pipeline and delete the build container.

Troubleshooting build-related problems

Failure of a build prepare command

If any prepare command fails, it returns an exit code other than 0 and the build is canceled. Read the build log to troubleshoot the error. If the command ends successfully, it returns the exit code 0 and Zerops triggers the following command. When all prepareCommands commands are finished, your custom build environment is ready for the build phase.

Invalidate the build cache

Some packages or tools can take a long time to install. Therefore, Zerops caches your custom build environment after each successful build where the prepareCommands commands were used. When the second or following build is triggered, Zerops will use the build cache from the previous build if both following conditions are met:

1. Content of the build.base and build.prepareCommands attributes didn't change from the previous build
2. The build cache wasn't invalidated in the Zerops GUI.

To invalidate the Zerops build cache go to your service detail in Zerops GUI, choose Pipelines & CI / CD settings from the left menu. Then click on the Clean build cache button.

When the build cache is used, Zerops doesn't run the prepare commands and the build of your application is faster.

Failure of a build command

If any build command fails, it returns an exit code other than 0 and the build is canceled. Read the build log to troubleshoot the error. If the error log doesn't contain any specific error message, try to run your build with the --verbose option.

buildCommands:
  - npm i --verbose
  - npm run build

If the command ends successfully, it returns the exit code 0 and Zerops triggers the following command. When all buildCommands are finished, the application build is completed and ready for the deploy phase.