Customize Alpine runtime environment

Build Custom Runtime Images

Zerops allows you to build custom runtime images (CRI) when the default base runtime images don't meet your application's requirements. This is an optional phase in the build and deploy pipeline.

Alpine is a versatile base for running anything not explicitly offered as a dedicated Zerops runtime. You can install any packages and tools you need, treating it as a clean OS to customize however you want.

It is also a great option when you need a specific version of a technology (like Go, Node.js, or PHP) that Zerops doesn't support by default—whether it's an older version for legacy projects or a newer release not yet available.

Configuration

Default Alpine Runtime Environment

The default Alpine runtime environment contains:

• Alpine 3.20
• zCLI
• Git

When You Need a Custom Runtime Image

Since Alpine serves as a general-purpose base, you'll likely want to customize it for your specific use case. Common scenarios include:

• System packages: Install any packages you need via apk, such as imagemagick, ffmpeg, or chromium
• Specific language versions: Install versions of Go, Node.js, PHP, Python, or other runtimes that are not available as dedicated Zerops services (e.g., older or cutting-edge versions)
• Custom binaries: Add compiled binaries or tools not available in the default repositories
• Development tools: Include debugging tools, profilers, or other utilities
• Specific libraries: Install dependencies required by your application

important

You should not include your application code in the custom runtime image, as your built/packaged code is deployed automatically into fresh containers.

Here are examples of configuring custom runtime images in your zerops.yml:

Basic Alpine Setup

...
run:
  base: alpine@3.20
  prepareCommands:
    - apk update
    - apk add --no-cache imagemagick ffmpeg

Using Build Files in Runtime Preparation

...
build:
  ...
  addToRunPrepare:
    - requirements.txt
run:
  ...
  prepareCommands:
    - apk update
    - apk add --no-cache libpq-dev py3-pip
    - pip install -r requirements.txt

For complete configuration details, see the runtime prepare phase configuration guide.

Process and Caching

How Runtime Prepare Works

The runtime prepare process follows the same steps for all runtimes. See how runtime prepare works for the complete process details.

Caching Behavior

Zerops caches custom runtime images to optimize deployment times. Learn about custom runtime image caching including when images are cached and reused.

Build Management

For information about managing builds and deployments, see managing builds and deployments.

Warning

Shared storage mounts are not available during the runtime prepare phase.

Troubleshooting

If your prepareCommands fail, check the prepare runtime log for specific error messages.