Node.js build process

Build process overview

Zerops starts a temporary build container and performs the following actions:

1. Installs the build environment - Sets up base system and Node.js runtime
2. Downloads your application source code - From GitHub ↗, GitLab ↗ or via Zerops CLI
3. Optionally customizes the build environment - Runs prepare commands if configured
4. Runs the build commands - Executes your build process
5. Uploads the application artifact - Stores build output to internal Zerops storage
6. Caches selected files - Preserves specified files for faster future builds

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

Build configuration

Configure your Node.js build process in your zerops.yaml file according to the full build & deploy Node.js pipeline guide.

Build environment

Default Node.js build environment

The default Node.js build environment contains:

• Alpine 3.20
• Selected version of Node.js defined in zerops.yaml build.base parameter
• zCLI, Zerops command line tool
• NPM, Yarn, Git and NPX tools

Customize build environment

If you prefer Ubuntu instead of Alpine, set the build.os attribute to ubuntu.

To install additional packages or tools, add one or more build.prepareCommands to your zerops.yaml.

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).

Build hardware resources

All runtime services use the same hardware resources for build containers:

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

Build containers start with minimum resources and scale vertically up to maximum capacity as needed.

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.

Info

Build container resources are not charged separately. Limited build time is included in your project core plan, with additional build time available if needed.

Troubleshooting Node.js builds

Advanced troubleshooting

For complex build issues that require investigation, you can enable debug mode to pause the build process at specific points and inspect the build container state interactively.

Build and prepare command failures

If any build command or prepare command fails (returns non-zero exit code), the build is canceled. Check the build log to troubleshoot the error.

For Node.js, if the error log doesn't contain specific error messages, try running your build with verbose output:

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

Build cache issues

If you encounter unexpected build behavior or dependency issues, the problem might be related to cached build data. While Zerops maintains the build cache to speed up deployments, sometimes you may need to start fresh.

To invalidate the build cache:

1. Go to your service detail in Zerops GUI
2. Choose Pipelines & CI/CD Settings from the left menu
3. Click on the Invalidate build cache button

This will force Zerops to run the next build clean, including all prepare commands.

Learn more about build cache behavior.

More resources

For more details about the build and deploy pipeline, including how to cancel builds and manage application versions, see the general pipeline documentation.

Next steps

• Understand the deployment process
• Learn how to customize the runtime environment
• Explore build and runtime logs